unitx 0.6.2__tar.gz → 0.7.0__tar.gz

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

@@ -1,5 +1,94 @@
 # Changelog
 
+## [0.7.0] - 2026-10-19
+
+### Added
+
+- Add `[registered name]` references as single factors in unit expressions,
+  including products, reciprocals, parentheses, and rational powers. References
+  resolve names and name aliases only, with whitespace normalization and no
+  expression evaluation or nested quoting.
+- Support standalone hyphenated names and adjacent Unicode integer superscripts
+  such as `m²`, `s⁻¹²`, and `[metre]²`.
+- Extend `prefixable: PrefixPolicy = True` on all `.define()` entry points to
+  accept a tuple of exact registered symbols, names, or aliases. Only those
+  spellings accept prefixes; True enables all spellings and False or () disables
+  all spellings. `PrefixPolicy` is `bool | tuple[str, ...]`.
+- Enable prefixes on `arcsec` and `arcsecond` while keeping angle punctuation
+  unprefixable. Register unprefixable are (`a`) and hectare (`ha`), and reactive
+  power (`var`, name `volt-ampere reactive`). Keep `as` as attosecond and `yr`
+  as a 365-day year.
+- Add the Julian year `a_j` (exactly 31,557,600 seconds) and its twelfth,
+  `mo`, as a fixed month interval distinct from variable calendar months.
+- Add light year (`ly`), unified atomic mass unit (`u`), and common prefixed
+  namespace attributes, including attosecond (`as_`) and petaelectronvolt (`PeV`).
+
+### Changed
+
+- Move definitions, spelling resolution, and registration validation into
+  `unitx.unitregistry`, shared by SingleUnit and UnitParser. Preserve formal identities,
+  exact SI factors, existing `.define()` defaults, and validation before mutation.
+- Remove the superseded private `_unit_data` module. Name definition records
+  `PrefixDefinition` and `UnitDefinition`, with explicit definition indexes and
+  alias-to-symbol mappings.
+- Select permitted canonical output spellings after applying binding policies.
+  When only a name permits a prefix, expressions use `[name]` so repr and pickle
+  preserve the prefixed identity. Expose `PrefixPolicy` for type annotations.
+- Use the finite spelling exceptions `megohm` and `kilohm` in preferred names,
+  retaining `megaohm` and `kiloohm` as accepted inputs.
+- Reuse Unicode superscript tables, handle malformed name brackets through
+  the common lexical error path, and simplify definition initialization,
+  preferred spelling selection, and generated prefix-name validation.
+- Share coherent SI units and the seven defining constants through private
+  bases. Derive `ly` from `c` and the Julian year, and `eV` from `e` and `V`,
+  preserving the public `si` and `SI` namespaces and constant magnitude types.
+
+### Fixed
+
+- Register metre of mercury (`mHg`) as the prefixable unit and construct `mmHg`
+  from its milli prefix. Preserve `760 mmHg = 1 atm` and the existing Torr scale,
+  keep the definition exact, and reject stacked prefixes such as `kmmHg`.
+
+### Migration
+
+- Square brackets and `⁰¹²³⁴⁵⁶⁷⁸⁹⁺⁻` are now reserved grammar characters and can
+  no longer occur in registered symbols or names. Rename custom spellings that
+  previously used them before rebuilding or unpickling those definitions.
+- Long names remain whole-input lookups unless explicitly referenced in brackets.
+  `str()` remains readable display and is not a general serialization format;
+  use `expression()` for formal unit products and repr for ScaledUnit state.
+- `mmHg` now has the formal identity of milli-prefixed `mHg`; rebuild stored
+  units when moving between versions. Its pressure conversion scale is unchanged.
+  `kmmHg` and names with repeated prefixes are no longer accepted.
+- Registering `u` makes ASCII micro spellings such as `um` issue the existing
+  ambiguity warning. Their meaning is unchanged; use `µm`, `μm`, or `micrometre`
+  to avoid the warning. `kt` remains a knot alias and tonne stays unprefixable.
+
+## [0.6.3] - 2026-10-18
+
+### Added
+
+- Add `Quantity.value_in(unit)` to return the same magnitude and concrete type as `.to(unit).value` without constructing a temporary quantity. The target unit is required and accepts a string or Unit, including ScaledUnit.
+- Add `Quantity.isclose()` for symmetric real scalar comparisons with relative and absolute tolerances in coherent SI units. Nonzero absolute tolerances for dimensional quantities must carry matching units. Rational coefficients remain exact; residual irrational factors are approximated. Zero tolerances use exact equality.
+- Make quantity truth values follow their magnitudes, so zero quantities are false regardless of unit.
+
+### Changed
+
+- Apply native magnitude operators in operand order for arithmetic, unary operations, and numerical powers, preserving numerical promotion, Decimal contexts, signals, and exceptions. Support the scalar operand types accepted by the magnitude, including complex values and custom scalars.
+- Keep Decimal conversions and arithmetic in Decimal. Rational conversions combine the magnitude and scale exactly before rounding once in the active context; identity conversions preserve the original magnitude. Addition and subtraction align integer operands in the Decimal domain when paired with Decimal magnitudes. Derived SI constants use Decimal arithmetic and `Decimal(str(math.pi))` where an approximate pi is required, with evaluation in the context active at import.
+- Interpret float formal exponents by their shortest decimal text, without a denominator limit, consistently across Monomial, Dimension, Factor, SymbolicConstant, Unit, and Quantity. For example, `0.1` represents `1/10` and `1e-10` remains nonzero. Numeric scale inputs to Factor retain their existing denominator-limit and warning rules.
+- Cache rationalized Factor decompositions lazily, independently of numerical value evaluation, while preserving equality, hashing, copying, and serialization.
+- Update public type hints, examples, and regression coverage for conversion, native arithmetic, comparisons, and formal exponents.
+
+### Fixed
+
+- Preserve native comparisons, including independent `!=`, Decimal signals, and complex ordering errors, when unit factors agree. Across different factors, compare builtin real values and complex components using exact coefficients, retaining consistent hashes for equal quantities and native unhashability for custom magnitudes.
+
+### Migration
+
+- Decimal arithmetic no longer converts operands to Fraction automatically. Mixing Decimal with float or Fraction in arithmetic now raises the native TypeError; explicitly choose a common numerical type when needed. Decimal conversion and derived SI constants can therefore have different result types and rounding from earlier releases.
+- Quantity numerical powers use the original exponent object; for example, an integer magnitude raised to `2.0` produces a float. Use `Fraction(1, 3)` for an exactly one-third formal exponent: the float `1 / 3` now represents the decimal `0.3333333333333333` and does not simplify as exactly one third.
+
 ## [0.6.2] - 2026-10-18
 
 ### Added

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: unitx
-Version: 0.6.2
+Version: 0.7.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
@@ -107,8 +107,9 @@ 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 constants involving numerical approximations, such as `math.pi`, are
-evaluated numerically.
+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.
 
 ## Constructing units and quantities
 
