ucon 0.3.1__py3-none-any.whl

ucon/unit.py

@@ -0,0 +1,92 @@
+"""
+ucon.unit
+==========
+
+Defines the **Unit** abstraction — the symbolic and algebraic representation of
+a measurable quantity associated with a :class:`ucon.dimension.Dimension`.
+
+A :class:`Unit` pairs a human-readable name and aliases with its underlying
+dimension.
+
+Units are composable:
+
+    >>> from ucon import units
+    >>> units.meter / units.second
+    <velocity | (m/s)>
+
+They can be multiplied or divided to form compound units, and their dimensional
+relationships are preserved algebraically.
+"""
+from ucon.dimension import Dimension
+
+
+class Unit:
+    """
+    Represents a **unit of measure** associated with a :class:`Dimension`.
+
+    Parameters
+    ----------
+    *aliases : str
+        Optional shorthand symbols (e.g., "m", "sec").
+    name : str
+        Canonical name of the unit (e.g., "meter").
+    dimension : Dimension
+        The physical dimension this unit represents.
+
+    Notes
+    -----
+    Units participate in algebraic operations that produce new compound units:
+
+        >>> density = units.gram / units.liter
+        >>> density.dimension
+        <Dimension.density: Vector(T=0, L=-3, M=1, I=0, Θ=0, J=0, N=0)>
+
+    The combination rules follow the same algebra as :class:`Dimension`.
+    """
+    def __init__(self, *aliases: str, name: str = '', dimension: Dimension = Dimension.none):
+        self.dimension = dimension
+        self.name = name
+        self.aliases = aliases
+        self.shorthand = aliases[0] if aliases else self.name
+
+    def __repr__(self):
+        addendum = f' | {self.name}' if self.name else ''
+        return f'<{self.dimension.name}{addendum}>'
+
+    # TODO -- limit `operator` param choices
+    def generate_name(self, unit: 'Unit', operator: str):
+        if (self.dimension is Dimension.none) and not (unit.dimension is Dimension.none):
+            return unit.name
+        if not (self.dimension is Dimension.none) and (unit.dimension is Dimension.none):
+            return self.name
+
+        if not self.shorthand and not unit.shorthand:
+            name = ''
+        elif self.shorthand and not unit.shorthand:
+            name = f'({self.shorthand}{operator}?)'
+        elif not self.shorthand and unit.shorthand:
+            name = f'(?{operator}{unit.shorthand})'
+        else:
+            name = f'({self.shorthand}{operator}{unit.shorthand})'
+        return name
+
+    def __truediv__(self, unit: 'Unit') -> 'Unit':
+        # TODO -- define __eq__ for simplification, here
+        if (self.name == unit.name) and (self.dimension == unit.dimension):
+            return Unit()
+
+        if (unit.dimension is Dimension.none):
+            return self
+        
+        return Unit(name=self.generate_name(unit, '/'), dimension=self.dimension / unit.dimension)
+
+    def __mul__(self, unit: 'Unit') -> 'Unit':
+        return Unit(name=self.generate_name(unit, '*'), dimension=self.dimension * unit.dimension)
+
+    def __eq__(self, unit: 'Unit') -> bool:
+        if not isinstance(unit, Unit):
+            raise TypeError(f'Cannot compare Unit to non-Unit type: {type(unit)}')
+        return (self.name == unit.name) and (self.dimension == unit.dimension)
+
+    def __hash__(self) -> int:
+        return hash(tuple([self.name, self.dimension,]))

ucon/units.py

