DictPath

0.5.0 · active · verified Wed Apr 15

DictPath provides an object-oriented way to navigate and manipulate nested dictionaries using path-like expressions. It allows for robust and type-safe access to dictionary values, supporting various path syntaxes and advanced traversal features. The current stable version is 0.5.0, with a release cadence that has recently seen significant updates focused on API enhancements and performance.

Warnings

breaking Version 0.5.0 and later now require Python 3.8+. Previous versions (0.1.x) supported Python 2.7 and a broader range of Python 3 versions. Applications on older Python versions must update their environment or stick to `dictpath<0.5.0`.
Fix: Upgrade your Python environment to 3.8 or newer. If not possible, downgrade dictpath to a version compatible with your Python interpreter (e.g., `pip install 'dictpath<0.5.0'` for Python 3.5-3.7 compatibility with older releases).
breaking The `BaseAccessor` class was replaced by `NodeAccessor` in the 0.5.0 release series (specifically from 0.5.0a3). Direct usage or subclassing of `BaseAccessor` will lead to `NameError` or `ImportError`.
Fix: Update imports and code references from `BaseAccessor` to `NodeAccessor`. Consult the 0.5.0 documentation for the new `NodeAccessor` API.
breaking The `AccessorPath` class became generic in the 0.5.0 release series (specifically from 0.5.0a3). This change primarily affects type hints and advanced usage involving generics, potentially breaking existing type annotations or specific instantiation patterns.
Fix: Review and update type annotations for `AccessorPath` instances. While basic usage might remain functional, type checkers will flag incompatibilities. Refer to the 0.5.0 documentation for updated typing guidance.
gotcha Version 0.5.0 introduced "Expanded parsing and typing guarantees," which might mean stricter validation of path strings. Paths that were previously tolerated but ambiguous or malformed might now raise errors.
Fix: Ensure your path strings adhere strictly to documented formats. Test existing paths thoroughly after upgrading to 0.5.0 to catch any new parsing exceptions. Consult the `dictpath` documentation for specific parsing rules.

Install

pip install dictpath Install stable version

Imports

AccessorPath
```
from dictpath import AccessorPath
```

Quickstart

This quickstart demonstrates creating an AccessorPath object and using it to read values from a nested dictionary. It covers basic dot notation, accessing list elements, and using the new subscriptable accessor syntax introduced in 0.5.0. It also shows how to provide a default value for missing paths.

from dictpath import AccessorPath

data = {
    'user': {
        'profile': {
            'name': 'Alice',
            'age': 30,
            'contact': [
                {'type': 'email', 'value': 'alice@example.com'},
                {'type': 'phone', 'value': '123-456-7890'}
            ]
        }
    }
}

# Create a path accessor
path = AccessorPath('user.profile.name')

# Read a value
name = path.read_value(data)
print(f"User name: {name}")

# Access a nested list item
email_path = AccessorPath('user.profile.contact.0.value')
email = email_path.read_value(data)
print(f"User email: {email}")

# Using subscriptable accessors (0.5.0+)
phone_path = AccessorPath('user')['profile']['contact'][1]['value']
phone = phone_path.read_value(data)
print(f"User phone: {phone}")

# Getting a default value if path doesn't exist
missing_path = AccessorPath('user.profile.address')
address = missing_path.read_value(data, default='No address provided')
print(f"User address: {address}")

view raw JSON →