Nested Lookup

0.2.25 · maintenance · verified Wed Apr 15

Nested-lookup is a Python library providing functions for working with deeply nested documents, typically a mix of dictionaries and lists, often derived from JSON, YAML, or XML. It simplifies tasks like performing key lookups, updating values, deleting keys, and altering values within these complex structures. The library is currently at version 0.2.25, with its last release in July 2022, indicating a maintenance cadence rather than active rapid development.

Warnings

gotcha Functions like `nested_update`, `nested_delete`, and `nested_alter` return a modified copy of the document by default. To mutate the original document in place, you must explicitly pass `in_place=True`. Failing to do so can lead to confusion if you expect the original object to change.
Fix: For in-place modification, use `nested_function(document, ..., in_place=True)`. Otherwise, assign the returned value to a new variable: `new_document = nested_function(document, ...)`.
gotcha The official GitHub repository (`russellballestrini/nested-lookup`) has been archived and redirects to a GitLab instance (`https://git.unturf.com/python/nested-lookup/`). Users looking for the source code or contributing might initially go to the outdated GitHub link.
Fix: Refer to the GitLab repository (`https://git.unturf.com/python/nested-lookup/`) for the most current source and project information.
gotcha The `wild` argument in `nested_lookup` treats the given key as a case-insensitive substring. This can lead to broader matches than intended if an exact, case-sensitive key lookup is desired.
Fix: Only use `wild=True` when case-insensitive substring matching is explicitly required. For exact key matches, ensure `wild` is `False` (which is the default).
gotcha The library's last release was in July 2022. While functional, this indicates a slower development pace, and new features or bug fixes might not be released frequently. Users should consider this for long-term project planning or if specific, unaddressed issues arise.
Fix: Review the GitLab repository's commit history for recent activity or consider contributing if specific enhancements are needed.

Install

pip install nested-lookup Install with pip

Imports

nested_lookup
```
from nested_lookup import nested_lookup
```
nested_update
```
from nested_lookup import nested_update
```
nested_delete
```
from nested_lookup import nested_delete
```

Quickstart

This quickstart demonstrates how to use `nested_lookup` to find values, `nested_update` to change values, and `nested_delete` to remove keys from a deeply nested document. It also highlights the `in_place` argument for mutation.

from nested_lookup import nested_lookup, nested_update, nested_delete

document = [
    {'taco': 42},
    {
        'salsa': [
            {'burrito': {'taco': 69}},
            {'nachos': 100}
        ]
    },
    {'drink': {'soda': 'coke'}}
]

# Lookup a key
tacos = nested_lookup('taco', document)
print(f"Found tacos: {tacos}")
# Expected: Found tacos: [42, 69]

# Update a value (returns a copy by default)
updated_document = nested_update(document, key='burrito', value='test_burrito_update')
print(f"Updated document (copy): {updated_document[1]['salsa'][0]}")
# Expected: Updated document (copy): {'burrito': 'test_burrito_update'}

# Delete a key (returns a copy by default)
deleted_document = nested_delete(document, 'taco')
print(f"Document after deleting 'taco' (copy): {deleted_document[0]}, {deleted_document[1]['salsa'][0]}")
# Expected: Document after deleting 'taco' (copy): {}, {'burrito': {'taco': 69}} (Note: original 'taco' in burrito is not deleted here as the key 'taco' at the top level of the inner dict is not directly deleted.)

# Demonstrate in_place update
print(f"Original document before in_place update: {document[0]}")
nested_update(document, key='taco', value='new_taco_val', in_place=True)
print(f"Original document after in_place update: {document[0]}")
# Expected: Original document after in_place update: {'taco': 42}\nOriginal document after in_place update: {'taco': 'new_taco_val'}

view raw JSON →