ucon 2.2.0__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 (90) hide show
  1. {ucon-2.2.0 → ucon-2.2.2}/.github/workflows/publish.yaml +27 -0
  2. {ucon-2.2.0 → ucon-2.2.2}/CHANGELOG.md +124 -0
  3. {ucon-2.2.0/ucon.egg-info → ucon-2.2.2}/PKG-INFO +1 -1
  4. {ucon-2.2.0 → ucon-2.2.2}/ROADMAP.md +34 -3
  5. {ucon-2.2.0 → ucon-2.2.2}/ucon/__init__.py +2 -0
  6. {ucon-2.2.0 → ucon-2.2.2}/ucon/core/__init__.py +2 -0
  7. {ucon-2.2.0 → ucon-2.2.2}/ucon/core/_types.py +162 -7
  8. {ucon-2.2.0 → ucon-2.2.2}/ucon/core/exceptions.py +61 -0
  9. {ucon-2.2.0 → ucon-2.2.2/ucon.egg-info}/PKG-INFO +1 -1
  10. {ucon-2.2.0 → ucon-2.2.2}/ucon.egg-info/scm_file_list.json +1 -0
  11. ucon-2.2.2/ucon.egg-info/scm_version.json +8 -0
  12. ucon-2.2.0/ucon.egg-info/scm_version.json +0 -8
  13. {ucon-2.2.0 → ucon-2.2.2}/.github/workflows/downstream.yaml +0 -0
  14. {ucon-2.2.0 → ucon-2.2.2}/.github/workflows/tests.yaml +0 -0
  15. {ucon-2.2.0 → ucon-2.2.2}/.gitignore +0 -0
  16. {ucon-2.2.0 → ucon-2.2.2}/.gitmodules +0 -0
  17. {ucon-2.2.0 → ucon-2.2.2}/LICENSE +0 -0
  18. {ucon-2.2.0 → ucon-2.2.2}/MANIFEST.in +0 -0
  19. {ucon-2.2.0 → ucon-2.2.2}/Makefile +0 -0
  20. {ucon-2.2.0 → ucon-2.2.2}/NOTICE +0 -0
  21. {ucon-2.2.0 → ucon-2.2.2}/README.md +0 -0
  22. {ucon-2.2.0 → ucon-2.2.2}/SECURITY.md +0 -0
  23. {ucon-2.2.0 → ucon-2.2.2}/SUPPORT.md +0 -0
  24. {ucon-2.2.0 → ucon-2.2.2}/mkdocs.yml +0 -0
  25. {ucon-2.2.0 → ucon-2.2.2}/netlify.toml +0 -0
  26. {ucon-2.2.0 → ucon-2.2.2}/pyproject.toml +0 -0
  27. {ucon-2.2.0 → ucon-2.2.2}/requirements.txt +0 -0
  28. {ucon-2.2.0 → ucon-2.2.2}/setup.cfg +0 -0
  29. {ucon-2.2.0 → ucon-2.2.2}/ucon/_active.py +0 -0
  30. {ucon-2.2.0 → ucon-2.2.2}/ucon/_algebra_cache.py +0 -0
  31. {ucon-2.2.0 → ucon-2.2.2}/ucon/_bootstrap.py +0 -0
  32. {ucon-2.2.0 → ucon-2.2.2}/ucon/_cache.py +0 -0
  33. {ucon-2.2.0 → ucon-2.2.2}/ucon/aspects/__init__.py +0 -0
  34. {ucon-2.2.0 → ucon-2.2.2}/ucon/aspects/exceptions.py +0 -0
  35. {ucon-2.2.0 → ucon-2.2.2}/ucon/aspects/forest.py +0 -0
  36. {ucon-2.2.0 → ucon-2.2.2}/ucon/aspects/resolution.py +0 -0
  37. {ucon-2.2.0 → ucon-2.2.2}/ucon/aspects/types.py +0 -0
  38. {ucon-2.2.0 → ucon-2.2.2}/ucon/basis/__init__.py +0 -0
  39. {ucon-2.2.0 → ucon-2.2.2}/ucon/basis/builtin.py +0 -0
  40. {ucon-2.2.0 → ucon-2.2.2}/ucon/basis/graph.py +0 -0
  41. {ucon-2.2.0 → ucon-2.2.2}/ucon/basis/ops.py +0 -0
  42. {ucon-2.2.0 → ucon-2.2.2}/ucon/basis/transforms.py +0 -0
  43. {ucon-2.2.0 → ucon-2.2.2}/ucon/basis/types.py +0 -0
  44. {ucon-2.2.0 → ucon-2.2.2}/ucon/basis/vector.py +0 -0
  45. {ucon-2.2.0 → ucon-2.2.2}/ucon/checking.py +0 -0
  46. {ucon-2.2.0 → ucon-2.2.2}/ucon/comprehensive.ucon.toml +0 -0
  47. {ucon-2.2.0 → ucon-2.2.2}/ucon/constants.py +0 -0
  48. {ucon-2.2.0 → ucon-2.2.2}/ucon/constants.pyi +0 -0
  49. {ucon-2.2.0 → ucon-2.2.2}/ucon/contexts.py +0 -0
  50. {ucon-2.2.0 → ucon-2.2.2}/ucon/conversion.py +0 -0
  51. {ucon-2.2.0 → ucon-2.2.2}/ucon/core/_parsing_graph.py +0 -0
  52. {ucon-2.2.0 → ucon-2.2.2}/ucon/dimension.py +0 -0
  53. {ucon-2.2.0 → ucon-2.2.2}/ucon/dimension.pyi +0 -0
  54. {ucon-2.2.0 → ucon-2.2.2}/ucon/expressions.py +0 -0
  55. {ucon-2.2.0 → ucon-2.2.2}/ucon/formulas/__init__.py +0 -0
  56. {ucon-2.2.0 → ucon-2.2.2}/ucon/formulas/exceptions.py +0 -0
  57. {ucon-2.2.0 → ucon-2.2.2}/ucon/formulas/registry.py +0 -0
  58. {ucon-2.2.0 → ucon-2.2.2}/ucon/formulas/types.py +0 -0
  59. {ucon-2.2.0 → ucon-2.2.2}/ucon/graph.py +0 -0
  60. {ucon-2.2.0 → ucon-2.2.2}/ucon/integrations/__init__.py +0 -0
  61. {ucon-2.2.0 → ucon-2.2.2}/ucon/integrations/numpy.py +0 -0
  62. {ucon-2.2.0 → ucon-2.2.2}/ucon/integrations/pandas.py +0 -0
  63. {ucon-2.2.0 → ucon-2.2.2}/ucon/integrations/polars.py +0 -0
  64. {ucon-2.2.0 → ucon-2.2.2}/ucon/integrations/pydantic.py +0 -0
  65. {ucon-2.2.0 → ucon-2.2.2}/ucon/kinds/__init__.py +0 -0
  66. {ucon-2.2.0 → ucon-2.2.2}/ucon/kinds/exceptions.py +0 -0
  67. {ucon-2.2.0 → ucon-2.2.2}/ucon/kinds/lattice.py +0 -0
  68. {ucon-2.2.0 → ucon-2.2.2}/ucon/kinds/types.py +0 -0
  69. {ucon-2.2.0 → ucon-2.2.2}/ucon/maps.py +0 -0
  70. {ucon-2.2.0 → ucon-2.2.2}/ucon/packages.py +0 -0
  71. {ucon-2.2.0 → ucon-2.2.2}/ucon/parsing/__init__.py +0 -0
  72. {ucon-2.2.0 → ucon-2.2.2}/ucon/parsing/aspects.py +0 -0
  73. {ucon-2.2.0 → ucon-2.2.2}/ucon/parsing/dimensions.py +0 -0
  74. {ucon-2.2.0 → ucon-2.2.2}/ucon/parsing/formulas.py +0 -0
  75. {ucon-2.2.0 → ucon-2.2.2}/ucon/parsing/kinds.py +0 -0
  76. {ucon-2.2.0 → ucon-2.2.2}/ucon/parsing/lexer.py +0 -0
  77. {ucon-2.2.0 → ucon-2.2.2}/ucon/parsing/namespaces.py +0 -0
  78. {ucon-2.2.0 → ucon-2.2.2}/ucon/parsing/quantity.py +0 -0
  79. {ucon-2.2.0 → ucon-2.2.2}/ucon/parsing/units.py +0 -0
  80. {ucon-2.2.0 → ucon-2.2.2}/ucon/quantity.py +0 -0
  81. {ucon-2.2.0 → ucon-2.2.2}/ucon/resolver.py +0 -0
  82. {ucon-2.2.0 → ucon-2.2.2}/ucon/serialization.py +0 -0
  83. {ucon-2.2.0 → ucon-2.2.2}/ucon/system/__init__.py +0 -0
  84. {ucon-2.2.0 → ucon-2.2.2}/ucon/units.py +0 -0
  85. {ucon-2.2.0 → ucon-2.2.2}/ucon/units.pyi +0 -0
  86. {ucon-2.2.0 → ucon-2.2.2}/ucon.egg-info/SOURCES.txt +0 -0
  87. {ucon-2.2.0 → ucon-2.2.2}/ucon.egg-info/dependency_links.txt +0 -0
  88. {ucon-2.2.0 → ucon-2.2.2}/ucon.egg-info/requires.txt +0 -0
  89. {ucon-2.2.0 → ucon-2.2.2}/ucon.egg-info/top_level.txt +0 -0
  90. {ucon-2.2.0 → ucon-2.2.2}/uv.lock +0 -0
