{"id":10363,"library":"yamlpath","title":"YAMLPath","description":"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.","status":"active","version":"3.9.0","language":"en","source_language":"en","source_url":"https://github.com/wwkimball/yamlpath","tags":["yaml","json","data processing","cli","configuration","data manipulation","pathing"],"install":[{"cmd":"pip install yamlpath","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Core dependency for YAML/JSON parsing and manipulation.","package":"ruamel.yaml","optional":false},{"reason":"Used for date/time object handling within YAML data.","package":"python-dateutil","optional":false}],"imports":[{"symbol":"YAMLPath","correct":"from yamlpath import YAMLPath"},{"symbol":"Processor","correct":"from yamlpath.processor import Processor"},{"note":"Exceptions are primarily exposed via `yamlpath.enums` for consistent access, though they also exist in `yamlpath.exceptions`.","wrong":"from yamlpath.exceptions import YAMLPathException","symbol":"YAMLPathException","correct":"from yamlpath.enums import YAMLPathException"}],"quickstart":{"code":"import io\nfrom ruamel.yaml import YAML\nfrom yamlpath import YAMLPath\nfrom yamlpath.processor import Processor\nimport logging\n\n# Configure a basic logger (required by Processor)\nlogger = logging.getLogger()\nlogger.setLevel(logging.INFO)\n\nyaml_data = \"\"\"\nconfig:\n  name: My App\n  version: 1.0.0\n  features:\n    - auth\n    - logging\n  settings:\n    debug: false\n\"\"\"\n\n# Load YAML data\nyaml = YAML()\ndata = yaml.load(io.StringIO(yaml_data))\n\n# Initialize Processor with the data and logger\nprocessor = Processor(logger, data)\n\n# Example 1: Get a value\npath_to_name = YAMLPath(\"$.config.name\")\nfor value, parent, key in processor.get_nodes(path_to_name):\n    print(f\"Current config name: {value}\")\n\n# Example 2: Set a value\npath_to_version = YAMLPath(\"$.config.version\")\nprocessor.set_value(path_to_version, \"1.1.0\")\nprint(f\"Set config version to 1.1.0\")\n\n# Example 3: Add an item to a list\npath_to_features = YAMLPath(\"$.config.features\")\nprocessor.append_value(path_to_features, \"analytics\")\nprint(f\"Added 'analytics' to features\")\n\n# Output the modified YAML\noutput_stream = io.StringIO()\nyaml.dump(data, output_stream)\nprint(\"\\nModified YAML:\\n\" + output_stream.getvalue())\n","lang":"python","description":"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`."},"warnings":[{"fix":"Upgrade Python to 3.8+ (3.10+ recommended) or downgrade `yamlpath` to <3.8.2.","message":"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.","severity":"breaking","affected_versions":"3.8.2 and newer"},{"fix":"Be aware of this behavior when dealing with timezone-specific timestamps. If original timezone is critical, custom pre/post-processing may be needed.","message":"When using `ruamel.yaml` (which `yamlpath` relies on), YAML timestamp values are often forced to UTC during loading, potentially stripping original timezone information.","severity":"gotcha","affected_versions":"All versions using `ruamel.yaml`"},{"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.","message":"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.","severity":"gotcha","affected_versions":"3.8.0 and newer"},{"fix":"Ensure your development environment uses Ruby 3.3 or newer if you are working with EYAML.","message":"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.","severity":"breaking","affected_versions":"3.9.0 and newer"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"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.","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.","error":"TypeError: 'collections.OrderedDict' object has no attribute 'insert'"},{"fix":"Upgrade `yamlpath` to version 3.8.1 or newer, where this bug was resolved.","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.","error":"Command 'yaml-merge' with Array/Array-of-Hash data in RHS causes interminable loop or maxed CPU."},{"fix":"Do not use `yamlpath` version 3.6.6. Upgrade to 3.6.7 or newer to get the corrected package.","cause":"Version 3.6.6 shipped with a broken package that unexpectedly omitted a critical `ruamel.yaml` patch.","error":"Package 'yamlpath' is missing required ruamel.yaml patch 'yamlpath.patches.timestamp'."}]}