jinjyaml package

Application specific tag of Jinja2 template in PyYAML.

It may be useful if you only want to render special tag nodes in the document, instead of whole YAML string as a template.

class jinjyaml.Constructor

Bases: object

Constructor class for jinja2.Template YAML tags.

When parsing YAML string, the class constructs template tags to Data objects.

Add the constructor to PyYAML Loader as below:

import yaml
import jinjyaml as jy

ctor = jy.Constructor()

# Attention: tag name starts with "!"

# Add to default loader
yaml.add_constructor("!j2", ctor)
# or: Add to CLoader
yaml.add_constructor("!j2", ctor, yaml.CLoader)
# or: Add to SafeLoader
yaml.add_constructor("!j2", ctor, yaml.SafeLoader)
# or: Add to other Loaders ...

Attention

  • Custom YAML tag starts with "!". When we invoke yaml.add_constructor, the tag parameter MUST have a single "!" at the beginning.

  • Content of the tag MUST be text

class jinjyaml.Data(source: str)

Bases: object

A PyYAML Custom tag stores string source of a jinja2.Template object.

Parameters:

source (str)

source: str

Source code of jinja2.Template object

jinjyaml.extract(obj: Any, loader_type: Type[_Loader | _CLoader], env: jinja2.Environment | None = None, context: Mapping[str, Any] | None = None, inplace: bool = False) → Any

Recursively render and parse template tag objects in a YAML doc-tree.

Parameters:

  • obj (Any) –

    Object like list or dictionary contains Data instances.

    It may be:

    • A mapping or sequence object returned by PyYAML Loader.

      In this case, the function does:

      1. Recursively search inside obj for Data objects.

      2. Render Data.source as string source of jinja2.Template of each found Data object.

      3. Parse the rendered string with the PyYAML Loader who loads obj.

      4. Return the whole obj with Data objects replaced with corresponding parsed Python object.

    • A single Data object.

      In this case, the function does:

      1. Render it’s Data.source() as string source of jinja2.Template.

      2. Parse the rendered string with the PyYAML Loader who loads obj.

      3. Return the parsed Python object.

    • Other scalar objects returned by a PyYAML Loader:

      In this case, the function directly returns obj with noting changed.

  • loader_type (Type[Union[_Loader, _CLoader]]) – The PyYAML Loader who loads obj

  • env (Optional[jinja2.Environment]) – Jinja2 environment for template rendering.

  • context (Optional[Mapping[str, Any]]) – Variables name-value pairs for Jinja2 template rendering.

  • inplace (bool) –

    Whether to make an in-place replacement on Data objects inside obj.

    • When True: In-place replace every Data object with corresponding parsed Python object inside the passed-in obj.

    • When False (default): render and parse every Data object with corresponding parsed Python object, without modify the passed-in object.

    Tip

    The obj must be a mutable dict or list like object if inplace is True.

    Note

    When the passed-in obj argument is an instance of Data, it won’t be changed, even inplace was set to True. But if there was a mutable dict or list like object pared by YAML loader, which has cascade Data in it, the cascade part would be replaced. However, return value is just the parsed result.

Returns:

Final extracted Python object

Return type:

Any

class jinjyaml.Representer(tag: str)

Bases: object

Representer for jinja2.Template tags.

When dumping an object into YAML string, convert Data to string.

Add the representer to PyYAML Dumper as below:

representer = jinjyaml.Representer("j2")  # No "!" here !!!
yaml.add_representer(Node, representer)
Parameters:

tag (str)

tag: str

YAML tag name for include statement

Attention

Custom YAML tag’s name starts with "!". But we MUST NOT put a "!" at the beginning here, because yaml.add_representer() will add the symbol itself.

Submodules