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.
- {ucon-2.2.1 → ucon-2.2.2}/CHANGELOG.md +63 -0
- {ucon-2.2.1/ucon.egg-info → ucon-2.2.2}/PKG-INFO +1 -1
- {ucon-2.2.1 → ucon-2.2.2}/ROADMAP.md +34 -3
- {ucon-2.2.1 → ucon-2.2.2}/ucon/__init__.py +2 -0
- {ucon-2.2.1 → ucon-2.2.2}/ucon/core/__init__.py +2 -0
- {ucon-2.2.1 → ucon-2.2.2}/ucon/core/_types.py +76 -3
- {ucon-2.2.1 → ucon-2.2.2}/ucon/core/exceptions.py +61 -0
- {ucon-2.2.1 → ucon-2.2.2/ucon.egg-info}/PKG-INFO +1 -1
- {ucon-2.2.1 → ucon-2.2.2}/ucon.egg-info/scm_version.json +2 -2
- {ucon-2.2.1 → ucon-2.2.2}/.github/workflows/downstream.yaml +0 -0
- {ucon-2.2.1 → ucon-2.2.2}/.github/workflows/publish.yaml +0 -0
- {ucon-2.2.1 → ucon-2.2.2}/.github/workflows/tests.yaml +0 -0
- {ucon-2.2.1 → ucon-2.2.2}/.gitignore +0 -0
- {ucon-2.2.1 → ucon-2.2.2}/.gitmodules +0 -0
- {ucon-2.2.1 → ucon-2.2.2}/LICENSE +0 -0
- {ucon-2.2.1 → ucon-2.2.2}/MANIFEST.in +0 -0
- {ucon-2.2.1 → ucon-2.2.2}/Makefile +0 -0
- {ucon-2.2.1 → ucon-2.2.2}/NOTICE +0 -0
- {ucon-2.2.1 → ucon-2.2.2}/README.md +0 -0
- {ucon-2.2.1 → ucon-2.2.2}/SECURITY.md +0 -0
- {ucon-2.2.1 → ucon-2.2.2}/SUPPORT.md +0 -0
- {ucon-2.2.1 → ucon-2.2.2}/mkdocs.yml +0 -0
- {ucon-2.2.1 → ucon-2.2.2}/netlify.toml +0 -0
- {ucon-2.2.1 → ucon-2.2.2}/pyproject.toml +0 -0
- {ucon-2.2.1 → ucon-2.2.2}/requirements.txt +0 -0
- {ucon-2.2.1 → ucon-2.2.2}/setup.cfg +0 -0
- {ucon-2.2.1 → ucon-2.2.2}/ucon/_active.py +0 -0
- {ucon-2.2.1 → ucon-2.2.2}/ucon/_algebra_cache.py +0 -0
- {ucon-2.2.1 → ucon-2.2.2}/ucon/_bootstrap.py +0 -0
- {ucon-2.2.1 → ucon-2.2.2}/ucon/_cache.py +0 -0
- {ucon-2.2.1 → ucon-2.2.2}/ucon/aspects/__init__.py +0 -0
- {ucon-2.2.1 → ucon-2.2.2}/ucon/aspects/exceptions.py +0 -0
- {ucon-2.2.1 → ucon-2.2.2}/ucon/aspects/forest.py +0 -0
- {ucon-2.2.1 → ucon-2.2.2}/ucon/aspects/resolution.py +0 -0
- {ucon-2.2.1 → ucon-2.2.2}/ucon/aspects/types.py +0 -0
- {ucon-2.2.1 → ucon-2.2.2}/ucon/basis/__init__.py +0 -0
- {ucon-2.2.1 → ucon-2.2.2}/ucon/basis/builtin.py +0 -0
- {ucon-2.2.1 → ucon-2.2.2}/ucon/basis/graph.py +0 -0
- {ucon-2.2.1 → ucon-2.2.2}/ucon/basis/ops.py +0 -0
- {ucon-2.2.1 → ucon-2.2.2}/ucon/basis/transforms.py +0 -0
- {ucon-2.2.1 → ucon-2.2.2}/ucon/basis/types.py +0 -0
- {ucon-2.2.1 → ucon-2.2.2}/ucon/basis/vector.py +0 -0
- {ucon-2.2.1 → ucon-2.2.2}/ucon/checking.py +0 -0
- {ucon-2.2.1 → ucon-2.2.2}/ucon/comprehensive.ucon.toml +0 -0
- {ucon-2.2.1 → ucon-2.2.2}/ucon/constants.py +0 -0
- {ucon-2.2.1 → ucon-2.2.2}/ucon/constants.pyi +0 -0
- {ucon-2.2.1 → ucon-2.2.2}/ucon/contexts.py +0 -0
- {ucon-2.2.1 → ucon-2.2.2}/ucon/conversion.py +0 -0
- {ucon-2.2.1 → ucon-2.2.2}/ucon/core/_parsing_graph.py +0 -0
- {ucon-2.2.1 → ucon-2.2.2}/ucon/dimension.py +0 -0
- {ucon-2.2.1 → ucon-2.2.2}/ucon/dimension.pyi +0 -0
- {ucon-2.2.1 → ucon-2.2.2}/ucon/expressions.py +0 -0
- {ucon-2.2.1 → ucon-2.2.2}/ucon/formulas/__init__.py +0 -0
- {ucon-2.2.1 → ucon-2.2.2}/ucon/formulas/exceptions.py +0 -0
- {ucon-2.2.1 → ucon-2.2.2}/ucon/formulas/registry.py +0 -0
- {ucon-2.2.1 → ucon-2.2.2}/ucon/formulas/types.py +0 -0
- {ucon-2.2.1 → ucon-2.2.2}/ucon/graph.py +0 -0
- {ucon-2.2.1 → ucon-2.2.2}/ucon/integrations/__init__.py +0 -0
- {ucon-2.2.1 → ucon-2.2.2}/ucon/integrations/numpy.py +0 -0
- {ucon-2.2.1 → ucon-2.2.2}/ucon/integrations/pandas.py +0 -0
- {ucon-2.2.1 → ucon-2.2.2}/ucon/integrations/polars.py +0 -0
- {ucon-2.2.1 → ucon-2.2.2}/ucon/integrations/pydantic.py +0 -0
- {ucon-2.2.1 → ucon-2.2.2}/ucon/kinds/__init__.py +0 -0
- {ucon-2.2.1 → ucon-2.2.2}/ucon/kinds/exceptions.py +0 -0
- {ucon-2.2.1 → ucon-2.2.2}/ucon/kinds/lattice.py +0 -0
- {ucon-2.2.1 → ucon-2.2.2}/ucon/kinds/types.py +0 -0
- {ucon-2.2.1 → ucon-2.2.2}/ucon/maps.py +0 -0
- {ucon-2.2.1 → ucon-2.2.2}/ucon/packages.py +0 -0
- {ucon-2.2.1 → ucon-2.2.2}/ucon/parsing/__init__.py +0 -0
- {ucon-2.2.1 → ucon-2.2.2}/ucon/parsing/aspects.py +0 -0
- {ucon-2.2.1 → ucon-2.2.2}/ucon/parsing/dimensions.py +0 -0
- {ucon-2.2.1 → ucon-2.2.2}/ucon/parsing/formulas.py +0 -0
- {ucon-2.2.1 → ucon-2.2.2}/ucon/parsing/kinds.py +0 -0
- {ucon-2.2.1 → ucon-2.2.2}/ucon/parsing/lexer.py +0 -0
- {ucon-2.2.1 → ucon-2.2.2}/ucon/parsing/namespaces.py +0 -0
- {ucon-2.2.1 → ucon-2.2.2}/ucon/parsing/quantity.py +0 -0
- {ucon-2.2.1 → ucon-2.2.2}/ucon/parsing/units.py +0 -0
- {ucon-2.2.1 → ucon-2.2.2}/ucon/quantity.py +0 -0
- {ucon-2.2.1 → ucon-2.2.2}/ucon/resolver.py +0 -0
- {ucon-2.2.1 → ucon-2.2.2}/ucon/serialization.py +0 -0
- {ucon-2.2.1 → ucon-2.2.2}/ucon/system/__init__.py +0 -0
- {ucon-2.2.1 → ucon-2.2.2}/ucon/units.py +0 -0
- {ucon-2.2.1 → ucon-2.2.2}/ucon/units.pyi +0 -0
- {ucon-2.2.1 → ucon-2.2.2}/ucon.egg-info/SOURCES.txt +0 -0
- {ucon-2.2.1 → ucon-2.2.2}/ucon.egg-info/dependency_links.txt +0 -0
- {ucon-2.2.1 → ucon-2.2.2}/ucon.egg-info/requires.txt +0 -0
- {ucon-2.2.1 → ucon-2.2.2}/ucon.egg-info/scm_file_list.json +0 -0
- {ucon-2.2.1 → ucon-2.2.2}/ucon.egg-info/top_level.txt +0 -0
- {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
|
|
@@ -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`). |
|
|
48
|
-
| v2.
|
|
49
|
-
| v2.
|
|
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
|
|
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
|
-
#
|
|
2324
|
-
|
|
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
|
+
)
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
{ucon-2.2.1 → ucon-2.2.2}/NOTICE
RENAMED
|
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
|