{"id":4651,"library":"nptyping","title":"nptyping","description":"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.","status":"active","version":"2.5.0","language":"en","source_language":"en","source_url":"https://github.com/ramonhagenaars/nptyping","tags":["numpy","typing","type-hints","ndarray","data-science","static-analysis"],"install":[{"cmd":"pip install nptyping","lang":"bash","label":"Install nptyping"}],"dependencies":[{"reason":"Core dependency for type definitions and runtime checks against NumPy arrays.","package":"numpy","optional":false},{"reason":"Required for `DataFrame` type hinting support.","package":"pandas","optional":true},{"reason":"Requires Python 3.7 or newer.","package":"Python","optional":false}],"imports":[{"symbol":"NDArray","correct":"from nptyping import NDArray"},{"symbol":"Shape","correct":"from nptyping import Shape"},{"symbol":"Structure","correct":"from nptyping import Structure"},{"note":"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.","wrong":"from nptyping import int32","symbol":"Int","correct":"from nptyping import Int"},{"symbol":"DataFrame","correct":"from nptyping import DataFrame"}],"quickstart":{"code":"import numpy as np\nfrom nptyping import NDArray, Shape, Int\n\ndef process_integer_array(arr: NDArray[Shape[\"*, *\"], Int[64]]) -> NDArray[Shape[\"*, *\"], Int[64]]:\n    \"\"\"Type-hinted function for processing a 2D integer array.\"\"\"\n    print(f\"Processing array with shape {arr.shape} and dtype {arr.dtype}\")\n    return arr * 2\n\n# Create a NumPy array\nmy_array = np.array([[1, 2, 3], [4, 5, 6]], dtype=np.int64)\n\n# Call the type-hinted function\nresult_array = process_integer_array(my_array)\nprint(f\"Resulting array:\\n{result_array}\")\n\n# Example of runtime type checking (works with numpy arrays)\nif isinstance(my_array, NDArray[Shape[\"*, *\"], Int]):\n    print(\"my_array is a 2D integer NDArray.\")","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=2.4.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"Various, e.g., v2.1.3, v2.3.1, v2.4.1 for specific fixes."},{"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.","message":"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.","severity":"gotcha","affected_versions":"v2.4.0 (potentially later until explicitly fixed)"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}