Jinjanator Plugins API

25.1.0 · active · verified Sun Apr 12

Jinjanator-plugins is a Python package, currently at version 25.1.0, that provides the essential plugin API (types and decorators) for extending the `jinjanator` CLI tool. This library allows developers to create custom plugins that add new data formats, Jinja2 filters, tests, globals, and extensions. It maintains an active development status with frequent releases, often tied to Python version support updates or API refinements.

Warnings

breaking Python 3.9 support was removed, and minimum Python version is now 3.10 as of version 25.1.0. Python 3.8 support was removed, and 3.13 was added in version 24.2.0. Users on older Python versions must upgrade to use recent `jinjanator-plugins` versions.
Fix: Upgrade your Python environment to 3.10 or newer (preferably 3.14+ for latest features and compatibility). If you cannot upgrade Python, use an older `jinjanator-plugins` version compatible with your environment.
gotcha It is strongly recommended to pin the dependency for `jinjanator-plugins` to a specific version or a narrow 'year.release' version range (e.g., `==25.1.*`) in your plugin projects. The API can change in a non-backward-compatible fashion, which may lead to breakage if not pinned.
Fix: When declaring `jinjanator-plugins` as a dependency in your `pyproject.toml` or `requirements.txt`, always use strict version pinning (e.g., `jinjanator-plugins==25.1.0`) or a compatible range (e.g., `jinjanator-plugins==25.1.*`).
breaking The 'formats' API underwent a redesign in version 23.4.0 to better support formats that need to store data for their parsers. Plugins implementing custom data formats might require updates.
Fix: Review the official documentation and examples for the `Format` protocol and `plugin_formats_hook` for plugins that define custom data formats to adapt to the redesigned API.

Install

pip install jinjanator-plugins Install `jinjanator-plugins`

Imports

plugin_filters_hook
```
from jinjanator_plugins import plugin_filters_hook
```
Decorator for registering custom Jinja2 filters.
plugin_tests_hook
```
from jinjanator_plugins import plugin_tests_hook
```
Decorator for registering custom Jinja2 tests.
plugin_globals_hook
```
from jinjanator_plugins import plugin_globals_hook
```
Decorator for registering custom global functions.
plugin_formats_hook
```
from jinjanator_plugins import plugin_formats_hook
```
Decorator for registering custom data format parsers.
plugin_extensions_hook
```
from jinjanator_plugins import plugin_extensions_hook
```
Decorator for registering Jinja2 extensions.
plugin_identities_hook
```
from jinjanator_plugins import plugin_identities_hook
```
Decorator for identifying the plugin.
Format
```
from jinjanator_plugins import Format
```
Protocol for defining custom format classes.

Quickstart

This example demonstrates how to create a minimal Jinjanator plugin that registers custom Jinja2 filters. It defines a `my_plugin.py` file using the `@plugin_filters_hook` decorator to expose 'scream' and 'reverse' filters. For Jinjanator to discover this plugin, it would typically be packaged as a Python project (e.g., using `pyproject.toml` with an entry-point) and installed into the same environment as `jinjanator`.

import os
from jinjanator_plugins import plugin_filters_hook

# my_plugin_example/pyproject.toml (illustrative, not run directly)
# [project]
# name = "jinjanator-my-plugin"
# version = "0.1.0"
# dependencies = [
#   "jinjanator-plugins==25.1.*", # Pinning recommended
# ]
#
# [project.entry-points."jinjanator.plugins"]
# my_plugin = "my_plugin_example.my_plugin"

# my_plugin_example/my_plugin.py

@plugin_filters_hook
def plugin_filters():
    """Registers custom Jinja2 filters."""
    def scream_filter(value):
        return str(value).upper() + "!!!"

    def reverse_filter(value):
        return str(value)[::-1]

    return {
        "scream": scream_filter,
        "reverse": reverse_filter,
    }

# Example usage within a Jinjanator template (template.j2) and CLI
# Assuming `my_plugin_example` is installed as a package and discoverable by jinjanator:
#
# template.j2:
# Hello {{ name | scream }}
# Message: {{ 'dlrow olleh' | reverse }}
#
# CLI command:
# $ jinjanate --data-var name="World" template.j2
# Output:
# Hello WORLD!!!
# Message: hello world

view raw JSON →