ndindex

library1.10.1pypypi✓ verified 30d ago

ndindex is a Python library designed for representing and manipulating objects that can serve as valid indices for NumPy arrays, including slices, integers, ellipses, None, and integer/boolean arrays, and tuples containing these types. It provides a uniform API for these objects, ensuring correct semantics aligned with NumPy's `ndarray` indexing rules. The current version is 1.10.1, and it maintains an active release cadence with recent updates.

data serialization

pip install ndindex

package ↗homepage ↗

INSTALL

IMPORT

SIG · NDINDEX

ndindex

datapythonv1.10.1

Install

1.6s avg

Import

41ms

Disk

19MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.10.1 · 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

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.044s · 23MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.6s · import 0.038s · 20MB

19MB installed

● package 19MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

ndindex

✓ from ndindex import ndindex

✗ import ndindex

The primary API entry point is the `ndindex()` function, usually imported directly to convert Python index objects to ndindex objects. Direct `import ndindex` requires prefixing all calls, which is less common for this library's typical usage.

Slice

✓ from ndindex import Slice

✗ import ndindex.Slice

Classes like `Slice`, `Integer`, `Tuple` are typically imported directly for convenience, or accessed via `ndindex.Slice` if `ndindex` is imported as a module.

This quickstart demonstrates creating `ndindex` objects from basic Python indices, canonicalizing slices (both generally and for a specific array shape), and converting an `ndindex` object back into a raw Python index suitable for use with NumPy arrays. It highlights the `reduce()` method for canonicalization and `raw` attribute for NumPy compatibility.

import numpy as np from ndindex import ndindex, Slice, Tuple # Create an ndindex object from a Python slice idx_slice = ndindex(slice(1, 10, 2)) print(f"Ndindex from slice: {idx_slice}") # Canonicalize a slice (reduce to simplest form) canonical_slice = Slice(None, 10).reduce() print(f"Canonical slice: {canonical_slice}") # Canonicalize for a specific array shape shaped_slice = Slice(-5, 10, 2).reduce(12) print(f"Slice reduced for shape 12: {shaped_slice}") # Manipulate a tuple index tuple_idx = Tuple(0, slice(0, 5), None, 1) print(f"Tuple index: {tuple_idx}") # Get the raw Python index to use with NumPy np_array = np.arange(20).reshape(2, 10) raw_index = tuple_idx.raw print(f"Raw Python index: {raw_index}") # Use the raw index with a NumPy array try: indexed_array = np.arange(100).reshape(10, 10)[raw_index] # Example with a 2D array print(f"Indexed array shape: {indexed_array.shape}") except IndexError as e: print(f"Indexing with {raw_index} failed due to: {e}")

Debug

Known issues

gotchandindex objects assume that indexing will not raise an `IndexError`. Operations like `reduce()` and transformations do not validate against array bounds; they assume the index is valid for *some* array. Users must handle `IndexError` when applying `ndindex.raw` to an actual NumPy array. [1, 4, 6, 8]

fix

Always use `try-except IndexError` blocks when applying `idx.raw` to a NumPy array if out-of-bounds indexing is a possibility. Perform explicit bounds checking if needed before constructing the `ndindex` object if strict validation is required.

affects: All versions

gotchaBy default, `ndindex` class constructors (e.g., `Slice(None, 10)`) only perform basic type checking and do not canonicalize the index. This means `Slice(None, 10)` is not strictly equal to `Slice(0, 10, 1)` by default. [1, 4, 8]

fix

To canonicalize an index or reduce it to its simplest equivalent form, you must explicitly call the `.reduce()` method on the `ndindex` object (e.g., `Slice(None, 10).reduce()`). If comparing two indices for equivalence over a specific array shape, use `idx1.reduce(shape) == idx2.reduce(shape)` rather than `idx1 == idx2`. [1, 4]

affects: All versions

gotchaDirect `==` comparison between `ndindex` objects performs exact equality checking, which might not reflect if two indices actually refer to the same elements in an array. For instance, `Slice(0, 10)` and `Slice(None, 10)` are not equal with `==`. [1]

fix

To check if two `ndindex` objects are equivalent in terms of the elements they would select from an array, first call their `.reduce()` method, optionally with an array `shape` argument if the context is known. Then compare the reduced objects: `idx1.reduce(shape) == idx2.reduce(shape)`. [1]

affects: All versions

Errors

Common errors & fixes

IndexError: only integers, slices (`:`), ellipsis (`...`), numpy.newaxis (`None`) and integer or boolean arrays are valid indices

This error occurs when an `ndindex` object is used directly to index a NumPy array without converting it to a 'raw' NumPy-compatible index. The NumPy array expects native index types, not `ndindex` wrapper objects.

fix

Access the underlying NumPy-compatible index by using the `.raw` attribute of the `ndindex` object (e.g., `array[idx.raw]`).

TypeError: 'Tuple' object is not subscriptable

An `ndindex.Tuple` object is being treated like a native Python tuple by attempting to access its elements using square brackets (e.g., `idx[0]`). `ndindex` objects do not support direct subscripting in this manner for their internal components.

fix

To access the individual index objects within an `ndindex.Tuple`, use the `.args` attribute (which returns the `ndindex` types) or `.raw` (which returns the raw Python types for indexing, e.g., `idx.raw[0]`).

AttributeError: 'numpy.ndarray' object has no attribute 'index'

This error arises when trying to use the built-in Python `list.index()` method on a NumPy `ndarray` object. NumPy arrays do not have an `index` method like Python lists.

fix

To find the indices of specific values in a NumPy array, use `numpy.where()` (e.g., `np.where(array == value)`).

TypeError: 'float' object cannot be interpreted as an integer

This commonly occurs when a floating-point number is provided in a context that strictly expects an integer, such as when using it directly as an array index or as an argument to functions like `range()`.

fix

Explicitly convert the floating-point number to an integer using `int()` before using it as an index or in functions that require integer arguments (e.g., `array[int(float_index)]`).

Upgrade

Version history

1.10.1latest on PyPI · released Nov 19, 2025

Audit

Dependencies

numpyrequiredCore functionality relies on concepts and types from NumPy for array indexing.

Agent activity

11 hits · last 30 days

node

Resources

packagehttps://pypi.org/project/ndindex/ ↗

homepagehttps://quansight-labs.github.io/ndindex/ ↗