isqx

What it is and what it does

isqx is a metadata-only library for documenting physical units and quantity kinds in Python code using type annotations. It defines units (kg, knots, pascal) and quantity kinds (mass, velocity, static pressure) based on the International System of Quantities, allowing developers to attach semantic meaning to function arguments and dataclass fields without wrapping numerical types at runtime. Because annotations are metadata only, Annotated[np.ndarray, isqx.M] is treated as np.ndarray by Python and external libraries, ensuring zero performance overhead and full interoperability.

The library is designed primarily for code documentation via PEP 593 type hints, but also includes optional runtime utilities: unit conversion (with dimension checking and exact arithmetic support), simplification of unit expressions into canonical form, and extensible formatting. It has a single lightweight runtime dependency and can be used as an optional dependency in downstream projects by placing imports in TYPE_CHECKING blocks.

Use it for:

• Annotate scientific function signatures with physical units to catch dimensional mismatches at type-check time without runtime overhead.
• Document dataclass fields with quantity kinds (e.g., GEOPOTENTIAL_ALTITUDE, STATIC_PRESSURE) to encode domain-specific metadata in type hints.
• Convert between compatible unit systems (e.g., feet per minute to meters per second) with dimension validation and exact or approximate arithmetic.
• Simplify complex unit expressions into flat canonical form to compute dimensions and verify dimensional consistency.
• Use as an optional typing dependency in libraries, allowing downstream users to inspect unit metadata at runtime without hard-depending on isqx.

Worth the install?

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

isqx provides type-annotation-friendly metadata objects for physical units and quantity kinds based on ISO/IEC 80000, with zero runtime overhead and optional utilities for unit conversion and simplification.

Yes, if you work with scientific or engineering code and want to document physical units in type annotations without runtime cost. The zero-dependency design (at annotation time) and optional utilities make it suitable for both pure documentation and runtime unit conversion. Active maintenance and MIT licensing add confidence. Not necessary for projects that don't deal with physical quantities or already use heavier wrapper libraries.

Install

isqx on PyPI

pip install isqx

uv add isqx

poetry add isqx

Installing isqx

Before you install

Low install friction with a single lightweight runtime dependency (typing-extensions). Active maintenance with recent releases; currently at Alpha status (Development Status :: 3).

License in practice

MIT license (permissive); no restrictions on commercial or private use, modification, or distribution.

Quickstart

pip install isqx

from typing import Annotated, TypeVar
import isqx

_T = TypeVar("_T")
M = Annotated[_T, isqx.M]

def calculate_distance(height: M[float]) -> M[float]:
    return height * 2

Requires Python 3.9 or later; type annotations are ignored at runtime, so static type checkers are needed to validate unit correctness.

Verify before relying

• Whether the package's interactive visualizer and documentation examples work reliably across all supported Python versions.
• Performance characteristics when used with large numpy arrays or in JAX/functional transformation pipelines at scale.
• Adoption and stability of the ISQ/ISO 80000 standard implementation—whether all quantity kinds are correctly defined.

Package facts

Evidence: isqx-0.1.2-py3-none-any.whl

Tags

More Scientific/Engineering packages