philiprehberger-dotpath 0.4.0

Access and mutate deeply nested dicts using dot-notation paths

philiprehberger-dotpath

Access and mutate deeply nested dicts using dot-notation paths.

Installation

pip install philiprehberger-dotpath

Usage

from philiprehberger_dotpath import (
    get, set, has, delete, flatten, unflatten, pop, merge, paths, search,
)

data = {"users": [{"name": "Alice", "email": "[e-mail]"}]}

# Get a value
get(data, "users[0].name")        # "Alice"

# Get with default
get(data, "users[0].phone", default=None)  # None

# Set a value (creates intermediate dicts)
set(data, "users[0].address.city", "Berlin")

# Check existence
has(data, "users[0].address.city")  # True

# Delete a key
delete(data, "users[0].address.city")

Wildcards

data = {"users": [{"email": "[e-mail]"}, {"email": "[e-mail]"}]}

get(data, "users[*].email")  # ["[e-mail]", "[e-mail]"]

# Set a field on all items
set(data, "users[*].active", True)
# data["users"] == [{"email": "[e-mail]", "active": True}, {"email": "[e-mail]", "active": True}]

# Delete a field from all items
delete(data, "users[*].active")

Negative Indexing

data = {"items": [{"name": "a"}, {"name": "b"}, {"name": "c"}]}

get(data, "items[-1].name")      # "c"
set(data, "items[-2].name", "B") # updates second-to-last

Pop

data = {"a": {"b": 1, "c": 2}}

pop(data, "a.b")               # 1  (key removed)
pop(data, "a.missing", default=0)  # 0  (no error)

Merge

data = {"config": {"db": {"host": "localhost", "port": 3306}}}

merge(data, "config.db", {"port": 5432, "name": "mydb"})
# data["config"]["db"] == {"host": "localhost", "port": 5432, "name": "mydb"}

Search

data = {"a": 1, "b": {"c": 2, "d": [10, 20]}}

search(data, lambda v: isinstance(v, int) and v > 5)
# ["b.d[0]", "b.d[1]"]

List All Paths

paths() is a lazy iterator over every leaf path — the keys of flatten() without materialising the dict.

data = {"a": {"b": 1}, "c": [10, 20]}

list(paths(data))
# ["a.b", "c[0]", "c[1]"]

# Useful for streaming over very large structures
for p in paths(huge_config):
    print(p)

Flatten and Unflatten

nested = {"a": {"b": {"c": 1}}, "d": [10, 20]}

flatten(nested)
# {"a.b.c": 1, "d[0]": 10, "d[1]": 20}

unflatten({"a.b.c": 1, "d[0]": 10, "d[1]": 20})
# {"a": {"b": {"c": 1}}, "d": [10, 20]}

Listing keys and counting leaves

data = {"a": {"b": 1}, "c": 2}

keys(data)            # ["a.b", "c"]
keys(data, depth=1)   # ["a", "c"]

count({"a": 1, "b": {"c": 2, "d": 3}})  # 3
count({"a": []})                         # 0  (empty containers don't count)

API

Function	Description
get(data, path, *, default=_MISSING)	Get value at dot path; raises KeyError if missing and no default
set(data, path, value)	Set value at dot path, creating intermediate dicts; supports wildcards
delete(data, path)	Delete the key at dot path; supports wildcards
has(data, path) -> bool	Check whether a path exists
pop(data, path, *, default=_MISSING)	Remove and return value at path; like dict.pop()
merge(data, path, value)	Deep-merge a dict into the dict at path
search(data, predicate) -> list[str]	Find all dot-paths where predicate(value) is True
paths(data, *, separator=".") -> Iterator[str]	Lazy iterator over every leaf path
flatten(data, *, separator=".") -> dict	Flatten nested dict to single level
unflatten(data, *, separator=".") -> dict	Restore flattened dict to nested structure
keys(data, depth=None) -> list[str]	List all dot-paths, optionally capped at depth
count(data) -> int	Total leaf count (non-dict, non-list values)

Development

pip install -e .
python -m pytest tests/ -v

Support

If you find this project useful:

⭐ Star the repo

🐛 Report issues

💡 Suggest features

❤️ Sponsor development

🌐 All Open Source Projects

💻 GitHub Profile

🔗 LinkedIn Profile

License

MIT