JinjaFiles

JinjaRope supports a TOML file format to define the environment. This includes all filters, functions and tests as well as the environment configuration (strip_blocks etc.) and loaders.

A jinjarope.JinjaFile looks like this:

[filters.name_of_filter]
fn: "mylibrary.some_filter"
group: "text"

[tests.name_of_test]
fn: "mylibrary.some_test"
group: "text"

[functions.name_of_function]
fn: "mylibrary.some_function"
group: "text"

[[loaders]]
type = "fsspec"
fs = "github://"

[config]
strip_blocks = True
...

These TOML files can be used to define an environment in a declarative way and can be combined as needed.

JinjaRope itself contains separate definition files for the jinja2-builtin filters / tests and the JinjaRope filters / tests. The jinja2-definition files are only used for documenation (that way the documenation contains all filters / tests, so no need to juggle between different docs), the JinjaRope definition files will also get loaded by the jinjarope environment.

JinjaFiles can get added to Environments easily via jinjarope.Environment.load_jinja_file.

In the following part the different sections of the TOML file will get explained.

Defining filters

 # define a filter with a unique name

[filters.name_of_filter]
fn: "mylibrary.some_function"  # dotted path to the callable.
group: "text"  # used for the documentation
description: # additional description
aliases: ["e"]  # for adding shortcuts / aliases
required_packages: ["my_package"]  # will only add filter / test when given package is installed

# define an example for the docs
[filters.name_of_filter.examples.some_identifier]
title = "Example title"
description = "Some explanation text"
template = """
{ { some jinja example } }
"""
...

Defining tests

[tests.name_of_test]
... #  same fields as for filters

Defining functions

[functions.name_of_function]
... #  same fields as for filters

Defining loaders

Every loader defined in TOML requires a type (either "filesystem", "package", "fsspec", "fsspec_protocol", "nested_dict" or "config_file"), which is mapped to a corresponding loader class. Every futher keyword - value pair is passed to the constructor of the corresponding loader.

[[loaders]]
type = "filesystem"
searchpath = "path/to/template/folder"

# we can define multiple loaders, this will result in a combined ChoiceLoader.

[[loaders]]
type = "fsspec"
fs = "github://phil65:jinjarope@main"

[[loaders]]
type = "package"
package = "jinjarope"

Pay attention to the double brackets, that´s how lists are defined in TOML!

Defining the environment config

These are all available options for the environment. Refer to the jinja2 docs for more information.

[config]
trim_blocks = ...
block_start_string = ...
block_end_string = ...
variable_start_string = ...
variable_end_string = ...
comment_start_string = ...
comment_end_string = ...
line_statement_prefix = ...
line_comment_prefix = ...
trim_blocks = ...
lstrip_blocks = ...
newline_sequence = ...
keep_trailing_newline = ...
...