jinjyaml package

Submodules

• jinjyaml.constructor module
  • Constructor
• jinjyaml.data module
  • Data
    • Data.source
• jinjyaml.functions module
  • extract()
• jinjyaml.representer module
  • Representer
    • Representer.tag

Module contents

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 a YAML string, this class constructs template tags into Data objects.

To add the constructor to a PyYAML loader, use the following code:

import yaml
import jinjyaml as jy

ctor = jy.Constructor()

# Note: Tag names start 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 tags must start with "!". When invoking yaml.add_constructor, the tag parameter must include a single leading "!".

• The content of the tag must be text.

class jinjyaml.Data(source: str)

Bases: object

A custom PyYAML tag that stores the string source of a jinja2.Template object.

Parameters:

source (str)

source: str

The source code of the 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 document tree.

This function processes an object that may contain Data instances, such as lists or dictionaries. It can handle the following types of input:

• A mapping or sequence object returned by a PyYAML Loader:

  1. Recursively searches for Data objects within obj.

  2. Renders the Data.source attribute as a string source for a jinja2.Template.

  3. Parses the rendered string using the same PyYAML Loader that loaded obj.

  4. Returns the entire obj with Data objects replaced by their corresponding parsed Python objects.

• A single Data object:

  1. Renders its Data.source attribute as a string source for a jinja2.Template.

  2. Parses the rendered string using the same PyYAML Loader that loaded obj.

  3. Returns the parsed Python object.

• Other scalar objects returned by a PyYAML Loader:

  Directly returns obj without any changes.

Note

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

• If obj is an instance of Data, it will not be changed, even if inplace is set to True.

  However, nested Data objects within mutable structures will still be replaced.

• The return value is always the parsed result.

Parameters:

• obj (Any) – An object that may contain Data instances.

• loader_type (Type[Union[_Loader, _CLoader]]) – The PyYAML Loader used to load obj.

• env (Optional[jinja2.Environment]) – The jinja2.Environment for template rendering (optional).

• context (Optional[Mapping[str, Any]]) – A dictionary of variable name-value pairs for jinja2 template rendering (optional).

• inplace (bool) –

  Whether to perform an in-place replacement of Data objects within obj.

  • When True: Replaces every Data object with its corresponding parsed Python object within the passed-in obj.

  • When False (default): Renders and parses every Data object with its corresponding parsed Python object without modifying the passed-in object.

Returns:

The final parsed and extracted Python object.

Return type:

Any

class jinjyaml.Representer(tag: str)

Bases: object

Representer for jinja2.Template tags.

When dumping an object into a YAML string, this class converts Data objects to their string representation.

To add the representer to a PyYAML dumper, use the following code:

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

Attention

• The tag name passed to the Representer constructor MUST NOT include the leading “!”. This is because PyYAML automatically adds the “!” when registering the representer.

• Ensure that Node is the correct type for the objects you want to represent.

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.