{"id":4753,"library":"ruamel-yaml-jinja2","title":"ruamel.yaml.jinja2","description":"ruamel.yaml.jinja2 is a plugin for ruamel.yaml that enables pre- and post-processing of Jinja2 templates within YAML files. This allows YAML files containing Jinja2 constructs to be loaded, modified as YAML, and then dumped back while preserving the Jinja2 templating. The current version is 0.2.7, released in September 2021, indicating a slow release cadence or maintenance mode.","status":"maintenance","version":"0.2.7","language":"en","source_language":"en","source_url":"https://pypi.org/project/ruamel-yaml-jinja2/","tags":["yaml","jinja2","templating","parser","round-trip"],"install":[{"cmd":"pip install 'ruamel.yaml[jinja2]'","lang":"bash","label":"Recommended installation"},{"cmd":"pip install ruamel-yaml-jinja2","lang":"bash","label":"Direct package installation"}],"dependencies":[{"reason":"Core dependency for YAML parsing and round-trip preservation, this package is an extension.","package":"ruamel.yaml","optional":false},{"reason":"Required for templating functionality.","package":"Jinja2","optional":false}],"imports":[{"note":"The 'jinja2' functionality is enabled by passing typ='jinja2' to the YAML constructor, not a direct import from ruamel.yaml.jinja2.","symbol":"YAML","correct":"from ruamel.yaml import YAML"}],"quickstart":{"code":"import sys\nfrom ruamel.yaml import YAML\n\nyaml_str = \"\"\"\n- {{ name }}: \"{% include 'ethnicity.jinja2' with context %}\"\n  age: 43\nhobbies: {% include 'hobbies.jinja2' with context %}\n\"\"\"\n\nyaml = YAML(typ='jinja2')\nyaml.preserve_quotes = True\n\ndata = yaml.load(yaml_str)\ndata[0]['age'] = 18\n\nyaml.dump(data, sys.stdout)\n","lang":"python","description":"This quickstart demonstrates loading a YAML string that contains Jinja2 directives. It then modifies a value within the loaded data structure and dumps it back to `stdout`, preserving the Jinja2 template elements. It is crucial to use `YAML(typ='jinja2')` to enable the pre- and post-processing and use the *same* `YAML` instance for both loading and dumping."},"warnings":[{"fix":"Always use the *same* `YAML(typ='jinja2')` instance for both `load()` and `dump()` operations on a given YAML document.","message":"Using different `YAML(typ='jinja2')` instances for loading and dumping will result in an `AttributeError` because the instance used for loading stores crucial internal information required for the subsequent dumping process.","severity":"breaking","affected_versions":"All versions"},{"fix":"Simplify complex Jinja2 constructs within YAML or comment them out before loading if they are not meant to be processed by `ruamel.yaml.jinja2` for modification, or preprocess the data to make the YAML valid before loading.","message":"Certain complex Jinja2 constructs, especially those that result in invalid YAML when not rendered (e.g., `{{- with ... }}` on a line of its own, or undocumented `jinja2` constructs), may not be handled correctly by `ruamel.yaml.jinja2` and might require manual pre-processing or lead to unexpected parsing errors.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always install `ruamel.yaml.jinja2` as an extra feature of `ruamel.yaml` using `pip install 'ruamel.yaml[jinja2]'`.","message":"The installation command `pip install ruamel.yaml[jinja2]` is the recommended way to ensure `ruamel.yaml.jinja2` is correctly integrated with `ruamel.yaml`. Direct installation of `ruamel-yaml-jinja2` might not set up the necessary plugin mechanism correctly, leading to unexpected behavior or an inability to use `typ='jinja2'`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Monitor `ruamel.yaml`'s official documentation for updates on its package name and installation procedures, especially if upgrading `ruamel.yaml` to a major new version.","message":"The `ruamel.yaml` project, which `ruamel.yaml.jinja2` extends, has discussed potential breaking changes regarding its PyPI package name to comply with PEP 625 (possibly changing to `ruamel_yaml`). While this specific plugin is not directly affected by a name change, its core dependency might experience installation or import path changes in the future, although `ruamel.yaml` has indicated they are trying to avoid this for older versions.","severity":"deprecated","affected_versions":"Future versions of ruamel.yaml (potential)"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}