OTIT

Object Traversal & Inspection Toolkit

OTIT is a small, typed, dependency-free Python library for navigating, inspecting, and modifying heterogeneous nested Python objects.

It provides a consistent path-based API for working with mappings, sequences, object attributes, and structures containing a mixture of all three.

Installation

pip install otit

Requires Python 3.10 or later.

Quick start

import otit

data = {
    "users": [
        {
            "name": "Matti",
            "address": {
                "city": "Oulu",
            },
        }
    ]
}

otit.get(data, "users.0.name")
# "Matti"

otit.get(data, "users.0.address.city")
# "Oulu"

otit.has(data, "users.0.email")
# False

Paths can also be given explicitly as sequences:

otit.get(data, ("users", 0, "name"))
# "Matti"

Explicit paths are useful when a mapping key contains a dot or when preserving the exact type of a path segment matters.

data = {"foo.bar": "value"}

otit.get(data, ("foo.bar",))
# "value"

Getting values

Use get() to resolve a path:

otit.get(data, "users.0.name")
# "Matti"

A default can be returned when the path does not exist:

otit.get(data, "users.0.email", default=None)
# None

Without a default, an unresolved path raises otit.PathNotFound.

Checking paths

Use has() to test whether a path can be resolved:

otit.has(data, "users.0.name")
# True

otit.has(data, "users.0.email")
# False

Setting values

Use set() to modify an existing value:

otit.set(data, "users.0.name", "Liisa")

By default, the complete path must already exist.

Set create=True to allow creation of the final mapping key or object attribute:

otit.set(
    data,
    "users.0.email",
    "liisa@example.com",
    create=True,
)

create=True does not create missing parent containers or extend sequences.

Deleting values

Use delete() to remove a value:

otit.delete(data, "users.0.address.city")

For mappings, the key is removed. For mutable sequences, the item is removed and subsequent indexes shift. For objects, the attribute is deleted.

Walking objects

walk() recursively yields every reachable child together with its path:

data = {
    "user": {
        "name": "Matti",
        "tags": ["admin", "active"],
    }
}

list(otit.walk(data))

produces:

[
    (("user",), {"name": "Matti", "tags": ["admin", "active"]}),
    (("user", "name"), "Matti"),
    (("user", "tags"), ["admin", "active"]),
    (("user", "tags", 0), "admin"),
    (("user", "tags", 1), "active"),
]

Traversal paths use tuples. Sequence indexes are represented as integers.

The root object itself is not yielded.

Finding values

Use find() to select reachable values with a predicate:

list(
    otit.find(
        data,
        lambda value: isinstance(value, str) and value.startswith("M"),
    )
)

The result contains (path, value) pairs.

Listing paths

Use paths() to iterate over every reachable path:

list(otit.paths(data))

For example:

[
    ("user",),
    ("user", "name"),
    ("user", "tags"),
    ("user", "tags", 0),
    ("user", "tags", 1),
]

Finding leaves

Use leaves() to iterate over terminal values:

list(otit.leaves(data))

For example:

[
    (("user", "name"), "Matti"),
    (("user", "tags", 0), "admin"),
    (("user", "tags", 1), "active"),
]

Empty mappings and sequences are not considered leaves.

Picking values

pick() creates a new structure containing only selected paths:

data = {
    "user": {
        "name": "Matti",
        "email": "matti@example.com",
        "password": "secret",
    }
}

otit.pick(
    data,
    "user.name",
    "user.email",
)

returns:

{
    "user": {
        "name": "Matti",
        "email": "matti@example.com",
    }
}

Selected sequence items are compacted while preserving their original order.

The original object is not modified.

Omitting values

omit() creates a copy with selected paths removed:

otit.omit(
    data,
    "user.password",
)

returns:

{
    "user": {
        "name": "Matti",
        "email": "matti@example.com",
    }
}

All omitted paths refer to the original object. This means removing sequence items does not change the meaning of other paths passed in the same call.

The original object is not modified.

Path semantics

A path may be a dot-separated string:

"users.0.address.city"

or an explicit sequence:

("users", 0, "address", "city")

OTIT resolves each segment according to the object currently being traversed:

• Mappings use the segment as a mapping key.
• Sequences interpret the segment as an integer index.
• Other objects use string segments as attribute names.
• Strings, bytes, and bytearrays are treated as terminal values rather than traversable sequences.
• Negative sequence indexes are supported.
• Numeric-looking mapping keys remain mapping keys.

For example:

data = {
    "lookup": {
        "0": "zero",
    },
    "items": [
        "first",
    ],
}

otit.get(data, "lookup.0")
# "zero"

otit.get(data, "items.0")
# "first"

The meaning of "0" depends on the object being traversed.

Root paths

The empty string and empty tuple represent the root object:

otit.get(data, "") is data
# True

otit.has(data, ())
# True

Operations that require a target below the root, such as set(), delete(), pick(), and omit(), reject a root path with otit.InvalidPath.

Exceptions

OTIT exposes a small exception hierarchy:

OtitError
├── PathNotFound
└── InvalidPath

PathNotFound is raised when OTIT cannot resolve a requested path.

InvalidPath is raised when a path is structurally invalid for the requested operation.

Exceptions raised by user-defined properties or other object behavior are not converted into PathNotFound.

Cycles and shared objects

Traversal functions detect cycles and do not recursively follow the same object through an active ancestor path.

Shared objects reachable through different paths are still traversed independently.

Supported objects

OTIT is designed for heterogeneous structures containing:

• mappings such as dict
• sequences such as list and tuple
• regular Python objects
• dataclass instances
• mixtures of the above

Mutation requires the underlying object to support the requested operation.

API

otit.get(obj, path, *, default=...)
otit.has(obj, path)

otit.set(obj, path, value, *, create=False)
otit.delete(obj, path)

otit.walk(obj)
otit.find(obj, predicate)
otit.paths(obj)
otit.leaves(obj)

otit.pick(obj, *paths)
otit.omit(obj, *paths)

Development

Install development dependencies:

uv sync

Run the test suite:

uv run pytest

Run linting:

uv run ruff check .

Run type checking:

uv run mypy src

Build the package:

uv build

License

OTIT is licensed under the GNU General Public License v3.0 or later (GPL-3.0-or-later).

See the LICENSE file for the full license text.