@@ -16,6 +16,27 @@ jobs:
16
16
  fetch-depth: 0 # needed for ancestry check
17
17
  ref: ${{ github.ref_name }}
18
18
 
19
+ - name: Verify CHANGELOG has a section for this tag
20
+ if: startsWith(github.ref, 'refs/tags/')
21
+ run: |
22
+ TAG=${GITHUB_REF#refs/tags/}
23
+ # Alpha and beta tags may come from feature branches and are not
24
+ # expected to carry a released section — same exemption the
25
+ # mainline ancestry check below applies.
26
+ if echo "$TAG" | grep -qE '[0-9]+\.[0-9]+\.[0-9]+(a|b)[0-9]+$'; then
27
+ echo "Pre-release tag $TAG — skipping CHANGELOG section check."
28
+ exit 0
29
+ fi
30
+ # Dots are escaped so the pattern cannot match a near-miss header.
31
+ PATTERN="^## \[$(printf '%s' "$TAG" | sed 's/[.]/\\./g')\]"
32
+ if ! grep -q "$PATTERN" CHANGELOG.md; then
33
+ echo "::error::CHANGELOG.md has no '## [$TAG]' section."
34
+ echo "Promote the [Unreleased] section to [$TAG] before tagging,"
35
+ echo "otherwise the release is published with empty notes."
36
+ exit 1
37
+ fi
38
+ echo "Found '## [$TAG]' in CHANGELOG.md."
39
+
19
40
  - name: Install uv
20
41
  uses: astral-sh/setup-uv@v5
21
42
 
@@ -84,6 +105,12 @@ jobs:
84
105
  }
