unitx 0.7.0__tar.gz → 0.8.0__tar.gz

{unitx-0.7.0 → unitx-0.8.0}/.github/workflows/ci.yml

@@ -48,3 +48,27 @@ jobs:
 
       - name: Run tests
         run: pytest -q
+
+  numpy:
+    name: NumPy ${{ matrix.numpy }} (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - python-version: '3.12'
+            numpy: '2.1.*'
+          - python-version: '3.14'
+            numpy: 'latest'
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v7
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install package and dependencies
+        run: python -m pip install -e '.[test,numpy]'
+      - name: Select minimum NumPy
+        if: matrix.numpy != 'latest'
+        run: python -m pip install 'numpy==${{ matrix.numpy }}'
+      - name: Run tests and typing
+        run: pytest -q

{unitx-0.7.0 → unitx-0.8.0}/CHANGELOG.md

@@ -1,5 +1,67 @@
 # Changelog
 
+## [0.8.0] - 2026-10-19
+
+### Added
+
+- Add optional NumPy >= 2.1 support through `unitx[numpy]`, with one Quantity
+  wrapping an entire plain numeric ndarray or NumPy numeric scalar. Preserve
+  input objects in both `array * unit` and `unit * array` construction.
+- Support unit-aware conversion, broadcasting arithmetic and comparisons,
+  matrix multiplication, indexing, iteration, array metadata, transpose, and
+  flattening. Preserve NumPy scalar indexing and view/copy behavior.
+- Implement a documented set of NumPy ufuncs and functions, including roots,
+  dimensionless transcendental functions, concatenation, statistics, predicates,
+  and position queries. Keep exact unit exponents and ScaledUnit factors.
+- Extend Quantity.isclose with symmetric array comparisons and broadcasting
+  tolerances; implement NumPy isclose/allclose with their own defaults and
+  asymmetric formula. Validate tolerance dimensions, finiteness, and signs.
+- Add runtime and installed-consumer typing coverage, import-order and optional
+  dependency checks, and CI jobs for minimum and current NumPy versions.
+
+### Changed
+
+- Define `Scalar`, `Array`, and `Magnitude = Scalar | Array` in `_numerics`.
+  Preserve concrete magnitude types at construction and in unit-only operations;
+  use conservative result types for array numerical operations.
+- Keep Python scalar arithmetic, Decimal behavior, and exact scalar comparisons
+  independent of the optional NumPy adapter. Array conversion follows the
+  documented NumPy promotion, rounding, and overflow rules.
+
+### NumPy scope
+
+- Document the supported function/keyword matrix and precision/storage rules in
+  `docs/numpy.md`. Other array backends, ndarray subclasses, object/boolean
+  magnitudes, and implicit list/tuple conversion are unsupported.
+- Reject implicit unit removal by `np.asarray(q)` or `np.array(q)`; use `.value`
+  or `.value_in(unit)` explicitly. NumPy magnitudes produce unhashable Quantities.
+- Reject writable out, item assignment, and operations that would require
+  heterogeneous units. Python augmented assignment creates and rebinds a result.
+
+## [0.7.1] - 2026-10-19
+
+### Added
+
+- Accept a single exact spelling string for `prefixable`, equivalent to a
+  one-element tuple, with the same spelling validation before registration.
+- Expand the `si` namespace's prefixed shortcuts and common units, including
+  percent, permille, permyriad, rotational frequency (`rpm`), speed of light
+  (`c`), gram-force, volt-ampere, ampere-hour, mho, and nit. Enable Torr prefixes.
+- Add `SI.kappa` and the wavelength and frequency Wien displacement constants,
+  `SI.b` and `SI.b_`.
+
+### Changed
+
+- Use fixed Decimal approximations with about 50 significant digits for pi and
+  the positive roots in the Wien displacement laws. Derived constants still use
+  the Decimal context active at import.
+- Treat `u` and `Da` as spellings of one formal unit, with prefixes enabled only
+  on `Da`. Rebuild stored units when migrating from the separate `u` identity;
+  the mass conversion scale is unchanged. Use `kDa` rather than `kilodalton`.
+- Keep ASCII micro spellings such as `um` and `us` convenient to type without
+  warnings. The explicit product `u m` retains its separate mass-times-length
+  meaning.
+
 ## [0.7.0] - 2026-10-19
 
 ### Added

{unitx-0.7.0 → unitx-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: unitx
-Version: 0.7.0
+Version: 0.8.0
 Summary: A modern, intuitive Python library for units, quantities, and dimensional analysis.
 Project-URL: Homepage, https://github.com/DaitTHU/unitx
 Project-URL: Issues, https://github.com/DaitTHU/unitx/issues
@@ -14,6 +14,8 @@ Classifier: Programming Language :: Python :: 3.14
 Classifier: Programming Language :: Python :: 3.15
 Classifier: Topic :: Scientific/Engineering :: Physics
 Requires-Python: >=3.12
+Provides-Extra: numpy
+Requires-Dist: numpy>=2.1; extra == 'numpy'
 Provides-Extra: test
 Requires-Dist: pyright>=1.1.414; extra == 'test'
 Requires-Dist: pytest>=8; extra == 'test'
@@ -22,11 +24,15 @@ Description-Content-Type: text/markdown
 
 # unitx
 
-Write Python formulas with ready-to-use units and physical constants. unitx
-handles scalar quantities, unit conversion, and dimensional analysis, with
-exact rational unit scales and exponents.
+[![PyPI version](https://img.shields.io/pypi/v/unitx)](https://pypi.org/project/unitx/)
+[![Python versions](https://img.shields.io/pypi/pyversions/unitx)](https://pypi.org/project/unitx/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 
-unitx is in early development. Public APIs may change during the 0.x series.
+Write Python formulas with ready-to-use units and physical constants. `unitx`
+handles scalar and optional NumPy quantities, unit conversion, and dimensional
+analysis, with exact rational unit scales and exponents.
+
+`unitx` is in early development. Public APIs may change during the 0.x series.
 
 ## Installation
 
@@ -101,15 +107,17 @@ astronomical units are included. Units and constants can be combined directly:
 
 Both namespaces are read-only and do not need to be instantiated. `si` exposes
 a selection of convenient attributes; other registered prefix combinations
-remain available through `Unit`, for example `Unit('Tm')`. Importing unitx
+remain available through `Unit`, for example `Unit('Tm')`. Importing `unitx`
 initializes the predefined unit catalogue. Defining a custom unit registers its
 text spellings without adding an attribute to `si`.
 
 SI defining constants retain their exact decimal values. Measured constants
 are stored nominal values; measurement uncertainties are not propagated.
 Derived Decimal constants are evaluated in the Decimal context active at
-import. Formulas involving pi use `Decimal(str(math.pi))` as an approximation;
-additional Decimal precision does not add precision to pi.
+import. Pi and the positive roots used by the Wien displacement constants
+(`SI.b` for wavelength and `SI.b_` for frequency) use fixed Decimal
+approximations with about 50 significant digits. Raising the context precision
+does not add accuracy beyond those stored approximations.
 
 ## Constructing units and quantities
 
@@ -267,7 +275,7 @@ meaning rather than acting as string delimiters. Bare compound names are
 not guessed from adjacent words, and ordinary parentheses still group products.
 
 The unit table contains `s`, `m`, `g`, `A`, `K`, `mol`, and `cd`, plus the
-dimensionless identity. Importing unitx also initializes the common units in
+dimensionless identity. Importing `unitx` also initializes the common units in
 `unitx.si`, including named derived units such as `N`. Mass scales are referenced
 to kilograms: `g` has factor `1/1000`, and `kg` has factor `1`.
 
@@ -337,8 +345,9 @@ Bare multiword names are recognized only as complete inputs. For example,
 as a factor; use `[astronomical unit] / arcsec`, symbols, or Unit objects instead.
 
 SI prefixes are enabled by default. `prefixable: PrefixPolicy = True` accepts
-`True` for all spellings, `False` for none, or a tuple of exact symbols, names,
-and aliases supplied in that definition. With a tuple, only the listed
+`True` for all spellings, `False` for none, a single spelling string, or a tuple
+of exact symbols, names, and aliases supplied in that definition. A string such
+as `prefixable='Da'` is equivalent to `prefixable=('Da',)`. Only the selected
 spellings accept prefixes; an empty tuple disables prefixes. Unknown spellings
 and non-string entries are errors. For example,
 `prefixable=('arcsec', 'arcsecond')` enables all SI prefixes on those two
@@ -347,7 +356,7 @@ spellings, while other spellings of that unit remain unprefixable.
 The tuple selects **unit spellings**, not prefix symbols. Prefix names attach
 directly to the first word of a multiword name, as in `kiloastronomical unit`;
 a separate `kilo astronomical unit` is not accepted. `PrefixPolicy` is available
-from `unitx.unitregistry` for annotations and means `bool | tuple[str, ...]`.
+from `unitx.unitregistry` for annotations and means `bool | str | tuple[str, ...]`.
 
 ```pycon
 >>> tick = si.s.define(
@@ -390,10 +399,24 @@ form; `760 * si.mmHg` converts to `si.atm` with value 1 under the library's
 existing pressure convention. Prefixes do not stack: `mmmHg` and `kmmHg` are
 invalid. `kt` retains its meaning as a knot alias; tonne remains unprefixable.
 
-The newly registered `u` denotes the unified atomic mass unit. ASCII micro
-spellings such as `um` still mean micrometres, but now issue `UnitSymbolWarning`
-because `u m` has a separate meaning. Use `µm`, `μm`, or `micrometre` to avoid
-this warning.
+`si.mas` and `si.uas` provide milli- and microarcseconds as namespace shortcuts;
+their registered expressions are `marcsec` and `µarcsec`. The strings `mas`
+and `uas` are not registered aliases. `si.Da` and `si.u` now share one formal
+unit identity; only the spelling `Da` accepts prefixes, such as `kDa`.
+`si.mTorr` is available, and Torr accepts SI prefixes. Tonne uses `t` or
+`tonne`; the ambiguous spelling `ton` is not registered.
+
+`si.rpm` represents rotational frequency: `60 * si.rpm` converts to `si.Hz`
+with value 1. For angular velocity, multiply that frequency by `2 * PI` and
+convert to `si.rad / si.s`; directly converting frequency to `rad/s` does
+not insert the physical factor of 2π. `si.c` is a speed unit equal to the
+speed of light, while `SI.c` is the corresponding physical quantity.
+
+The spelling `u` denotes the unified atomic mass unit when used on its own.
+ASCII micro spellings such as `um` and `us` remain supported without warnings,
+so entering non-ASCII characters is optional. `um`, `µm`, `μm`, and
+`micrometre` all mean micrometres; the explicit product `u m` instead means
+unified atomic mass unit times metre.
 
 Registration raises `UnitRegistryError` if a new spelling, including a generated
 prefixed form, already resolves to a unit or conflicts with another spelling
@@ -549,9 +572,10 @@ python -m pip install sympy
 
 ## Current scope
 
-- **NumPy scalars, arrays, and NumPy operations are not supported yet. NumPy
-  integration is planned.** Structural compatibility with a magnitude protocol
-  does not imply NumPy support.
+- Optional NumPy support accepts plain numeric ndarrays and NumPy numeric
+  scalars. Install `unitx[numpy]`; see the [support matrix and numerical
+  contract](https://github.com/DaitTHU/unitx/blob/v0.8.0/docs/numpy.md). Array operations preserve units, comparisons return
+  masks, and implicit unit stripping and writable `out` are rejected.
 - Custom magnitudes must support scalar arithmetic, return a Python `bool`
   from equality, and defer raw operations with `Unit` operands to its reflected
   operators.
@@ -567,7 +591,7 @@ python -m pip install sympy
 | Class | Import module | Purpose |
 | --- | --- | --- |
 | `si` / `SI` | `unitx.si` | Ready-to-use units and physical constants |
-| `Quantity` | `unitx.quantity` | Scalar values paired with units, conversion, and arithmetic |
+| `Quantity` | `unitx.quantity` | Scalar or NumPy magnitudes paired with units, conversion, and arithmetic |
 | `Unit` | `unitx.unit` | Compound units, scaling factors, and physical dimensions |
 | `ScaledUnit` | `unitx.unit` | Formal unit products with an additional exact scale |
 | `Dimension` | `unitx.dimension` | Seven physical dimensions with rational exponents |

{unitx-0.7.0 → unitx-0.8.0}/README.md

@@ -1,10 +1,14 @@
 # unitx
 
-Write Python formulas with ready-to-use units and physical constants. unitx
-handles scalar quantities, unit conversion, and dimensional analysis, with
-exact rational unit scales and exponents.
+[![PyPI version](https://img.shields.io/pypi/v/unitx)](https://pypi.org/project/unitx/)
+[![Python versions](https://img.shields.io/pypi/pyversions/unitx)](https://pypi.org/project/unitx/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 
-unitx is in early development. Public APIs may change during the 0.x series.
+Write Python formulas with ready-to-use units and physical constants. `unitx`
+handles scalar and optional NumPy quantities, unit conversion, and dimensional
+analysis, with exact rational unit scales and exponents.
+
+`unitx` is in early development. Public APIs may change during the 0.x series.
 
 ## Installation
 
@@ -79,15 +83,17 @@ astronomical units are included. Units and constants can be combined directly:
 
 Both namespaces are read-only and do not need to be instantiated. `si` exposes
 a selection of convenient attributes; other registered prefix combinations
-remain available through `Unit`, for example `Unit('Tm')`. Importing unitx
+remain available through `Unit`, for example `Unit('Tm')`. Importing `unitx`
 initializes the predefined unit catalogue. Defining a custom unit registers its
 text spellings without adding an attribute to `si`.
 
 SI defining constants retain their exact decimal values. Measured constants
 are stored nominal values; measurement uncertainties are not propagated.
 Derived Decimal constants are evaluated in the Decimal context active at
-import. Formulas involving pi use `Decimal(str(math.pi))` as an approximation;
-additional Decimal precision does not add precision to pi.
+import. Pi and the positive roots used by the Wien displacement constants
+(`SI.b` for wavelength and `SI.b_` for frequency) use fixed Decimal
+approximations with about 50 significant digits. Raising the context precision
+does not add accuracy beyond those stored approximations.
 
 ## Constructing units and quantities
 
@@ -245,7 +251,7 @@ meaning rather than acting as string delimiters. Bare compound names are
 not guessed from adjacent words, and ordinary parentheses still group products.
 
 The unit table contains `s`, `m`, `g`, `A`, `K`, `mol`, and `cd`, plus the
-dimensionless identity. Importing unitx also initializes the common units in
+dimensionless identity. Importing `unitx` also initializes the common units in
 `unitx.si`, including named derived units such as `N`. Mass scales are referenced
 to kilograms: `g` has factor `1/1000`, and `kg` has factor `1`.
 
@@ -315,8 +321,9 @@ Bare multiword names are recognized only as complete inputs. For example,
 as a factor; use `[astronomical unit] / arcsec`, symbols, or Unit objects instead.
 
 SI prefixes are enabled by default. `prefixable: PrefixPolicy = True` accepts
-`True` for all spellings, `False` for none, or a tuple of exact symbols, names,
-and aliases supplied in that definition. With a tuple, only the listed
+`True` for all spellings, `False` for none, a single spelling string, or a tuple
+of exact symbols, names, and aliases supplied in that definition. A string such
+as `prefixable='Da'` is equivalent to `prefixable=('Da',)`. Only the selected
 spellings accept prefixes; an empty tuple disables prefixes. Unknown spellings
 and non-string entries are errors. For example,
 `prefixable=('arcsec', 'arcsecond')` enables all SI prefixes on those two
@@ -325,7 +332,7 @@ spellings, while other spellings of that unit remain unprefixable.
 The tuple selects **unit spellings**, not prefix symbols. Prefix names attach
 directly to the first word of a multiword name, as in `kiloastronomical unit`;
 a separate `kilo astronomical unit` is not accepted. `PrefixPolicy` is available
-from `unitx.unitregistry` for annotations and means `bool | tuple[str, ...]`.
+from `unitx.unitregistry` for annotations and means `bool | str | tuple[str, ...]`.
 
 ```pycon
 >>> tick = si.s.define(
@@ -368,10 +375,24 @@ form; `760 * si.mmHg` converts to `si.atm` with value 1 under the library's
 existing pressure convention. Prefixes do not stack: `mmmHg` and `kmmHg` are
 invalid. `kt` retains its meaning as a knot alias; tonne remains unprefixable.
 
-The newly registered `u` denotes the unified atomic mass unit. ASCII micro
-spellings such as `um` still mean micrometres, but now issue `UnitSymbolWarning`
-because `u m` has a separate meaning. Use `µm`, `μm`, or `micrometre` to avoid
-this warning.
+`si.mas` and `si.uas` provide milli- and microarcseconds as namespace shortcuts;
+their registered expressions are `marcsec` and `µarcsec`. The strings `mas`
+and `uas` are not registered aliases. `si.Da` and `si.u` now share one formal
+unit identity; only the spelling `Da` accepts prefixes, such as `kDa`.
+`si.mTorr` is available, and Torr accepts SI prefixes. Tonne uses `t` or
+`tonne`; the ambiguous spelling `ton` is not registered.
+
+`si.rpm` represents rotational frequency: `60 * si.rpm` converts to `si.Hz`
+with value 1. For angular velocity, multiply that frequency by `2 * PI` and
+convert to `si.rad / si.s`; directly converting frequency to `rad/s` does
+not insert the physical factor of 2π. `si.c` is a speed unit equal to the
+speed of light, while `SI.c` is the corresponding physical quantity.
+
+The spelling `u` denotes the unified atomic mass unit when used on its own.
+ASCII micro spellings such as `um` and `us` remain supported without warnings,
+so entering non-ASCII characters is optional. `um`, `µm`, `μm`, and
+`micrometre` all mean micrometres; the explicit product `u m` instead means
+unified atomic mass unit times metre.
 
 Registration raises `UnitRegistryError` if a new spelling, including a generated
 prefixed form, already resolves to a unit or conflicts with another spelling
@@ -527,9 +548,10 @@ python -m pip install sympy
 
 ## Current scope
 
-- **NumPy scalars, arrays, and NumPy operations are not supported yet. NumPy
-  integration is planned.** Structural compatibility with a magnitude protocol
-  does not imply NumPy support.
+- Optional NumPy support accepts plain numeric ndarrays and NumPy numeric
+  scalars. Install `unitx[numpy]`; see the [support matrix and numerical
+  contract](https://github.com/DaitTHU/unitx/blob/v0.8.0/docs/numpy.md). Array operations preserve units, comparisons return
+  masks, and implicit unit stripping and writable `out` are rejected.
 - Custom magnitudes must support scalar arithmetic, return a Python `bool`
   from equality, and defer raw operations with `Unit` operands to its reflected
   operators.
@@ -545,7 +567,7 @@ python -m pip install sympy
 | Class | Import module | Purpose |
 | --- | --- | --- |
 | `si` / `SI` | `unitx.si` | Ready-to-use units and physical constants |
-| `Quantity` | `unitx.quantity` | Scalar values paired with units, conversion, and arithmetic |
+| `Quantity` | `unitx.quantity` | Scalar or NumPy magnitudes paired with units, conversion, and arithmetic |
 | `Unit` | `unitx.unit` | Compound units, scaling factors, and physical dimensions |
 | `ScaledUnit` | `unitx.unit` | Formal unit products with an additional exact scale |
 | `Dimension` | `unitx.dimension` | Seven physical dimensions with rational exponents |

{unitx-0.7.0 → unitx-0.8.0}/conftest.py

@@ -1,9 +1,13 @@
+from importlib.util import find_spec
+
 import pytest
 
 from unitx._numerics import as_fraction
 from unitx.exceptions import InexactFloatWarning
 from unitx.factor import Factor
 
+collect_ignore = ['src/unitx/_numpy.py'] if find_spec('numpy') is None else []
+
 _DOCTEST_FILTER: dict[str, tuple[pytest.MarkDecorator, ...]] = {
     f'{obj.__module__}.{obj.__qualname__}': tuple(
         pytest.mark.filterwarnings(f'ignore::{warning.__module__}.{warning.__qualname__}')

unitx-0.8.0/docs/numpy.md

@@ -0,0 +1,133 @@
+# NumPy support
+
+Install `unitx[numpy]` for NumPy >= 2.1. Core imports and Python scalar
+arithmetic do not import NumPy.
+
+```python
+import numpy as np
+from unitx import Quantity, Unit
+
+metre = Unit('m')
+a = np.arange(6.0).reshape(2, 3)
+q = a * metre
+assert q.value is a and (metre * a).value is a
+speed = q / Quantity(2, 's')
+centimetres = q.value_in('cm')
+column_means = np.mean(q, axis=0)
+mask = q > Quantity(100, 'cm')
+```
+
+One Quantity holds one unit for its entire magnitude. Supported magnitudes
+are plain ndarrays and NumPy numeric scalars with integer, floating, or complex
+dtype. Object, boolean, string, structured, datetime, masked arrays, ndarray
+subclasses, and other backends are unsupported. Boolean arrays are accepted
+as masks and returned by predicates. Construct ndarrays explicitly: list/tuple
+magnitudes and implicit Fraction/Decimal object arrays are rejected.
+
+## Values, storage, and precision
+
+`.value`, `.value_in(unit)`, and `.to(unit).value` are explicit numerical exits.
+`np.asarray(q)` and `np.array(q)` raise TypeError even for dimensionless q;
+use `np.asarray(q.value_in(target_unit))`.
+
+Construction, unit-only multiplication/division, and an identity conversion
+preserve the magnitude object. Factor/SymbolicConstant operands change the
+exact unit scale. Indexing, iteration, `.T`, reshape, and transpose follow
+NumPy's scalar/view/copy rules; `.flatten(order='C')` copies. Zero-dimensional
+arrays cannot be iterated. `.shape`, `.ndim`, `.dtype`, and `.size` are available
+for NumPy magnitudes. Python scalars do not acquire array attributes. Exposed
+values and views may share writable storage.
+
+Unit algebra stays exact. Nonidentity conversion uses `np.multiply`: integral
+rational ratios become Python int multipliers; nonintegral rational ratios
+become one Python float multiplier; irrational ratios use Factor's approximate
+value. NumPy controls dtype promotion, rounding, and overflow. Conversion
+allocates and never writes to the input. Integer overflow, multiplier
+conversion errors, and float overflow/underflow remain possible, including for
+extended precision inputs. Conversion never creates Fraction/Decimal arrays.
+
+Comparisons broadcast and return bare boolean results. Equal unit factors
+compare native values; otherwise both operands convert to coherent SI values.
+Different dimensions yield False equality / True inequality masks; ordering
+raises DimensionError. Bare numbers/arrays are dimensionless. These numerical
+rules are distinct from Python scalar Quantity's exact comparison and hash
+rules. All NumPy magnitudes, including scalars and zero-dimensional arrays,
+produce unhashable Quantities. `bool(q)` delegates to `bool(q.value)`.
+
+## Support matrix
+
+Unit-bearing results are Quantities, including dimensionless values and scalar
+reductions. Predicates and indices are bare results. Unsupported functions,
+methods, mixed array types, and keywords fail explicitly.
+
+| ufunc / Python operation | Result rule |
+| --- | --- |
+| add, subtract / `+`, `-` | Align compatible dimensions to the first Quantity's unit |
+| multiply, divide/true_divide, matmul / `*`, `/`, `@` | Combine units |
+| equal, not_equal, less, less_equal, greater, greater_equal / comparisons | Bare boolean results |
+| positive, negative, absolute, fabs, conjugate / unary `+`, `-`, `abs` | Preserve unit |
+| square, sqrt, cbrt, reciprocal | Exact unit exponents 2, 1/2, 1/3, -1 |
+| power, float_power / `**` | Dimensional bases require a finite real scalar exponent; dimensionless bases/exponents normalize their scales |
+| sin, cos, tan, exp, expm1, log, log2, log10, log1p | Require coherent dimensionless values; return dimensionless Quantity |
+| isfinite, isnan, isinf, signbit | Bare boolean results |
+| add.reduce, add.accumulate | Preserve unit; accept axis and dtype, plus keepdims for reduce |
+
+Ufunc `__call__` accepts `where`, `dtype`, `casting`, `order`, `subok`, and empty
+`out`. Each kernel validates its own options. `where` is a bare boolean scalar
+or plain boolean ndarray; masked-out positions without an output buffer follow
+NumPy's uninitialized-result behavior. Numeric outputs must stay in the
+supported dtype domain. Product reductions, at, outer, and reduceat are
+unsupported. Python `**` also accepts Fraction/Decimal exponents, retaining
+exact unit exponents while passing a float exponent to the NumPy kernel.
+Angles retain unitx's dimensionless model: deg/rad normalize before these
+functions, including exp/log. Python scalar numerical semantics remain native.
+
+| NumPy function | Unit/result rule | Supported options |
+| --- | --- | --- |
+| reshape, transpose | Preserve unit | shape/order/copy; axes |
+| concatenate, stack | Convert to first Quantity's unit; bare arrays remain dimensionless | axis, dtype, casting |
+| sum, mean | Preserve unit | axis, dtype, keepdims |
+| median | Preserve unit | axis, keepdims; overwrite_input=False |
+| std, var | Preserve unit / square unit | axis, dtype, ddof, keepdims |
+| cumsum | Preserve unit | axis, dtype |
+| argmin, argmax | Bare indices | axis, keepdims |
+| isclose, allclose | Bare mask / Python bool | rtol, atol, equal_nan |
+
+Supply the first magnitude argument positionally; concatenate/stack take a
+sequence. Options follow each supported signature, including positional out
+checks. Writable `out` and overwrite_input=True are rejected. Unsupported
+initial, statistical where, mean, correction, and other keywords raise TypeError.
+There is no `__setitem__`; `q += other` creates a result and rebinds q.
+
+## Close comparisons and typing
+
+`q.isclose(other, rel_tol=1e-9, abs_tol=0)` uses the symmetric formula in
+coherent SI coordinates:
+`abs(a-b) <= max(rel_tol * max(abs(a), abs(b)), abs_tol)`.
+`np.isclose` instead uses `abs(a-b) <= atol + rtol*abs(b)` with defaults
+rtol=1e-5 and atol=1e-8; `np.allclose` reduces that mask. Tolerances broadcast
+and must be finite, nonnegative, and real. Relative tolerance is dimensionless;
+absolute tolerance matches the operands' dimension. Nonzero bare absolute
+tolerance is dimensionless, so dimensional `np.isclose` calls need a Quantity
+atol or zero. Matching infinities are close; NaNs require equal_nan=True.
+The NumPy path enters at least float64 before subtraction, preserving
+longdouble when present; large integers may lose precision. Mixed NumPy
+operations require supported arrays/scalars or Python int/float/complex.
+
+```python
+np.isclose(q, Quantity(a * 100, 'cm'), atol=Quantity(1e-8, 'm'))
+q.isclose(Quantity(a * 100, 'cm'), abs_tol=Quantity(1e-8, 'm'))
+```
+
+`_numerics.py` defines `Scalar`, `Array`, and `Magnitude = Scalar | Array`
+without importing NumPy. Array is a typing protocol, not a guarantee of other
+backend support. Construction and unit-only operators preserve Quantity[T];
+numerical array results conservatively use Array. NumPy's left-operand and
+function stubs cannot generally infer wrapped unitx results; use
+Quantity(array, unit) or unit * array for precise construction types. Arbitrary
+shape/dtype inference is not promised. NumPy-free scalar consumers retain
+working type hints.
+
+References: [NumPy dispatch](https://numpy.org/doc/stable/reference/arrays.classes.html),
+[promotion](https://numpy.org/doc/stable/reference/arrays.promotion.html),
+[isclose](https://numpy.org/doc/stable/reference/generated/numpy.isclose.html).

{unitx-0.7.0 → unitx-0.8.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = 'hatchling.build'
 
 [project]
 name = 'unitx'
-version = '0.7.0'
+version = '0.8.0'
 description = 'A modern, intuitive Python library for units, quantities, and dimensional analysis.'
 readme = 'README.md'
 requires-python = '>=3.12'
@@ -23,6 +23,7 @@ classifiers = [
 
 [project.optional-dependencies]
 test = ['pytest>=8', 'ruff>=0.8', 'pyright>=1.1.414']
+numpy = ['numpy>=2.1']
 
 [project.urls]
 Homepage = 'https://github.com/DaitTHU/unitx'

{unitx-0.7.0 → unitx-0.8.0}/pyrightconfig.json

@@ -1,6 +1,7 @@
 {
   "include": [
     "src/unitx/quantity.py",
+    "src/unitx/_numpy.py",
     "src/unitx/_numerics.py",
     "src/unitx/factor.py",
     "src/unitx/unit.py",

unitx-0.8.0/pyrightconfig.numpy.json

@@ -0,0 +1,5 @@
+{
+  "extends": "./pyrightconfig.json",
+  "include": ["tests/numpy_typing"],
+  "strict": ["tests/numpy_typing"]
+}

unitx-0.8.0/src/unitx/_constnamespace.py

@@ -0,0 +1,33 @@
+"""Class-based namespaces for constants accessed directly as class attributes.
+
+Namespaces cannot be instantiated, and their attributes cannot be rebound or
+deleted. Objects referenced by those attributes are not recursively frozen.
+"""
+
+from typing import Any, NoReturn
+
+__all__ = ['ConstNamespace']
+
+
+class _ConstNamespaceMeta(type):
+    def __call__(metacls, *args: Any, **kwds: Any) -> NoReturn:
+        """
+        This namespace cannot be instantiated; access constants via class attributes.
+        """
+        raise TypeError(metacls.__call__.__doc__)
+
+    def __setattr__(cls, name, value) -> NoReturn:
+        """
+        Constant namespace attributes cannot be assigned.
+        """
+        raise AttributeError(cls.__class__.__setattr__.__doc__)
+
+    def __delattr__(cls, name) -> NoReturn:
+        """
+        Constant namespace attributes cannot be deleted.
+        """
+        raise AttributeError(cls.__class__.__delattr__.__doc__)
+
+
+class ConstNamespace(metaclass=_ConstNamespaceMeta):
+    """Base for constant namespaces with protected class attribute bindings."""