@@ -192,16 +193,23 @@ grouped denominator factors and multiplication dots between adjacent numbers.
 
 ## Conversion and arithmetic
 
-Use `.to()` to convert between units with the same physical dimensions.
+Use `.to()` to obtain a new quantity in a unit with the same physical dimensions,
+or `.value_in(unit)` to obtain only its numerical value. The target unit is
+required and accepts a string or `Unit`, including `ScaledUnit`.
+`.value_in(unit)` returns the same value and concrete type as `.to(unit).value`,
+without constructing a temporary quantity. Both follow the conversion rules
+below. A conversion with scale one preserves the original magnitude; Decimal
+magnitudes stay Decimal and other conversions can change the numerical type.
+`.value` reads the original stored magnitude.
 Addition and subtraction convert the right operand to the left operand's unit:
 
 ```pycon
 >>> length = Quantity(1, 'm')
 >>> print(length + Quantity(50, 'cm'))
 3/2 m
->>> length.to('cm').value
+>>> length.value_in('cm')
 100
->>> Quantity(1, 'cm').to('m').value
+>>> Quantity(1, 'cm').value_in('m')
 Fraction(1, 100)
 
 ```
@@ -238,14 +246,25 @@ False
   token: `ms` is a millisecond, while `m s` is metre times second.
 - Powers can use adjacent numbers, `^`, or `**`. Exponents written as ratios
   require parentheses, as in `m^(1/2)`; decimal exponents such as `m^0.5` are exact.