85
106
  found { print }
86
107
  ' CHANGELOG.md > release_notes.md
108
+ # Backstop: the preflight proved the header exists, so an empty
109
+ # extraction here means the section itself has no body.
110
+ if [ ! -s release_notes.md ]; then
111
+ echo "::error::Extracted release notes for $TAG are empty."
112
+ exit 1
113
+ fi
87
114
 
88
115
  - name: 📋 Create GitHub Release
89
116
  if: startsWith(github.ref, 'refs/tags/')
@@ -7,6 +7,130 @@ 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
+
73
+ ## [2.2.1] - 2026-09-18
74
+
75
+ ### Changed
76
+
77
+ - **The publish workflow refuses to release a tag whose changelog section
78
+ is missing.** (#311) Release notes are generated by scanning
79
+ `CHANGELOG.md` for `## [<tag>]` at tag-push time. When the content was
80
+ still under `## [Unreleased]`, the scan matched nothing, wrote an empty
81
+ file, and the GitHub release was created with a blank body — silently,
82
+ with every step reporting success. Seven releases shipped that way:
83
+ `2.1.2` through `2.1.7`, plus `2.1.2a1`.
84
+
85
+ A preflight now runs before the build and before any upload, so a
86
+ missing section fails the run while it is still cheap to fix — promote
87
+ the section, move the tag, push again. Guarding after the upload would
88
+ instead leave the package public and the run red, with a re-run
89
+ skipping PyPI and failing the same check. Alpha and beta tags are
90
+ exempt, matching the mainline-ancestry check's existing exemption,
91
+ since those may come from feature branches. A second check rejects a
92
+ section header that matches but has no body.
93
+
94
+ No effect on the published package. The seven blank release bodies have
95
+ been backfilled from the changelog.
96
+
97
+ ### Fixed
98
+
99
+ - **`Number` addition and subtraction now convert operands stated in
100
+ different units.** Both operators guarded the dimension and then combined
101
+ raw magnitudes, so `parse("1 volt") - parse("1000 millivolt")` returned
102
+ `-999.0 V` while `==` reported the two equal. Any same-dimension pair with
103
+ a differing scale was affected — `1 meter - 100 centimeter`,
104
+ `1 hour - 30 minute`, `1 kilogram - 500 gram` — and the wrong value came
105
+ back silently, with no exception at any boundary.
106
+
107
+ `other` is now restated in the left operand's unit before the magnitudes
108
+ combine, using the same `_canonical_magnitude` normalization `__eq__`
109
+ already performed. That makes comparison and arithmetic agree: whenever
110
+ `a == b`, `(a - b).quantity` is zero. The rescaling is pure algebra over
111
+ `base_form` prefactors and consults no `ConversionGraph`, so additive
112
+ arithmetic still needs no active graph, and matched-unit operands take a
113
+ fast path that leaves their magnitudes bit-identical.
114
+
115
+ Uncertainty is rescaled by the same factor before quadrature. Previously
116
+ `1 V ± 0.03 V` combined with `100 mV ± 10 mV` propagated
117
+ `sqrt(0.03² + 10²)`, mixing volts with millivolts.
118
+
119
+ Units with no `base_form` — affine temperature scales, logarithmic units,
120
+ units defined only by a graph edge — normalize to themselves and so still
121
+ combine unscaled. That matches `__eq__`, which reports `1 K == 1 °C`, and
122
+ leaves the two consistent; correcting affine arithmetic is separate work.
123
+ `NumberArray` is unchanged: it refuses mismatched units uniformly across
124
+ comparison and arithmetic, which is internally coherent.
125
+
126
+ ### Documentation
127
+
128
+ - **ucon-tools docs submodule advanced to v0.9.0.** The
129
+ `docs/external/ucon-tools` pin had been frozen at 0.4.5rc1 while the
130
+ MCP-server guide and tool reference it serves into the docs site were
131
+ rewritten upstream; the published pages now describe the consolidated
132
+ discover/define/system tool surface.
133
+
10
134
  ## [2.2.0] - 2026-09-12
11
135
 
12
136
  ### Removed
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: ucon
3
- Version: 2.2.0
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,7 +2284,111 @@ 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
+
2326
+ def _additive_operand(self, other: 'Number') -> tuple:
2327
+ """``other``'s quantity and uncertainty expressed in ``self.unit``.
2328
+
2329
+ Additive operations combine magnitudes, so an operand stated in a
2330
+ different unit of the same dimension has to be rescaled before the
2331
+ two can be added — otherwise ``1 volt - 1000 millivolt`` returns
2332
+ ``-999 V``.
2333
+
2334
+ The rescaling is pure algebra over :attr:`~Unit.base_form`
2335
+ prefactors, routed through :attr:`_canonical_magnitude`; no
2336
+ :class:`~ucon.graph.ConversionGraph` is consulted, so additive
2337
+ arithmetic needs no active graph. It is the same normalization
2338
+ :meth:`__eq__` performs, which is what makes ``a == b`` and
2339
+ ``a - b == 0`` agree about the same pair.
2340
+
2341
+ Returns
2342
+ -------
2343
+ tuple
2344
+ ``(quantity, uncertainty)`` in ``self.unit``. Uncertainty is
2345
+ scaled by the same factor as the quantity, and stays ``None``
2346
+ when ``other`` carries none.
2347
+
2348
+ Notes
2349
+ -----
2350
+ Operands already in ``self.unit`` are returned unchanged, so the
2351
+ common same-unit case is bit-identical to plain magnitude
2352
+ arithmetic.
2353
+
2354
+ Units with no ``base_form`` — affine temperature scales,
2355
+ logarithmic units, units defined only by a graph edge — normalize
2356
+ to themselves, so their magnitudes still combine unscaled. That
2357
+ matches :meth:`__eq__`, which reports ``1 K == 1 °C``; the two
2358
+ remain consistent, and neither is yet correct for affine scales.
2359
+ """
2360
+ if self.unit == other.unit:
2361
+ return other.quantity, other.uncertainty
2362
+
2363
+ target = Number(1.0, self.unit)._canonical_magnitude
2364
+ source = Number(1.0, other.unit)._canonical_magnitude
2365
+ if not target or not source:
2366
+ # A zero normalization factor means a malformed unit definition;
2367
+ # refusing beats dividing by zero or combining unscaled.
2368
+ raise UnitsNotNormalizable(
2369
+ left=self.unit, right=other.unit, operation="combine"
2370
+ )
2371
+
2372
+ factor = source / target
2373
+ uncertainty = (
2374
+ other.uncertainty * abs(factor)
2375
+ if other.uncertainty is not None
2376
+ else None
2377
+ )
2378
+ return other.quantity * factor, uncertainty
2379
+
2282
2380
  def __add__(self, other: 'Number') -> 'Number':
2381
+ """Sum two ``Number``s, rescaling ``other`` into ``self.unit`` first.
2382
+
2383
+ Operands must share a dimension; they need not share a unit. The
2384
+ result is stated in ``self.unit``. See :meth:`_additive_operand`
2385
+ for the normalization and its limits.
2386
+
2387
+ Raises
2388
+ ------
2389
+ TypeError
2390
+ The operands' dimensions differ.
2391
+ """
2283
2392
  if not isinstance(other, Number):
2284
2393
  return NotImplemented
2285
2394
 
@@ -2290,25 +2399,44 @@ class Number:
2290
2399
  f"{self.unit.dimension} vs {other.unit.dimension}"
2291
2400
  )
