google-deepmind/nested

google-deepmind/nested

Description: A Python library for easy access and manipulation of nested data structures.

Language: Python

License: Apache-2.0

Stars: 1

Forks: 0

Open issues: 0

Created: 2026-05-18T16:16:42Z

Pushed: 2026-05-19T08:55:12Z

Default branch: master

Fork: no

Archived: no

README:

Nested

A Python library for easy access and manipulation of nested data structures.

nested treats Python objects as trees: containers (dict, list, tuple, namedtuple, dataclass, attrs) form the nodes and everything else forms the leaves. It provides a concise, dot-separated field-path syntax (e.g. 'a.1.bar') for accessing, checking, updating, adding, removing, and comparing elements at arbitrary depth — without writing chains of brackets and attribute lookups by hand.

Installation

pip install gdm-nested

Quick Start

import collections
import nested

MyTuple = collections.namedtuple('MyTuple', ['foo', 'bar'])
obj = {
'a': [1, (2, 3, 4)],
'b': MyTuple(foo='f', bar='b'),
}

# Access deeply nested values with a dot-separated path.
nested.access_field(obj, 'a.0') # → 1
nested.access_field(obj, 'a.1.2') # → 4
nested.access_field(obj, 'b.bar') # → 'b'

# Check if a path exists.
nested.check_field(obj, 'a.0') # → True
nested.check_field(obj, 'a.99') # → False

# Update (or upsert) a value.
nested.update_field(obj, 'b.foo', 'g')
# → {'a': [1, (2, 3, 4)], 'b': MyTuple(foo='g', bar='b')}

# Remove a field and get the popped value.
obj2, popped = nested.remove_field(obj, 'b')
# obj2 → {'a': [1, (2, 3, 4)]}
# popped → MyTuple(foo='f', bar='b')

Supported Container Types

nested recognises the following types as tree nodes:

| Type | Description | |---|---| | dict | Any dict subclass, collections.OrderedDict, collections.defaultdict, ml_collections.ConfigDict | | list | Any list instance | | tuple | Plain tuples (not namedtuples) | | namedtuple | Any tuple-like class with a _fields attribute | | dataclass | Any dataclasses.dataclass instance | | attrs | Any attr.s / attrs.define instance |

Everything else is treated as an opaque leaf.

> Note: Sequences and custom containers are only recognised as structures > when derived from dict or list.

Field Path Syntax

Fields are specified as dot-separated strings, tuples, or single keys:

# All of these are equivalent:
nested.access_field(obj, 'a.1.2')
nested.access_field(obj, ('a', 1, 2))
nested.access_field(obj, ('a', '1', '2'))

• String keys address dict keys and namedtuple/dataclass/attrs field names.
• Integer keys address list and tuple indices (including negative indices).

Comparison with dm-tree

At first glance, nested might seem similar to google-deepmind/tree, as both operate on nested Python structures (dictionaries, lists, tuples). However, they solve entirely different problems and are highly complementary.

• `tree` is for Transformation: It focuses on applying operations across the

entirety of a nested structure. You use tree when you want to map a function over every leaf node (tree.map_structure), flatten a complex structure into a 1D list (tree.flatten), or verify that two structures have the same exact shape.

• `nested` is for Navigation and Access: It focuses on traversal and

targeting. tree lacks utilities to easily grab a specific value deep inside a structure without manual indexing. nested provides the tools to safely and cleanly query, extract, and navigate to specific paths within complex, heavily-nested objects.

Rule of thumb: If you need to multiply every number in a nested dictionary by 2, use tree. If you need to safely extract a specific configuration value buried five levels deep in that dictionary, use nested.

API Reference

Accessing Fields

access_field(nested_obj, field)

Returns the value at the given field path.

nested.access_field({'x': [10, 20]}, 'x.1') # → 20

access_fields(nested_obj, fields)

Returns a list of values for multiple field paths.

nested.access_fields({'x': 1, 'y': 2}, ['x', 'y']) # → [1, 2]

get(nested_obj, field, value=None)

Like access_field, but returns a default value instead of raising when the field does not exist.

nested.get({'x': 1}, 'y', 'default') # → 'default'

---

Checking Fields

check_field(nested_obj, field)

Returns True if the field path exists.

nested.check_field({'x': [1]}, 'x.0') # → True
nested.check_field({'x': [1]}, 'x.5') # → False

check_fields(nested_obj, fields)

Returns a list of booleans for multiple field paths.

all(nested.check_fields(obj, ['a', 'b'])) # True if both exist

---

Updating Fields

update_field(nested_obj, field, value)

Replaces the value if the field exists, or inserts it if it doesn't (upsert).

nested.update_field({'x': 1}, 'x', 2) # → {'x': 2}
nested.update_field({'x': 1}, 'y', 2) # → {'x': 1, 'y': 2}

update_fields(nested_obj, *field_value_tuples, **field_value_kwargs)

Batch update/upsert multiple fields at once.

nested.update_fields({'a': 1}, ('b', 2), c=3) # → {'a': 1, 'b': 2, 'c': 3}

---

Replacing Fields

replace_field(nested_obj, field, value)

Like update_field, but raises `KeyError` if the field does not already exist.

nested.replace_field({'x': 1}, 'x', 2) # → {'x': 2}

nested.replace_field({'x': 1}, 'y', 2)
# raises KeyError: '"y" field not in structure.'

nested.replace_field({'x': {'z': 1}}, 'x.y', 2)
# raises KeyError: '"y" field not in structure.'

replace_fields(nested_obj, *field_value_tuples, **field_value_kwargs)

Batch version of replace_field.

---

Adding Fields

add_field(nested_obj, field, value)

Like update_field, but raises `KeyError` if the field already exists.

nested.add_field({'x': 1}, 'y', 2) # → {'x': 1, 'y': 2}

# raises KeyError: '"x" field already in structure.'
nested.add_field({'x': 1}, 'x', 2)

add_fields(nested_obj, *field_value_tuples, **field_value_kwargs)

Batch version of add_field.

> Note: For sequences, elements are *inserted* at the given index. Order > matters — additions are applied sequentially.

---

Removing Fields

remove_field(nested_obj, field, *, default=...)

Removes a field and returns a `(modified_obj,…