YAMLPath

3.9.0 · active · verified Fri Apr 17

YAMLPath is a Python library and collection of command-line tools for powerful, intuitive manipulation of YAML, JSON, and compatible data. It provides get, set, merge, validate, scan, convert, and diff processors using a command-line friendly path syntax. The library is actively maintained with frequent releases, currently at version 3.9.0, supporting modern Python versions.

Common errors

```
TypeError: 'collections.OrderedDict' object has no attribute 'insert'
```
cause Attempting to update bare Python `dict` or `collections.OrderedDict` data structures directly, which lack the `insert` method required by `ruamel.yaml` for certain operations. This was partially removed and then restored in 3.6.9 but still indicates a mismatch if not using `ruamel.yaml` objects.

fix Always load YAML/JSON data using `ruamel.yaml.YAML().load()` to ensure `ruamel.yaml`'s enhanced data structures (e.g., `ruamel.yaml.comments.CommentedMap`) are used, which support the necessary methods.
```
Command 'yaml-merge' with Array/Array-of-Hash data in RHS causes interminable loop or maxed CPU.
```
cause A bug (Issue #220) in `yaml-merge` where novel `mergeat` paths with Array or Array-of-Hash data in the right-hand-side (RHS) document could lead to an infinite loop.

fix Upgrade `yamlpath` to version 3.8.1 or newer, where this bug was resolved.
```
Package 'yamlpath' is missing required ruamel.yaml patch 'yamlpath.patches.timestamp'.
```
cause Version 3.6.6 shipped with a broken package that unexpectedly omitted a critical `ruamel.yaml` patch.

fix Do not use `yamlpath` version 3.6.6. Upgrade to 3.6.7 or newer to get the corrected package.

Warnings

breaking Support for Python 3.6 was dropped. Python 3.7 support is 'tepid' and not fully guaranteed. Users on these versions must upgrade Python or pin an older `yamlpath` version.
Fix: Upgrade Python to 3.8+ (3.10+ recommended) or downgrade `yamlpath` to <3.8.2.
gotcha When using `ruamel.yaml` (which `yamlpath` relies on), YAML timestamp values are often forced to UTC during loading, potentially stripping original timezone information.
Fix: Be aware of this behavior when dealing with timezone-specific timestamps. If original timezone is critical, custom pre/post-processing may be needed.
gotcha When outputting JSON via command-line tools like `yaml-set` or `yaml-merge`, the default output is a single-line document. For pretty-printed JSON, a specific option is required.
Fix: Use the `--json-indent` or `-J` option with an integer value (e.g., `--json-indent 2`) to specify the indentation level for JSON output.
breaking For developers using EYAML integration, Ruby 3.3 is now the minimum supported version for development due to end-of-life status of older Ruby versions. This mainly affects testing and development environments.
Fix: Ensure your development environment uses Ruby 3.3 or newer if you are working with EYAML.

Install

pip install yamlpath Install latest version

Imports

YAMLPath
```
from yamlpath import YAMLPath
```

Processor

from yamlpath.processor import Processor

YAMLPathException
wrong:
```
from yamlpath.exceptions import YAMLPathException
```
correct:
```
from yamlpath.enums import YAMLPathException
```
Exceptions are primarily exposed via `yamlpath.enums` for consistent access, though they also exist in `yamlpath.exceptions`.

Quickstart

This quickstart demonstrates how to load YAML data using `ruamel.yaml`, create `YAMLPath` objects for specific nodes, and then use `Processor` to get, set, and append values within the data structure. A logger is required for `Processor`.

import io
from ruamel.yaml import YAML
from yamlpath import YAMLPath
from yamlpath.processor import Processor
import logging

# Configure a basic logger (required by Processor)
logger = logging.getLogger()
logger.setLevel(logging.INFO)

yaml_data = """
config:
  name: My App
  version: 1.0.0
  features:
    - auth
    - logging
  settings:
    debug: false
"""

# Load YAML data
yaml = YAML()
data = yaml.load(io.StringIO(yaml_data))

# Initialize Processor with the data and logger
processor = Processor(logger, data)

# Example 1: Get a value
path_to_name = YAMLPath("$.config.name")
for value, parent, key in processor.get_nodes(path_to_name):
    print(f"Current config name: {value}")

# Example 2: Set a value
path_to_version = YAMLPath("$.config.version")
processor.set_value(path_to_version, "1.1.0")
print(f"Set config version to 1.1.0")

# Example 3: Add an item to a list
path_to_features = YAMLPath("$.config.features")
processor.append_value(path_to_features, "analytics")
print(f"Added 'analytics' to features")

# Output the modified YAML
output_stream = io.StringIO()
yaml.dump(data, output_stream)
print("\nModified YAML:\n" + output_stream.getvalue())

view raw JSON →