2292
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
+
2293
2406
  # Kind lattice dispatch, then family-wise aspect resolution
2294
2407
  result_kind = self._resolve_add_kind(other)
2295
2408
  result_aspects = self._resolve_add_aspects(other)
2296
2409
 
2410
+ # Same dimension, possibly different unit: combine magnitudes only
2411
+ # after restating `other` in this Number's unit.
2412
+ other_quantity, other_uncertainty = self._additive_operand(other)
2413
+
2297
2414
  # Uncertainty propagation for addition: δc = sqrt(δa² + δb²)
2298
2415
  new_uncertainty = None
2299
- if self.uncertainty is not None or other.uncertainty is not None:
2416
+ if self.uncertainty is not None or other_uncertainty is not None:
2300
2417
  ua = self.uncertainty if self.uncertainty is not None else 0
2301
- ub = other.uncertainty if other.uncertainty is not None else 0
2418
+ ub = other_uncertainty if other_uncertainty is not None else 0
2302
2419
  new_uncertainty = math.sqrt(ua**2 + ub**2)
2303
2420
 
2304
2421
  return Number(
2305
- quantity=self.quantity + other.quantity,
2422
+ quantity=self.quantity + other_quantity,
2306
2423
  unit=self.unit,
2307
2424
  uncertainty=new_uncertainty,
2308
2425
  kind=result_kind,
2309
2426
  )._carry(result_aspects)
