numerary

What it is and what it does

numerary solves the problem of type-checking numeric interfaces that need to work with more than just int and float. Python's numeric tower and standard library types like Decimal and Fraction lack proper integration with the type system, leaving developers unable to write functions that accept arbitrary numeric types without breaking type-checking or resorting to overly broad annotations. numerary provides composable, runtime-checkable Protocol definitions—such as RealLike, IntegralLike, SupportsIntegralOps, and SupportsAbs—that let you declare numeric requirements precisely and have them work correctly with both type checkers and runtime isinstance checks.

The package is built on the Supports pattern from the standard library's typing module, extended with a caching protocol metaclass to handle edge cases where standard library types have inconsistent operator definitions. It targets developers writing numeric libraries, scientific code, or domain-specific interfaces that need to accept diverse numeric types while maintaining type safety. The single runtime dependency is beartype, and the package supports Python 3.8 through 3.11 on both CPython and PyPy.

Use it for:

• Define a function that accepts any real number type and type-check it correctly without forcing callers to convert.
• Build a numeric library that works with standard library numbers and third-party types, catching operator incompatibilities.
• Compose custom protocols by mixing SupportsAbs, SupportsDivmod, and other operator protocols to express precise requirements.
• Validate at runtime that an object truly supports the numeric operations your code needs, catching silent failures.
• Document numeric interfaces for scientific or financial code where type distinctions matter for correctness.

Worth the install?

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

Provides runtime-checkable protocols and type hints for working with numeric types beyond Python's built-in int and float, enabling type-safe interfaces that accept members of the numeric tower and other numeric primitives.

Yes. If you write numeric code or libraries that need to accept diverse numeric types while maintaining type safety, numerary solves a real gap in Python's type system. It has low install friction, active maintenance, no known vulnerabilities, and a permissive license. The trade-off is that it's still marked Beta and requires deliberate use of its protocols—it won't magically fix existing code, but it will let you write new numeric interfaces correctly.

Install

numerary on PyPI

pip install numerary

uv add numerary

poetry add numerary

Installing numerary

Before you install

Low friction: pure-Python wheel with a single runtime dependency on beartype. Actively maintained with a recent commit on 2026-02-27 and no known vulnerabilities.

License in practice

MIT License permits commercial and private use with minimal restrictions, requiring only license and copyright notice retention.

Quickstart

pip install numerary

from numerary import RealLike, IntegralLike

def process(arg: RealLike) -> IntegralLike:
    return int(arg // 1)

Requires Python 3.8 or later; best used with a type checker like mypy to catch incompatibilities at development time.

Verify before relying

• Whether protocol implementations remain compatible with latest versions of third-party numeric libraries.
• Performance characteristics when composing multiple protocols or checking isinstance at runtime.

Package facts

Evidence: numerary-0.4.4-py3-none-any.whl

Tags

More Python Modules packages