ucon 0.3.5__py3-none-any.whl → 0.3.5rc1__py3-none-any.whl

ucon/__init__.py

@@ -38,7 +38,7 @@ Design Philosophy
 """
 from ucon import units
 from ucon.algebra import Exponent
-from ucon.core import Dimension, Scale, Unit, UnitFactor, UnitProduct
+from ucon.core import Dimension, Scale, Unit
 from ucon.quantity import Number, Ratio
 
 
@@ -49,7 +49,5 @@ __all__ = [
     'Ratio',
     'Scale',
     'Unit',
-    'UnitFactor',
-    'UnitProduct',
     'units',
 ]

ucon/core.py

@@ -240,7 +240,8 @@ class Scale(Enum):
 
     def __mul__(self, other):
         # --- Case 1: applying Scale to simple Unit --------------------
-        if isinstance(other, Unit):
+        if isinstance(other, Unit) and not isinstance(other, UnitProduct):
+            # Unit no longer has scale attribute - always safe to apply
             return UnitProduct({UnitFactor(unit=other, scale=self): 1})
 
         # --- Case 2: other cases are NOT handled here -----------------
@@ -342,6 +343,8 @@ class Unit:
         Unit * Unit -> UnitProduct
         Unit * UnitProduct -> UnitProduct
         """
+        from ucon.core import UnitProduct  # local import to avoid circulars
+
         if isinstance(other, UnitProduct):
             # let UnitProduct handle merging
             return other.__rmul__(self)
@@ -353,13 +356,12 @@ class Unit:
 
     def __truediv__(self, other):
         """
-        Unit / Unit or Unit / UnitProduct => UnitProduct
+        Unit / Unit:
+          - If same unit => dimensionless Unit()
+          - If denominator is dimensionless => self
+          - Else => UnitProduct
         """
-        if isinstance(other, UnitProduct):
-            combined = {self: 1.0}
-            for u, exp in other.factors.items():
-                combined[u] = combined.get(u, 0.0) - exp
-            return UnitProduct(combined)
+        from ucon.core import UnitProduct  # local import
 
         if not isinstance(other, Unit):
             return NotImplemented
@@ -383,13 +385,13 @@ class Unit:
         """
         Unit ** n => UnitProduct with that exponent.
         """
+        from ucon.core import UnitProduct  # local import
+
         return UnitProduct({self: power})
 
     # ----------------- equality & hashing -----------------
 
     def __eq__(self, other):