@@ -0,0 +1,84 @@
+"""
+ucon.units
+===========
+
+Defines and registers the canonical **unit set** for the *ucon* library.
+
+This module exports the standard SI base and derived units, along with a few
+common non-SI units. Each unit is a pre-constructed :class:`ucon.unit.Unit`
+object associated with a :class:`ucon.dimension.Dimension`.
+
+Example
+-------
+>>> from ucon import units
+>>> units.meter.dimension
+<Dimension.length>
+>>> units.newton.dimension
+<Dimension.force>
+
+Includes convenience utilities such as :func:`have(name)` for unit membership
+checks.
+
+Notes
+-----
+The design allows for future extensibility: users can register their own units,
+systems, or aliases dynamically, without modifying the core definitions.
+"""
+from ucon.dimension import Dimension
+from ucon.unit import Unit
+
+
+none = Unit()
+
+
+# -- International System of Units (SI) --------------------------------
+ampere = Unit('I', 'amp', name='ampere', dimension=Dimension.current)
+becquerel = Unit('Bq', name='becquerel', dimension=Dimension.frequency)
+celsius = Unit('°C', name='celsius', dimension=Dimension.temperature)
+coulomb = Unit('C', name='coulomb', dimension=Dimension.charge)
+farad = Unit('F', name='farad', dimension=Dimension.capacitance)
+gram = Unit('g', 'G', name='gram', dimension=Dimension.mass)
+gray = Unit('Gy', name='gray', dimension=Dimension.energy)
+henry = Unit('H', name='henry', dimension=Dimension.inductance)
+hertz = Unit('Hz', name='hertz', dimension=Dimension.frequency)
+hour = Unit('h', 'H', name='hour', dimension=Dimension.time)
+joule = Unit('J', name='joule', dimension=Dimension.energy)
+joule_per_kelvin = Unit('J/K', name='joule_per_kelvin', dimension=Dimension.entropy)
+kelvin = Unit('K', name='kelvin', dimension=Dimension.temperature)
+liter = Unit('L', 'l', name='liter', dimension=Dimension.volume)
+lumen = Unit('lm', name='lumen', dimension=Dimension.luminous_intensity)
+lux = Unit('lx', name='lux', dimension=Dimension.illuminance)
+meter = Unit('m', 'M', name='meter', dimension=Dimension.length)
+mole = Unit('mol', 'n', name='mole', dimension=Dimension.amount_of_substance)
+newton = Unit('N', name='newton', dimension=Dimension.force)
+ohm = Unit('Ω', name='ohm', dimension=Dimension.resistance)
+pascal = Unit('Pa', name='pascal', dimension=Dimension.pressure)
+radian = Unit('rad', name='radian', dimension=Dimension.none)
+second = Unit('s', 'sec', name='second', dimension=Dimension.time)
+sievert = Unit('Sv', name='sievert', dimension=Dimension.energy)
+siemens = Unit('S', name='siemens', dimension=Dimension.conductance)
+steradian = Unit('sr', name='steradian', dimension=Dimension.none)
+tesla = Unit('T', name='tesla', dimension=Dimension.magnetic_flux_density)
+volt = Unit('V', name='volt', dimension=Dimension.voltage)
+watt = Unit('W', name='watt', dimension=Dimension.power)
+webers = Unit('Wb', name='weber', dimension=Dimension.magnetic_flux)
+webers_per_meter = Unit('Wb/m', name='webers_per_meter', dimension=Dimension.magnetic_permeability)
+# ----------------------------------------------------------------------
+
+
+def have(name: str) -> bool:
+    assert name, "Must provide a unit name to check"
+    assert isinstance(name, str), "Unit name must be a string"
+    target = name.lower()
+    for attr, val in globals().items():
+        if isinstance(val, Unit):
+            # match the variable name (e.g., "none", "meter")
+            if attr.lower() == target:
+                return True
+            # match the declared unit name
+            if val.name and val.name.lower() == target:
+                return True
+            # match any alias
+            if any((alias or "").lower() == target for alias in getattr(val, "aliases", ())):
+                return True
+    return False

ucon-0.3.1.dist-info/METADATA

