nptyping

What it is and what it does

nptyping adds type-hint support for NumPy arrays and pandas DataFrames, letting you annotate array shape, dtype, and structure in your code. It works with standard Python type hints (e.g., `NDArray[Shape["2, 2"], Int]`) so type checkers like MyPy can validate your code statically. Beyond static checking, it also provides runtime validation through `isinstance()` checks and an `assert_isinstance()` helper, so you can verify that actual arrays match their declared types at runtime—catching shape mismatches, dtype errors, or structural inconsistencies.

The package handles NumPy's structured arrays, record arrays, and pandas DataFrames with a concise syntax. It depends only on typing-extensions and numpy, making it lightweight to add to existing projects. However, maintenance is dormant (last release February 2023), so it receives no active updates or bug fixes.

Use it for:

• Add type hints to NumPy array function signatures so IDEs and MyPy can catch shape/dtype mismatches before runtime.
• Validate that incoming arrays match expected structure (shape, dtype, field names) using runtime isinstance checks.
• Document the expected structure of pandas DataFrames in function signatures for better code clarity.
• Catch accidental type errors in numerical computing pipelines by asserting array properties at key points.
• Express complex structured arrays (with named fields and nested shapes) in a readable, type-checkable form.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Provides type hints and runtime type checking for NumPy arrays and pandas DataFrames, including shape and dtype validation.

Yes, if you need type hints for NumPy or pandas and are comfortable with a dormant package. The low install friction and permissive license make it easy to adopt. However, verify that it works with your current NumPy and pandas versions, and be aware that no active maintenance means bugs or incompatibilities with future releases will not be fixed.

Install

nptyping on PyPI

pip install nptyping

uv add nptyping

poetry add nptyping

Installing nptyping

Before you install

Low install friction with only two runtime dependencies (typing-extensions and numpy). Maintenance is dormant—last release was 2023-02-20 and no commits since 2024-08-01—so expect no active bug fixes or feature updates.

License in practice

MIT license is permissive; you can use this package freely in commercial and private projects with minimal restrictions.

Quickstart

pip install nptyping

from nptyping import NDArray, Shape, Int
import numpy as np

arr: NDArray[Shape["2, 2"], Int] = np.array([[1, 2], [3, 4]])
print(isinstance(arr, NDArray[Shape["2, 2"], Int]))

Requires Python 3.7 or later and numpy installed.

Verify before relying

• Whether runtime type checking performance is acceptable for large arrays or frequent checks in production code.
• Current compatibility with recent numpy and pandas versions beyond what the fact sheet confirms.

Package facts

Evidence: nptyping-2.5.0-py3-none-any.whl

Tags

More Scientific/Engineering packages