Jinjanator

Warnings

• breaking Major versions of Jinjanator frequently drop support for older Python versions and add support for newer ones. For example, version 25.3.0 removed support for Python 3.9, and 24.4.0 removed Python 3.8 support. Users must ensure their Python environment meets the `requires_python` specification for their installed Jinjanator version.
  Fix: Upgrade your Python environment to a version supported by your Jinjanator installation, or pin Jinjanator to an older version that supports your Python environment. Refer to the project's `pyproject.toml` or release notes for current Python compatibility.
• breaking The `jinjanator-plugins` dependency, which underpins extensibility, explicitly recommends pinning to a specific version or a narrow 'year.release' range (e.g., '25.1.*'). This is due to potential non-backward-compatible API changes. Plugins relying on specific `jinjanator-plugins` versions may break if the core `jinjanator` library upgrades its `jinjanator-plugins` dependency or if the plugin itself is not carefully versioned.
  Fix: When developing or using custom plugins, ensure they explicitly declare and pin their `jinjanator-plugins` dependency to prevent unexpected breakage with `jinjanator` updates. Consult `jinjanator-plugins` documentation for best practices.
• gotcha In versions prior to 25.2.0, there was a corrected behavior for the `--customize` argument when the customization file did not contain every possible type of customization function. Users with complex or incomplete customization files on older versions might encounter unexpected behavior.
  Fix: Upgrade to Jinjanator 25.2.0 or newer to benefit from the corrected behavior of the `--customize` argument, ensuring all customization functions are handled gracefully, even if not all hooks are present in the file. [cite: 25.2.0 release notes]

Install

• pip install jinjanator Install stable version

Imports

• main

  from jinjanator.cli import main

  Jinjanator is primarily a CLI tool; `main` is its internal entry point. Direct programmatic use of the `jinjanator` *tool* itself is uncommon. For general Python-level templating, import `jinja2` directly.
• Environment

  from jinja2 import Environment

  For programmatic templating within Python applications, you typically interact with the `Jinja2` library directly rather than through `jinjanator`'s internal API.

Quickstart

This quickstart demonstrates how to use `jinjanator` via its command-line interface within a Python script. It creates a temporary Jinja2 template file, sets environment variables, and then executes the `jinjanate` command to render the template. The output is printed to the console.

import subprocess
import os
import tempfile

# Create a simple Jinja2 template content
template_content = "<data><name>{{ name }}</name><age>{{ age }}</age></data>"

# Create a temporary template file
with tempfile.NamedTemporaryFile(mode="w", delete=False, suffix=".j2") as tmp_template:
    tmp_template.write(template_content)
    template_path = tmp_template.name

try:
    # Set environment variables for the subprocess that runs jinjanate
    env = os.environ.copy()
    env["name"] = "Andrew"
    env["age"] = "31"

    print(f"Rendering template: {template_path} with name={env['name']}, age={env['age']}")

    # Run jinjanate command. Both 'j2' and 'jinjanate' are valid entry points.
    result = subprocess.run(
        ["jinjanate", template_path],
        capture_output=True,
        text=True,
        check=True, # Raise CalledProcessError if the command returns a non-zero exit code
        env=env
    )

    print("\n--- Rendered output ---")
    print(result.stdout)
    print("-----------------------")

except subprocess.CalledProcessError as e:
    print(f"Error rendering template: {e}")
    print(f"Stderr: {e.stderr}")
finally:
    # Clean up the temporary file
    os.remove(template_path)