+  Adjacent integer superscripts are also accepted: `m²`, `s⁻¹²`, and `(m/s)²`.
+  Superscript fractions and mixed exponent notations are not supported.
 - Multiplication and division associate left to right. Use `m/(s A)` to put
   both `s` and `A` in the denominator; `m/s A` means `(m/s)*A`.
 - Unit symbols and names are case-sensitive. `u`, `µ`, and `μ` are accepted
   micro prefixes. Use lowercase `k` for kilo; `K` denotes kelvin.
-- A registered multiword name is recognized before implicit multiplication
+- A registered multiword or hyphenated name is recognized before implicit multiplication
   when it occupies the entire input. Whitespace between its words is treated
-  as a single space. Inside products, parentheses, reciprocals, and powers,
-  use its symbol or combine `Unit` objects instead.
+  as a single space. Inside expressions, use `[name]` to make a name one factor,
+  for example `[astronomical unit] / s` or `[volt-ampere reactive]**2`.
+  Symbols and `Unit` object composition remain available.
+
+Square brackets reference registered names and name aliases only: `[metre]`
+works, while `[m]` and `[m/s]` do not. The contents are never evaluated as an
+expression. Empty, nested, and unmatched brackets are errors. Put permitted
+name prefixes inside the brackets, as in `[kiloastronomical unit]`; `k[name]`
+does not apply a prefix. Single and double quotes retain their angle-unit
+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
@@ -295,9 +314,10 @@ aliases gives an empty tuple. `symbol_aliases` accepts a string or tuple of
 strings; it and `prefixable` must be passed by keyword.
 Symbols and symbol aliases must each be a single printable unit token.
 Names and name aliases may contain multiple such tokens separated by single
-ASCII spaces, without leading or trailing spaces. Decimal digits and parser
-operators are not allowed in any token. The primary symbol and `name` are
-required and must be nonempty; empty aliases are ignored.
+ASCII spaces or hyphens, without leading or trailing separators. Decimal digits
+and parser operators are not allowed in any token. The primary symbol and `name` are
+required and must be nonempty; empty aliases are ignored. Square brackets and
+the superscript characters `⁰¹²³⁴⁵⁶⁷⁸⁹⁺⁻` are reserved for parser syntax.
 
 ```pycon
 >>> span = (2 * si.m).define('span', 'survey span', 'survey distance')
@@ -307,22 +327,86 @@ True
 True
 >>> Unit('survey span') / si.s == Unit('span / s')
 True
+>>> Unit('[survey span] / [second]') == Unit('span / s')
+True
 
 ```
 
-Multiword names are recognized only as complete inputs. For example,
+Bare multiword names are recognized only as complete inputs. For example,
 `Unit('astronomical unit / arcsec')` does not recognize `astronomical unit`
-as a factor; use one of the two compound forms above instead.
+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
+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
+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, ...]`.
+
+```pycon
+>>> tick = si.s.define(
+...     'demoTick',
+...     'survey interval',
+...     symbol_aliases='demoT',
+...     prefixable=('demoT', 'survey interval'),
+... )
+>>> Unit('[millisurvey interval]') == Unit('mdemoT')
+True
+>>> Quantity(1000, 'mdemoT').to(tick).value
+Fraction(1, 1)
+>>> Unit('mdemoT').expression()
+'mdemoT'
+
+```
+
+Prefix permissions are checked before alias normalization. Canonical identity
+still uses the original registered unit and canonical prefix, independent of
+the input alias. Preferred spellings use the first permitted symbol or alias;
+if only a name supports a prefix, `SingleUnit.symbol` falls back to that name
+and `Unit.expression()` emits a `[name]` reference. Conversely, `SingleUnit.name`
+falls back to a symbol if no name allows that prefix. Repr and pickle preserve
+the same formal unit, rather than replacing the prefix with an extra scale.
+
+`arcsec` and `arcsecond` accept prefixes, for example `marcsec` and
+`milliarcsecond`; `″` and `"` do not. `as` continues to mean attosecond,
+and `mas` is not an arcsecond alias. `a` (are) and `ha` (hectare) are separate
+unprefixable units; `Pa` remains pascal. `yr` remains exactly 365 days.
+`a_j` is the Julian year of exactly 365.25 days (31,557,600 seconds), while
+`mo` is one twelfth of that interval, rather than a variable calendar month.
+The name exceptions `megohm` and `kilohm` are supported alongside the older
+`megaohm` and `kiloohm` spellings; `gigaohm` retains both vowels. No general
+vowel-elision rule is applied.
+
+`ly` is defined using the speed of light and the Julian year; `eV` uses the
+elementary charge and volt. Both reuse the defining constants exposed by `SI`.
+`mHg` is the registered metre-of-mercury unit and `mmHg` is its milli-prefixed
+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 prefixes are enabled by default; set `prefixable=False` to disable them.
-Prefix names attach directly to the first word of a multiword name, as in
-`kiloastronomical unit`; a separate `kilo astronomical unit` is not accepted.
 Registration raises `UnitRegistryError` if a new spelling, including a generated
 prefixed form, already resolves to a unit or conflicts with another spelling
 in the same definition. A multiword spelling must not replace an existing
 implicit product such as `metre second`. Validation finishes before the
 registry changes.
 
