Install & Compatibility
Where this runs
tested against v0.2.25 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.014s · 19.4MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 2.5s · import 0.012s · 20MB
17MB installed
● package 17MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
nested_lookup
✓ from nested_lookup import nested_lookup
nested_update
✓ from nested_lookup import nested_update
nested_delete
✓ from nested_lookup import nested_delete
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'}
Debug
Known issues
gotchaFunctions 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.fixFor in-place modification, use `nested_function(document, ..., in_place=True)`. Otherwise, assign the returned value to a new variable: `new_document = nested_function(document, ...)`.
affects: All versions
gotchaThe 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.fixRefer to the GitLab repository (`https://git.unturf.com/python/nested-lookup/`) for the most current source and project information.
affects: All versions since July 2022
gotchaThe `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.fixOnly use `wild=True` when case-insensitive substring matching is explicitly required. For exact key matches, ensure `wild` is `False` (which is the default).
affects: All versions
gotchaThe 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.fixReview the GitLab repository's commit history for recent activity or consider contributing if specific enhancements are needed.
affects: 0.2.25 and older
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'nested_lookup'
The `nested-lookup` library is not installed in the current Python environment or the import statement is incorrect.
fixEnsure the library is installed using pip: `pip install nested-lookup`. Then, import functions from the `nested_lookup` module, for example: `from nested_lookup import nested_lookup`.
IndexError: list index out of range
The `nested_lookup` function returns an empty list (`[]`) when the specified key is not found in the document, and the user attempts to access an element from this empty list (e.g., `result[0]`).
fixAlways check if the returned list is not empty before attempting to access its elements, or provide a default value. For example:
```python
from nested_lookup import nested_lookup
document = {'a': {'b': 1}}
results = nested_lookup('c', document)
if results:
value = results
print(value)
else:
print("Key not found or list is empty")
``` KeyError: 'some_missing_key'
This occurs when `nested_lookup` successfully returns a sub-dictionary (within a list), but then the user attempts to access a non-existent key within that specific returned dictionary without handling potential `KeyError`.
fixWhen processing dictionaries obtained from `nested_lookup` (which are typically elements within the returned list), use the `.get()` method with a default value, or check for key existence before accessing. For example:
```python
from nested_lookup import nested_lookup
document = {'data': [{'item': {'id': 101, 'name': 'widget'}}, {'item': {'id': 102}}]}
# Look for 'item' key
items = nested_lookup('item', document)
for item_dict in items:
# Safely access 'name' using .get()
name = item_dict.get('name', 'N/A')
print(f"Item Name: {name}")
``` AttributeError: 'list' object has no attribute 'get'
The `nested_lookup` function always returns a list of matching values. If the user mistakenly assumes it returns a single dictionary or value and attempts to call dictionary-specific methods like `.get()` directly on the returned list, this error occurs.
fixRemember that `nested_lookup` returns a list. If you expect a single dictionary, access the first element of the list (after checking if the list is not empty) and then apply dictionary methods to that element. If multiple matches are possible, iterate through the list. For example:
```python
from nested_lookup import nested_lookup
document = {'config': {'setting1': 'value1', 'setting2': 'value2'}}
# Correct: results is a list
results = nested_lookup('config', document)
if results and isinstance(results, dict):
config_dict = results
value = config_dict.get('setting1', 'default_value')
print(f"Setting1: {value}")
else:
print("Config key not found or not a dictionary")
``` Upgrade
Version history
0.2.25latest on PyPI · released Jul 6, 2022
Audit
Dependencies
No dependency data recorded yet.