@@ -0,0 +1,192 @@
+Metadata-Version: 2.4
+Name: ucon
+Version: 0.3.1
+Summary: a tool for dimensional analysis: a "Unit CONverter"
+Home-page: https://github.com/withtwoemms/ucon
+Author: Emmanuel I. Obi
+Maintainer: Emmanuel I. Obi
+Maintainer-email: withtwoemms@gmail.com
+License: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: author
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license
+Dynamic: license-file
+Dynamic: maintainer
+Dynamic: maintainer-email
+Dynamic: summary
+
+<img src="https://gist.githubusercontent.com/withtwoemms/0cb9e6bc8df08f326771a89eeb790f8e/raw/dde6c7d3b8a7d79eb1006ace03fb834e044cdebc/ucon-logo.png" align="left" width="200" />
+
+# ucon
+
+> Pronounced: _yoo · cahn_
+
+[![tests](https://github.com/withtwoemms/ucon/workflows/tests/badge.svg)](https://github.com/withtwoemms/ucon/actions?query=workflow%3Atests)
+[![codecov](https://codecov.io/gh/withtwoemms/ucon/graph/badge.svg?token=BNONQTRJWG)](https://codecov.io/gh/withtwoemms/ucon)
+[![publish](https://github.com/withtwoemms/ucon/workflows/publish/badge.svg)](https://github.com/withtwoemms/ucon/actions?query=workflow%3Apublish)
+
+> A lightweight, **unit-aware computation library** for Python — built on first-principles.
+
+---
+
+## Overview
+
+`ucon` helps Python understand the *physical meaning* of your numbers.
+It combines **units**, **scales**, and **dimensions** into a composable algebra that supports:
+
+- Dimensional analysis through `Number` and `Ratio`
+- 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.
+
+## Introduction
+
+The crux of this tiny library is to provide abstractions that simplify the answering of questions like:
+
+> _"If given two milliliters of bromine (liquid Br<sub>2</sub>), how many grams of bromine does one have?"_
+
+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.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).                         |
+| **`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/f3518d37445301950026fc9ffd1bd062768005fe/ucon.data-model.png align="center" alt="ucon Data Model" width=600/>
+
+## Why `ucon`?
+
+Python already has mature libraries for handling units and physical quantities — Pint, SymPy, and Unum — each solving part of the same problem from different angles:
+
+| 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. |
+| **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.
+
+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:
+```python
+from ucon import Number, units
+
+length = Number(quantity=5, unit=units.meter)
+time = Number(quantity=2, unit=units.second)
+
+speed = length / time     # ✅ valid: L / T = velocity
+invalid = length + time   # ❌ raises: incompatible dimensions
+```
+
+## Setup
+
+Simple:
+```bash
+pip install ucon
+```
+
+## Usage
+
+This sort of dimensional analysis:
+```
+ 2 mL bromine | 3.119 g bromine
+--------------x-----------------  #=> 6.238 g bromine
+      1       |  1 mL bromine
+```
+becomes straightforward when you define a measurement:
+```python
+from ucon import Number, Scale, Units, Ratio
+
+# Two milliliters of bromine
+two_mL_bromine = Number(unit=Units.liter, scale=Scale.milli, quantity=2)
+
+# Density of bromine: 3.119 g/mL
+bromine_density = Ratio(
+    numerator=Number(unit=Units.gram, quantity=3.119),
+    denominator=Number(unit=Units.liter, scale=Scale.milli),
+)
+
+# Multiply to find mass
+grams_bromine = two_mL_bromine * bromine_density
+print(grams_bromine)  # <6.238 gram>
+```
+
+Scale conversion is automatic and precise:
+
+```python
+grams_bromine.to(Scale.milli)  # <6238.0 milligram>
+grams_bromine.to(Scale.kibi)   # <0.006091796875 kibigram>
+```
+
+---
+
+## Roadmap Highlights
+
+| 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)
+
+---
+
+## Contributing
+
+Contributions, issues, and pull requests are welcome!
+Ensure `nox` is installed.
+```
+pip install -r requirements.txt
+```
+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 represented, it can be validated.
+If it can be validated, it can be trusted.”

ucon-0.3.1.dist-info/RECORD

@@ -0,0 +1,15 @@
+tests/ucon/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+tests/ucon/test_core.py,sha256=fD4c6K35RxCyaR5pHqBSr8DEHTqmMvYX9ZuVS6JdSwo,16408
+tests/ucon/test_dimension.py,sha256=JyA9ySFvohs2l6oK77ehCQ7QvvFVqB_9t0iC7CUErjw,7296
+tests/ucon/test_unit.py,sha256=vEPOeSxFBqcRBAUczCN9KPo_dTmLk4LQExPSt6UGVa4,5712
+tests/ucon/test_units.py,sha256=248JZbo8RVvG_q3T0IhKG43vxM4F_2Xgf4_RjGZNsFM,704
+ucon/__init__.py,sha256=ZWWLodIiG17OgCfoAm532wpwmJzdRXlUGX3w6OBxFeQ,1743
+ucon/core.py,sha256=DRymayBlXfVZMSHIt_Hi-xe8GPs9WYHOCCJ1QDaKn7Q,10643
+ucon/dimension.py,sha256=uUP05bPE8r15oFeD36DrclNIfBsugV7uFhvtJRYy4qI,6598
+ucon/unit.py,sha256=KxOBcQNxciljGskhZCfktLhRF5u-rWgrTg565Flo3eI,3213
+ucon/units.py,sha256=e1j7skYMghlMZi7l94EAgxq4_lNRDC7FcSooJoE_U50,3689
+ucon-0.3.1.dist-info/licenses/LICENSE,sha256=-Djjiq2wM8Cc6fzTsdMbr_T2_uaX6Yorxcemr3GGkqc,1072
+ucon-0.3.1.dist-info/METADATA,sha256=kchGc0Q4C3RSbQdT1WxGlFMEsRqp1ZNnptzy1VF4SQo,10603
+ucon-0.3.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+ucon-0.3.1.dist-info/top_level.txt,sha256=zZYRJiQrVUtN32ziJD2YEq7ClSvDmVYHYy5ArRAZGxI,11
+ucon-0.3.1.dist-info/RECORD,,

ucon-0.3.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

ucon-0.3.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020 Emmanuel I. Obi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ucon-0.3.1.dist-info/top_level.txt

@@ -0,0 +1,2 @@
+tests
+ucon