{"id":8358,"library":"numerary","title":"Numerary","description":"Numerary is a Python library that provides a set of type-hinting protocols (e.g., `Integer`, `Float`, `Real`, `Complex`, `Number`) designed for more precise and robust type-checking of numeric types in Python. It is currently at version 0.4.4 and is under active development with frequent, smaller updates.","status":"active","version":"0.4.4","language":"en","source_language":"en","source_url":"https://github.com/numerary-dev/numerary","tags":["type-hinting","protocol","numbers","mypy","static-analysis","runtime-checking"],"install":[{"cmd":"pip install numerary","lang":"bash","label":"Install stable release"}],"dependencies":[{"reason":"Requires Python 3.8 or higher.","package":"python","optional":false}],"imports":[{"symbol":"Integer","correct":"from numerary import Integer"},{"symbol":"Float","correct":"from numerary import Float"},{"symbol":"Real","correct":"from numerary import Real"},{"symbol":"Complex","correct":"from numerary import Complex"},{"symbol":"Number","correct":"from numerary import Number"}],"quickstart":{"code":"from numerary import Integer, Float, Real, Number\n\ndef process_number(n: Number) -> str:\n    if isinstance(n, Integer):\n        return f\"It's an integer: {n} (type: {type(n).__name__})\"\n    elif isinstance(n, Float):\n        return f\"It's a float: {n} (type: {type(n).__name__})\"\n    elif isinstance(n, Real):\n        return f\"It's a real number: {n} (type: {type(n).__name__})\"\n    else:\n        return f\"It's a generic number: {n} (type: {type(n).__name__})\"\n\nprint(process_number(5))\nprint(process_number(5.0))\nprint(process_number(3 + 4j))\nprint(process_number(10.5))","lang":"python","description":"This quickstart demonstrates how to use `numerary` protocols for runtime type checking with `isinstance` and static type hints. The protocols allow distinguishing between different categories of numbers."},"warnings":[{"fix":"Always pin to a specific minor version (e.g., `numerary==0.4.*`) and review release notes for breaking changes before updating.","message":"Numerary is pre-1.0.0, meaning its API may still undergo breaking changes in minor versions. While efforts are made to maintain compatibility, users should review release notes when upgrading.","severity":"breaking","affected_versions":"<1.0.0"},{"fix":"Understand that `numerary` works with Python's existing type system to add more granular numeric type hints, rather than replacing or altering core numeric behavior.","message":"Numerary protocols are `typing.Protocol`s. They define interfaces for numeric types, primarily for static type checking (e.g., MyPy) and runtime `isinstance` checks when decorated with `@runtime_checkable` (which `numerary` does). They do not modify Python's built-in numeric types, but rather describe properties they satisfy.","severity":"gotcha","affected_versions":"All"},{"fix":"For strict runtime differentiation between `int` and `float` (e.g., `float` only), prefer `isinstance(value, float)` rather than `isinstance(value, numerary.Float)`.","message":"The `numerary.Float` protocol (like `numbers.Real`) is satisfied by both `int` and `float` built-in types. If you need to strictly differentiate between `int` and `float` instances at runtime (i.e., accept only `float` and not `int`), use `isinstance(obj, float)` directly rather than `isinstance(obj, numerary.Float)`.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Ensure that the value being passed or assigned is an instance of a Python numeric type (`int`, `float`, `complex`) or a custom class that correctly implements the required `numerary` protocol.","cause":"Attempting to pass a non-numeric type (e.g., a string, list, or None) to a function or variable annotated with a `numerary` numeric protocol like `Number`, `Integer`, or `Float`.","error":"TypeError: Argument 1 to \"my_function\" has incompatible type \"str\"; expected \"Number\""},{"fix":"If you intend to accept both `int` and `float` values, use `numerary.Float` as the type hint for the parameter or variable, as `numerary.Float` is a protocol satisfied by both `int` and `float`.","cause":"When using strict type checkers (like MyPy in certain configurations), assigning an `int` to a variable or parameter explicitly typed as `float` can raise an error. While Python allows implicit conversion, type checkers might flag this depending on context.","error":"TypeError: Argument of type \"int\" cannot be assigned to parameter \"x\" of type \"float\""}]}