Registry / serialization / yamlpath

yamlpath

JSON →
library3.9.1pypypi✓ verified 89d 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.9–3.13
musl
3.9–3.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.10–3.910 runs
installs and imports cleanly · install 0.0s · import 0.124s · 21.3MB
glibc
py 3.10–3.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
50 hits · last 30 days
node
40
Anthropic
1
OpenAI (training)
1
Resources