2310
2427
 
2311
2428
  def __sub__(self, other: 'Number') -> 'Number':
2429
+ """Subtract ``other``, rescaling it into ``self.unit`` first.
2430
+
2431
+ Operands must share a dimension; they need not share a unit. The
2432
+ result is stated in ``self.unit``. See :meth:`_additive_operand`
2433
+ for the normalization and its limits.
2434
+
2435
+ Raises
2436
+ ------
2437
+ TypeError
2438
+ The operands' dimensions differ.
2439
+ """
2312
2440
  if not isinstance(other, Number):
2313
2441
  return NotImplemented
2314
2442
 
@@ -2319,19 +2447,26 @@ class Number:
2319
2447
  f"{self.unit.dimension} vs {other.unit.dimension}"
2320
2448
  )
2321
2449
 
2450
+ # Refuse before kind/aspect dispatch, as in __add__.
2451
+ self._require_normalizable(other, "subtract")
2452
+
2322
2453
  # Kind lattice dispatch — same rules as addition
2323
2454
  result_kind = self._resolve_add_kind(other)
2324
2455
  result_aspects = self._resolve_add_aspects(other, op="Subtracting")
2325
2456
 
2457
+ # Same dimension, possibly different unit: combine magnitudes only
2458
+ # after restating `other` in this Number's unit.
2459
+ other_quantity, other_uncertainty = self._additive_operand(other)
2460
+
2326
2461
  # Uncertainty propagation for subtraction: δc = sqrt(δa² + δb²)
