Install & Compatibility
Where this runs
tested against v2.5.0 · 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
py 3.13
✕ build_error
✕ build_error
91MB installed
● package 91MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
NDArray
✓ from nptyping import NDArray
Shape
✓ from nptyping import Shape
Structure
✓ from nptyping import Structure
Int
✓ from nptyping import Int
✗ from nptyping import int32
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
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.")
Debug
Known issues
breakingIn `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.fixExplicitly use `nptyping.Int[32]` (or other bit-widths) if a specific integer bit-width is required. For generic integer types, `nptyping.Int` remains appropriate.
affects: >=2.4.0
gotchanptyping 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.fixEnsure 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.
affects: Various, e.g., v2.1.3, v2.3.1, v2.4.1 for specific fixes.
gotchaWhile `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.fixVerify 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.
affects: v2.4.0 (potentially later until explicitly fixed)
Errors
Common errors & fixes
AttributeError: module 'numpy' has no attribute 'bool8'. Did you mean: 'bool'?
This error occurs because 'bool8' is not a valid attribute in the 'numpy' module; the correct attribute is 'bool'.
fixReplace 'numpy.bool8' with 'numpy.bool' in your code.
TypeError: 'numpy._DTypeMeta' object is not subscriptable
This error arises when attempting to subscript 'numpy.dtype' directly, which is not allowed.
fixUse 'numpy.dtype("uint8")' instead of 'numpy.dtype[numpy.uint8]'. TypeError: 'type' object is not subscriptable
This error occurs when trying to subscript a type object, such as 'numpy.ndarray', which is not subscriptable.
fixUse 'nptyping.NDArray' for type annotations instead of subscripting 'numpy.ndarray'.
Expected Type 'Array[float, Any]', got 'ndarray' instead
This error indicates a mismatch between the expected type hint and the actual type of the object.
fixEnsure that the variable is correctly annotated with 'nptyping.NDArray' and that the actual object matches the expected type.
AttributeError: module 'numpy' has no attribute 'bool8'
This error occurs when `nptyping` is used with NumPy 2.x, as NumPy 2.x deprecated or removed `np.bool8`, which older `nptyping` versions might still reference.
fixUpgrade `nptyping` to a version compatible with NumPy 2.x, or if a compatible version is not available, consider using `np2typing` (a NumPy 2.x compatible fork) or downgrade NumPy to a 1.x version.
Upgrade
Version history
2.5.0latest on PyPI · released Feb 20, 2023
Audit
Dependencies
numpyrequiredCore dependency for type definitions and runtime checks against NumPy arrays.
pandasoptionalRequired for `DataFrame` type hinting support.
PythonrequiredRequires Python 3.7 or newer.