ucon 2.2.1__tar.gz → 2.2.2__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (89) hide show
  1. {ucon-2.2.1 → ucon-2.2.2}/CHANGELOG.md +63 -0
  2. {ucon-2.2.1/ucon.egg-info → ucon-2.2.2}/PKG-INFO +1 -1
  3. {ucon-2.2.1 → ucon-2.2.2}/ROADMAP.md +34 -3
  4. {ucon-2.2.1 → ucon-2.2.2}/ucon/__init__.py +2 -0
  5. {ucon-2.2.1 → ucon-2.2.2}/ucon/core/__init__.py +2 -0
  6. {ucon-2.2.1 → ucon-2.2.2}/ucon/core/_types.py +76 -3
  7. {ucon-2.2.1 → ucon-2.2.2}/ucon/core/exceptions.py +61 -0
  8. {ucon-2.2.1 → ucon-2.2.2/ucon.egg-info}/PKG-INFO +1 -1
  9. {ucon-2.2.1 → ucon-2.2.2}/ucon.egg-info/scm_version.json +2 -2
  10. {ucon-2.2.1 → ucon-2.2.2}/.github/workflows/downstream.yaml +0 -0
  11. {ucon-2.2.1 → ucon-2.2.2}/.github/workflows/publish.yaml +0 -0
  12. {ucon-2.2.1 → ucon-2.2.2}/.github/workflows/tests.yaml +0 -0
  13. {ucon-2.2.1 → ucon-2.2.2}/.gitignore +0 -0
  14. {ucon-2.2.1 → ucon-2.2.2}/.gitmodules +0 -0
  15. {ucon-2.2.1 → ucon-2.2.2}/LICENSE +0 -0
  16. {ucon-2.2.1 → ucon-2.2.2}/MANIFEST.in +0 -0
  17. {ucon-2.2.1 → ucon-2.2.2}/Makefile +0 -0
  18. {ucon-2.2.1 → ucon-2.2.2}/NOTICE +0 -0
  19. {ucon-2.2.1 → ucon-2.2.2}/README.md +0 -0
  20. {ucon-2.2.1 → ucon-2.2.2}/SECURITY.md +0 -0
  21. {ucon-2.2.1 → ucon-2.2.2}/SUPPORT.md +0 -0
  22. {ucon-2.2.1 → ucon-2.2.2}/mkdocs.yml +0 -0
  23. {ucon-2.2.1 → ucon-2.2.2}/netlify.toml +0 -0
  24. {ucon-2.2.1 → ucon-2.2.2}/pyproject.toml +0 -0
  25. {ucon-2.2.1 → ucon-2.2.2}/requirements.txt +0 -0
  26. {ucon-2.2.1 → ucon-2.2.2}/setup.cfg +0 -0
  27. {ucon-2.2.1 → ucon-2.2.2}/ucon/_active.py +0 -0
  28. {ucon-2.2.1 → ucon-2.2.2}/ucon/_algebra_cache.py +0 -0
  29. {ucon-2.2.1 → ucon-2.2.2}/ucon/_bootstrap.py +0 -0
  30. {ucon-2.2.1 → ucon-2.2.2}/ucon/_cache.py +0 -0
  31. {ucon-2.2.1 → ucon-2.2.2}/ucon/aspects/__init__.py +0 -0
  32. {ucon-2.2.1 → ucon-2.2.2}/ucon/aspects/exceptions.py +0 -0
  33. {ucon-2.2.1 → ucon-2.2.2}/ucon/aspects/forest.py +0 -0
  34. {ucon-2.2.1 → ucon-2.2.2}/ucon/aspects/resolution.py +0 -0
  35. {ucon-2.2.1 → ucon-2.2.2}/ucon/aspects/types.py +0 -0
  36. {ucon-2.2.1 → ucon-2.2.2}/ucon/basis/__init__.py +0 -0
  37. {ucon-2.2.1 → ucon-2.2.2}/ucon/basis/builtin.py +0 -0
  38. {ucon-2.2.1 → ucon-2.2.2}/ucon/basis/graph.py +0 -0
  39. {ucon-2.2.1 → ucon-2.2.2}/ucon/basis/ops.py +0 -0
  40. {ucon-2.2.1 → ucon-2.2.2}/ucon/basis/transforms.py +0 -0
  41. {ucon-2.2.1 → ucon-2.2.2}/ucon/basis/types.py +0 -0
  42. {ucon-2.2.1 → ucon-2.2.2}/ucon/basis/vector.py +0 -0
  43. {ucon-2.2.1 → ucon-2.2.2}/ucon/checking.py +0 -0
  44. {ucon-2.2.1 → ucon-2.2.2}/ucon/comprehensive.ucon.toml +0 -0
  45. {ucon-2.2.1 → ucon-2.2.2}/ucon/constants.py +0 -0
  46. {ucon-2.2.1 → ucon-2.2.2}/ucon/constants.pyi +0 -0
  47. {ucon-2.2.1 → ucon-2.2.2}/ucon/contexts.py +0 -0
  48. {ucon-2.2.1 → ucon-2.2.2}/ucon/conversion.py +0 -0
  49. {ucon-2.2.1 → ucon-2.2.2}/ucon/core/_parsing_graph.py +0 -0
  50. {ucon-2.2.1 → ucon-2.2.2}/ucon/dimension.py +0 -0
  51. {ucon-2.2.1 → ucon-2.2.2}/ucon/dimension.pyi +0 -0
  52. {ucon-2.2.1 → ucon-2.2.2}/ucon/expressions.py +0 -0
  53. {ucon-2.2.1 → ucon-2.2.2}/ucon/formulas/__init__.py +0 -0
  54. {ucon-2.2.1 → ucon-2.2.2}/ucon/formulas/exceptions.py +0 -0
  55. {ucon-2.2.1 → ucon-2.2.2}/ucon/formulas/registry.py +0 -0
  56. {ucon-2.2.1 → ucon-2.2.2}/ucon/formulas/types.py +0 -0
  57. {ucon-2.2.1 → ucon-2.2.2}/ucon/graph.py +0 -0
  58. {ucon-2.2.1 → ucon-2.2.2}/ucon/integrations/__init__.py +0 -0
  59. {ucon-2.2.1 → ucon-2.2.2}/ucon/integrations/numpy.py +0 -0
  60. {ucon-2.2.1 → ucon-2.2.2}/ucon/integrations/pandas.py +0 -0
  61. {ucon-2.2.1 → ucon-2.2.2}/ucon/integrations/polars.py +0 -0
  62. {ucon-2.2.1 → ucon-2.2.2}/ucon/integrations/pydantic.py +0 -0
  63. {ucon-2.2.1 → ucon-2.2.2}/ucon/kinds/__init__.py +0 -0
  64. {ucon-2.2.1 → ucon-2.2.2}/ucon/kinds/exceptions.py +0 -0
  65. {ucon-2.2.1 → ucon-2.2.2}/ucon/kinds/lattice.py +0 -0
  66. {ucon-2.2.1 → ucon-2.2.2}/ucon/kinds/types.py +0 -0
  67. {ucon-2.2.1 → ucon-2.2.2}/ucon/maps.py +0 -0
  68. {ucon-2.2.1 → ucon-2.2.2}/ucon/packages.py +0 -0
  69. {ucon-2.2.1 → ucon-2.2.2}/ucon/parsing/__init__.py +0 -0
  70. {ucon-2.2.1 → ucon-2.2.2}/ucon/parsing/aspects.py +0 -0
  71. {ucon-2.2.1 → ucon-2.2.2}/ucon/parsing/dimensions.py +0 -0
  72. {ucon-2.2.1 → ucon-2.2.2}/ucon/parsing/formulas.py +0 -0
  73. {ucon-2.2.1 → ucon-2.2.2}/ucon/parsing/kinds.py +0 -0
  74. {ucon-2.2.1 → ucon-2.2.2}/ucon/parsing/lexer.py +0 -0
  75. {ucon-2.2.1 → ucon-2.2.2}/ucon/parsing/namespaces.py +0 -0
  76. {ucon-2.2.1 → ucon-2.2.2}/ucon/parsing/quantity.py +0 -0
  77. {ucon-2.2.1 → ucon-2.2.2}/ucon/parsing/units.py +0 -0
  78. {ucon-2.2.1 → ucon-2.2.2}/ucon/quantity.py +0 -0
  79. {ucon-2.2.1 → ucon-2.2.2}/ucon/resolver.py +0 -0
  80. {ucon-2.2.1 → ucon-2.2.2}/ucon/serialization.py +0 -0
  81. {ucon-2.2.1 → ucon-2.2.2}/ucon/system/__init__.py +0 -0
  82. {ucon-2.2.1 → ucon-2.2.2}/ucon/units.py +0 -0
  83. {ucon-2.2.1 → ucon-2.2.2}/ucon/units.pyi +0 -0
  84. {ucon-2.2.1 → ucon-2.2.2}/ucon.egg-info/SOURCES.txt +0 -0
  85. {ucon-2.2.1 → ucon-2.2.2}/ucon.egg-info/dependency_links.txt +0 -0
  86. {ucon-2.2.1 → ucon-2.2.2}/ucon.egg-info/requires.txt +0 -0
  87. {ucon-2.2.1 → ucon-2.2.2}/ucon.egg-info/scm_file_list.json +0 -0
  88. {ucon-2.2.1 → ucon-2.2.2}/ucon.egg-info/top_level.txt +0 -0
  89. {ucon-2.2.1 → ucon-2.2.2}/uv.lock +0 -0