2327
2462
  new_uncertainty = None
2328
- if self.uncertainty is not None or other.uncertainty is not None:
2463
+ if self.uncertainty is not None or other_uncertainty is not None:
2329
2464
  ua = self.uncertainty if self.uncertainty is not None else 0
2330
- ub = other.uncertainty if other.uncertainty is not None else 0
2465
+ ub = other_uncertainty if other_uncertainty is not None else 0
2331
2466
  new_uncertainty = math.sqrt(ua**2 + ub**2)
2332
2467
 
2333
2468
  return Number(
2334
- quantity=self.quantity - other.quantity,
2469
+ quantity=self.quantity - other_quantity,
2335
2470
  unit=self.unit,
2336
2471
  uncertainty=new_uncertainty,
2337
2472
  kind=result_kind,
@@ -2391,6 +2526,22 @@ class Number:
2391
2526
  )._carry(result_aspects)
2392
2527
 
2393
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
+ """
2394
2545
  if not isinstance(other, (Number, Ratio)):
2395
2546
  raise TypeError(
2396
2547
  f"Cannot compare Number to non-Number/Ratio type: {type(other)}"
@@ -2404,6 +2555,10 @@ class Number:
2404
2555
  if self.unit.dimension != other.unit.dimension:
2405
2556
  return False
2406
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
+
2407
2562
  # Compare magnitudes, scale-adjusted
2408
2563
  if abs(self._canonical_magnitude - other._canonical_magnitude) >= 1e-12:
2409
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.0
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>
@@ -235,6 +235,7 @@
235
235
  "tests/ucon/system/test_bridge.py",
236
236
  "tests/ucon/system/test_relations.py",
237
237
  "tests/ucon/system/test_strict_resolution.py",
238
+ "tests/ucon/test_additive_unit_conversion.py",
238
239
  "tests/ucon/test_algebra.py",
239
240
  "tests/ucon/test_base_form.py",
240
241
  "tests/ucon/test_cache.py",
@@ -0,0 +1,8 @@
1
+ {
2
+ "tag": "2.2.2",
3
+ "distance": 0,
4
+ "node": "g8a550240fb6e60ab9783552ddacec527a1b803bc",
5
+ "dirty": false,
6
+ "branch": "HEAD",
7
+ "node_date": "2026-09-18"
8
+ }
@@ -1,8 +0,0 @@
1
- {
2
- "tag": "2.2.0",
3
- "distance": 0,
4
- "node": "ga8b5c201c4adff68ad0909d2ef29f02462444fa5",
5
- "dirty": false,
6
- "branch": "HEAD",
7
- "node_date": "2026-09-13"
8
- }
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