unitx 0.1.2__tar.gz → 0.1.3__tar.gz

{unitx-0.1.2 → unitx-0.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: unitx
-Version: 0.1.2
+Version: 0.1.3
 Summary: A modern, intuitive Python library for units, quantities, and dimensional analysis.
 Project-URL: Homepage, https://github.com/DaitTHU/unitx
 Project-URL: Issues, https://github.com/DaitTHU/unitx/issues

{unitx-0.1.2 → unitx-0.1.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "unitx"
-version = "0.1.2"
+version = "0.1.3"
 description = "A modern, intuitive Python library for units, quantities, and dimensional analysis."
 readme = "README.md"
 requires-python = ">=3.11"

unitx-0.1.3/src/unitx/__init__.py

@@ -0,0 +1,5 @@
+"""Utilities for working with physical units and quantities."""
+
+__all__ = ['Dimension', 'DIMENSIONLESS']
+
+from .dimension import Dimension, DIMENSIONLESS

unitx-0.1.3/src/unitx/dimension.py

@@ -0,0 +1,135 @@
+from __future__ import annotations
+
+from fractions import Fraction
+from typing import Iterable, Literal
+
+from .utils.number import common_fraction, ZERO, FloatConversionWarning
+from .utils.special_char import superscript
+
+__all__ = ['Dimension', 'DIMENSIONLESS']
+
+_SYMBOL = ('T', 'L', 'M', 'I', 'Θ', 'N', 'J')
+_SYMBOL_ASCII = ('T', 'L', 'M', 'I', 'Theta', 'N', 'J')
+_LEN = len(_SYMBOL)
+_ALLZERO = (ZERO,) * _LEN
+
+
+class Dimension:
+    '''
+    Implementation of physical dimensions.
+    - `T`: time
+    - `L`: length
+    - `M`: mass
+    - `I`: current
+    - `Θ`: temperature (use ASCII alias `Theta` for code)
+    - `N`: amount
+    - `J`: luminous
+
+    Construct
+    ---
+    >>> dim_velocity = Dimension(L=1, T=-1)
+    >>> dim_force = Dimension(M=1, L=1, T=-2)
+
+    Attributes
+    ---
+    You can access the exponents of each dimension by symbols or full names.
+    >>> dim_force.T
+    -2
+    >>> dim_force.mass
+    1
+
+    Operations
+    ---
+    You can perform multiplication, division, and exponentiation on dimensions.
+    >>> dim_force * dim_velocity
+    Dimension(T=-3, L=2, M=1)
+    >>> dim_velocity / Dimension(T=1)
+    Dimension(T=-2, L=1)
+    >>> dim_force ** 2
+    Dimension(T=-4, L=2, M=2)
+    >>> 1 / dim_force
+    Dimension(T=2, L=-1, M=-1)
+    '''
+
+    __slots__ = ('_exponents',)
+
+    def __new__(cls, T=0, L=0, M=0, I=0, Theta=0, N=0, J=0) -> Dimension:
+        exponents = tuple(map(common_fraction, (T, L, M, I, Theta, N, J)))
+        if not any(exponents):
+            return DIMENSIONLESS
+        obj = object.__new__(cls)
+        object.__setattr__(obj, '_exponents', exponents)
+        return obj
+
+    def __setattr__(self, name: str, value) -> None:
+        raise AttributeError(
+            'Dimension is immutable and cannot set attribute.')
+
+    @classmethod
+    def _from_iter(cls, iterable: Iterable[Fraction], /) -> Dimension:
+        '''Constructor from an iterable of exponents. Internal use only.'''
+        exponents = tuple(iterable)
+        if len(exponents) != _LEN:
+            raise ValueError(
+                f'Expected {_LEN} exponents, got {len(exponents)}.')
+        if not any(exponents):
+            return DIMENSIONLESS
+        obj = object.__new__(cls)
+        object.__setattr__(obj, '_exponents', exponents)
+        return obj
+
+    def __mul__(self, other: Dimension) -> Dimension:
+        if not isinstance(other, Dimension):
+            return NotImplemented
+        return self._from_iter(a + b for a, b in zip(self._exponents, other._exponents))
+
+    def __truediv__(self, other: Dimension) -> Dimension:
+        if not isinstance(other, Dimension):
+            return NotImplemented
+        return self._from_iter(a - b for a, b in zip(self._exponents, other._exponents))
+
+    def __pow__(self, power: int | Fraction | float) -> Dimension:
+        if isinstance(power, float):
+            import warnings
+            power_fraction = common_fraction(power)
+            warnings.warn(f'Float power {power} converted to {power_fraction}, use Fraction to specify an exact exponent.', FloatConversionWarning, stacklevel=2)
+            power = power_fraction
+        if not isinstance(power, (int, Fraction)):
+            return NotImplemented
+        return self._from_iter(a * power for a in self._exponents)
+
+    def __rtruediv__(self, other: Literal[1]) -> Dimension:
+        if other == 1:
+            return self._from_iter(-a for a in self._exponents)
+        return NotImplemented
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, Dimension):
+            return NotImplemented
+        return self._exponents == other._exponents
+
+    def __hash__(self) -> int: return hash(self._exponents)
+
+    def as_tuple(self) -> tuple[Fraction, ...]: return self._exponents
+
+    @staticmethod
+    def __unpack_exponents():
+        def __getter(index: int):
+            return lambda self: self._exponents[index]
+        return (property(__getter(i)) for i in range(_LEN))
+
+    T, L, M, I, Θ, N, J = __unpack_exponents()
+    Theta = Θ  # Alias for Θ
+    time, length, mass, current, temperature, amount, luminous = T, L, M, I, Θ, N, J
+
+    def __repr__(self) -> str:
+        para = ', '.join(f'{s}={v}' for s, v in zip(
+            _SYMBOL_ASCII, self._exponents) if v)
+        return '{}({})'.format(self.__class__.__name__, para)
+
+    def __str__(self) -> str:
+        return ''.join(s + superscript(v) for s, v in zip(_SYMBOL, self._exponents) if v) or '1'
+
+
+DIMENSIONLESS = object.__new__(Dimension)
+object.__setattr__(DIMENSIONLESS, '_exponents', _ALLZERO)

unitx-0.1.3/src/unitx/utils/number.py

@@ -0,0 +1,28 @@
+from decimal import Decimal
+from fractions import Fraction
+
+ZERO = Fraction(0)
+ONE = Fraction(1)
+TWO = Fraction(2)
+THREE = Fraction(3)
+TEN = Fraction(10)
+
+
+def common_fraction(value: int | float | Decimal | Fraction) -> Fraction:
+    '''
+    Convert a number to a Fraction with a small denominator, like 1, 42, -2/3...
+
+    >>> Fraction(1.47)
+    Fraction(6620291452234629, 4503599627370496)
+    >>> common_fraction(1.47)
+    Fraction(147, 100)
+    '''
+    if isinstance(value, Fraction):
+        return value
+    frac = Fraction(value)
+    return frac.limit_denominator() if isinstance(value, float) else frac
+
+
+class FloatConversionWarning(UserWarning):
+    '''Warning issued when a float is converted to an approximate Fraction.'''
+

unitx-0.1.3/src/unitx/utils/special_char.py

@@ -0,0 +1,39 @@
+import re
+from fractions import Fraction
+
+__all__ = ['superscript']
+
+DIGIT = '0123456789+-=()'
+SUPERSCRIPT = '⁰¹²³⁴⁵⁶⁷⁸⁹⁺⁻⁼⁽⁾'
+SUBSCRIPT = '₀₁₂₃₄₅₆₇₈₉₊₋₌₍₎'
+SUP_TRANS = str.maketrans(SUPERSCRIPT, DIGIT)
+SUB_TRANS = str.maketrans(SUBSCRIPT, DIGIT)
+
+
+def superscript(ratio: int | Fraction, /, *, omit1=True) -> str:
+    '''
+    Convert a ratio to a string of superscript characters.
+    Superscript ¹ is omitted by setting `omit1=True` (default).
+    >>> superscript(2)
+    '²'
+    >>> superscript(-1)
+    '⁻¹'
+    >>> superscript(Fraction(3, 4))
+    '³ᐟ⁴'
+    '''
+    if ratio < 0:
+        return '⁻' + superscript(-ratio, omit1=False)
+    if ratio.denominator == 1:
+        if omit1 and ratio.numerator == 1:
+            return ''
+        return _sup(ratio.numerator)
+    assert isinstance(ratio, Fraction)
+    return _sup(ratio.numerator) + 'ᐟ' + _sup(ratio.denominator)
+
+
+def _sup(number: int, /) -> str:
+    return ''.join(SUPERSCRIPT[int(digit)] for digit in str(number))
+
+
+def _sub(number: int, /) -> str:
+    return ''.join(SUBSCRIPT[int(digit)] for digit in str(number))

unitx-0.1.3/tests/test_dimension.py

@@ -0,0 +1,80 @@
+import pytest
+from fractions import Fraction
+from unitx import Dimension, DIMENSIONLESS
+
+
+def test_dimension_creation() -> None:
+    d1 = Dimension(T=1, L=2)
+    d2 = Dimension(T=1, L=2)
+    d3 = Dimension()
+
+    assert d1 == d2
+    assert d1 != d3
+    assert d3 is DIMENSIONLESS
+    assert d1.as_tuple() == (1, 2, 0, 0, 0, 0, 0)
+    assert repr(d2) == "Dimension(T=1, L=2)"
+    assert str(d3) == "1"
+    assert str(d1) == "TL²"
+
+
+def test_temperature_alias() -> None:
+    d = Dimension(Theta=1)
+
+    assert d.Theta == 1
+    assert d.Θ == 1
+    assert d.temperature == 1
+    assert str(d) == "Θ"
+
+
+def test_dimension_operations() -> None:
+    d1 = Dimension(T=1, L=2)
+    d2 = Dimension(M=1)
+
+    d_mul = d1 * d2
+    d_div = d1 / d2
+    d_pow = d1 ** 2
+    d_inv = 1 / d1
+
+    assert d_mul == Dimension(T=1, L=2, M=1)
+    assert d_div == Dimension(T=1, L=2, M=-1)
+    assert d_pow == Dimension(T=2, L=4)
+    assert d_inv == Dimension(T=-1, L=-2)
+
+
+def test_fractional_exponents() -> None:
+    d = Dimension(L=1) ** Fraction(1, 2)
+    assert d.L == Fraction(1, 2)
+    assert str(d) == "L¹ᐟ²"
+
+
+def test_invalid_operations() -> None:
+    with pytest.raises(TypeError):
+        Dimension(L=1) * 2  # type: ignore
+
+    with pytest.raises(TypeError):
+        Dimension(L=1) / 2  # type: ignore
+
+
+def test_hash() -> None:
+    assert hash(Dimension(L=1)) == hash(Dimension(L=1))
+    assert {Dimension(L=1), Dimension(L=1)} == {Dimension(L=1)}
+
+
+def test_float_power_warns() -> None:
+    with pytest.warns(UserWarning):
+        Dimension(L=1) ** 0.5  # type: ignore
+
+
+def test_operation_returns_dimensionless_singleton() -> None:
+    d = Dimension(L=1)
+    assert d / d is DIMENSIONLESS
+    assert d ** 0 is DIMENSIONLESS
+
+
+def test_dimension_is_immutable() -> None:
+    d = Dimension(L=1)
+
+    with pytest.raises(AttributeError):
+        d._exponents = (1, 2, 3, 4, 5, 6, 7)  # type: ignore
+    with pytest.raises(AttributeError):
+        d.L = 2  # type: ignore

unitx-0.1.2/src/unitx/__init__.py

@@ -1,3 +0,0 @@
-"""Utilities for working with physical units and quantities."""
-
-__all__ = []

unitx-0.1.2/tests/test_import.py

@@ -1,5 +0,0 @@
-import unitx
-
-
-def test_import() -> None:
-    assert unitx.__all__ == []