nptyping

2.5.0 · active · verified Sun Apr 12

nptyping provides type hints for NumPy arrays and structured arrays, enabling static type checking for data science code that uses NumPy. It also includes experimental support for Pandas DataFrames. As of version 2.5.0, it's actively maintained with a moderate release cadence, focusing on compatibility, new features like structure expressions, and bug fixes.

Warnings

breaking In `nptyping` v2.4.0, the `nptyping.Int` type was changed to point to `numpy.integer` (a generic integer type) instead of the more specific `numpy.int32`. This can subtly break type checking or runtime behavior if code implicitly relied on `nptyping.Int` always implying a 32-bit integer.
Fix: Explicitly use `nptyping.Int[32]` (or other bit-widths) if a specific integer bit-width is required. For generic integer types, `nptyping.Int` remains appropriate.
gotcha nptyping has experienced several compatibility issues with specific versions of MyPy (e.g., v0.991, v1.23.1) and other type checkers like Pyright/Pylance. These can manifest as 'Value of type variable ... cannot be ...' or 'Literal' is not a class' errors.
Fix: Ensure you are using a version of `nptyping` that explicitly supports your type checker's version. Consult `nptyping` release notes or the issue tracker if encountering such errors, and consider upgrading `nptyping` or adjusting your type checker version.
gotcha While `nptyping` added experimental support for Pandas `DataFrame` in `v2.4.0`, this feature initially had an exception for Python 3.11 users. This may lead to unexpected type checking failures or runtime errors when combining `nptyping.DataFrame` with Python 3.11.
Fix: Verify the `nptyping` documentation for the latest compatibility status with Python 3.11 and `pandas.DataFrame`. Consider using an earlier Python version or avoiding `nptyping.DataFrame` types on Python 3.11 if issues persist.

Install

pip install nptyping Install nptyping

Imports

NDArray
```
from nptyping import NDArray
```
Shape
```
from nptyping import Shape
```
Structure
```
from nptyping import Structure
```
Int
```
from nptyping import Int
```
nptyping provides its own higher-level type definitions like Int, Float, Bool, etc., which can be parameterized (e.g., Int[32]). Importing direct NumPy dtypes is not typical for nptyping's primary use case.
DataFrame
```
from nptyping import DataFrame
```

Quickstart

This quickstart demonstrates how to use `nptyping.NDArray` with `Shape` and a specific integer type (`Int[64]`) to provide type hints for a NumPy array in a function signature. It also shows a basic runtime `isinstance` check using `nptyping` types.

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

def process_integer_array(arr: NDArray[Shape["*, *"], Int[64]]) -> NDArray[Shape["*, *"], Int[64]]:
    """Type-hinted function for processing a 2D integer array."""
    print(f"Processing array with shape {arr.shape} and dtype {arr.dtype}")
    return arr * 2

# Create a NumPy array
my_array = np.array([[1, 2, 3], [4, 5, 6]], dtype=np.int64)

# Call the type-hinted function
result_array = process_integer_array(my_array)
print(f"Resulting array:\n{result_array}")

# Example of runtime type checking (works with numpy arrays)
if isinstance(my_array, NDArray[Shape["*, *"], Int]):
    print("my_array is a 2D integer NDArray.")

view raw JSON →