{"id":9595,"library":"cogapp","title":"Cogapp - Content Generator","description":"Cogapp, currently at version 3.6.0, is a content generator that executes Python snippets embedded within source files (like Python, C, HTML, or plain text) to produce updated output. It helps keep documentation, code examples, and derived content in sync with their source, primarily operating as a command-line tool. Releases are generally stable, with new versions addressing bug fixes and minor enhancements.","status":"active","version":"3.6.0","language":"en","source_language":"en","source_url":"http://github.com/nedbat/cog","tags":["code generation","preprocessor","documentation","text templating","build tool"],"install":[{"cmd":"pip install cogapp","lang":"bash","label":"Install latest version"}],"dependencies":[],"imports":[{"note":"Cogapp is primarily a command-line tool. This import allows programmatic execution of the main utility function, mirroring the 'python -m cogapp' command.","symbol":"main","correct":"from cogapp.cogapp import main"}],"quickstart":{"code":"import subprocess\nimport os\nimport datetime\n\n# Create a dummy input file\nfile_content = \"\"\"\nHello, cogapp user!\nThis line will be replaced by cog.\n[[[cog\nprint(f\"The current UTC time is: {datetime.datetime.utcnow().isoformat(timespec='seconds')}\")\n]]]\nThis line will remain.\n\"\"\"\ninput_filename = \"cog_example.txt\"\nwith open(input_filename, \"w\") as f:\n    f.write(file_content)\n\nprint(f\"Created {input_filename} with initial content:\")\nwith open(input_filename, \"r\") as f:\n    print(f.read())\n\n# Run cog in-place\nprint(f\"\\nRunning 'python -m cogapp -r {input_filename}'...\")\ntry:\n    result = subprocess.run([\n        \"python\", \"-m\", \"cogapp\", \"-r\", input_filename\n    ], capture_output=True, text=True, check=True)\n    \n    if result.stdout:\n        print(\"Cog output (stdout):\")\n        print(result.stdout)\n    if result.stderr:\n        print(\"Cog errors (stderr):\")\n        print(result.stderr)\n    \n    print(f\"\\nUpdated {input_filename} content:\")\n    with open(input_filename, \"r\") as f:\n        print(f.read())\n\nexcept subprocess.CalledProcessError as e:\n    print(f\"Error running cogapp: {e}\")\n    print(f\"Stdout: {e.stdout}\")\n    print(f\"Stderr: {e.stderr}\")\nfinally:\n    # Clean up\n    if os.path.exists(input_filename):\n        os.remove(input_filename)\n    print(f\"\\nCleaned up {input_filename}.\")\n","lang":"python","description":"This quickstart demonstrates how to use cogapp to generate content within a file. It creates a sample file with a `[[[cog ... ]]]` block, runs cogapp in-place using `python -m cogapp`, and then prints the updated file content. The subprocess call ensures cogapp is run robustly even if the `cog` executable is not directly in PATH."},"warnings":[{"fix":"If calling `cogapp.main()` programmatically, pass command-line arguments as a list of strings directly, e.g., `main(['-r', 'my_file.txt'])` instead of `main(argv=['-r', 'my_file.txt'])`.","message":"The `main()` function signature changed significantly in version 3.0.0. It no longer accepts `sys.argv` implicitly or via an `argv` keyword argument.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"To write output to a new file, use `-o <output_file.txt>`. To modify the input file in-place, use the `-r` (replace) flag, e.g., `cog -r my_file.txt`.","message":"By default, cogapp writes its generated output to standard output (stdout). This means if you simply run `cog my_file.txt`, the changes will be printed to your console, not written back to the file.","severity":"gotcha","affected_versions":"All"},{"fix":"Always ensure `[[[cog` blocks are properly closed with `[[[end]]]`. Check for valid Python syntax inside the blocks. Use `cog -v` (verbose) for more detailed output during processing if debugging issues.","message":"Cogapp's default delimiters `[[[cog ... ]]]` and `[[[end]]]` are strict. Incorrect nesting, unmatched delimiters, or Python syntax errors within the `cog` block can lead to silent failures, unexpected output, or incomplete processing.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"First, ensure `pip install cogapp` was successful. If the problem persists, run `python -m cogapp ...` instead of `cog ...` to explicitly invoke the module.","cause":"The `cogapp` package is either not installed, or the directory containing its `cog` executable is not included in your system's PATH environment variable.","error":"cog: command not found"},{"fix":"Pass command-line arguments as a list of strings directly to the `main()` function, for example: `from cogapp.cogapp import main; main(['-r', 'my_file.txt'])`.","cause":"You are attempting to call `cogapp.main()` programmatically using the `argv` keyword argument, which was removed in version 3.0.0.","error":"TypeError: main() got an unexpected keyword argument 'argv'"},{"fix":"Verify that the file path and name provided to `cog` are correct and the file exists. Use an absolute path or ensure you are running the command from the correct directory.","cause":"The input file specified in the `cog` command does not exist at the given path or the path is incorrect.","error":"FileNotFoundError: [Errno 2] No such file or directory: 'non_existent_file.txt'"}]}