Python Benedict

0.35.0 · active · verified Sat Apr 11

python-benedict is a `dict` subclass that enhances the standard Python dictionary with powerful features like keylist, keypath, and keyattr support. It provides normalized I/O operations for various data formats (including base64, csv, ini, json, pickle, plist, query-string, toml, xls, xml, yaml) and numerous utility methods. It is currently active, with its latest version being 0.35.0, and maintains a regular release cadence.

Warnings

breaking Version 0.34.0 dropped official support for Python 3.8 and 3.9. Users on these versions should remain on an earlier `python-benedict` release or upgrade their Python interpreter.
Fix: Upgrade Python to 3.10 or newer, or pin `python-benedict<0.34.0`.
breaking In version 0.34.0, the `keylist` feature was fixed to work only with actual lists, addressing previous backward-compatibility issues with standard `dict` behavior. If you previously relied on non-list iterables for keylist operations, your code may break.
Fix: Ensure that arguments passed for keylist access are strictly `list` types.
gotcha When casting an existing `dict` to a `benedict` instance, if the original dictionary's keys contain the default keypath separator ('.'), a `ValueError` may be raised.
Fix: Either choose a custom keypath separator by passing `keypath_separator='_'` (or another suitable character) to the `benedict` constructor, or disable keypath functionality with `keypath=False` if not needed. Alternatively, sanitize keys in the original dictionary.
gotcha As of version 0.32.1, the `items()` and `values()` methods return `benedict` instances (or `list` of `benedict` instances for values) rather than standard `dict_items` or `dict_values` objects. This might affect type checks or expected iteration behavior.
Fix: Adjust code to expect `benedict` instances from `items()` and `values()`, or explicitly cast results to `dict` if standard `dict` behavior is strictly required.

Install

pip install python-benedict Core package
pip install "python-benedict[all]" All features and I/O formats

Imports

benedict
```
from benedict import benedict
```

Quickstart

This example demonstrates creating a `benedict` instance, accessing and setting values using both keypath (dot notation) and keylist (list of keys), and serializing the dictionary to a JSON string.

from benedict import benedict

# Create a benedict instance from a dictionary
data = {
    "user": {
        "profile": {
            "name": "Alice",
            "email": "alice@example.com"
        },
        "id": 123
    },
    "settings": {
        "theme": "dark"
    }
}
d = benedict(data)

# Access values using keypath (dot notation)
print(f"User Name: {d['user.profile.name']}")

# Set values using keypath
d['user.profile.age'] = 30
print(f"User Age: {d.get('user.profile.age')}")

# Access using keylist (list of keys)
print(f"User ID: {d[['user', 'id']]}")

# Output to JSON string
json_output = d.to_json(indent=2)
print("\nJSON Output:")
print(json_output)

view raw JSON →