# Library for Jinja2 Template Extensions
[](https://github.com/jenisys/jinja2-library/actions/workflows/test.yml)
[](https://pypi.python.org/pypi/jinja2-library)
[](https://github.com/jenisys/jinja2-library/blob/main/LICENSE)
Provides a library functionality for [Jinja2] extensions that can be used in templates.
FEATURES:
* Provides a `library` concept for [Jinja2] extensions,
like [filters], [tests], [globals] and [directives] (aka: `extensions`),
* Declarative approach to describe and register [Jinja2] extensions.
* Simplifies how `library` items are registered in an `Environment` (in one step).
* Supports own namespace/scope for each library.
* Supports control over registered names.
## EXAMPLE 1: Basic Example
```python
# -- FILE: example/hello.py
from jinja2_library import Library
import jinja2.ext
this_library = Library()
register = this_library.make_register_decorator()
@register.filter
def hello(value, greeting=None):
greeting = greeting or "Hello"
return u"{greeting} {name}".format(greeting=greeting, name=value)
class LibraryExtension(jinja2.ext.Extension):
"""Simplifies to use ``this_library`` as Jinja2 extension."""
def __init__(self, environment):
super(LibraryExtension, self).__init__(environment)
this_library.add_to_environment(environment)
```
The template library can be used by using the `LibraryExtension` class in [Jinja2]:
```python
# -- FILE: use_template_library_hello.py
# USING: example.hello.LibraryExtension
from jinja2 import Environment
from assertpy import assert_that
this_extension = "example.hello.LibraryExtension"
this_template = "HELLO: {{ this.name|hello(greeting=this.greeting) }}"
this_data = dict(name="Alice", greeting="Ciao")
environment = Environment(extensions=[this_extension])
template = environment.from_string(this_template)
this_text = template.render(this=this_data)
assert_that(this_text).is_equal_to("HELLO: Ciao Alice")
```
## API
### Library class
The `Library` constructor provides the following parameter:
| Parameter | Type | Default | Description |
|-----------|--------------------|---------|---------------------------------------|
| `scope` | `Optional[string]` | `None` | Scope/namespace for registered items. |
* The `scope` parameter allows to provide a namespace for the registered `Library` items.
* This prevents name collisions if many filters/tests/globals are used.
* Simplifies the registration of filters/tests/globals/extensions into an `Environment`.
EXAMPLE:
```python
# -- FILE: example/scoped_hello.py
from jinja2_library import Library
import jinja2.ext
this_library = Library("foo.bar") # -- HINT: Library with scope="foo.bar".
register = this_library.make_register_decorator()
@register.filter(name="hello")
def hello_filter(value, greeting=None):
greeting = greeting or "Hello"
return u"{greeting} {name}".format(greeting=greeting, name=value)
class LibraryExtension(jinja2.ext.Extension):
def __init__(self, environment):
super(LibraryExtension, self).__init__(environment)
this_library.add_to_environment(environment)
```
Scoped library names can then be used inside a template, like:
```jinja
{#- FILE: template.jinja -#}
{#- USING: extensions=["example.scoped_hello.LibraryExtension"] -#}
HELLO: {{ this.name|foo.bar.hello(greeting="Ciao") }}
```
### Register Decorators
This Python package provides the following [decorators] (in the context of the example above):
| Register Decorator | Description |
|:----------------------|:--------------------------------------------------------------------|
| `@register.filter` | Register a [Jinja2 filter] function to `this_library`. |
| `@register.test` | Register a [Jinja2 test] predicate function to `this_library`. |
| `@register.global_` | Register a [Jinja2 global] function or variable to `this_library`. |
| `@register.extension` | Register a [Jinja2 extension] class (aka: `jinja2.ext.Extension`). |
The function [decorators] for `@register.filter/test/global_` support optional parameters.
These optional decorator parameters are:
| Parameter | Type | Default | Description |
|:----------|:-------------------|:------------------|:----------------------------------|
| `name` | `string` | `{function.name}` | Name of the `filter/test/global`. |
| `aliases` | `sequence<string>` | `EMPTY_SEQUENCE` | List of alternative names. |
Background Info
-------------------------------------------------------------------------------
Inspired by the [Django template library] approach.
History
-------------------------------------------------------------------------------
* INITIALLY CREATED AS: `simplegen.template_lib`
* REFACTORING: Extracted into own standalone package to simplify reuse
with [Jinja2] template engine.
----
[decorators]: https://peps.python.org/pep-0318/
[Jinja2]: https://github.com/pallets/jinja/
[Jinja2 filter]: https://jinja.palletsprojects.com/en/stable/api/#custom-filters
[Jinja2 test]: https://jinja.palletsprojects.com/en/stable/api/#custom-tests
[Jinja2 global]: https://jinja.palletsprojects.com/en/stable/api/#the-global-namespace
[Jinja2 directive]: https://jinja.palletsprojects.com/en/stable/templates/#extensions
[Django template library]: https://docs.djangoproject.com/en/5.2/howto/custom-template-tags/
[filters]: https://jinja.palletsprojects.com/en/stable/api/#custom-filters
[tests]: https://jinja.palletsprojects.com/en/stable/api/#custom-tests
[globals]: https://jinja.palletsprojects.com/en/stable/api/#the-global-namespace
[directives]: https://jinja.palletsprojects.com/en/stable/templates/#extensions
Raw data
{
"_id": null,
"home_page": "https://github.com/jenisys/jinja2-library",
"name": "jinja2-library",
"maintainer": null,
"docs_url": null,
"requires_python": "!=3.0.*,!=3.1.*,!=3.2.*,!=3.3.*,!=3.4.*,>=2.7",
"maintainer_email": null,
"keywords": "Jinja2, jinja2, template-extensions",
"author": "Jens Engel",
"author_email": "Jens Engel <jenisys@noreply.github.com>",
"download_url": "https://files.pythonhosted.org/packages/96/72/0a85c6d7f6f247e14f551659deac1758b3cffa7f3c43e1d4f168c1ce3772/jinja2_library-0.5.1.tar.gz",
"platform": "any",
"description": "# Library for Jinja2 Template Extensions\n\n[](https://github.com/jenisys/jinja2-library/actions/workflows/test.yml)\n[](https://pypi.python.org/pypi/jinja2-library)\n[](https://github.com/jenisys/jinja2-library/blob/main/LICENSE)\n\nProvides a library functionality for [Jinja2] extensions that can be used in templates.\n\nFEATURES:\n\n* Provides a `library` concept for [Jinja2] extensions,\n like [filters], [tests], [globals] and [directives] (aka: `extensions`),\n* Declarative approach to describe and register [Jinja2] extensions.\n* Simplifies how `library` items are registered in an `Environment` (in one step).\n* Supports own namespace/scope for each library.\n* Supports control over registered names.\n\n## EXAMPLE 1: Basic Example\n\n```python\n# -- FILE: example/hello.py\nfrom jinja2_library import Library\nimport jinja2.ext\n\nthis_library = Library()\nregister = this_library.make_register_decorator()\n\n@register.filter\ndef hello(value, greeting=None):\n greeting = greeting or \"Hello\"\n return u\"{greeting} {name}\".format(greeting=greeting, name=value)\n\nclass LibraryExtension(jinja2.ext.Extension):\n \"\"\"Simplifies to use ``this_library`` as Jinja2 extension.\"\"\"\n def __init__(self, environment):\n super(LibraryExtension, self).__init__(environment)\n this_library.add_to_environment(environment)\n```\n\nThe template library can be used by using the `LibraryExtension` class in [Jinja2]:\n\n```python\n# -- FILE: use_template_library_hello.py\n# USING: example.hello.LibraryExtension\nfrom jinja2 import Environment\nfrom assertpy import assert_that\n\nthis_extension = \"example.hello.LibraryExtension\"\nthis_template = \"HELLO: {{ this.name|hello(greeting=this.greeting) }}\"\nthis_data = dict(name=\"Alice\", greeting=\"Ciao\")\n\nenvironment = Environment(extensions=[this_extension])\ntemplate = environment.from_string(this_template)\nthis_text = template.render(this=this_data)\nassert_that(this_text).is_equal_to(\"HELLO: Ciao Alice\")\n```\n\n## API\n\n### Library class\n\nThe `Library` constructor provides the following parameter:\n\n| Parameter | Type | Default | Description |\n|-----------|--------------------|---------|---------------------------------------|\n| `scope` | `Optional[string]` | `None` | Scope/namespace for registered items. |\n\n* The `scope` parameter allows to provide a namespace for the registered `Library` items.\n* This prevents name collisions if many filters/tests/globals are used.\n* Simplifies the registration of filters/tests/globals/extensions into an `Environment`.\n\nEXAMPLE:\n\n```python\n# -- FILE: example/scoped_hello.py\nfrom jinja2_library import Library\nimport jinja2.ext\n\nthis_library = Library(\"foo.bar\") # -- HINT: Library with scope=\"foo.bar\".\nregister = this_library.make_register_decorator()\n\n@register.filter(name=\"hello\")\ndef hello_filter(value, greeting=None):\n greeting = greeting or \"Hello\"\n return u\"{greeting} {name}\".format(greeting=greeting, name=value)\n\nclass LibraryExtension(jinja2.ext.Extension):\n def __init__(self, environment):\n super(LibraryExtension, self).__init__(environment)\n this_library.add_to_environment(environment)\n```\n\nScoped library names can then be used inside a template, like:\n\n```jinja\n{#- FILE: template.jinja -#}\n{#- USING: extensions=[\"example.scoped_hello.LibraryExtension\"] -#}\nHELLO: {{ this.name|foo.bar.hello(greeting=\"Ciao\") }}\n```\n\n### Register Decorators\n\nThis Python package provides the following [decorators] (in the context of the example above):\n\n| Register Decorator | Description |\n|:----------------------|:--------------------------------------------------------------------|\n| `@register.filter` | Register a [Jinja2 filter] function to `this_library`. |\n| `@register.test` | Register a [Jinja2 test] predicate function to `this_library`. |\n| `@register.global_` | Register a [Jinja2 global] function or variable to `this_library`. |\n| `@register.extension` | Register a [Jinja2 extension] class (aka: `jinja2.ext.Extension`). |\n\nThe function [decorators] for `@register.filter/test/global_` support optional parameters.\nThese optional decorator parameters are:\n\n| Parameter | Type | Default | Description |\n|:----------|:-------------------|:------------------|:----------------------------------|\n| `name` | `string` | `{function.name}` | Name of the `filter/test/global`. |\n| `aliases` | `sequence<string>` | `EMPTY_SEQUENCE` | List of alternative names. |\n\n\nBackground Info\n-------------------------------------------------------------------------------\n\nInspired by the [Django template library] approach.\n\n\nHistory\n-------------------------------------------------------------------------------\n\n* INITIALLY CREATED AS: `simplegen.template_lib`\n* REFACTORING: Extracted into own standalone package to simplify reuse\n with [Jinja2] template engine.\n\n----\n\n[decorators]: https://peps.python.org/pep-0318/\n[Jinja2]: https://github.com/pallets/jinja/\n[Jinja2 filter]: https://jinja.palletsprojects.com/en/stable/api/#custom-filters\n[Jinja2 test]: https://jinja.palletsprojects.com/en/stable/api/#custom-tests\n[Jinja2 global]: https://jinja.palletsprojects.com/en/stable/api/#the-global-namespace\n[Jinja2 directive]: https://jinja.palletsprojects.com/en/stable/templates/#extensions\n[Django template library]: https://docs.djangoproject.com/en/5.2/howto/custom-template-tags/\n\n[filters]: https://jinja.palletsprojects.com/en/stable/api/#custom-filters\n[tests]: https://jinja.palletsprojects.com/en/stable/api/#custom-tests\n[globals]: https://jinja.palletsprojects.com/en/stable/api/#the-global-namespace\n[directives]: https://jinja.palletsprojects.com/en/stable/templates/#extensions\n",
"bugtrack_url": null,
"license": null,
"summary": "Library functionality for Jinja2 extensions",
"version": "0.5.1",
"project_urls": {
"Download": "https://pypi.org/project/jinja2-library",
"Homepage": "https://github.com/jenisys/jinja2-library",
"Issues": "https://github.com/jenisys/jinja2-library/issues/",
"Repository": "https://github.com/jenisys/jinja2-library"
},
"split_keywords": [
"jinja2",
" jinja2",
" template-extensions"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "c7c50fa7926cb38e18b207cc0b7ddaa56b0046670710996b34f6852abdff3f46",
"md5": "74d4fde9c0103b18751afbc7be6db047",
"sha256": "b3259bda08d7cd72628761d521682c04899a3ade8d73f7fd41627583c75577a8"
},
"downloads": -1,
"filename": "jinja2_library-0.5.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "74d4fde9c0103b18751afbc7be6db047",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "!=3.0.*,!=3.1.*,!=3.2.*,!=3.3.*,!=3.4.*,>=2.7",
"size": 8211,
"upload_time": "2025-08-11T20:31:49",
"upload_time_iso_8601": "2025-08-11T20:31:49.911183Z",
"url": "https://files.pythonhosted.org/packages/c7/c5/0fa7926cb38e18b207cc0b7ddaa56b0046670710996b34f6852abdff3f46/jinja2_library-0.5.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "96720a85c6d7f6f247e14f551659deac1758b3cffa7f3c43e1d4f168c1ce3772",
"md5": "b6798efc9f87c37c51ed794c443ca66f",
"sha256": "6ae80dbf25ae15c278e20f24db9fecce075e378d31e83871f36624be07730962"
},
"downloads": -1,
"filename": "jinja2_library-0.5.1.tar.gz",
"has_sig": false,
"md5_digest": "b6798efc9f87c37c51ed794c443ca66f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "!=3.0.*,!=3.1.*,!=3.2.*,!=3.3.*,!=3.4.*,>=2.7",
"size": 17093,
"upload_time": "2025-08-11T20:31:51",
"upload_time_iso_8601": "2025-08-11T20:31:51.273948Z",
"url": "https://files.pythonhosted.org/packages/96/72/0a85c6d7f6f247e14f551659deac1758b3cffa7f3c43e1d4f168c1ce3772/jinja2_library-0.5.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-11 20:31:51",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "jenisys",
"github_project": "jinja2-library",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "jinja2-library"
}
JSON