+The registry and spelling rules live in `unitx.unitregistry`; parsing expressions
+does not change unit definitions. A parser instance caches only a successful
+result; failed parses may be retried after a definition is added. Registration
+preserves existing valid spellings and validates before updating its indexes.
+Concurrent registry writes and isolated registry contexts are not supported.
+
 Quantity definitions require positive finite `int`, `Fraction`, `Decimal`, or
 `float` magnitudes. Prefer `Fraction` or `Decimal` for exact scales. Floats use
 Factor's denominator limit and can warn or round to zero and fail, for example
@@ -368,29 +452,90 @@ Fraction(1001, 1)
 
 Exact unit algebra and numerical magnitude evaluation have different rules:
 
-- Rational unit scales and exponents remain exact. Prefer `Fraction` or
-  `Decimal` for exact exponents; float exponents may be approximated with an
-  `InexactFloatWarning`.
-- Conversion and arithmetic can change the magnitude's type. Finite `Decimal`
-  operands are converted exactly to `Fraction`, without Decimal context
-  rounding.
-- Other magnitudes use native numerical arithmetic. In particular, integer
-  division produces a float, and nonintegral magnitude powers can round or
-  produce complex values.
+- Formal exponents use one rule in Monomial, Dimension, Factor, Unit, and
+  Quantity: int/Fraction/Decimal values stay exact; floats use their shortest
+  decimal text without a denominator limit. Thus `0.1` means `1/10` and
+  `1e-10` remains nonzero. Use `Fraction(1, 3)` for exactly one third:
+  the float `1 / 3` means the decimal `0.3333333333333333` in formal exponents.
+  Factor's numeric scale inputs retain their separate denominator-limit rules.
+- Quantity handles units; the magnitudes determine numerical arithmetic.
+  Operators use the magnitudes in operand order and preserve native promotion,
+  rounding, signals, and exceptions. Decimal arithmetic returns Decimal and
+  follows its active context. Mixing Decimal with float or Fraction raises
+  `TypeError`, as it does for the bare numbers; choose a common numerical type
+  explicitly when needed.
+- Conversion with a rational scale keeps int/Fraction values exact. Decimal
+  conversion combines the value and scale exactly internally, then rounds once
+  to Decimal in the active context. Irrational unit scales are approximated as
+  floats, using their shortest decimal representations for Decimal conversion.
+  A scale of one preserves the magnitude without arithmetic or rounding.
+  Direct `Factor(value)` retains its separate exact Fraction evaluation rules.
+- Addition and subtraction align the right operand with the left quantity's
+  unit before numerical arithmetic. Integers being aligned with a Decimal
+  magnitude are scaled in the Decimal domain, so `Decimal('1') * si.m + 50 *
+  si.cm` returns a Decimal magnitude of `1.5`. Explicit Fraction/float operands
+  keep their own numerical domains. Finite-precision conversion and arithmetic
+  can round; changing the result unit can therefore change rounding errors.
+- Unary `+` and `-` apply the magnitude's native operators and preserve the unit.
+  Decimal results remain Decimal and follow its context precision, rounding,
+  signals, and exceptions; unary `+` can therefore change the numerical value.
+- Integer division produces a float; Fraction arithmetic remains rational.
+  Use Fraction magnitudes explicitly for exact rational results. Powers pass
+  the original exponent to the magnitude: `2 ** 2.0` returns float and
+  `2 ** Decimal('0.5')` returns Decimal. Decimal magnitudes require int or
+  Decimal exponents, as in Python. The unit follows the common formal exponent
+  rule above; numerical evaluation still uses the original exponent object.
+  Exponents must be finite real scalars other than bool. Numerical powers can
+  round or produce complex values, following the magnitude's rules.
+- Truth values follow the magnitude, so zero quantities are false regardless
+  of unit. Comparisons with equal unit factors use native magnitude operators,
+  including independent `!=`, Decimal signals/exceptions and complex ordering
+  errors. For different unit factors, builtin real values and complex
+  components are aligned exactly to avoid rounding-dependent equality or
+  hashes. Ordinary numeric subclasses use the same alignment as their base
+  types. Decimal/float signals apply to native comparisons with equal factors;
+  cross-factor alignment compares exact rational coefficients and does not
+  perform an additional comparison merely to reproduce signals. Decimal/Fraction
+  comparisons are supported natively.
 - Equality is exact, without a tolerance. Finite floats are compared as their
   stored binary rational values. Floating-point conversions and irrational