@@ -7,6 +7,69 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
7
7
 
8
8
  ## [Unreleased]
9
9
 
10
+ ## [2.2.2] - 2026-09-18
11
+
12
+ ### Fixed
13
+
14
+ - **Comparison and additive arithmetic refuse units they cannot normalize
15
+ instead of ignoring them.** (#313) `_canonical_magnitude` falls back to
16
+ the raw quantity when a unit has no `base_form`, so `__eq__`, `__add__`
17
+ and `__sub__` treated `1` of such a unit as `1` of every other unit in
18
+ its dimension. Three families were affected, wrong in both directions:
19
+
20
+ | expression | before | now |
21
+ |---|---|---|
22
+ | `Number(1, kelvin) == Number(1, celsius)` | `True` | refuses |
23
+ | `Number(0, celsius) == Number(273.15, kelvin)` | `False` | refuses |
24
+ | `Number(180, degree) - Number(pi, radian)` | `176.86 deg` | refuses |
25
+ | `Number(20, decibel) == Number(1, neper)` | `False` | refuses |
26
+
27
+ A new `UnitsNotNormalizable` names both units, the operation, and the
28
+ conversion that resolves it. The relationships exist in the
29
+ `ConversionGraph` — `Number(0, celsius).to(kelvin)` has always returned
30
+ `273.15 K` — but these paths are pure functions of `(quantity, unit)`
31
+ and deliberately consult no graph, so the honest answer is a refusal
32
+ rather than a number. Converting first succeeds as before.
33
+
34
+ Same-unit operands are untouched: `0 °C == 0 °C` and
35
+ `90 deg - 90 deg` behave exactly as they did. Cross-dimension
36
+ comparison still returns `False` rather than raising. A `UnitProduct`
37
+ is refused when any single factor is unnormalizable.
38
+
39
+ This supersedes the behavior 2.2.1 documented, where affine operands
40
+ combined unscaled on the grounds that arithmetic then agreed with
41
+ `__eq__`. They did agree, and both were wrong.
42
+
43
+ Angle units are *not* given a `base_form` to fix their third of this:
44
+ `BaseForm.factors` is contracted to reference only canonical SI base
45
+ units, and angle is a pseudo-dimension with no SI base expansion, so a
46
+ radian-based factorization would violate the type's invariant. Making
47
+ angle, ratio, and count comparable on their own terms needs a separate
48
+ within-dimension canonical scale, which is design work rather than a
49
+ point release.
50
+
51
+ ### Documentation
52
+
53
+ - **Roadmap recast around the chart defects.** `ROADMAP.md` marked v2.2.0
54
+ planned after it had shipped, and had no home for the correctness work
55
+ that followed. It now records a **v2.2.x scale correctness train**
56
+ (symmetrical with v2.1.x), moves currency to its own v2.4.0 ahead of
57
+ array parity at v2.5.0, and adds a *Where the chart defects land*
58
+ section.
59
+
60
+ That section exists because #309 and #313 are not standalone bugs: ADR
61
+ 009 predicted both, and the Turnstile evidence record (internal) documents
62
+ `1 rad + 180 deg → <181 rad>` as a shipped defect before it was
63
+ reported from outside. The v2.2.x refusals are a waypoint — 3.1.0's
64
+ chart stratum is meant to *compute* some of what 2.2.2 refuses — and
65
+ the table says which release does which so the interim is not mistaken
66
+ for the destination.
67
+
68
+ Also notes that #282 is the last open Turnstile prerequisite, putting
69
+ v2.3.0 on the critical path for v3.1.0, and that
70
+ the internal release-plan trajectory table is superseded from
71
+ 2.2.0 onward.
72
+
10
73
  ## [2.2.1] - 2026-09-18
11
74
 
12
75
  ### Changed
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: ucon
3
- Version: 2.2.1
3
+ Version: 2.2.2
4
4
  Summary: A tool for dimensional analysis: a 'Unit CONverter'
5
5
  Author-email: "Emmanuel I. Obi" <withtwoemms@gmail.com>
6
6
  Maintainer-email: "Emmanuel I. Obi" <withtwoemms@gmail.com>
@@ -44,14 +44,45 @@ This roadmap tracks **major milestones** on the path to v2. For incremental upda
44
44
  | v1.12.0 | **Cycle-break completion — structural rather than runtime.** The `_active` ContextVar relocates to a true Layer-0 leaf (`ucon._active`) with zero intra-ucon imports; `AlgebraCache` moves to `ucon._algebra_cache`; the transitional `_resolve_unit_impl` dependency-injection scaffold and the `constants._constants_cache` cross-module attribute assignment both retire. A static AST audit (`test_no_cross_module_injection.py`) guards against future regressions. No public API change. | Complete |
45
45
  | **v2.0.0** | **`UnitSystem` algebra, global retirement, and `Number.kind` wiring.** Closes the value-type loop: pure-function operations `extend` / `restrict` / `merge` / `with_*`, first-class relations `subsystem_of` / `compatible_with` / `diff` / `shared_units` / `shared_dimensions`, explicit cross-system value movement (`system.adopt`, `Bridge(A, B)` with `rename` + `basis_transform`), and retirement of the module-global registries (`_REGISTRY`, `_DIMENSION_ATTRS`, default `ConversionGraph`) in favour of the default `UnitSystem` value. Promotes the v1.9.x KOQ surface to first-class: `Number` accepts `kind=`, arithmetic dispatches through the active `FormulaRegistry`, and the `ActiveContext` substrate (single ContextVar payload bundling `system + formulas + kinds + strict`, extended `use(...)` with field-wise inheritance) makes scope explicit. `strict=True` by default raises `UnitDefinitionMismatch` on identity-mismatched source units. Removes the deprecated `UnitSystem` alias for `BaseUnits` and the `_DIM_*_CACHE` shims. Marshal-based graph cache (~15-25x import speedup). | Complete |
46
46
  | v2.1.x | **Correctness train** — six per-issue patch releases (2.1.2–2.1.7) closing the 2026-09 audit: exact customary prefactors derived from statutory seeds, constant symbols in package edge factors, path resolution through composite edge endpoints, typed `DisjointKinds` refusals, idempotent kind re-add, exact SI `base_form`s for mechanical CGS units. Per-issue detail in [`CHANGELOG.md`](CHANGELOG.md). | Complete |
47
- | v2.2.0 | **Aspect stratum** — per [decisions/008](docs/internal/decisions/008-aspect-stratum.md): one `Aspect` type (peer of `Kind`), flat additive `Number.aspects`, family-wise resolution, carry rule, D3 namespacing; the never-exported flat `AspectSet` model is removed outright; pseudo-dimension deprecations begin (`PendingDeprecationWarning`). | Planned |
48
- | v2.3.0 | **Package infrastructure** — `[[contexts]]` in TOML, `PolynomialMap` with branch inverses, declared `Unit.chart` ([decisions/010](docs/internal/decisions/010-chart-nomenclature.md)), `default_kind`. | Planned |
49
- | v2.4.0 | **Array stratum parity** — `NumberArray` receives the kind and aspect strata (#297, #298): array-level `kind` and `aspects` fields mirroring the shared-`unit` design, scalar-resolver reuse (one resolution per array op), extraction stamping so `arr[i]` satisfies every `Number` invariant, integrations round-trip. | Planned |
47
+ | **v2.2.0** | **Aspect stratum** — per [decisions/008](docs/internal/decisions/008-aspect-stratum.md): one `Aspect` type (peer of `Kind`), flat additive `Number.aspects`, family-wise resolution, carry rule, D3 namespacing; the never-exported flat `AspectSet` model is removed outright; pseudo-dimension deprecations begin (`PendingDeprecationWarning`). | Complete |
48
+ | v2.2.x | **Scale correctness train** — a second per-issue patch train, unplanned but symmetrical with v2.1.x, closing the ψ (scale) defects [ADR 009](docs/internal/decisions/009-turnstile.md) predicted: additive operands converted before combining (2.2.1, #309), unnormalizable pairs refused rather than combined unscaled (2.2.2, #313), plus catalog papercuts (#307, #308). Interim by construction — see *Where the chart defects land*. | In progress |
49
+ | v2.3.0 | **Package infrastructure** — `[[contexts]]` in TOML (#282), `PolynomialMap` with branch inverses, declared `Unit.chart` ([decisions/010](docs/internal/decisions/010-chart-nomenclature.md)), `default_kind` (#305). Carries the last open Turnstile prerequisite and unblocks currency. | Planned |
50
+ | v2.4.0 | **Native currency** — currency as kinds plus rate contexts (#292), consuming 2.3.0's `[[contexts]]` and `default_kind`. The first real consumer of `default_kind`, which is why #306 lands with this rather than ahead of it. | Planned |
51
+ | v2.5.0 | **Array stratum parity** — `NumberArray` receives the kind and aspect strata (#297, #298): array-level `kind` and `aspects` fields mirroring the shared-`unit` design, scalar-resolver reuse (one resolution per array op), extraction stamping so `arr[i]` satisfies every `Number` invariant, integrations round-trip. | Planned |
50
52
  | v3.0.0 | **Lean structural major** — pseudo-dimension retirement (TOML schema), `Number` frozen, `Unit`/`UnitProduct` identity unification, deprecation removals. The breaks, and only the breaks. | Planned |
51
53
  | v3.1.0 | **The Turnstile** — per [decisions/009](docs/internal/decisions/009-turnstile.md): four-stratum arithmetic dispatch (dimension, chart, kind, aspect), derived point/displacement, cyclic/ordinal kind flags, lazy warrants via `explain()`. New refusals on previously-wrong paths are fixes. | Planned |
52
54
 
53
55
  ---
54
56
 
57
+ ## Where the chart defects land
58
+
59
+ `Number.__add__` gates on dimension and never consults scale.
60
+ [ADR 009](docs/internal/decisions/009-turnstile.md) §2 diagnosed this before it
61
+ was reported from outside, recording the shipped behavior as
62
+ `1 rad + 180 deg → <181 rad>` and `1 Gy + 1 Sv → <2 Gy>`.
63
+
64
+ The Turnstile is the fix, and it rides after the 3.0.0 breaks. That is several
65
+ releases out, so the v2.2.x train converts silence into either a correct answer
66
+ or a loud refusal in the meantime. **The interim work is a waypoint, not the
67
+ destination** — some of what 2.2.2 refuses, 3.1.0 is meant to compute:
68
+
69
+ | Step | Release | What changes |
70
+ |---|---|---|
71
+ | Ratio-chart operands converted before combining | 2.2.1 | `1 V - 1000 mV` returns `0 V`, not `-999 V` (#309) |
72
+ | Unnormalizable pairs refused, not combined unscaled | 2.2.2 | `1 K == 1 °C` raises instead of reporting `True` (#313) |
73
+ | Refusal keys on a principled marker | 2.3.0 | the `base_form is None` proxy gives way to declared `Unit.chart`; `base_form` is a statement about SI factorization, not about chart class |
74
+ | Angle becomes a real dimension | 3.0.0 | pseudo-dimension retirement; `degree` and `radian` gain a canonical scale they cannot have while angle is pseudo-dimensional |
75
+ | Chart-crossing arithmetic returns a value | 3.1.0 | the chart stratum supplies factors and offsets, so `1 rad + 180 deg` converts rather than refusing |
76
+
77
+ Two consequences worth stating plainly. `BaseForm.factors` is contracted to
78
+ reference only canonical SI base units, so giving angle units a `base_form` to
79
+ shortcut this would violate the type rather than fix it — the BFS oracle skips
80
+ pseudo-dimensions for that reason. And #282 is the last open Turnstile
81
+ prerequisite (#279 and #280 are closed), which puts v2.3.0 on the critical path
82
+ for v3.1.0 despite reading as routine package work.
83
+
84
+ ---
85
+
55
86
  ## v1.9.x — Kind-of-Quantity Preview Line
56
87
 
57
88
  **Theme:** Land the kind subsystem as a complete, standalone data model before binding it to arithmetic.
@@ -82,6 +82,7 @@ from ucon.core import (
82
82
  Scale,
83
83
  Unit,
84
84
  UnitDefinitionMismatch,
85
+ UnitsNotNormalizable,
85
86
  UnitFactor,
86
87
  UnitProduct,
87
88
  UnknownUnitError,
@@ -225,6 +226,7 @@ __all__ = [
225
226
  'Unit',
226
227
  'UnitDef',
227
228
  'UnitDefinitionMismatch',
229
+ 'UnitsNotNormalizable',
228
230
  'UnitFactor',
229
231
  'UnitPackage',
230
232
  'UnitProduct',
@@ -18,6 +18,7 @@ from ucon.core.exceptions import (
18
18
  KindMismatch,
19
19
  NonScalableError,
20
20
  UnitDefinitionMismatch,
21
+ UnitsNotNormalizable,
21
22
  UnknownUnitError,
22
23
  )
23
24
  from ucon.core._types import (
@@ -58,6 +59,7 @@ __all__ = [
58
59
  'Scale',
59
60
  'Unit',
60
61
  'UnitDefinitionMismatch',
62
+ 'UnitsNotNormalizable',
61
63
  'UnitFactor',
62
64
  'UnitProduct',
63
65
  'UnknownUnitError',
@@ -44,7 +44,12 @@ from ucon.aspects.resolution import resolve_add_aspects, resolve_mul_aspects
44
44
  from ucon.aspects.types import Aspect
45
45
  from ucon.basis import Basis, BasisGraph
46
46
  from ucon.core._parsing_graph import _parsing_graph
47
- from ucon.core.exceptions import KindDimensionMismatch, KindMismatch, UnitDefinitionMismatch
47
+ from ucon.core.exceptions import (
48
+ KindDimensionMismatch,
49
+ KindMismatch,
50
+ UnitDefinitionMismatch,
51
+ UnitsNotNormalizable,
52
+ )
48
53
  from ucon.formulas.exceptions import FormulaNotFound
49
54
  from ucon.kinds.exceptions import JoinRefused
50
55
  from ucon.dimension import Dimension, NONE
@@ -2279,6 +2284,45 @@ class Number:
2279
2284
  kind=self._resolve_mul_kind(other),
2280
2285
  )._carry(result_aspects)
2281
2286
 
2287
+ @staticmethod
2288
+ def _is_algebraically_normalizable(unit) -> bool:
2289
+ """Whether ``unit``'s magnitude can be rescaled without a graph.
2290
+
2291
+ True when every unit involved carries a ``base_form``, which is
2292
+ what :attr:`_canonical_magnitude` needs to produce a meaningful
2293
+ factor. False for affine units (an offset no prefactor can
2294
+ express), logarithmic units (levels, not scalings), and
2295
+ pseudo-dimensional units whose canonical unit sits outside the
2296
+ SI basis — angle, ratio, count, solid angle.
2297
+
2298
+ A :class:`UnitProduct` is normalizable only if every one of its
2299
+ factors is; one unnormalizable factor taints the product.
2300
+ """
2301
+ if isinstance(unit, UnitProduct):
2302
+ return all(
2303
+ uf.unit.base_form is not None for uf in unit.factors
2304
+ )
2305
+ return unit.base_form is not None
2306
+
2307
+ def _require_normalizable(self, other: 'Number', operation: str) -> None:
2308
+ """Refuse ``operation`` when no algebraic factor relates the units.
2309
+
2310
+ Same-unit operands are always fine — no rescaling is needed. For
2311
+ differing units, both sides must be normalizable, otherwise
2312
+ :attr:`_canonical_magnitude` would silently fall back to the raw
2313
+ quantity and combine magnitudes that do not denote the same
2314
+ thing.
2315
+ """
2316
+ if self.unit == other.unit:
2317
+ return
2318
+ if self._is_algebraically_normalizable(
2319
+ self.unit
2320
+ ) and self._is_algebraically_normalizable(other.unit):
2321
+ return
2322
+ raise UnitsNotNormalizable(
2323
+ left=self.unit, right=other.unit, operation=operation
2324
+ )
2325
+
2282
2326
  def _additive_operand(self, other: 'Number') -> tuple:
2283
2327
  """``other``'s quantity and uncertainty expressed in ``self.unit``.
2284
2328
 
@@ -2320,8 +2364,10 @@ class Number:
2320
2364
  source = Number(1.0, other.unit)._canonical_magnitude
2321
2365
  if not target or not source:
2322
2366
  # A zero normalization factor means a malformed unit definition;
2323
- # fall back to unscaled magnitudes rather than dividing by zero.
2324
- return other.quantity, other.uncertainty
2367
+ # refusing beats dividing by zero or combining unscaled.
2368
+ raise UnitsNotNormalizable(
2369
+ left=self.unit, right=other.unit, operation="combine"
2370
+ )
2325
2371
 
2326
2372
  factor = source / target
2327
2373
  uncertainty = (
@@ -2353,6 +2399,10 @@ class Number:
2353
2399
  f"{self.unit.dimension} vs {other.unit.dimension}"
2354
2400
  )
2355
2401
 
2402
+ # Refuse before kind/aspect dispatch: those can warn or mutate
2403
+ # ambient state, and a refused operation should do neither.
2404
+ self._require_normalizable(other, "add")
2405
+
2356
2406
  # Kind lattice dispatch, then family-wise aspect resolution
2357
2407
  result_kind = self._resolve_add_kind(other)
2358
2408
  result_aspects = self._resolve_add_aspects(other)
@@ -2397,6 +2447,9 @@ class Number:
2397
2447
  f"{self.unit.dimension} vs {other.unit.dimension}"
2398
2448
  )
2399
2449
 
2450
+ # Refuse before kind/aspect dispatch, as in __add__.
2451
+ self._require_normalizable(other, "subtract")
2452
+
2400
2453
  # Kind lattice dispatch — same rules as addition
2401
2454
  result_kind = self._resolve_add_kind(other)
2402
2455
  result_aspects = self._resolve_add_aspects(other, op="Subtracting")
@@ -2473,6 +2526,22 @@ class Number:
2473
2526
  )._carry(result_aspects)
2474
2527
 
2475
2528
  def __eq__(self, other: _Quantifiable) -> bool:
2529
+ """Compare two quantities, normalizing for scale.
2530
+
2531
+ Operands of differing dimension are unequal. Operands of the same
2532
+ dimension are compared after both are normalized to base-unit
2533
+ scale, so ``1 volt`` equals ``1000 millivolt``.
2534
+
2535
+ Raises
2536
+ ------
2537
+ TypeError
2538
+ ``other`` is neither a ``Number`` nor a ``Ratio``.
2539
+ UnitsNotNormalizable
2540
+ The units differ and no algebraic factor relates them — an
2541
+ affine, logarithmic, or pseudo-dimensional pair. Convert with
2542
+ :meth:`to` first. Returning a bool here would mean asserting
2543
+ equality or inequality that cannot be determined.
2544
+ """
2476
2545
  if not isinstance(other, (Number, Ratio)):
2477
2546
  raise TypeError(
2478
2547
  f"Cannot compare Number to non-Number/Ratio type: {type(other)}"
@@ -2486,6 +2555,10 @@ class Number:
2486
2555
  if self.unit.dimension != other.unit.dimension:
2487
2556
  return False
2488
2557
 
2558
+ # Same dimension, differing units: refuse rather than compare
2559
+ # magnitudes that do not denote the same thing.
2560
+ self._require_normalizable(other, "compare")
2561
+
2489
2562
  # Compare magnitudes, scale-adjusted
2490
2563
  if abs(self._canonical_magnitude - other._canonical_magnitude) >= 1e-12:
2491
2564
  return False
@@ -148,3 +148,64 @@ class KindDimensionMismatch(Exception):
148
148
  f"but unit {unit_name!r} has dimension {unit.dimension!r}. "
149
149
  f"A Number's kind must refine the dimension of its unit."
150
150
  )
151
+
152
+
153
+ class UnitsNotNormalizable(Exception):
154
+ """Two same-dimension units cannot be reconciled without a graph.
155
+
156
+ Raised by :meth:`ucon.Number.__eq__`, :meth:`ucon.Number.__add__`
157
+ and :meth:`ucon.Number.__sub__` when the operands carry different
158
+ units of the same dimension and at least one of them has no
159
+ ``base_form``, so no purely algebraic factor relates them.
160
+
161
+ Comparison and additive arithmetic are pure functions of
162
+ ``(quantity, unit)`` — they never consult a
163
+ :class:`~ucon.conversion.Graph` — which means they cannot express an
164
+ affine offset (celsius, fahrenheit), a logarithmic level (decibel,
165
+ neper, bel), or a pseudo-dimensional ratio whose canonical unit is
166
+ outside the SI basis (degree against radian). Before v2.2.2 these
167
+ combined unconverted, so ``Number(1, kelvin) == Number(1, celsius)``
168
+ reported ``True`` and ``Number(180, degree) - Number(pi, radian)``
169
+ returned ``176.86 deg``.
170
+
171
+ The conversion graph *does* know these relationships. Convert first
172
+ and the operation succeeds::
173
+
174
+ a - b.to(a.unit)
175
+ a == b.to(a.unit)
176
+
177
+ Attributes
178
+ ----------
179
+ left : Unit | UnitProduct
180
+ The left operand's unit.
181
+ right : Unit | UnitProduct
182
+ The right operand's unit.
183
+ operation : str
184
+ The operation that refused (``"compare"``, ``"add"`` or
185
+ ``"subtract"``).
186
+ """
187
+
188
+ def __init__(
189
+ self,
190
+ *,
191
+ left: 'Unit | UnitProduct',
192
+ right: 'Unit | UnitProduct',
193
+ operation: str,
194
+ ) -> None:
195
+ self.left = left
196
+ self.right = right
197
+ self.operation = operation
198
+ left_name = getattr(left, "name", None) or repr(left)
199
+ right_name = getattr(right, "name", None) or repr(right)
200
+ missing = [
201
+ getattr(u, "name", None) or repr(u)
202
+ for u in (left, right)
203
+ if getattr(u, "base_form", None) is None
204
+ ]
205
+ super().__init__(
206
+ f"Cannot {operation} {left_name!r} and {right_name!r} without "
207
+ f"converting first: {' and '.join(repr(m) for m in missing)} "
208
+ f"{'have' if len(missing) > 1 else 'has'} no base_form, so no "
209
+ f"algebraic factor relates the two units. Use "
210
+ f".to({left_name!r}) on the right operand first."
211
+ )
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: ucon
3
- Version: 2.2.1
3
+ Version: 2.2.2
4
4
  Summary: A tool for dimensional analysis: a 'Unit CONverter'
5
5
  Author-email: "Emmanuel I. Obi" <withtwoemms@gmail.com>
6
6
  Maintainer-email: "Emmanuel I. Obi" <withtwoemms@gmail.com>
@@ -1,7 +1,7 @@
1
1
  {
2
- "tag": "2.2.1",
2
+ "tag": "2.2.2",
3
3
  "distance": 0,
4
- "node": "g3abafc0f29cd250c8add5780329e80900564a959",
4
+ "node": "g8a550240fb6e60ab9783552ddacec527a1b803bc",
5
5
  "dirty": false,
6
6
  "branch": "HEAD",
7
7
  "node_date": "2026-09-18"
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes