ChainGang

Tuple-style indexing for nested lists — obj[i, j, k] means obj[i][j][k] for get, set, and delete.

Overview

ChainGang exposes small class decorators that wrap __getitem__, __setitem__, and __delitem__ so that a tuple key walks nested containers in one step. Non-tuple keys (single indexes, slices) are passed through to the base type unchanged.

Python 3.10+. No runtime dependencies beyond the standard library.

Install

pip install chaingang

Install from source:

git clone https://github.com/eddiethedean/chaingang.git
cd chaingang
pip install .

Optional dev tools: pip install chaingang[testing]

Usage

Apply @selection_chaining to a class that already supports nested indexing (typically a list subclass). Then use comma-separated indices anywhere you would otherwise chain brackets.

from chaingang import selection_chaining


@selection_chaining
class ChainList(list):
    """Nested list with tuple indexing."""

    pass


cl = ChainList([[1, 2, 3], [4, 5, 6]])

# Read: tuple index equals chained brackets
assert cl[1, 2] == 6
assert cl[1][2] == 6

# Write
cl[1, 2] = 100
assert cl == [[1, 2, 3], [4, 5, 100]]

# Delete (here, remove the middle element of the inner row)
del cl[1, 1]
assert cl == [[1, 2, 3], [4, 100]]

You can compose the lower-level decorators if you only need one protocol, for example:

from chaingang.selection_chaining import getitem_chaining

ReadOnlyChain = getitem_chaining(list)

Import the combined decorator from the package root or from chaingang.selection_chaining.

Tuple keys and compatibility

In Python, obj[a, b] always passes key as the tuple (a, b). These decorators always treat a tuple key as a chain of lookups or updates. That matches nested lists (and similar sequence-like types).

Avoid using the decorators on types where a tuple is already a single valid key (for example dict with tuple keys, or NumPy-style indexing). Tuple keys are reserved for chaining and will not match the base mapping or array semantics.

An empty tuple () is rejected with TypeError (it would otherwise be meaningless for set/delete).

Type checkers

The package ships py.typed (PEP 561). Point mypy, Pyright, or other tools at your environment after pip install chaingang.

Development

pip install -r requirements_dev.txt
pytest
# or full lint + tests as in CI:
tox

Changelog and links

• CHANGELOG.md
• Repository
• Issue tracker
• PyPI

License

MIT — see LICENSE.