numpy-typing-compat

What it is and what it does

numpy-typing-compat is a compatibility layer that lets you write NumPy type annotations that adapt to the installed NumPy version. It provides version-specific boolean constants (like NUMPY_GE_2_1) and type aliases (StringDType, ABCPolyBase, LiteralTrue, LiteralFalse) that static type-checkers can understand, similar to how you'd use sys.version_info for Python version checks. This is particularly useful for library authors who need to support multiple NumPy versions while maintaining accurate type hints.

The package is tightly coupled to NumPy versions—each release targets a specific NumPy minor version range (e.g., 20260602.2.5 targets numpy >=2.4,<2.5). Modern package managers like uv and pixi automatically install the correct version, but pip users must manually ensure alignment. The package is actively maintained and designed as a helper for the optype library, though it can be used directly when you need fine-grained version-aware typing.

Use it for:

• Library authors supporting multiple NumPy versions who need type-checkers to understand version-specific APIs without runtime overhead
• Conditional type annotations for NumPy 2.0+ features like StringDType that weren't available in earlier versions
• Handling NumPy 2.1+ generic type changes (ABCPolyBase) while maintaining backward compatibility with older versions
• Type-safe use of NumPy 2.2+ bool scalar generics (LiteralTrue, LiteralFalse) across version boundaries

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Provides version-specific type annotations for NumPy code, allowing static type-checkers to understand which NumPy version is installed and apply appropriate type hints accordingly.

Yes, if you are a library author supporting multiple NumPy versions and need static type-checkers to understand version-specific type differences. Use modern package managers (uv, pixi) to avoid manual version management. Not necessary for applications using a single NumPy version or if you rely on optype for higher-level typing utilities.

Install

numpy-typing-compat on PyPI

pip install numpy-typing-compat

uv add numpy-typing-compat

poetry add numpy-typing-compat

Installing numpy-typing-compat

Before you install

Low install friction with a single runtime dependency on numpy. Actively maintained as of 2026-08-14 with recent releases. Requires Python 3.12 or later and is designed to work with modern package managers like uv and pixi that respect version constraints; pip users must manually ensure version compatibility.

License in practice

BSD-3-Clause permissive license allows use in most projects without significant restrictions.

Quickstart

pip install numpy-typing-compat

from numpy_typing_compat import NUMPY_GE_2_1, StringDType

if NUMPY_GE_2_1:
    dtype = StringDType()
else:
    dtype = None

Requires Python 3.12 or later. The installed version of numpy-typing-compat must match your NumPy version—modern package managers handle this automatically, but pip requires manual version alignment.

Verify before relying

• How well mypy and pyright actually support Literal-based version conditions in practice beyond the documented 'limited support'
• Whether the package is actively used by optype or other production libraries beyond its intended helper role

Package facts

Evidence: numpy_typing_compat-20260602.2.5-py3-none-any.whl

Keywords: numpy, optype, typing, compatibility

Tags

More Software Development packages