-  powers may round; compare their values approximately in a common unit when
-  appropriate.
+  powers may round; use `isclose()` for approximate real scalar comparisons.
+  It uses the symmetric condition
+  `abs(a - b) <= max(rel_tol * max(abs(a), abs(b)), abs_tol)` in coherent SI
+  units, with defaults `rel_tol=1e-9` and `abs_tol=0`. Swapping quantities
+  preserves the result. Nonzero absolute tolerances for dimensional quantities
+  must carry matching units; plain operands and plain absolute tolerances
+  represent unscaled dimensionless values. Tolerances must be finite and
+  nonnegative. Different dimensions raise `DimensionError`. NaNs are never
+  close, and infinities are close only to infinities of the same sign.
+  Finite rational coefficients stay exact; residual irrational unit factors
+  are approximated. With both tolerances zero, `isclose()` uses exact equality.
 
 ```pycon
->>> from decimal import Decimal
+>>> from decimal import Decimal, localcontext
 >>> from fractions import Fraction
+>>> with localcontext() as context:
+...     context.prec = 2
+...     q = Quantity(Decimal('1.2345'), 'm')
+...     print((+q).value, (-q).value, (q * 2).value)
+1.2 -1.2 2.5
 >>> Quantity(Decimal('0.1'), 'm').to('cm').value
-10
+Decimal('10')
 >>> (Quantity(Fraction(1), 'm') / Quantity(3, 's')).value
 Fraction(1, 3)
+>>> (Quantity(2, 'm') ** 2.0).value
+4.0
+>>> bool(Quantity(0, 'm'))
+False
 >>> Quantity(0.1, '') == Quantity(Fraction(1, 10), '')
 False
+>>> Quantity(0.1 + 0.2, 'm').isclose(Quantity(0.3, 'm'))
+True
+>>> a, b = Quantity(1, 'm'), Quantity(100.05, 'cm')
+>>> a.isclose(b, rel_tol=0, abs_tol=Quantity(1, 'mm'))
+True
+>>> b.isclose(a, rel_tol=0, abs_tol=Quantity(1, 'mm'))
+True
 
 ```
 
@@ -410,9 +555,10 @@ python -m pip install sympy
 - Custom magnitudes must support scalar arithmetic, return a Python `bool`
   from equality, and defer raw operations with `Unit` operands to its reflected
   operators.
-- Scalar multiplication and division of quantities currently accept `int`,
-  `float`, `Fraction`, and `Decimal`. Complex magnitudes are supported, including
-  results of fractional powers; ordering follows the magnitude's native rules.
+- Scalar operations use the magnitude's supported operand types, including
+  complex numbers and custom scalar magnitudes. Custom magnitudes must also
+  defer operations with Quantity operands so that Quantity can handle units.
+  Ordering follows the magnitude's native rules.
 - Unit conversion is multiplicative. Offset temperature scales such as Celsius
   and Fahrenheit are not supported.