path-seeker

Find, count, and update keys anywhere in a nested dict or list of dicts — with full path disambiguation when the same key occurs at multiple depths.

Installation

pip install path-seeker

Usage

from path_seeker import PathSeeker

data = {
    "user": {
        "id": 1,
        "address": {"id": 42, "city": "Berlin"},
    },
    "orders": [
        {"id": 100, "status": "shipped"},
        {"id": 101, "status": "pending"},
    ],
}

seeker = PathSeeker(data)

# All values found under a key, at any depth
seeker.find_values("id")
# [1, 42, 100, 101]

# All (path, value) matches — use this to disambiguate duplicates
seeker.find_paths("id")
# [Match(path=['user', 'id'], value=1),
#  Match(path=['user', 'address', 'id'], value=42),
#  Match(path=['orders', 0, 'id'], value=100),
#  Match(path=['orders', 1, 'id'], value=101)]

# The first/last value found under a key, in traversal order
seeker.find_first_value("id")
# 1
seeker.find_last_value("id")
# 101

# The first/last (path, value) match found under a key, in traversal order
seeker.find_first_path("id")
# Match(path=['user', 'id'], value=1)
seeker.find_last_path("id")
# Match(path=['orders', 1, 'id'], value=101)

# Every distinct key name in the structure
seeker.get_keys()
# ['address', 'city', 'id', 'orders', 'status', 'user']

# How many times a key occurs
seeker.count_key("id")
# 4

# Whether a key occurs anywhere
seeker.has_key("id")
# True

# Update one exact occurrence, using a path from find_paths
seeker.set_value(["orders", 1, "status"], "cancelled")

# Update every occurrence of a key at once
seeker.update_values("id", 0)
# 4  (number of occurrences updated)

# Update just the first/last occurrence, in traversal order
seeker.update_first("id", -1)
# True
seeker.update_last("id", -2)
# True

# Delete every occurrence of a key
seeker.delete_key("status")
# 2  (number of occurrences deleted)

# Delete just the first/last occurrence, in traversal order
seeker.delete_first("id")
# True
seeker.delete_last("id")
# True

API

Search is by key name, not by value — searching for a value and getting its path back is not supported yet.

find_first_*/find_last_* raise UnknownKeyProvided when key doesn't occur anywhere; update_first/update_last/delete_first/delete_last/delete_key return False/0 instead, since "the key wasn't there" is an expected outcome for a write, not an error.

Limitations

• PathSeeker holds a reference to the structure you pass in — it does not make a defensive copy, so updates via set_value/update_values mutate your original object too.
• Nested dicts and lists are traversed; other iterables (tuples, sets, generators) are treated as opaque values, since list-index-style paths don't make sense for them.
• No cycle detection. This is fine for JSON/YAML-shaped data, which can't contain cycles, but a structure with a manually-introduced reference cycle will recurse forever.
• count_key, has_key, and get_keys do a full traversal on every call — there's no indexing or caching, so repeated calls on a large structure cost proportionally more each time.

Development

make install      # uv sync --all-extras
make check        # lint + typecheck + test (what CI runs)

Individual targets: make test, make lint, make format, make typecheck.

See CONTRIBUTING.md for the full workflow.

License

MIT — see LICENSE.