# `numpy-typing-compat`
[][RELEASES]
[][CF]
[][NP]
## 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-compat` is intended as a helper package for the [`optype`][OP] library,
> which provides high-level typing utilities for annotating NumPy operations.
> In most situations, it is recommended to use `optype` instead of
> `numpy-typing-compat`. See the [`optype.numpy` documentation][ONP] for more details.
## Installation and Versioning
The `numpy-typing-compat` packages are available on PyPI and conda-forge.
Modern package managers such as [`uv`](https://github.com/astral-sh/uv) and
[`pixi`](https://github.com/prefix-dev/pixi/) 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`.
> [!WARNING]
> Legacy package managers such as `pip` don't always respect dependency restrictions.
> Running `pip install --upgrade numpy` will *not* automatically upgrade
> `numpy-typing-compat` to the correct version. If for some reason you need to use
> `pip`, then be sure to manually install the correct version of `numpy-typing-compat`
> that matches your installed NumPy version. Running `pip check` will tell you whether
> the installed `numpy-typing-compat` and `numpy` versions are compatible.
To illustrate, the `numpy-typing-compat==20250818.2.1` distribution of release `v20250818`
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 for this example would be `numpy-typing-compat==20250818.2.3`.
| numpy-typing-compat | NumPy | Python |
| ------------------- | -------------- | -------- |
| `20250818.1.22` | `>=1.22,<1.23` | `>=3.8` |
| `20250818.1.23` | `>=1.23,<1.25` | `>=3.8` |
| `20250818.1.25` | `>=1.25,<2.0` | `>=3.9` |
| `20250818.2.0` | `>=2.0,<2.1` | `>=3.9` |
| `20250818.2.1` | `>=2.1,<2.2` | `>=3.10` |
| `20250818.2.2` | `>=2.2,<2.3` | `>=3.10` |
| `20250818.2.3` | `>=2.3,<2.4` | `>=3.11` |
## 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 e.g. `numpy-typing-compat==20250818.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 `Literal` type
> conditions, and will not treat `if NUMPY_GE_2_0: ...` in the same way as
> `if sys.version_info >= (3, 12): ...` or `if sys.platform == "win32": ...`.
[RELEASES]: https://github.com/jorenham/numpy-typing-compat/releases
[NP]: https://github.com/numpy/numpy
[OP]: https://github.com/jorenham/optype
[ONP]: https://github.com/jorenham/optype#optypenumpy
[CF]: https://anaconda.org/conda-forge/numpy-typing-compat
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, optype, typing, compatibility",
"author": "Joren Hammudoglu",
"author_email": "Joren Hammudoglu <jhammudoglu@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/c9/e3/1a29f174c1e09a2bf111d37a41afceea1b501371abb39e73170ca31a7599/numpy_typing_compat-20250818.2.3.tar.gz",
"platform": null,
"description": "# `numpy-typing-compat`\n\n[][RELEASES]\n[][CF]\n\n\n[][NP]\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> [!TIP]\n> `numpy-typing-compat` is intended as a helper package for the [`optype`][OP] library,\n> which provides high-level typing utilities for annotating NumPy operations.\n> In most situations, it is recommended to use `optype` instead of\n> `numpy-typing-compat`. See the [`optype.numpy` documentation][ONP] for more details.\n\n## Installation and Versioning\n\nThe `numpy-typing-compat` packages are available on PyPI and conda-forge.\n\nModern package managers such as [`uv`](https://github.com/astral-sh/uv) and\n[`pixi`](https://github.com/prefix-dev/pixi/) will automatically install the\nappropriate version of `numpy-typing-compat` that matches your installed NumPy version,\nin order to satisfy the `numpy` dependency restrictions of `numpy-typing-compat`.\n\n> [!WARNING]\n> Legacy package managers such as `pip` don't always respect dependency restrictions.\n> Running `pip install --upgrade numpy` will *not* automatically upgrade\n> `numpy-typing-compat` to the correct version. If for some reason you need to use\n> `pip`, then be sure to manually install the correct version of `numpy-typing-compat`\n> that matches your installed NumPy version. Running `pip check` will tell you whether\n> the installed `numpy-typing-compat` and `numpy` versions are compatible.\n\nTo illustrate, the `numpy-typing-compat==20250818.2.1` distribution of release `v20250818`\nspecifies `numpy>=2.1,<2.2` as a required dependency. Modern package managers will\nensure that these dependency restrictions are satisfied. That way, if you upgrade\n`numpy` from `2.1` to `2.3` (e.g. by running `uv sync --upgrade`) then `uv` will also\nautomatically look for a version of `numpy-typing-compat` that satisfies the new `numpy`\nversion, which for this example would be `numpy-typing-compat==20250818.2.3`.\n\n| numpy-typing-compat | NumPy | Python |\n| ------------------- | -------------- | -------- |\n| `20250818.1.22` | `>=1.22,<1.23` | `>=3.8` |\n| `20250818.1.23` | `>=1.23,<1.25` | `>=3.8` |\n| `20250818.1.25` | `>=1.25,<2.0` | `>=3.9` |\n| `20250818.2.0` | `>=2.0,<2.1` | `>=3.9` |\n| `20250818.2.1` | `>=2.1,<2.2` | `>=3.10` |\n| `20250818.2.2` | `>=2.2,<2.3` | `>=3.10` |\n| `20250818.2.3` | `>=2.3,<2.4` | `>=3.11` |\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 e.g. `numpy-typing-compat==20250818.1.22`.\n\n### `long` and `ulong`\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### `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### `ABCPolyBase`\n\nIn NumPy 2.1, the `numpy.polynomial._polybase.ABCPolyBase` was made into a generic type,\nand in NumPy 2.2 the type parameter was made optional. This can be problematic on\n`numpy==2.1.*` if you also require support for `numpy < 2.1`.\nTo work around this, the `numpy_typing_compat.ABCPolyBase` is a type alias for\n`numpy.polynomial._polybase.ABCPolyBase[LiteralString | None]` on `numpy==2.1.*`, and\na direct re-export of `numpy.polynomial._polybase.ABCPolyBase` otherwise. This way,\ntype checkers (when configured in strict mode) won't report an error on `numpy==2.1.*`\nwhen using `ABCPolyBase`. Note that `numpy_typing_compat.ABCPolyBase` does not accept a\ntype parameter, even on `numpy >= 2.1`, for the sake of consistency.\n\n### `LiteralTrue` and `LiteralFalse`\n\nIn NumPy 2.2, the `np.bool` scalar type became a generic type that accepts a type\nparameter of either `True` or `False`. For compatibility with `numpy < 2.2`, the\n`numpy_typing_compat.LiteralTrue` and `numpy_typing_compat.LiteralFalse` types are\nprovided. These are type aliases for `Literal[True]` and `Literal[False]` on\n`numpy < 2.2`, and `Literal[True] | np.bool[Literal[True]]` and\n`Literal[False] | np.bool[Literal[False]]` on `numpy >= 2.2`, respectively.\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, so that static type-checkers are able to understand the NumPy version being\nused.\n\n> [!WARNING]\n> At the moment, mypy and pyright only have limited support for `Literal` type\n> conditions, and will not treat `if NUMPY_GE_2_0: ...` in the same way as\n> `if sys.version_info >= (3, 12): ...` or `if sys.platform == \"win32\": ...`.\n\n[RELEASES]: https://github.com/jorenham/numpy-typing-compat/releases\n[NP]: https://github.com/numpy/numpy\n[OP]: https://github.com/jorenham/optype\n[ONP]: https://github.com/jorenham/optype#optypenumpy\n[CF]: https://anaconda.org/conda-forge/numpy-typing-compat\n",
"bugtrack_url": null,
"license": null,
"summary": "Static typing compatibility layer for older versions of NumPy",
"version": "20250818.2.3",
"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",
" optype",
" typing",
" compatibility"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "c94afa4c90a03d6a8ee1a7f0e0fb101887d9a8cdb9b07a5901af9ae831e9feea",
"md5": "79f795fecb655b5338a0a85441208046",
"sha256": "930413d34dd9083c0bf418815576222f1c66ea2d68950f447fd27ea1a78b26b0"
},
"downloads": -1,
"filename": "numpy_typing_compat-20250818.2.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "79f795fecb655b5338a0a85441208046",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 6286,
"upload_time": "2025-08-18T23:46:35",
"upload_time_iso_8601": "2025-08-18T23:46:35.681421Z",
"url": "https://files.pythonhosted.org/packages/c9/4a/fa4c90a03d6a8ee1a7f0e0fb101887d9a8cdb9b07a5901af9ae831e9feea/numpy_typing_compat-20250818.2.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "c9e31a29f174c1e09a2bf111d37a41afceea1b501371abb39e73170ca31a7599",
"md5": "973d7789ee3901b6b40c8d4732d2b406",
"sha256": "72e83d535b635d668ba7315e43ae80be1469a6faea6fc96d312516f39b3d8fa5"
},
"downloads": -1,
"filename": "numpy_typing_compat-20250818.2.3.tar.gz",
"has_sig": false,
"md5_digest": "973d7789ee3901b6b40c8d4732d2b406",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 4974,
"upload_time": "2025-08-18T23:46:42",
"upload_time_iso_8601": "2025-08-18T23:46:42.968133Z",
"url": "https://files.pythonhosted.org/packages/c9/e3/1a29f174c1e09a2bf111d37a41afceea1b501371abb39e73170ca31a7599/numpy_typing_compat-20250818.2.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-18 23:46:42",
"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
