python-units 0.3.0__tar.gz → 0.4.0__tar.gz

{python_units-0.3.0 → python_units-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-units
-Version: 0.3.0
+Version: 0.4.0
 Summary: Python library to represent numbers with units
 Author-email: "Paul K. Korir, PhD" <paul.korir@gmail.com>
 License-Expression: GPL-3.0-or-later
@@ -30,7 +30,74 @@ Dynamic: license-file
 [![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://pypi.org/project/python-units/)
 [![Coverage 92%](https://img.shields.io/badge/coverage-92%25-brightgreen.svg)](/Users/paulkorir/PycharmProjects/python-units/tests/unit/test_units.py)
 
-Python library to represent quantities with units.
+# The Price of Unitless Arithmetic
+
+On September 23, 1999, flight controllers expected NASA's Mars Climate Orbiter
+to pass behind Mars, fire its engine, and come back into radio contact after
+orbit insertion. It never came back. When engineers reviewed the final hours of
+flight data, the trajectory was not where the navigation system thought it was:
+the spacecraft had approached Mars far lower than planned. The investigation
+traced the loss to a unit boundary that software had failed to defend. One side
+of the system handled "small forces" data in English units; the navigation side
+expected metric units.
+
+That is the kind of bug this package is meant to stop. Without units, the
+mistake is just arithmetic:
+
+```python
+# A navigation routine expects impulse in newton-seconds.
+expected_impulse_ns = 120
+
+# A supplier routine accidentally sends a value in a different force unit.
+# The number is still just a number, so Python accepts it.
+reported_impulse_other_units = 120
+
+trajectory_impulse = expected_impulse_ns + reported_impulse_other_units
+print(trajectory_impulse)  # 240
+```
+
+There is nothing in `240` that tells you a spacecraft trajectory may now be
+wrong. With units attached, the mismatch stops at the boundary:
+
+```python
+from units import CustomUnitBase
+from units.dimension import DimensionSystem
+from units.si import newton, second
+
+class EnglishImpulseUnit(CustomUnitBase):
+    dimension_system = DimensionSystem("english-impulse", ("lbf_s",))
+
+pound_force_second = EnglishImpulseUnit.define("lbf_s")
+
+expected_impulse = 120 * newton * second
+reported_impulse = 120 * pound_force_second
+
+trajectory_impulse = expected_impulse + reported_impulse
+# UnitCompatibilityError: units mismatch: m·kg·s^-1 and lbf_s
+```
+
+That failure is the feature. A bug that would otherwise move through a program
+as an ordinary number is stopped before it contaminates mission-critical
+calculations.
+
+Background: NASA/JPL describe the Mars Climate Orbiter loss as a navigation
+error caused by a failure to translate English units to metric, sending the
+spacecraft too close to Mars.
+
+Source: https://en.wikipedia.org/wiki/Mars_Climate_Orbiter
+
+# About
+
+`python-units` is a Python package for unit-aware arithmetic. It provides:
+- a `Quantity` type that combines numeric values with unit information
+- a registry of SI base and derived units
+- algebraic unit manipulation and compatibility checks
+- explicit multiplicative conversions between compatible units
+- a public API that prioritizes scalar-by-unit construction and SI unit imports
+- a migration path from the legacy `Unit` constructor and compatibility helpers
+- a Python 3-only codebase with no Python 2 compatibility shims
+- a project structure that separates public API, core logic, data models, and utilities
+- comprehensive unit tests and documentation
 
 Supported Python versions: 3.10+
 
@@ -139,12 +206,18 @@ Stable top-level imports:
 
 * `Quantity`
 * `Unit` (compatibility alias for `Quantity`)
+* `convert`
+* `value`
+* `unit`
+* `multiplier`
 * `UnitsError`, `InvalidUnitError`, `InvalidValueError`,
   `UnitCompatibilityError`, `UnitOperandError`
 
 Canonical unit imports:
 
 * `from units.si import metre, second, newton`
+* prefixed and scaled units such as `kilometre`, `centimetre`, `gram`,
+  `minute`, `hour`, `kilowatt`, and `millivolt`
 
 Legacy compatibility helpers:
 
@@ -166,11 +239,119 @@ deprecated compatibility paths are scheduled for removal in `1.0.0`.
 
 * Addition and subtraction require identical units.
 * Multiplication and division combine units algebraically.
+* Explicit scale-only conversions are available through `quantity.to(unit)` and
+  `convert(quantity, unit)`.
 * Integer powers of units and unit-bearing quantities are supported.
 * Unitless quantities are supported explicitly.
+* Affine conversions, such as `degree_celcius <-> kelvin`, are intentionally not
+  implemented yet.
 * The core quantity model allows signed values. Domain-specific constraints such
   as non-negative lengths should be enforced by higher-level types or validators.
 
+# Conversion foundations
+
+`0.4.0` adds explicit multiplicative conversions. Conversion never happens
+silently during addition or subtraction; you choose the target unit.
+
+```python
+from units import convert, multiplier, unit, value
+from units.si import gram, hour, kilogram, kilometre, metre, minute, second
+
+distance = 1.5 * kilometre
+print(distance.to(metre))           # 1500 m
+print(convert(2500 * metre, kilometre))  # 2.5 km
+
+duration = 2 * hour
+print(duration.to(minute))          # 120 min
+print((1500 * gram).to(kilogram))   # 1.5 kg
+
+speed = (72 * kilometre) / (2 * hour)
+print(speed)                        # 10.0 m·s^-1
+
+print(value(distance))              # 1.5
+print(unit(distance))               # km
+print(multiplier(kilometre))        # 1000.0
+```
+
+The conversion model is scale-only in this release. Celsius is a named
+temperature unit, but converting between Celsius and kelvin requires an offset
+and is reserved for a later affine-conversion release.
+
+# Prefixed and scaled units
+
+Common SI prefixes and practical time units are available from `units.si`:
+
+```python
+from units.si import (
+    centimetre,
+    gram,
+    hour,
+    kiloampere,
+    kilometre,
+    kilovolt,
+    kilowatt,
+    megawatt,
+    micrometre,
+    microsecond,
+    milliampere,
+    milligram,
+    millimetre,
+    millisecond,
+    millivolt,
+    milliwatt,
+    minute,
+    nanometre,
+    nanosecond,
+    tonne,
+)
+```
+
+Scaled units participate correctly in multiplication, division, and powers:
+
+```python
+from units.si import hour, kilometre, metre
+
+area = (2 * kilometre) * (3 * metre)
+print(area)                         # 6000 m^2
+
+square = (2 * kilometre) ** 2
+print(square)                       # 4000000 m^2
+
+speed = (72 * kilometre) / (2 * hour)
+print(speed)                        # 10.0 m·s^-1
+```
+
+# Familiar composite units
+
+Composite unit expressions such as `kilometre / hour` are algebraic unit
+definitions. They carry the correct scale factor, but anonymous composite units
+render in canonical SI base form:
+
+```python
+from units.si import hour, kilometre
+
+speed = 30 * kilometre / hour
+print(speed)                        # 8.333333333333334 m·s^-1
+```
+
+When you want a semantically familiar display unit, give that composite unit an
+explicit name and convert to it:
+
+```python
+from units import DerivedUnit, convert
+from units.si import hour, kilometre
+
+kilometres_per_hour = DerivedUnit.define("km·hr^-1", kilometre / hour)
+
+speed = 30 * kilometre / hour
+print(convert(speed, kilometres_per_hour))  # 30 km·hr^-1
+print(30 * kilometres_per_hour)             # 30 km·hr^-1
+```
+
+This keeps the arithmetic deterministic while letting application code choose
+domain-specific display names such as `km·hr^-1`, `N·m`, or any other familiar
+derived unit form.
+
 # Real-world examples
 
 ## Electrical engineering: from resistance to power dissipation

{python_units-0.3.0 → python_units-0.4.0}/README.md

@@ -4,7 +4,74 @@
 [![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://pypi.org/project/python-units/)
 [![Coverage 92%](https://img.shields.io/badge/coverage-92%25-brightgreen.svg)](/Users/paulkorir/PycharmProjects/python-units/tests/unit/test_units.py)
 
-Python library to represent quantities with units.
+# The Price of Unitless Arithmetic
+
+On September 23, 1999, flight controllers expected NASA's Mars Climate Orbiter
+to pass behind Mars, fire its engine, and come back into radio contact after
+orbit insertion. It never came back. When engineers reviewed the final hours of
+flight data, the trajectory was not where the navigation system thought it was:
+the spacecraft had approached Mars far lower than planned. The investigation
+traced the loss to a unit boundary that software had failed to defend. One side
+of the system handled "small forces" data in English units; the navigation side
+expected metric units.
+
+That is the kind of bug this package is meant to stop. Without units, the
+mistake is just arithmetic:
+
+```python
+# A navigation routine expects impulse in newton-seconds.
+expected_impulse_ns = 120
+
+# A supplier routine accidentally sends a value in a different force unit.
+# The number is still just a number, so Python accepts it.
+reported_impulse_other_units = 120
+
+trajectory_impulse = expected_impulse_ns + reported_impulse_other_units
+print(trajectory_impulse)  # 240
+```
+
+There is nothing in `240` that tells you a spacecraft trajectory may now be
+wrong. With units attached, the mismatch stops at the boundary:
+
+```python
+from units import CustomUnitBase
+from units.dimension import DimensionSystem
+from units.si import newton, second
+
+class EnglishImpulseUnit(CustomUnitBase):
+    dimension_system = DimensionSystem("english-impulse", ("lbf_s",))
+
+pound_force_second = EnglishImpulseUnit.define("lbf_s")
+
+expected_impulse = 120 * newton * second
+reported_impulse = 120 * pound_force_second
+
+trajectory_impulse = expected_impulse + reported_impulse
+# UnitCompatibilityError: units mismatch: m·kg·s^-1 and lbf_s
+```
+
+That failure is the feature. A bug that would otherwise move through a program
+as an ordinary number is stopped before it contaminates mission-critical
+calculations.
+
+Background: NASA/JPL describe the Mars Climate Orbiter loss as a navigation
+error caused by a failure to translate English units to metric, sending the
+spacecraft too close to Mars.
+
+Source: https://en.wikipedia.org/wiki/Mars_Climate_Orbiter
+
+# About
+
+`python-units` is a Python package for unit-aware arithmetic. It provides:
+- a `Quantity` type that combines numeric values with unit information
+- a registry of SI base and derived units
+- algebraic unit manipulation and compatibility checks
+- explicit multiplicative conversions between compatible units
+- a public API that prioritizes scalar-by-unit construction and SI unit imports
+- a migration path from the legacy `Unit` constructor and compatibility helpers
+- a Python 3-only codebase with no Python 2 compatibility shims
+- a project structure that separates public API, core logic, data models, and utilities
+- comprehensive unit tests and documentation
 
 Supported Python versions: 3.10+
 
@@ -113,12 +180,18 @@ Stable top-level imports:
 
 * `Quantity`
 * `Unit` (compatibility alias for `Quantity`)
+* `convert`
+* `value`
+* `unit`
+* `multiplier`
 * `UnitsError`, `InvalidUnitError`, `InvalidValueError`,
   `UnitCompatibilityError`, `UnitOperandError`
 
 Canonical unit imports:
 
 * `from units.si import metre, second, newton`
+* prefixed and scaled units such as `kilometre`, `centimetre`, `gram`,
+  `minute`, `hour`, `kilowatt`, and `millivolt`
 
 Legacy compatibility helpers:
 
@@ -140,11 +213,119 @@ deprecated compatibility paths are scheduled for removal in `1.0.0`.
 
 * Addition and subtraction require identical units.
 * Multiplication and division combine units algebraically.
+* Explicit scale-only conversions are available through `quantity.to(unit)` and
+  `convert(quantity, unit)`.
 * Integer powers of units and unit-bearing quantities are supported.
 * Unitless quantities are supported explicitly.
+* Affine conversions, such as `degree_celcius <-> kelvin`, are intentionally not
+  implemented yet.
 * The core quantity model allows signed values. Domain-specific constraints such
   as non-negative lengths should be enforced by higher-level types or validators.
 
+# Conversion foundations
+
+`0.4.0` adds explicit multiplicative conversions. Conversion never happens
+silently during addition or subtraction; you choose the target unit.
+
+```python
+from units import convert, multiplier, unit, value
+from units.si import gram, hour, kilogram, kilometre, metre, minute, second
+
+distance = 1.5 * kilometre
+print(distance.to(metre))           # 1500 m
+print(convert(2500 * metre, kilometre))  # 2.5 km
+
+duration = 2 * hour
+print(duration.to(minute))          # 120 min
+print((1500 * gram).to(kilogram))   # 1.5 kg
+
+speed = (72 * kilometre) / (2 * hour)
+print(speed)                        # 10.0 m·s^-1
+
+print(value(distance))              # 1.5
+print(unit(distance))               # km
+print(multiplier(kilometre))        # 1000.0
+```
+
+The conversion model is scale-only in this release. Celsius is a named
+temperature unit, but converting between Celsius and kelvin requires an offset
+and is reserved for a later affine-conversion release.
+
+# Prefixed and scaled units
+
+Common SI prefixes and practical time units are available from `units.si`:
+
+```python
+from units.si import (
+    centimetre,
+    gram,
+    hour,
+    kiloampere,
+    kilometre,
+    kilovolt,
+    kilowatt,
+    megawatt,
+    micrometre,
+    microsecond,
+    milliampere,
+    milligram,
+    millimetre,
+    millisecond,
+    millivolt,
+    milliwatt,
+    minute,
+    nanometre,
+    nanosecond,
+    tonne,
+)
+```
+
+Scaled units participate correctly in multiplication, division, and powers:
+
+```python
+from units.si import hour, kilometre, metre
+
+area = (2 * kilometre) * (3 * metre)
+print(area)                         # 6000 m^2
+
+square = (2 * kilometre) ** 2
+print(square)                       # 4000000 m^2
+
+speed = (72 * kilometre) / (2 * hour)
+print(speed)                        # 10.0 m·s^-1
+```
+
+# Familiar composite units
+
+Composite unit expressions such as `kilometre / hour` are algebraic unit
+definitions. They carry the correct scale factor, but anonymous composite units
+render in canonical SI base form:
+
+```python
+from units.si import hour, kilometre
+
+speed = 30 * kilometre / hour
+print(speed)                        # 8.333333333333334 m·s^-1
+```
+
+When you want a semantically familiar display unit, give that composite unit an
+explicit name and convert to it:
+
+```python
+from units import DerivedUnit, convert
+from units.si import hour, kilometre
+
+kilometres_per_hour = DerivedUnit.define("km·hr^-1", kilometre / hour)
+
+speed = 30 * kilometre / hour
+print(convert(speed, kilometres_per_hour))  # 30 km·hr^-1
+print(30 * kilometres_per_hour)             # 30 km·hr^-1
+```
+
+This keeps the arithmetic deterministic while letting application code choose
+domain-specific display names such as `km·hr^-1`, `N·m`, or any other familiar
+derived unit form.
+
 # Real-world examples
 
 ## Electrical engineering: from resistance to power dissipation

{python_units-0.3.0 → python_units-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-units"
-version = "0.3.0"
+version = "0.4.0"
 description = "Python library to represent numbers with units"
 readme = { file = "README.md", content-type = "text/markdown" }
 requires-python = ">=3.10"

{python_units-0.3.0 → python_units-0.4.0}/src/api/public.py

@@ -5,20 +5,40 @@ from api.si import (
     ampere,
     becquerel,
     candela,
+    centimetre,
     coulomb,
     degree_celcius,
     farad,
+    gram,
     gray,
     henry,
     hertz,
+    hour,
     joule,
     katal,
     kelvin,
     kilogram,
+    kiloampere,
+    kilometre,
+    kilovolt,
+    kilowatt,
     lumen,
     lux,
+    megawatt,
     metre,
+    microgram,
+    micrometre,
+    microsecond,
+    milliampere,
+    milligram,
+    millimetre,
+    millisecond,
+    millivolt,
+    milliwatt,
+    minute,
     mole,
+    nanometre,
+    nanosecond,
     newton,
     ohm,
     pascal,
@@ -28,6 +48,7 @@ from api.si import (
     sievert,
     steradian,
     tesla,
+    tonne,
     volt,
     watt,
     weber,
@@ -43,12 +64,16 @@ from core.quantity import (
     Quantity,
     complex_quantity,
     complex_unit,
+    convert,
     float_quantity,
     float_unit,
     int_quantity,
     int_unit,
     long_quantity,
     long_unit,
+    multiplier,
+    unit,
+    value,
 )
 from core.unit_definitions import BaseUnit, CustomUnitBase, DerivedUnit, SIUnit
 from models.dimension import Dimension, DimensionSystem
@@ -73,28 +98,50 @@ __all__ = [
     "ampere",
     "becquerel",
     "candela",
+    "centimetre",
     "complex_quantity",
     "complex_unit",
+    "convert",
     "coulomb",
     "degree_celcius",
     "farad",
     "float_quantity",
     "float_unit",
+    "gram",
     "gray",
     "henry",
     "hertz",
+    "hour",
     "int_quantity",
     "int_unit",
     "joule",
     "katal",
     "kelvin",
     "kilogram",
+    "kiloampere",
+    "kilometre",
+    "kilovolt",
+    "kilowatt",
     "long_quantity",
     "long_unit",
     "lumen",
     "lux",
+    "megawatt",
     "metre",
+    "microgram",
+    "micrometre",
+    "microsecond",
+    "milliampere",
+    "milligram",
+    "millimetre",
+    "millisecond",
+    "millivolt",
+    "milliwatt",
+    "minute",
+    "multiplier",
     "mole",
+    "nanometre",
+    "nanosecond",
     "newton",
     "ohm",
     "pascal",
@@ -104,6 +151,9 @@ __all__ = [
     "sievert",
     "steradian",
     "tesla",
+    "tonne",
+    "unit",
+    "value",
     "volt",
     "watt",
     "weber",

{python_units-0.3.0 → python_units-0.4.0}/src/api/si.py

@@ -29,7 +29,11 @@ siemens = DerivedUnit.define("S", ampere / volt)
 weber = DerivedUnit.define("Wb", volt * second)
 tesla = DerivedUnit.define("T", weber / metre / metre)
 henry = DerivedUnit.define("H", weber / ampere)
-degree_celcius = DerivedUnit.define("°C", kelvin)
+degree_celcius = DerivedUnit.define(
+    "°C",
+    kelvin,
+    supports_multiplicative_conversion=False,
+)
 lumen = DerivedUnit.define("lm", candela * steradian)
 lux = DerivedUnit.define("lx", lumen / metre / metre)
 becquerel = DerivedUnit.define("Bq", SIUnit() / second)
@@ -37,6 +41,31 @@ gray = DerivedUnit.define("Gy", joule / kilogram)
 sievert = DerivedUnit.define("Sv", joule / kilogram)
 katal = DerivedUnit.define("kat", mole / second)
 
+kilometre = DerivedUnit.define("km", metre, conversion_factor=1000.0)
+centimetre = DerivedUnit.define("cm", metre, conversion_factor=0.01)
+millimetre = DerivedUnit.define("mm", metre, conversion_factor=0.001)
+micrometre = DerivedUnit.define("µm", metre, conversion_factor=0.000001)
+nanometre = DerivedUnit.define("nm", metre, conversion_factor=0.000000001)
+
+gram = DerivedUnit.define("g", kilogram, conversion_factor=0.001)
+milligram = DerivedUnit.define("mg", kilogram, conversion_factor=0.000001)
+microgram = DerivedUnit.define("µg", kilogram, conversion_factor=0.000000001)
+tonne = DerivedUnit.define("t", kilogram, conversion_factor=1000.0)
+
+minute = DerivedUnit.define("min", second, conversion_factor=60.0)
+hour = DerivedUnit.define("h", second, conversion_factor=3600.0)
+millisecond = DerivedUnit.define("ms", second, conversion_factor=0.001)
+microsecond = DerivedUnit.define("µs", second, conversion_factor=0.000001)
+nanosecond = DerivedUnit.define("ns", second, conversion_factor=0.000000001)
+
+milliampere = DerivedUnit.define("mA", ampere, conversion_factor=0.001)
+kiloampere = DerivedUnit.define("kA", ampere, conversion_factor=1000.0)
+millivolt = DerivedUnit.define("mV", volt, conversion_factor=0.001)
+kilovolt = DerivedUnit.define("kV", volt, conversion_factor=1000.0)
+milliwatt = DerivedUnit.define("mW", watt, conversion_factor=0.001)
+kilowatt = DerivedUnit.define("kW", watt, conversion_factor=1000.0)
+megawatt = DerivedUnit.define("MW", watt, conversion_factor=1000000.0)
+
 for unit in (
     newton,
     pascal,
@@ -59,20 +88,40 @@ __all__ = [
     "ampere",
     "becquerel",
     "candela",
+    "centimetre",
     "coulomb",
     "degree_celcius",
     "farad",
+    "gram",
     "gray",
     "henry",
     "hertz",
+    "hour",
     "joule",
     "katal",
     "kelvin",
     "kilogram",
+    "kiloampere",
+    "kilometre",
+    "kilovolt",
+    "kilowatt",
     "lumen",
     "lux",
+    "megawatt",
     "metre",
+    "microgram",
+    "micrometre",
+    "microsecond",
+    "milliampere",
+    "milligram",
+    "millimetre",
+    "millisecond",
+    "millivolt",
+    "milliwatt",
+    "minute",
     "mole",
+    "nanometre",
+    "nanosecond",
     "newton",
     "ohm",
     "pascal",
@@ -82,6 +131,7 @@ __all__ = [
     "sievert",
     "steradian",
     "tesla",
+    "tonne",
     "volt",
     "watt",
     "weber",

{python_units-0.3.0 → python_units-0.4.0}/src/core/__init__.py

@@ -11,12 +11,16 @@ from .quantity import (
     Quantity,
     complex_quantity,
     complex_unit,
+    convert,
     float_quantity,
     float_unit,
     int_quantity,
     int_unit,
     long_quantity,
     long_unit,
+    multiplier,
+    unit,
+    value,
 )
 from .unit_definitions import BaseUnit, CustomUnitBase, DerivedUnit, SIUnit
 
@@ -33,10 +37,14 @@ __all__ = [
     "UnitsError",
     "complex_quantity",
     "complex_unit",
+    "convert",
     "float_quantity",
     "float_unit",
     "int_quantity",
     "int_unit",
     "long_quantity",
     "long_unit",
+    "multiplier",
+    "unit",
+    "value",
 ]