-        if isinstance(other, UnitProduct):
-            return other.__eq__(self)
         if not isinstance(other, Unit):
             return NotImplemented
         return (
@@ -496,7 +498,7 @@ class UnitFactor:
         return NotImplemented
 
 
-class UnitProduct:
+class UnitProduct(Unit):
     """
     Represents a product or quotient of Units.
 
@@ -525,7 +527,8 @@ class UnitProduct:
         encountered UnitFactor (keeps user-intent scale).
         """
 
-        self.name = ""
+        # UnitProduct always starts dimensionless
+        super().__init__(name="", dimension=Dimension.none)
         self.aliases = ()
 
         merged: dict[UnitFactor, float] = {}
@@ -703,16 +706,6 @@ class UnitProduct:
             result *= factor.scale.value.evaluated ** power
         return result
 
-    # ------------- Helpers ---------------------------------------------------
-
-    def _norm(self, aliases: tuple[str, ...]) -> tuple[str, ...]:
-        """Normalize alias bag: drop empty/whitespace-only aliases."""
-        return tuple(a for a in aliases if a.strip())
-
-    def __pow__(self, power):
-        """UnitProduct ** n => new UnitProduct with scaled exponents."""
-        return UnitProduct({u: exp * power for u, exp in self.factors.items()})
-
     # ------------- Algebra ---------------------------------------------------
 
     def __mul__(self, other):
@@ -806,7 +799,7 @@ class UnitProduct:
         return f"<{self.__class__.__name__} {self.shorthand}>"
 
     def __eq__(self, other):
-        if isinstance(other, Unit):
+        if isinstance(other, Unit) and not isinstance(other, UnitProduct):
             # Only equal to a plain Unit if we have exactly that unit^1
             # Here, the tuple comparison will invoke UnitFactor.__eq__(Unit)
             # on the key when factors are keyed by UnitFactor.

ucon/quantity.py

@@ -43,7 +43,7 @@ class Number:
         <2.5 (m/s)>
     """
     quantity: Union[float, int] = 1.0
-    unit: Union[Unit, UnitProduct] = units.none
+    unit: Unit = units.none
 
     @property
     def value(self) -> float:

{ucon-0.3.5.dist-info → ucon-0.3.5rc1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ucon
-Version: 0.3.5
+Version: 0.3.5rc1
 Summary: a tool for dimensional analysis: a "Unit CONverter"
 Home-page: https://github.com/withtwoemms/ucon
 Author: Emmanuel I. Obi
@@ -55,8 +55,8 @@ Dynamic: summary
 It combines **units**, **scales**, and **dimensions** into a composable algebra that supports:
 
 - Dimensional analysis through `Number` and `Ratio`
-- Scale-aware arithmetic via `UnitFactor` and `UnitProduct`
-- Metric and binary prefixes (`kilo`, `kibi`, `micro`, `mebi`, etc.)
+- Scale-aware arithmetic and conversions
+- Metric and binary prefixes (`kilo`, `kibi`, `micro`, `mebi`, ect.)
 - A clean foundation for physics, chemistry, data modeling, and beyond
 
 Think of it as **`decimal.Decimal` for the physical world** — precise, predictable, and type-safe.
@@ -70,22 +70,20 @@ The crux of this tiny library is to provide abstractions that simplify the answe
 To best answer this question, we turn to an age-old technique ([dimensional analysis](https://en.wikipedia.org/wiki/Dimensional_analysis)) which essentially allows for the solution to be written as a product of ratios. `ucon` comes equipped with some useful primitives:
 | Type                          | Defined In                              | Purpose                                                                                             | Typical Use Cases                                                                                                      |
 | ----------------------------- | --------------------------------------- | --------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
-| **`Vector`**                  | `ucon.algebra`                          | Represents the exponent tuple of a physical quantity's base dimensions (e.g., T, L, M, I, Θ, J, N). | Internal representation of dimensional algebra; building derived quantities (e.g., area, velocity, force).             |
-| **`Exponent`**                | `ucon.algebra`                          | Represents base-power pairs (e.g., 10³, 2¹⁰) used by `Scale`.                                       | Performing arithmetic on powers and bases; normalizing scales across conversions.                                      |
-| **`Dimension`**               | `ucon.core`                             | Encapsulates physical dimensions (e.g., length, time, mass) as algebraic combinations of vectors.   | Enforcing dimensional consistency; defining relationships between quantities (e.g., length / time = velocity).         |
+| **`Vector`**                  | `ucon.dimension`                        | Represents the exponent tuple of a physical quantity’s base dimensions (e.g., T, L, M, I, Θ, J, N). | Internal representation of dimensional algebra; building derived quantities (e.g., area, velocity, force).             |
+| **`Dimension`**               | `ucon.dimension`                        | Encapsulates physical dimensions (e.g., length, time, mass) as algebraic combinations of vectors.   | Enforcing dimensional consistency; defining relationships between quantities (e.g., length / time = velocity).         |
+| **`Unit`**                    | `ucon.unit`                             | Represents a named, dimensioned measurement unit (e.g., meter, second, joule).                      | Attaching human-readable units to quantities; defining or composing new units (`newton = kilogram * meter / second²`). |
 | **`Scale`**                   | `ucon.core`                             | Encodes powers of base magnitudes (binary or decimal prefixes like kilo-, milli-, mebi-).           | Adjusting numeric scale without changing dimension (e.g., kilometer ↔ meter, byte ↔ kibibyte).                         |
-| **`Unit`**                    | `ucon.core`                             | An atomic, scale-free measurement symbol (e.g., meter, second, joule) with a `Dimension`.           | Defining base units; serving as graph nodes for future conversions.                                                    |
-| **`UnitFactor`**              | `ucon.core`                             | Pairs a `Unit` with a `Scale` (e.g., kilo + gram = kg). Used as keys inside `UnitProduct`.          | Preserving user-provided scale prefixes through algebraic operations.                                                  |
-| **`UnitProduct`**             | `ucon.core`                             | A product/quotient of `UnitFactor`s with exponent tracking and simplification.                      | Representing composite units like m/s, kg·m/s², kJ·h.                                                                 |
-| **`Number`**                  | `ucon.quantity`                         | Combines a numeric quantity with a unit; the primary measurable type.                               | Performing arithmetic with units; representing physical quantities like 5 m/s.                                         |
-| **`Ratio`**                   | `ucon.quantity`                         | Represents the division of two `Number` objects; captures relationships between quantities.         | Expressing rates, densities, efficiencies (e.g., energy / time = power, length / time = velocity).                     |
-| **`units` module**            | `ucon.units`                            | Defines canonical unit instances (SI and common derived units).                                     | Quick access to standard physical units (`units.meter`, `units.second`, `units.newton`, etc.).                          |
+| **`Exponent`**                | `ucon.core`                             | Represents base-power pairs (e.g., 10³, 2¹⁰) used by `Scale`.                                       | Performing arithmetic on powers and bases; normalizing scales across conversions.                                      |
+| **`Number`**                  | `ucon.core`                             | Combines a numeric quantity with a unit and scale; the primary measurable type.                     | Performing arithmetic with units; converting between compatible units; representing physical quantities like 5 m/s.    |
+| **`Ratio`**                   | `ucon.core`                             | Represents the division of two `Number` objects; captures relationships between quantities.         | Expressing rates, densities, efficiencies (e.g., energy / time = power, length / time = velocity).                     |
+| **`units` module**            | `ucon.units`                            | Defines canonical unit instances (SI and common derived units).                                     | Quick access to standard physical units (`units.meter`, `units.second`, `units.newton`, etc.).                               |                                                   |
 
 ### Under the Hood
 
 `ucon` models unit math through a hierarchy where each layer builds on the last:
 
-<img src=https://gist.githubusercontent.com/withtwoemms/429d2ca1f979865aa80a2658bf9efa32/raw/f24134c362829dc72e7dff18bfcaa24b9be01b54/ucon.data-model_v035.png align="center" alt="ucon Data Model" width=600/>
+<img src=https://gist.githubusercontent.com/withtwoemms/429d2ca1f979865aa80a2658bf9efa32/raw/0c704737a52b9e4a87cda5c839e9aa40f7e5bb48/ucon.data-model_v035.png align="center" alt="ucon Data Model" width=600/>
 
 ## Why `ucon`?
 
@@ -93,22 +91,24 @@ Python already has mature libraries for handling units and physical quantities
 
 | Library   | Focus                                                   | Limitation                                                                                                             |
 | --------- | ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
-| **Pint**  | Runtime unit conversion and compatibility checking      | Treats quantities as decorated numbers — conversions work, but the algebra behind them isn't inspectable or type-safe. |
+| **Pint**  | Runtime unit conversion and compatibility checking      | Treats quantities as decorated numbers — conversions work, but the algebra behind them isn’t inspectable or type-safe. |
 | **SymPy** | Symbolic algebra and simplification of unit expressions | Excellent for symbolic reasoning, but not designed for runtime validation, conversion, or serialization.               |
 | **Unum**  | Unit-aware arithmetic and unit propagation              | Tracks units through arithmetic but lacks explicit dimensional algebra, conversion taxonomy, or runtime introspection. |
 
 Together, these tools can _use_ units, but none can explicitly represent and verify the relationships between units and dimensions.
 
-That's the gap `ucon` fills.
+That’s the gap `ucon` fills.
 
 It treats units, dimensions, and scales as first-class objects and builds a composable algebra around them.
 This allows you to:
 - Represent dimensional meaning explicitly (`Dimension`, `Vector`);
 - Compose and compute with type-safe, introspectable quantities (`Unit`, `Number`);
+- Perform reversible, declarative conversions (standard, linear, affine, nonlinear);
+- Serialize and validate measurements with Pydantic integration;
 - Extend the system with custom unit registries and conversion families.
 
 Where Pint, Unum, and SymPy focus on _how_ to compute with units,
-`ucon` focuses on why those computations make sense. Every operation checks the dimensional structure, _not just the unit labels_. This means ucon doesn't just track names: it enforces physics:
+`ucon` focuses on why those computations make sense. Every operation checks the dimensional structure, _not just the unit labels_. This means ucon doesn’t just track names: it enforces physics:
 ```python
 from ucon import Number, units
 
@@ -136,8 +136,7 @@ This sort of dimensional analysis:
 ```
 becomes straightforward when you define a measurement:
 ```python
-from ucon import Number, Scale, units
-from ucon.quantity import Ratio
+from ucon import Number, Scale, Units, Ratio
 
 # Two milliliters of bromine
 mL = Scale.milli * units.liter
@@ -150,36 +149,27 @@ bromine_density = Ratio(
 )
 
 # Multiply to find mass
-grams_bromine = bromine_density.evaluate() * two_mL_bromine
-print(grams_bromine)  # <6.238 g>
+grams_bromine = two_mL_bromine * bromine_density
+print(grams_bromine)  # <6.238 gram>
 ```
 
-Scale prefixes compose naturally:
-```python
-km = Scale.kilo * units.meter       # UnitProduct with kilo-scaled meter
-mg = Scale.milli * units.gram       # UnitProduct with milli-scaled gram
-
-print(km.shorthand)  # 'km'
-print(mg.shorthand)  # 'mg'
+Scale conversion is automatic and precise:
 
-# Scale arithmetic
-print(km.fold_scale())  # 1000.0
-print(mg.fold_scale())  # 0.001
+```python
+grams_bromine.to(Scale.milli)  # <6238.0 milligram>
+grams_bromine.to(Scale.kibi)   # <0.006091796875 kibigram>
 ```
 
-> **Note:** Unit _conversions_ (e.g., `number.to(units.inch)`) are planned for v0.4.x
-> via the `ConversionGraph` abstraction. See [ROADMAP.md](./ROADMAP.md).
-
 ---
 
 ## Roadmap Highlights
 
-| Version | Theme | Focus | Status |
-|----------|-------|--------|--------|
-| **0.3.5** | Dimensional Algebra | Unit/Scale separation, `UnitFactor`, `UnitProduct` | ✅ Complete |
-| [**0.4.x**](https://github.com/withtwoemms/ucon/milestone/2) | Conversion System | `ConversionGraph`, `Number.to()` | 🚧 Up Next |
-| [**0.6.x**](https://github.com/withtwoemms/ucon/milestone/4) | Nonlinear / Specialized Units | Decibel, Percent, pH | ⏳ Planned |
-| [**0.8.x**](https://github.com/withtwoemms/ucon/milestone/6) | Pydantic Integration | Type-safe quantity validation | ⏳ Planned |
+| Version | Theme | Focus |
+|----------|-------|--------|
+| [**0.3.x**](https://github.com/withtwoemms/ucon/milestone/1) | Primitive Type Refinement | Unified algebraic foundation |
+| [**0.4.x**](https://github.com/withtwoemms/ucon/milestone/2) | Conversion System | Linear & affine conversions |
+| [**0.6.x**](https://github.com/withtwoemms/ucon/milestone/4) | Nonlinear / Specialized Units | Decibel, Percent, pH |
+| [**0.8.x**](https://github.com/withtwoemms/ucon/milestone/6) | Pydantic Integration | Type-safe quantity validation |
 
 See full roadmap: [ROADMAP.md](./ROADMAP.md)
 
@@ -192,13 +182,13 @@ Ensure `nox` is installed.
 ```
 pip install -r requirements.txt
 ```
-Then run the full test suite (against all supported python versions) before committing:
+Then run the full test suite (agains all supported python versions) before committing:
 
 ```bash
 nox -s test
 ```
 ---
 
-> "If it can be measured, it can be represented.
+> “If it can be measured, it can be represented.
 If it can be represented, it can be validated.
-If it can be validated, it can be trusted."
+If it can be validated, it can be trusted.”

ucon-0.3.5rc1.dist-info/RECORD

@@ -0,0 +1,16 @@
+tests/ucon/__init__.py,sha256=9BAHYTs27Ed3VgqiMUH4XtVttAmOPgK0Zvj-dUNo7D8,119
+tests/ucon/test_algebra.py,sha256=0mxkiXibZfnzYtbscgVXPDcX1JelrVpcqNBcQe3cn3g,8330
+tests/ucon/test_core.py,sha256=x5JLJAKuaTBkxQzYqTFnDaStVcIlnCviJNiN2OJ7KGQ,32435
+tests/ucon/test_quantity.py,sha256=YLV78_t4AkZcJeEGu-lBvIXNLhTV_MLkTbIKV67rs4Y,14955
+tests/ucon/test_units.py,sha256=SILymDtDNDyxEhkYQubrfkakKCMexwEwjyHfhrkDrMI,869
+ucon/__init__.py,sha256=vJ6A2BU6s2_3vW4fExhn3VEjbn8yrvgF2hYBfGrKPrY,1865
+ucon/algebra.py,sha256=ZVF8B2kUOeSN20R-lTHJNJDxe_Zv7s8kJ70F2JOSYxk,7262
+ucon/core.py,sha256=cjq0hc5L7iA3ObWUT9JetUnWN6-WWqoQJ7c9YWbS35Y,29597
+ucon/quantity.py,sha256=rjJLx1bktnfddfgn80m3eyVEPq0LU9RmUVR0aOeopqM,7290
+ucon/units.py,sha256=-CShNMLr9t7f3pyYsfmZv3wMCZU4lEnoe8r_9YQWjxA,3783
+ucon-0.3.5rc1.dist-info/licenses/LICENSE,sha256=LtimSYBSw1L_X6n1-VEdZRdwuROzPumrMUNX21asFuI,11356
+ucon-0.3.5rc1.dist-info/licenses/NOTICE,sha256=bh4fBOItio3kM4hSNYhqfFpcaAvOoixjD7Du8im-sYA,1079
+ucon-0.3.5rc1.dist-info/METADATA,sha256=EqRVt-FxtnB-C73U_-JZqzouAKJl_y3ofiBAKxxBVtM,10626
+ucon-0.3.5rc1.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+ucon-0.3.5rc1.dist-info/top_level.txt,sha256=zZYRJiQrVUtN32ziJD2YEq7ClSvDmVYHYy5ArRAZGxI,11
+ucon-0.3.5rc1.dist-info/RECORD,,

ucon-0.3.5.dist-info/RECORD

@@ -1,16 +0,0 @@
-tests/ucon/__init__.py,sha256=9BAHYTs27Ed3VgqiMUH4XtVttAmOPgK0Zvj-dUNo7D8,119
-tests/ucon/test_algebra.py,sha256=0mxkiXibZfnzYtbscgVXPDcX1JelrVpcqNBcQe3cn3g,8330
-tests/ucon/test_core.py,sha256=x5JLJAKuaTBkxQzYqTFnDaStVcIlnCviJNiN2OJ7KGQ,32435
-tests/ucon/test_quantity.py,sha256=YLV78_t4AkZcJeEGu-lBvIXNLhTV_MLkTbIKV67rs4Y,14955
-tests/ucon/test_units.py,sha256=SILymDtDNDyxEhkYQubrfkakKCMexwEwjyHfhrkDrMI,869
-ucon/__init__.py,sha256=Va7KJ5ImQCkf06TWPKs0r6kfziURsvGh5I63ipiYiLo,1927
-ucon/algebra.py,sha256=ZVF8B2kUOeSN20R-lTHJNJDxe_Zv7s8kJ70F2JOSYxk,7262
-ucon/core.py,sha256=Dx8HNwjGpF-RFlO_2Cz1BZikRFeLcYlMy7hscw106vo,29825
-ucon/quantity.py,sha256=skXge9RU-5dW1ULCV6kiE4jk-rMVzXpBa4hV4mVr_Eo,7310
-ucon/units.py,sha256=-CShNMLr9t7f3pyYsfmZv3wMCZU4lEnoe8r_9YQWjxA,3783
-ucon-0.3.5.dist-info/licenses/LICENSE,sha256=LtimSYBSw1L_X6n1-VEdZRdwuROzPumrMUNX21asFuI,11356
-ucon-0.3.5.dist-info/licenses/NOTICE,sha256=bh4fBOItio3kM4hSNYhqfFpcaAvOoixjD7Du8im-sYA,1079
-ucon-0.3.5.dist-info/METADATA,sha256=unyLeaX8cl9Uf-EaX1NnylgaW5yUBLf_k22-cfCzaq0,11429
-ucon-0.3.5.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
-ucon-0.3.5.dist-info/top_level.txt,sha256=zZYRJiQrVUtN32ziJD2YEq7ClSvDmVYHYy5ArRAZGxI,11
-ucon-0.3.5.dist-info/RECORD,,