numpy-typing-compat
Overview
This package provides version-specific boolean constants that allow library authors to
write NumPy-version-dependent static type annotations. Similar to how you might use
if sys.version_info >= (3, 12): for Python version checks, numpy-typing-compat
enables static type-checkers to understand which NumPy version is being used and apply
appropriate type annotations.
[!TIP]
numpy-typing-compatis intended as a helper package for theoptypelibrary, which provides high-level typing utilities for annotating NumPy operations. In most situations, it is recommended to useoptypeinstead ofnumpy-typing-compat. See theoptype.numpydocumentation for more details.
Installation
Modern package managers such as uv will
automatically install the appropriate version of numpy-typing-compat that matches your
installed NumPy version, in order to satisfy the numpy dependency restrictions of
numpy-typing-compat.
For example, the numpy-typing-compat==2.1.* distribution specifies numpy>=2.1,<2.2
as a required dependency. Modern package managers will ensure that these dependency
restrictions are satisfied. That way, if you upgrade numpy from 2.1 to 2.3, e.g.
by running uv sync --upgrade, then uv will also automatically look for a version of
numpy-typing-compat that satisfies the new numpy version, which in this case
would be numpy-typing-compat==2.3.*.
[!WARNING] Legacy package managers such as
pipdon't respect dependency restrictions. Runningpip install --upgrade numpywill not automatically upgradenumpy-typing-compatto the correct version. If for some reason you need to usepip, then be sure to manually install the correct version ofnumpy-typing-compatthat matches your installed NumPy version. Runningpip checkwill tell you whether the installednumpy-typing-compatandnumpyversions are compatible.
Reference
array_api
Additionally, the package provides a numpy_typing_compat.array_api namespace that's a
re-export of the numpy.array_api module on numpy < 2.0, or the main numpy module
on numpy >= 2.0. Note that the numpy.array_api module was introduced in
numpy >= 1.23, so it isn't available in numpy-typing-compat==1.22.*.
long and ulong
NumPy 2.0 introduced the new long and ulong scalar types, which are not available in
numpy < 2.0, and instead went by the names int_ and uint (which in numpy >= 2.0
are aliases for intp and uintp).
If you need to support both NumPy versions, you can use the long and ulong types
from numpy_typing_compat, which on numpy < 2.0 are aliases for np.int_ and
np.uint, and on numpy >= 2.0 are re-exports of np.long and np.ulong.
StringDType
In NumPy 2.0, the numpy.dtypes.StringDType was introduced, but it wasn't until
NumPy 2.1 that it was also available in the numpy stubs. The
numpy_typing_compat.StringDType is a re-export of numpy.dtypes.StringDType on
numpy >= 2.1, and an alias of np.dtype[Never] on numpy < 2.1. This allows type
checkers to also accept StringDType as a valid type on numpy == 2.0.*.
ABCPolyBase
In NumPy 2.1, the numpy.polynomial._polybase.ABCPolyBase was made into a generic type,
and in NumPy 2.2 the type parameter was made optional. This can be problematic on
numpy==2.1.* if you also require support for numpy < 2.1.
To work around this, the numpy_typing_compat.ABCPolyBase is a type alias for
numpy.polynomial._polybase.ABCPolyBase[LiteralString | None] on numpy==2.1.*, and
a direct re-export of numpy.polynomial._polybase.ABCPolyBase otherwise. This way,
type checkers (when configured in strict mode) won't report an error on numpy==2.1.*
when using ABCPolyBase. Note that numpy_typing_compat.ABCPolyBase does not accept a
type parameter, even on numpy >= 2.1, for the sake of consistency.
LiteralTrue and LiteralFalse
In NumPy 2.2, the np.bool scalar type became a generic type that accepts a type
parameter of either True or False. For compatibility with numpy < 2.2, the
numpy_typing_compat.LiteralTrue and numpy_typing_compat.LiteralFalse types are
provided. These are type aliases for Literal[True] and Literal[False] on
numpy < 2.2, and Literal[True] | np.bool[Literal[True]] and
Literal[False] | np.bool[Literal[False]] on numpy >= 2.2, respectively.
Version constants
The following low-level boolean version constants are available:
| Constant | True when |
|---|---|
NUMPY_GE_1_22 |
numpy >= 1.22 |
NUMPY_GE_1_23 |
numpy >= 1.23 |
NUMPY_GE_1_25 |
numpy >= 1.25 |
NUMPY_GE_2_0 |
numpy >= 2.0 |
NUMPY_GE_2_1 |
numpy >= 2.1 |
NUMPY_GE_2_2 |
numpy >= 2.2 |
NUMPY_GE_2_3 |
numpy >= 2.3 |
Each constant is typed as Literal[True] or Literal[False] depending on your NumPy
version, so that static type-checkers are able to understand the NumPy version being
used.
[!WARNING] At the moment, mypy and pyright only have limited support for
Literaltype conditions, and will not treatif NUMPY_GE_2_0: ...in the same way asif sys.version_info >= (3, 12): ...orif sys.platform == "win32": ....
2 maintainers
Release files for numpy-typing-compat 2.3.20250814
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| numpy_typing_compat-2.3.20250814.tar.gz | 4.8 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| numpy_typing_compat-2.3.20250814-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 10.9 kB
Release files / numpy_typing_compat-2.3.20250814.tar.gz
| Download URL | numpy_typing_compat-2.3.20250814.tar.gz |
|---|---|
| Size | 4.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
5b27cda3b05cf95eacb4296443ff9cd640d5adfed59067d4b7cbcfb22898916d
|
|
BLAKE2b-256 checksum How to use checksums |
7cd3da1034868794b1c60eef891c5d123ab6008d9d10dd1a8371a2277201a15c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.12.8
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 14, 2025.
Transparency logRelease files / numpy_typing_compat-2.3.20250814-py3-none-any.whl
| Download URL | numpy_typing_compat-2.3.20250814-py3-none-any.whl |
|---|---|
| Size | 6.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
e94d188edc728a7720470a60bac9e193d77680998a614517793ca9fd0c19833a
|
|
BLAKE2b-256 checksum How to use checksums |
39927905fd41db8f2f4b4bdd22f3a106b27e8f83aaa40d9c58b594f671cca988
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.12.8
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 14, 2025.
Transparency log
