# numpy-typing-compat
*NumPy version information that type-checkers understand*
[](https://github.com/jorenham/numpy-typing-compat/releases)
[](https://github.com/numpy/numpy)
## 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.
## Use Case
This package is particularly useful for libraries that need to support multiple NumPy
versions, for example because they follow
[SPEC 0](https://scientific-python.org/specs/spec-0000/). However, there may have been
changes in NumPy that affect type annotations. For instance, the `numpy.exceptions`
module was introduced in NumPy 1.25, and contains the exceptions that were previously in
the global `numpy` namespace. In NumPy 2.0, these exceptions were removed from the
global namespace. So if you support `<1.25` and also `>=2.0`, you will need to
conditionally import these exceptions to ensure compatibility across versions.
```python
from numpy_typing_compat import NUMPY_GE_1_25
if NUMPY_GE_1_25:
from numpy.exceptions import AxisError
else:
from numpy import AxisError
```
Type checkers like mypy, pyright, and basedpyright understand these patterns and will
apply the correct type annotations based on the installed NumPy version.
## Installation
```bash
pip install numpy-typing-compat
```
The package automatically selects the appropriate version constants based on your
installed NumPy version. It does so by requiring a specific version of NumPy in its
`pyproject.toml` file, so that your package manager will install the correct version of
`numpy-typing-compat` that matches the NumPy version you have installed.
For example, if you have `numpy==2.1.3` pinned in your `pyproject.toml`, and you run
`uv add numpy-typing-compat`, it will install `numpy-typing-compat==2.1.*`. That
specific version has `NUMPY_GE_2_1 = True`, and `NUMPY_GE_2_2 = False` set.
Note that `numpy-typing-compat` does not import `numpy`, and instead relies on the
package manager to install the correct version of `numpy-typing-compat` that matches the
installed NumPy version.
## 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.*`.
### `numpy.long`
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`.
### `numpy.dtypes.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.*`.
### 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, allowing type checkers to perform accurate type narrowing.
Raw data
{
"_id": null,
"home_page": null,
"name": "numpy-typing-compat",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "numpy, typing, compatibility",
"author": "Joren Hammudoglu",
"author_email": "Joren Hammudoglu <jhammudoglu@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/6b/c5/ba00ae592e495ee300c071d6e6bd679f4fbaa81225d27e9297d9f2900d49/numpy_typing_compat-2.3.20250725.tar.gz",
"platform": null,
"description": "# numpy-typing-compat\n\n*NumPy version information that type-checkers understand*\n\n[](https://github.com/jorenham/numpy-typing-compat/releases)\n\n\n[](https://github.com/numpy/numpy)\n\n## Overview\n\nThis package provides version-specific boolean constants that allow library authors to\nwrite NumPy-version-dependent static type annotations. Similar to how you might use\n`if sys.version_info >= (3, 12):` for Python version checks, `numpy-typing-compat`\nenables static type-checkers to understand which NumPy version is being used and apply\nappropriate type annotations.\n\n## Use Case\n\nThis package is particularly useful for libraries that need to support multiple NumPy\nversions, for example because they follow\n[SPEC 0](https://scientific-python.org/specs/spec-0000/). However, there may have been\nchanges in NumPy that affect type annotations. For instance, the `numpy.exceptions`\nmodule was introduced in NumPy 1.25, and contains the exceptions that were previously in\nthe global `numpy` namespace. In NumPy 2.0, these exceptions were removed from the\nglobal namespace. So if you support `<1.25` and also `>=2.0`, you will need to\nconditionally import these exceptions to ensure compatibility across versions.\n\n```python\nfrom numpy_typing_compat import NUMPY_GE_1_25\n\nif NUMPY_GE_1_25:\n from numpy.exceptions import AxisError\nelse:\n from numpy import AxisError\n```\n\nType checkers like mypy, pyright, and basedpyright understand these patterns and will\napply the correct type annotations based on the installed NumPy version.\n\n## Installation\n\n```bash\npip install numpy-typing-compat\n```\n\nThe package automatically selects the appropriate version constants based on your\ninstalled NumPy version. It does so by requiring a specific version of NumPy in its\n`pyproject.toml` file, so that your package manager will install the correct version of\n`numpy-typing-compat` that matches the NumPy version you have installed.\n\nFor example, if you have `numpy==2.1.3` pinned in your `pyproject.toml`, and you run\n`uv add numpy-typing-compat`, it will install `numpy-typing-compat==2.1.*`. That\nspecific version has `NUMPY_GE_2_1 = True`, and `NUMPY_GE_2_2 = False` set.\n\nNote that `numpy-typing-compat` does not import `numpy`, and instead relies on the\npackage manager to install the correct version of `numpy-typing-compat` that matches the\ninstalled NumPy version.\n\n## Reference\n\n### Array API\n\nAdditionally, the package provides a `numpy_typing_compat.array_api` namespace that's a\nre-export of the `numpy.array_api` module on `numpy < 2.0`, or the main `numpy` module\non `numpy >= 2.0`. Note that the `numpy.array_api` module was introduced in\n`numpy >= 1.23`, so it isn't available in `numpy-typing-compat==1.22.*`.\n\n### `numpy.long`\n\nNumPy 2.0 introduced the new `long` and `ulong` scalar types, which are not available in\n`numpy < 2.0`, and instead went by the names `int_` and `uint` (which in `numpy >= 2.0`\nare aliases for `intp` and `uintp`).\nIf you need to support both NumPy versions, you can use the `long` and `ulong` types\nfrom `numpy_typing_compat`, which on `numpy < 2.0` are aliases for `np.int_` and\n`np.uint`, and on `numpy >= 2.0` are re-exports of `np.long` and `np.ulong`.\n\n### `numpy.dtypes.StringDType`\n\nIn NumPy 2.0, the `numpy.dtypes.StringDType` was introduced, but it wasn't until\nNumPy 2.1 that it was also available in the `numpy` stubs. The\n`numpy_typing_compat.StringDType` is a re-export of `numpy.dtypes.StringDType` on\n`numpy >= 2.1`, and an alias of `np.dtype[Never]` on `numpy < 2.1`. This allows type\ncheckers to also accept `StringDType` as a valid type on `numpy == 2.0.*`.\n\n### Version constants\n\nThe following low-level boolean version constants are available:\n\n| Constant | `True` when |\n| --------------- | --------------- |\n| `NUMPY_GE_1_22` | `numpy >= 1.22` |\n| `NUMPY_GE_1_23` | `numpy >= 1.23` |\n| `NUMPY_GE_1_25` | `numpy >= 1.25` |\n| `NUMPY_GE_2_0` | `numpy >= 2.0` |\n| `NUMPY_GE_2_1` | `numpy >= 2.1` |\n| `NUMPY_GE_2_2` | `numpy >= 2.2` |\n| `NUMPY_GE_2_3` | `numpy >= 2.3` |\n\nEach constant is typed as `Literal[True]` or `Literal[False]` depending on your NumPy\nversion, allowing type checkers to perform accurate type narrowing.\n",
"bugtrack_url": null,
"license": null,
"summary": "NumPy version information that type-checkers understand",
"version": "2.3.20250725",
"project_urls": {
"Changelog": "https://github.com/jorenham/numpy-typing-compat/releases",
"Issues": "https://github.com/jorenham/numpy-typing-compat/issues",
"Repository": "https://github.com/jorenham/numpy-typing-compat"
},
"split_keywords": [
"numpy",
" typing",
" compatibility"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "53e4a65c1b7860a9242b6702b5c0ca015021cab7ea3a4b61fb429d604825017c",
"md5": "6eca2d0bfeeca7530b78840110f0ceac",
"sha256": "b2df54d9beefe63abe33ab257b44dd06435d5cd479e97a77a5a53185304039f5"
},
"downloads": -1,
"filename": "numpy_typing_compat-2.3.20250725-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6eca2d0bfeeca7530b78840110f0ceac",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 5045,
"upload_time": "2025-07-25T03:27:53",
"upload_time_iso_8601": "2025-07-25T03:27:53.093454Z",
"url": "https://files.pythonhosted.org/packages/53/e4/a65c1b7860a9242b6702b5c0ca015021cab7ea3a4b61fb429d604825017c/numpy_typing_compat-2.3.20250725-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "6bc5ba00ae592e495ee300c071d6e6bd679f4fbaa81225d27e9297d9f2900d49",
"md5": "c521740fa58aa1ab5a3c4e4e551cdbad",
"sha256": "87f590ae3b09afd2c529d2f3447c519f5f79cc0a89b9423bdcbed43434a308e0"
},
"downloads": -1,
"filename": "numpy_typing_compat-2.3.20250725.tar.gz",
"has_sig": false,
"md5_digest": "c521740fa58aa1ab5a3c4e4e551cdbad",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 3722,
"upload_time": "2025-07-25T03:28:00",
"upload_time_iso_8601": "2025-07-25T03:28:00.957565Z",
"url": "https://files.pythonhosted.org/packages/6b/c5/ba00ae592e495ee300c071d6e6bd679f4fbaa81225d27e9297d9f2900d49/numpy_typing_compat-2.3.20250725.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-25 03:28:00",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "jorenham",
"github_project": "numpy-typing-compat",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "numpy-typing-compat"
}
JSON
