Registry / serialization / yamlpath

yamlpath

JSON →
library3.9.1pypypi✓ verified 84d ago

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.

pip install yamlpath
INSTALL
IMPORT
SIG · YAMLPATH
Y
yamlpath
serializationpythonv3.9.1
Install
2.0s avg
Import
121ms
Disk
20MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v3.9.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.910 runs
installs and imports cleanly · install 0.0s · import 0.124s · 21.3MB
glibc
py 3.103.910 runs
installs and imports cleanly · install 2.0s · import 0.117s · 22MB
20MB installed
● package 20MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

YAMLPath
from yamlpath import YAMLPath
Processor
from yamlpath.processor import Processor
YAMLPathException
from yamlpath.enums import YAMLPathException
from yamlpath.exceptions import YAMLPathException
Exceptions are primarily exposed via `yamlpath.enums` for consistent access, though they also exist in `yamlpath.exceptions`.

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())
yamlpath --version
Debug
Known issues
breakingSupport 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.
affects: 3.8.2 and newer
gotchaWhen 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.
affects: All versions using `ruamel.yaml`
gotchaWhen 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.
affects: 3.8.0 and newer
breakingFor 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.
affects: 3.9.0 and newer
Errors
Common errors & fixes
TypeError: 'collections.OrderedDict' object has no attribute 'insert'
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.
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'.
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.
Upgrade
Version history
3.9.1latest on PyPI · released May 2, 2026
Audit
Dependencies
ruamel.yamlrequiredCore dependency for YAML/JSON parsing and manipulation.
python-dateutilrequiredUsed for date/time object handling within YAML data.
Agent activity
42 hits · last 30 days
node
34
OpenAI (training)
1
Resources
yamlpath — pip install yamlpath · libregistry