{"id":4587,"library":"jinjanator-plugins","title":"Jinjanator Plugins API","description":"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.","status":"active","version":"25.1.0","language":"en","source_language":"en","source_url":"https://github.com/kpfleming/jinjanator-plugins","tags":["plugin","jinja2","templating","cli","api"],"install":[{"cmd":"pip install jinjanator-plugins","lang":"bash","label":"Install `jinjanator-plugins`"}],"dependencies":[{"reason":"Build-time dependency for packages that implement plugins using this API.","package":"setuptools","optional":true},{"reason":"Used for compatibility with older Python versions, though newer versions require Python 3.10+.","package":"typing-extensions","optional":true}],"imports":[{"note":"Decorator for registering custom Jinja2 filters.","symbol":"plugin_filters_hook","correct":"from jinjanator_plugins import plugin_filters_hook"},{"note":"Decorator for registering custom Jinja2 tests.","symbol":"plugin_tests_hook","correct":"from jinjanator_plugins import plugin_tests_hook"},{"note":"Decorator for registering custom global functions.","symbol":"plugin_globals_hook","correct":"from jinjanator_plugins import plugin_globals_hook"},{"note":"Decorator for registering custom data format parsers.","symbol":"plugin_formats_hook","correct":"from jinjanator_plugins import plugin_formats_hook"},{"note":"Decorator for registering Jinja2 extensions.","symbol":"plugin_extensions_hook","correct":"from jinjanator_plugins import plugin_extensions_hook"},{"note":"Decorator for identifying the plugin.","symbol":"plugin_identities_hook","correct":"from jinjanator_plugins import plugin_identities_hook"},{"note":"Protocol for defining custom format classes.","symbol":"Format","correct":"from jinjanator_plugins import Format"}],"quickstart":{"code":"import os\nfrom jinjanator_plugins import plugin_filters_hook\n\n# my_plugin_example/pyproject.toml (illustrative, not run directly)\n# [project]\n# name = \"jinjanator-my-plugin\"\n# version = \"0.1.0\"\n# dependencies = [\n#   \"jinjanator-plugins==25.1.*\", # Pinning recommended\n# ]\n#\n# [project.entry-points.\"jinjanator.plugins\"]\n# my_plugin = \"my_plugin_example.my_plugin\"\n\n# my_plugin_example/my_plugin.py\n\n@plugin_filters_hook\ndef plugin_filters():\n    \"\"\"Registers custom Jinja2 filters.\"\"\"\n    def scream_filter(value):\n        return str(value).upper() + \"!!!\"\n\n    def reverse_filter(value):\n        return str(value)[::-1]\n\n    return {\n        \"scream\": scream_filter,\n        \"reverse\": reverse_filter,\n    }\n\n# Example usage within a Jinjanator template (template.j2) and CLI\n# Assuming `my_plugin_example` is installed as a package and discoverable by jinjanator:\n#\n# template.j2:\n# Hello {{ name | scream }}\n# Message: {{ 'dlrow olleh' | reverse }}\n#\n# CLI command:\n# $ jinjanate --data-var name=\"World\" template.j2\n# Output:\n# Hello WORLD!!!\n# Message: hello world\n","lang":"python","description":"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`."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=24.2.0"},{"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.*`).","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"breaking","affected_versions":">=23.4.0"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}