---
id: numerary
version: "0.4.4"
license: MIT License
license_treatment: permissive
maintenance: active
---

# numerary — Python hacks for type-checking numbers

License: permissive · Maintenance: active · Downloads: 80.3K/mo

## 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 above — 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

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

- License: MIT License (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 80.3K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

numeric type protocols, type checking numbers, numeric tower typing, protocol-based numeric types, runtime checkable number types, numeric interface typing, custom numeric type hints, numeric-typing, protocol-based, type-safety

[View on SkillFed](https://skillfed.io/packages/numerary) · [View on PyPI](https://pypi.org/project/numerary/)