Cogapp - Content Generator

Common errors

• cog: command not found

  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.
  fix First, ensure `pip install cogapp` was successful. If the problem persists, run `python -m cogapp ...` instead of `cog ...` to explicitly invoke the module.

• TypeError: main() got an unexpected keyword argument 'argv'

  cause You are attempting to call `cogapp.main()` programmatically using the `argv` keyword argument, which was removed in version 3.0.0.
  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'])`.

• FileNotFoundError: [Errno 2] No such file or directory: 'non_existent_file.txt'

  cause The input file specified in the `cog` command does not exist at the given path or the path is incorrect.
  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.

Warnings

• breaking The `main()` function signature changed significantly in version 3.0.0. It no longer accepts `sys.argv` implicitly or via an `argv` keyword argument.
  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'])`.
• gotcha 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.
  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`.
• gotcha 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.
  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.

Install

• pip install cogapp Install latest version

Imports

• main

  from cogapp.cogapp import main

  Cogapp is primarily a command-line tool. This import allows programmatic execution of the main utility function, mirroring the 'python -m cogapp' command.

Quickstart

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.

import subprocess
import os
import datetime

# Create a dummy input file
file_content = """
Hello, cogapp user!
This line will be replaced by cog.
[[[cog
print(f"The current UTC time is: {datetime.datetime.utcnow().isoformat(timespec='seconds')}")
]]]
This line will remain.
"""
input_filename = "cog_example.txt"
with open(input_filename, "w") as f:
    f.write(file_content)

print(f"Created {input_filename} with initial content:")
with open(input_filename, "r") as f:
    print(f.read())

# Run cog in-place
print(f"\nRunning 'python -m cogapp -r {input_filename}'...")
try:
    result = subprocess.run([
        "python", "-m", "cogapp", "-r", input_filename
    ], capture_output=True, text=True, check=True)
    
    if result.stdout:
        print("Cog output (stdout):")
        print(result.stdout)
    if result.stderr:
        print("Cog errors (stderr):")
        print(result.stderr)
    
    print(f"\nUpdated {input_filename} content:")
    with open(input_filename, "r") as f:
        print(f.read())

except subprocess.CalledProcessError as e:
    print(f"Error running cogapp: {e}")
    print(f"Stdout: {e.stdout}")
    print(f"Stderr: {e.stderr}")
finally:
    # Clean up
    if os.path.exists(input_filename):
        os.remove(input_filename)
    print(f"\nCleaned up {input_filename}.")