units-lib 0.2.0__tar.gz → 0.3.0__tar.gz

{units_lib-0.2.0 → units_lib-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: units-lib
-Version: 0.2.0
+Version: 0.3.0
 Summary: Library for managing calculations of quantities with units.
 Author-email: blm34 <pypi.escalate394@passmail.net>
 License-Expression: GPL-3.0-or-later

units_lib-0.3.0/tests/hypothesis/test_scale.py

@@ -0,0 +1,248 @@
+import math
+from fractions import Fraction as F
+
+import pytest
+from hypothesis import given
+from hypothesis import strategies as st
+
+from units_lib.scale import Scale
+
+ONE = Scale()
+PI = Scale.constant("pi")
+
+
+rationals = st.builds(F, st.integers(1, 10**6), st.integers(1, 10**4))
+
+exponents = st.fractions(min_value=-3, max_value=3, max_denominator=5)
+int_exponents = st.integers(-3, 3)
+nonzero_exponents = exponents.filter(lambda e: e != 0)
+
+
+@st.composite
+def scales(draw) -> Scale:
+    """Scales mixing rational powers of primes with powers of pi."""
+    s = Scale.from_number(draw(rationals)) ** draw(exponents)
+    s *= PI ** draw(exponents)
+    return s
+
+
+def is_prime(n: int) -> bool:
+    return n > 1 and all(n % d for d in range(2, math.isqrt(n) + 1))
+
+
+def is_square(n: int) -> bool:
+    return math.isqrt(n) ** 2 == n
+
+
+def approx(x: float) -> object:
+    return pytest.approx(x, rel=1e-9)
+
+
+@given(rationals)
+def test_from_number_roundtrips(q):
+    assert Scale.from_number(q).to_fraction() == q
+
+
+@given(rationals)
+def test_from_number_uses_only_primes_and_nonzero_exponents(q):
+    for base, exp in Scale.from_number(q).factors:
+        assert isinstance(base, int) and is_prime(base)
+        assert exp != 0
+
+
+@given(rationals, rationals)
+def test_from_number_is_injective(a, b):
+    assert (Scale.from_number(a) == Scale.from_number(b)) == (a == b)
+
+
+@given(rationals, rationals)
+def test_from_number_is_multiplicative(a, b):
+    assert Scale.from_number(a) * Scale.from_number(b) == Scale.from_number(a * b)
+
+
+@given(rationals)
+def test_from_number_float_matches_fraction(q):
+    assert float(Scale.from_number(q)) == approx(float(q))
+
+
+@given(st.integers(max_value=0))
+def test_from_number_rejects_non_positive_ints(n):
+    with pytest.raises(ValueError):
+        Scale.from_number(n)
+
+
+@given(rationals)
+def test_from_number_rejects_negated_rationals(q):
+    with pytest.raises(ValueError):
+        Scale.from_number(-q)
+
+
+@given(scales(), scales())
+def test_results_never_contain_zero_exponents(a, b):
+    for s in (a * b, a / b, a**2, a ** F(-1, 3)):
+        assert all(exp != 0 for _, exp in s.factors)
+
+
+@given(scales(), scales())
+def test_mul_commutative(a, b):
+    assert a * b == b * a
+
+
+@given(scales(), scales(), scales())
+def test_mul_associative(a, b, c):
+    assert (a * b) * c == a * (b * c)
+
+
+@given(scales())
+def test_mul_identity(a):
+    assert a * ONE == a == ONE * a
+
+
+@given(scales())
+def test_inverse(a):
+    assert a * a**-1 == ONE
+    assert a / a == ONE
+
+
+@given(scales(), scales())
+def test_div_is_mul_by_inverse(a, b):
+    assert a / b == a * b**-1
+
+
+@given(scales(), scales())
+def test_div_undoes_mul(a, b):
+    assert (a * b) / b == a
+
+
+@given(scales(), scales())
+def test_operations_do_not_mutate_operands(a, b):
+    before = (a.factors, b.factors)
+    _ = a * b, a / b, a**2
+    assert (a.factors, b.factors) == before
+
+
+@given(scales(), rationals)
+def test_mul_by_number_equals_mul_by_scale(a, q):
+    assert a * q == a * Scale.from_number(q)
+
+
+@given(scales(), rationals)
+def test_div_by_number_equals_div_by_scale(a, q):
+    assert a / q == a / Scale.from_number(q)
+
+
+@given(scales(), st.integers(max_value=0))
+def test_mul_by_non_positive_int_raise(a, n):
+    with pytest.raises(ValueError):
+        _ = a * n
+
+
+@given(scales(), st.integers(max_value=0))
+def test_div_by_non_positive_int_raise(a, n):
+    with pytest.raises(ValueError):
+        _ = a / n
+
+
+@given(scales())
+def test_pow_one(a):
+    assert a**0 == ONE
+
+
+@given(scales())
+def test_pow_zero(a):
+    assert a**1 == a
+
+
+@given(scales(), exponents, exponents)
+def test_pow_adds_exponents(a, p, q):
+    assert a ** (p + q) == a**p * a**q
+
+
+@given(scales(), exponents, exponents)
+def test_pow_of_pow_multiplies_exponents(a, p, q):
+    assert (a**p) ** q == a ** (p * q)
+
+
+@given(scales(), scales(), exponents)
+def test_pow_distributes_over_mul(a, b, p):
+    assert (a * b) ** p == a**p * b**p
+
+
+@given(rationals, rationals)
+def test_to_fraction_of_product_and_quotient(a, b):
+    sa = Scale.from_number(a)
+    sb = Scale.from_number(b)
+
+    assert (sa * sb).to_fraction() == a * b
+    assert (sa / sb).to_fraction() == a / b
+
+
+@given(rationals, int_exponents)
+def test_to_fraction_of_integer_power(q, n):
+    assert (Scale.from_number(q) ** n).to_fraction() == q**n
+
+
+@given(rationals)
+def test_square_root_is_rational_iff_perfect_square(q):
+    root = Scale.from_number(q) ** F(1, 2)
+    expected_rational = is_square(q.numerator) and is_square(q.denominator)
+
+    result = root.to_fraction()
+
+    assert (result is not None) == expected_rational
+    if result is not None:
+        assert result * result == q
+
+    # Squaring always recovers the original, exactly
+    assert root**2 == Scale.from_number(q)
+
+
+@given(rationals, nonzero_exponents)
+def test_any_pi_power_makes_value_irrational(q, e):
+    assert (Scale.from_number(q) * PI**e).to_fraction() is None
+
+
+@given(rationals, exponents)
+def test_pi_powers_cancel(q, e):
+    s = Scale.from_number(q) * PI**e / PI**e
+    assert s.to_fraction() == q
+
+
+@given(scales())
+def test_float_is_positive_finite_float(a):
+    f = float(a)
+
+    assert type(f) is float
+    assert 0 < f < math.inf
+
+
+@given(scales(), scales())
+def test_float_of_mul_and_div(a, b):
+    assert float(a * b) == approx(float(a) * float(b))
+    assert float(a / b) == approx(float(a) / float(b))
+
+
+@given(scales(), exponents)
+def test_float_of_pow(a, p):
+    assert float(a**p) == approx(float(a) ** float(p))
+
+
+@given(scales())
+def test_float_of_inverse(a):
+    assert float(a**-1) == approx(1 / float(a))
+
+
+@given(exponents)
+def test_float_of_pi_power(e):
+    assert float(PI**e) == approx(math.pi ** float(e))
+
+
+@given(scales(), scales())
+def test_equal_scales_hash_equal(a, b):
+    assert (a * b) == (b * a)
+    assert hash(a * b) == hash(b * a)
+
+
+@given(scales(), scales())
+def test_set_membership_matches_equality(a, b):
+    assert (len({a, b}) == 1) == (a == b)

units_lib-0.3.0/tests/hypothesis/utils/test_factors.py

@@ -0,0 +1,75 @@
+import math
+from collections import Counter
+
+import pytest
+from hypothesis import given
+from hypothesis import strategies as st
+
+from units_lib.utils.factors import factorise
+
+# fmt: off
+SMALL_PRIMES = [2, 3, 5, 7, 11, 13, 53, 97, 101, 103, 107, 109, 113, 997, 1009, 10007, 104729]
+# fmt: on
+
+positive_ints = st.integers(min_value=1, max_value=10**9)
+
+
+def is_prime(n: int) -> bool:
+    return n > 1 and all(n % d for d in range(2, math.isqrt(n) + 1))
+
+
+def as_counter(n: int) -> Counter:
+    return Counter(dict(factorise(n)))
+
+
+@given(positive_ints)
+def test_product_of_factors_reconstructs_value(n):
+    assert math.prod(p**e for p, e in factorise(n)) == n
+
+
+@given(positive_ints)
+def test_factors_are_prime_ascending_and_unique_with_positive_powers(n):
+    result = list(factorise(n))
+
+    primes = [p for p, _ in result]
+    exponents = [e for _, e in result]
+
+    assert all(is_prime(p) for p in primes)
+    assert all(e >= 1 for e in exponents)
+    assert primes == sorted(set(primes))
+
+
+@given(st.lists(st.sampled_from(SMALL_PRIMES), max_size=8))
+def test_recovers_constructed_factorisation(primes):
+    """Build a number from known primes, and check we get exactly those back."""
+    expected = Counter(primes)
+    n = math.prod(primes)
+
+    assert as_counter(n) == expected
+
+
+@given(st.sampled_from(SMALL_PRIMES), st.integers(min_value=1, max_value=3))
+def test_prime_powers(p, k):
+    assert list(factorise(p**k)) == [(p, k)]
+
+
+@given(st.integers(1, 10**4), st.integers(1, 10**4))
+def test_factorisation_is_multiplicative(a, b):
+    assert as_counter(a * b) == as_counter(a) + as_counter(b)
+
+
+@given(st.integers(1, 10**5), st.integers(1, 4))
+def test_powers_scale_exponents(n, k):
+    assert as_counter(n**k) == Counter({p: e * k for p, e in factorise(n)})
+
+
+@given(st.sampled_from([p for p in SMALL_PRIMES if p > 97]))
+def test_primes_beyond_precomputed_list_are_found(p):
+    assert list(factorise(p)) == [(p, 1)]
+    assert list(factorise(p * p)) == [(p, 2)]
+
+
+@given(st.integers(max_value=0))
+def test_non_positive_raises(n):
+    with pytest.raises(ValueError):
+        list(factorise(n))

units_lib-0.3.0/tests/unit/test_scale.py

@@ -0,0 +1,452 @@
+import dataclasses
+import math
+from fractions import Fraction as F
+
+import pytest
+
+from units_lib.scale import _CONSTANTS, Scale
+
+
+def factors(s: Scale) -> dict:
+    return dict(s.factors)
+
+
+class TestScale:
+    @pytest.fixture
+    def pi(self):
+        return Scale.constant("pi")
+
+    @pytest.fixture
+    def one(self):
+        return Scale.from_number(1)
+
+    def test_one_is_identity(self, one):
+        # ACT
+        scale = Scale()
+
+        # ASSERT
+        assert scale == one
+        assert scale.factors == frozenset()
+
+    @pytest.mark.parametrize(
+        "value, expected",
+        [
+            (2, {2: F(1)}),
+            (12, {2: F(2), 3: F(1)}),
+            (7, {7: F(1)}),
+            (F(1, 2), {2: F(-1)}),
+            (F(3, 4), {2: F(-2), 3: F(1)}),
+            (F(9, 4), {2: F(-2), 3: F(2)}),
+            (F(5, 7), {5: F(1), 7: F(-1)}),
+            (F(7, 101), {7: F(1), 101: F(-1)}),
+        ],
+    )
+    def test_factors(self, value, expected):
+        # ACT
+        scale = Scale.from_number(value)
+
+        # ASSERT
+        assert factors(scale) == expected
+
+    def test_equal_values_give_equal_scales(self):
+        # ARRANGE
+        first = F(6, 4)
+        second = F(3, 2)
+
+        # ACT
+        first_scale = Scale.from_number(first)
+        second_scale = Scale.from_number(second)
+
+        # ASSERT
+        assert first_scale == second_scale
+
+    @pytest.mark.parametrize("value", [0, -1, F(-1, 2)])
+    def test_from_number_non_positive_raises(self, value):
+        with pytest.raises(ValueError):
+            Scale.from_number(value)
+
+    def test_no_zero_exponents_stored(self):
+        # ACT
+        scale = Scale.from_number(F(6, 6))
+
+        # ASSERT
+        assert all(exp != 0 for _, exp in scale.factors)
+
+    @pytest.mark.parametrize(
+        "value",
+        [1, 2, 10, 97, 101, 360, 10201, F(22, 7), F(1, 1000)],
+    )
+    def test_roundtrip_through_to_fraction(self, value):
+        # ACT
+        scale = Scale.from_number(value)
+        result = scale.to_fraction()
+
+        # ASSERT
+        assert result == F(value)
+
+    def test_constant_pi_factors(self):
+        # ACT
+        pi = Scale.constant("pi")
+
+        # ASSERT
+        assert factors(pi) == {"pi": F(1)}
+
+    def test_constant_matches_manual_construction(self):
+        # ARRANGE
+        manual = Scale(frozenset({("pi", F(1))}))
+
+        # ACT
+        constant = Scale.constant("pi")
+
+        # ASSERT
+        assert constant == manual
+
+    @pytest.mark.parametrize("name", ["tau", "", "PI", "2"])
+    def test_constant_unknown_name_raises(self, name):
+        with pytest.raises(ValueError, match="not known"):
+            Scale.constant(name)
+
+    @pytest.mark.parametrize("name", _CONSTANTS.keys())
+    def test_every_known_constant_is_constructible_and_floatable(self, name):
+        # ARRANGE
+        value = _CONSTANTS[name]
+
+        # ACT
+        result = float(Scale.constant(name))
+
+        # ASSERT
+        assert result == pytest.approx(value)
+
+    def test_simple_multiplication(self):
+        # ARRANGE
+        two = Scale.from_number(2)
+        three = Scale.from_number(3)
+        six = Scale.from_number(6)
+
+        # ACT
+        result = two * three
+
+        # ASSERT
+        assert result == six
+
+    def test_multiplication_adds_exponents(self):
+        # ARRANGE
+        two = Scale.from_number(2)
+        four = Scale.from_number(4)
+
+        # ACT
+        result = two * four
+
+        # ASSERT
+        assert factors(result) == {2: F(3)}
+
+    def test_multiplicitive_identity(self, one):
+        # ARRANGE
+        a = Scale.from_number(F(3, 5))
+
+        # ACT
+        first = a * one
+        second = one * a
+
+        # ASSERT
+        assert first == a
+        assert second == a
+
+    def test_multiplication_is_commutative(self):
+        # ARRANGE
+        a = Scale.from_number(F(3, 5))
+        b = Scale.from_number(10)
+
+        # ACT
+        same = a * b == b * a
+
+        # ASSERT
+        assert same
+
+    def test_multiplication_isassociative(self):
+        # ARRANGE
+        a, b, c = (Scale.from_number(n) for n in (2, 3, 5))
+
+        # ACT
+        same = (a * b) * c == a * (b * c)
+
+        # ASSERT
+        assert same
+
+    def test_multiplicitive_inverse_cancels_to_identity(self, one):
+        # ARRANGE
+        a = Scale.from_number(F(7, 12))
+
+        # ACT
+        result = a * a**-1
+
+        # ASSERT
+        assert result == one
+
+    def test_cancelled_factors_are_removed(self):
+        assert Scale.from_number(6) * Scale.from_number(F(1, 3)) == Scale.from_number(2)
+
+    def test_multiplication_with_constant(self, pi):
+        # ARRANGE
+        two = Scale.from_number(2)
+
+        # ACT
+        result = pi * two
+
+        # ASSERT
+        assert factors(result) == {"pi": F(1), 2: F(1)}
+
+    def test_matches_rational_multiplication(self):
+        # ARRANGE
+        a = F(15, 4)
+        b = F(8, 25)
+
+        expected = a * b
+
+        # ACT
+        result = Scale.from_number(a) * Scale.from_number(b)
+
+        # ASSERT
+        assert result.to_fraction() == expected
+
+    def test_multiplication_int_operand(self):
+        assert Scale.from_number(3) * 4 == Scale.from_number(12)
+
+    def test_multiplication_fraction_operand(self):
+        assert Scale.from_number(3) * F(2, 9) == Scale.from_number(F(2, 3))
+
+    def test_multiplication_int_operand_matches_scale_operand(self):
+        # ARRANGE
+        a = Scale.from_number(F(5, 7))
+
+        # ACT & ASSERT
+        assert a * 6 == a * Scale.from_number(6)
+
+    def test_int_operand_with_constant(self, pi):
+        assert factors(pi * 2) == {"pi": F(1), 2: F(1)}
+
+    def test_chained_with_numbers(self, one):
+        assert (one * 2 * F(3, 4) * 8).to_fraction() == 12
+
+    @pytest.mark.parametrize("value", [0, -3, F(-1, 2)])
+    def test_multiplication_non_positive_number_raises(self, one, value):
+        with pytest.raises(ValueError):
+            _ = one * value
+
+    @pytest.mark.parametrize("value", [1.5, "2", None])
+    def test_multiplication_unsupported_operand_returns_not_implemented(
+        self, one, value
+    ):
+        assert Scale.__mul__(one, value) is NotImplemented
+
+        with pytest.raises(TypeError):
+            _ = one * value
+
+    def test_multiplication_reflected_int_operand(self):
+        assert 4 * Scale.from_number(3) == Scale.from_number(12)
+
+    def test_multiplication_reflected_fraction_operand(self):
+        assert F(1, 2) * Scale.from_number(6) == Scale.from_number(3)
+
+    def test_truediv(self):
+        # ARRANGE
+        a = Scale.from_number(6)
+        b = Scale.from_number(3)
+
+        # ACT & ASSERT
+        assert a / b == Scale.from_number(2)
+
+    def test_self_division_is_identity(self, one):
+        # ARRANGE
+        a = Scale.from_number(F(5, 9))
+
+        # ACT & ASSERT
+        assert a / a == one
+
+    def test_division_by_pi(self, pi):
+        assert factors(Scale.from_number(2) / pi) == {2: F(1), "pi": F(-1)}
+
+    def test_division_int_operand(self):
+        assert Scale.from_number(12) / 4 == Scale.from_number(3)
+
+    def test_division_fraction_operand(self):
+        assert Scale.from_number(3) / F(3, 4) == Scale.from_number(4)
+
+    def test_division_int_operand_matches_scale_operand(self):
+        # ARRANGE
+        a = Scale.from_number(F(5, 7))
+
+        # ACT & ASSERT
+        assert a / 6 == a / Scale.from_number(6)
+
+    def test_constant_divided_by_itself(self, pi, one):
+        assert pi / pi == one
+
+    @pytest.mark.parametrize("value", [0, -3, F(-1, 2)])
+    def test_division_non_positive_number_raises(self, one, value):
+        # ASSERT
+        with pytest.raises(ValueError):
+            _ = one / value
+
+    @pytest.mark.parametrize("value", [1.5, "2", None])
+    def test_division_unsupported_operand_returns_not_implemented(self, one, value):
+        assert Scale.__truediv__(one, value) is NotImplemented
+
+        with pytest.raises(TypeError):
+            _ = one / value
+
+    def test_division_reflected_int_operand(self):
+        assert 12 / Scale.from_number(4) == Scale.from_number(3)
+
+    def test_division_reflected_fraction_operand(self):
+        assert F(1, 2) / Scale.from_number(4) == Scale.from_number(F(1, 8))
+
+    def test_power_zero_gives_identity(self, one):
+        assert Scale.from_number(12) ** 0 == one
+
+    def test_power_one_is_noop(self):
+        # ARRANGE
+        a = Scale.from_number(12)
+
+        # ACT & ASSERT
+        assert a**1 == a
+
+    def test_integer_power(self):
+        assert Scale.from_number(2) ** 3 == Scale.from_number(8)
+
+    def test_negative_power(self):
+        assert Scale.from_number(2) ** -2 == Scale.from_number(F(1, 4))
+
+    def test_fractional_power_stays_exact(self):
+        # ACT
+        s = Scale.from_number(4) ** F(1, 2)
+
+        # ASSERT
+        assert s == Scale.from_number(2)
+
+    def test_irrational_result_has_no_fraction(self):
+        # ASSERT
+        assert (Scale.from_number(2) ** F(1, 2)).to_fraction() is None
+
+    def test_power_of_power(self):
+        # ARRANGE
+        a = Scale.from_number(F(3, 2))
+
+        # ACT & ASSERT
+        assert (a**2) ** 3 == a**6
+
+    def test_power_distributes_over_mul(self):
+        # ARRANGE
+        a = Scale.from_number(6)
+        b = Scale.from_number(F(5, 3))
+
+        # ACT & ASSERT
+        assert (a * b) ** 2 == a**2 * b**2
+
+    def test_pi_power(self, pi):
+        assert factors(pi**3) == {"pi": F(3)}
+
+    def test_from_number_to_fraction_round_trip_integer(self):
+        assert Scale.from_number(1).to_fraction() == 1
+
+    def test_from_number_to_fraction_round_trip_fraction(self):
+        assert Scale.from_number(F(3, 4)).to_fraction() == F(3, 4)
+
+    def test_pi_is_not_rational(self, pi):
+        assert pi.to_fraction() is None
+
+    def test_fractional_exponent_is_not_rational(self):
+        assert (Scale.from_number(3) ** F(1, 3)).to_fraction() is None
+
+    def test_constants_cancelling_become_rational(self, pi):
+        assert (pi * Scale.from_number(5) / pi).to_fraction() == 5
+
+    def test_fractional_exponents_combining_to_integer(self):
+        # ARRANGE
+        root2 = Scale.from_number(2) ** F(1, 2)
+
+        # ACT & ASSERT
+        assert (root2 * root2).to_fraction() == 2
+
+    @pytest.mark.parametrize("value", [2, F(1, 2), 1])
+    def test_returns_a_float(self, value):
+        # ACT
+        result = float(Scale.from_number(value))
+
+        # ASSERT
+        assert type(result) is float
+
+    @pytest.mark.parametrize(
+        "value", [1, 2, 12, F(1, 2), F(22, 7), F(1, 1000), 101 * 103]
+    )
+    def test_rational_values(self, value):
+        assert float(Scale.from_number(value)) == pytest.approx(float(value))
+
+    def test_float_pi(self, pi):
+        assert float(pi) == pytest.approx(math.pi)
+
+    @pytest.mark.parametrize("power", [-2, -1, 2, 3, F(1, 2), F(-1, 2)])
+    def test_pi_powers(self, pi, power):
+        assert float(pi**power) == pytest.approx(math.pi ** float(power))
+
+    @pytest.mark.parametrize("power", [-3, -1, 2, F(1, 3), F(-3, 2)])
+    def test_rational_powers(self, power):
+        # ACT
+        s = Scale.from_number(F(5, 3)) ** power
+
+        # ASSERT
+        assert float(s) == pytest.approx((5 / 3) ** float(power))
+
+    def test_large_value(self):
+        assert float(Scale.from_number(10**30)) == pytest.approx(1e30)
+
+    def test_tiny_value(self):
+        assert float(Scale.from_number(F(1, 10**30))) == pytest.approx(1e-30)
+
+    def test_sqrt(self):
+        assert float(Scale.from_number(2) ** F(1, 2)) == pytest.approx(math.sqrt(2))
+
+    def test_mixed(self, pi):
+        # ARRANGE
+        s = Scale.from_number(F(3, 2)) * pi**2
+
+        # ASSERT
+        assert float(s) == pytest.approx(1.5 * math.pi**2)
+
+    def test_float_of_product_matches_product_of_floats(self, pi):
+        # ARRANGE
+        a = Scale.from_number(F(7, 3))
+        b = pi
+
+        # ACT & ASSERT
+        assert float(a * b) == pytest.approx(float(a) * float(b))
+
+    def test_hashable_and_equal_hash(self):
+        # ARRANGE
+        a = Scale.from_number(F(3, 2))
+        b = Scale.from_number(F(6, 4))
+
+        # ASSERT
+        assert hash(a) == hash(b)
+        assert len({a, b}) == 1
+
+    def test_different_values_not_equal(self):
+        assert Scale.from_number(2) != Scale.from_number(3)
+
+    def test_frozen(self, one):
+        with pytest.raises(dataclasses.FrozenInstanceError):
+            one.factors = frozenset()  # type: ignore[misc]
+
+    def test_operations_do_not_mutate_operands(self):
+        # ARRANGE
+        a = Scale.from_number(6)
+        b = Scale.from_number(10)
+
+        before = (a.factors, b.factors)
+
+        # ACT
+        _ = a * b
+        _ = a**2
+
+        # ASSERT
+        assert (a.factors, b.factors) == before

units_lib-0.3.0/tests/unit/utils/test_factors.py

@@ -0,0 +1,88 @@
+import math
+from collections.abc import Generator
+
+import pytest
+
+from units_lib.utils.factors import factorise
+
+
+def is_prime(n: int) -> bool:
+    return n > 1 and all(n % d for d in range(2, math.isqrt(n) + 1))
+
+
+def as_dict(generator: Generator[tuple[int, int], None, None]) -> dict[int, int]:
+    return dict(generator)
+
+
+@pytest.mark.parametrize(
+    "value, expected",
+    [
+        (1, {}),
+        (2, {2: 1}),
+        (3, {3: 1}),
+        (4, {2: 2}),
+        (6, {2: 1, 3: 1}),
+        (7, {7: 1}),
+        (12, {2: 2, 3: 1}),
+        (97, {97: 1}),
+        (97 * 97, {97: 2}),
+        (101, {101: 1}),
+        (101 * 101, {101: 2}),
+        (101 * 103, {101: 1, 103: 1}),
+        (2**10, {2: 10}),
+        (2**3 * 3**2 * 5 * 101, {2: 3, 3: 2, 5: 1, 101: 1}),
+        (1_000_003, {1_000_003: 1}),
+        (999_983 * 2, {2: 1, 999_983: 1}),
+        (97 * 101, {97: 1, 101: 1}),
+    ],
+)
+def test_known_factorisations(value, expected):
+    # ACT
+    factorisation = factorise(value)
+
+    # ASSERT
+    assert as_dict(factorisation) == expected
+
+
+@pytest.mark.parametrize(
+    "value",
+    list(range(1, 200)) + [10201, 123456, 999_999, 1_030_301],
+)
+def test_product_reconstructs_value(value):
+    # ACT
+    result = factorise(value)
+
+    # ASSERT
+    reconstructed = math.prod(p**e for p, e in result)
+    assert reconstructed == value
+
+
+@pytest.mark.parametrize("value", list(range(1, 500)) + [10201, 1_030_301])
+def test_all_factors_prime_with_positive_powers(value):
+    # ACT
+    factorisation = factorise(value)
+
+    # ASSERT
+    for prime, power in factorisation:
+        assert is_prime(prime)
+        assert power >= 1
+
+
+@pytest.mark.parametrize("value", [2 * 3 * 5 * 7 * 101, 12, 360, 10201])
+def test_primes_unique_and_ascending(value):
+    # ACT
+    primes = [p for p, _ in factorise(value)]
+
+    # ASSERT
+    assert primes == sorted(set(primes))
+
+
+@pytest.mark.parametrize("value", [0, -1, -100])
+def test_non_positive_raises(value):
+    with pytest.raises(ValueError):
+        list(factorise(value))
+
+
+def test_error_message_is_formatted_properly():
+    with pytest.raises(ValueError, match="-5 is not valid"):
+        list(factorise(-5))

units_lib-0.3.0/units_lib/scale.py

@@ -0,0 +1,101 @@
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+from fractions import Fraction
+from typing import Self
+
+from units_lib.utils.factors import factorise
+
+Base = int | str  # primes or names of constants (e.g. 'pi')
+
+_CONSTANTS = {
+    "pi": math.pi,
+}
+
+
+@dataclass(frozen=True, slots=True)
+class Scale:
+    """A positive real number represented as a product of independant values raised to powers."""
+
+    factors: frozenset[tuple[Base, Fraction]] = frozenset()
+
+    @classmethod
+    def _build(cls, exps: dict[Base, Fraction]) -> Self:
+        return cls(frozenset((base, exp) for base, exp in exps.items() if exp != 0))
+
+    @classmethod
+    def from_number(cls, value: int | Fraction) -> Self:
+        """Produce a `Scale` from a number."""
+        value = Fraction(value)
+
+        if value <= 0:
+            raise ValueError("A `Scale` must be positive")
+
+        exps: dict[Base, Fraction] = {}
+
+        for prime, power in factorise(value.numerator):
+            exps[prime] = Fraction(power)
+
+        for prime, power in factorise(value.denominator):
+            exps[prime] = exps.get(prime, Fraction(0)) - power
+
+        return cls._build(exps)
+
+    @classmethod
+    def constant(cls, value: str) -> Self:
+        """Produce a `Scale` from a constant value."""
+        if value not in _CONSTANTS:
+            raise ValueError(f"Constant value {value!r} is not known")
+
+        return cls._build({value: Fraction(1)})
+
+    def __mul__(self, other: Scale | int | Fraction) -> Scale:
+        if isinstance(other, (int, Fraction)) and not isinstance(other, bool):
+            other = self.from_number(other)
+
+        if not isinstance(other, Scale):
+            return NotImplemented
+
+        exps = dict(self.factors)
+        for base, exp in other.factors:
+            exps[base] = exps.get(base, Fraction(0)) + exp
+        return self._build(exps)
+
+    __rmul__ = __mul__
+
+    def __truediv__(self, other: Scale | int | Fraction) -> Scale:
+        if isinstance(other, (int, Fraction)) and not isinstance(other, bool):
+            other = self.from_number(other)
+
+        if not isinstance(other, Scale):
+            return NotImplemented
+
+        return self * other**-1
+
+    def __rtruediv__(self, other: int | Fraction) -> Scale:
+        return other * self**-1
+
+    def __pow__(self, p: int | Fraction) -> Scale:
+        exps = {base: exp * p for base, exp in self.factors}
+        return self._build(exps)
+
+    def to_fraction(self) -> Fraction | None:
+        """The exact rational value, or None if it isn't rational."""
+        result = Fraction(1)
+
+        for base, exp in self.factors:
+            if not isinstance(base, int) or exp.denominator != 1:
+                return None
+            result *= Fraction(base) ** int(exp)
+        return result
+
+    def __float__(self) -> float:
+        result = 1.0
+
+        for base, exp in self.factors:
+            if isinstance(base, str):
+                base = _CONSTANTS[base]
+            result *= float(base**exp)
+
+        return result

units_lib-0.3.0/units_lib/utils/factors.py

@@ -0,0 +1,62 @@
+from collections.abc import Generator
+
+# fmt: off
+_PRIMES = [
+    2, 3, 5, 7,
+    11, 13, 17, 19,
+    23, 29, 31, 37,
+    41, 43, 47,
+    53, 59,
+    61, 67,
+    71, 73, 79,
+    83, 89,
+    97,
+]
+# fmt: on
+
+
+def factorise(value: int) -> Generator[tuple[int, int], None, None]:
+    """Calculate the prime factorisation on `value`.
+
+    Yields pairs of (prime, power) that make up the prime factorisation.
+
+    Args:
+        value: The number to calculate the prime factorisation of
+
+    Returns:
+        A generator of tuples containing (prime, power) pairs
+    """
+    if value < 1:
+        raise ValueError(f"Number must be positive - {value!r} is not valid")
+
+    for prime in _PRIMES:
+        if prime * prime > value:
+            break
+
+        exp = 0
+        while value % prime == 0:
+            value //= prime
+            exp += 1
+
+        if exp != 0:
+            yield prime, exp
+
+    # Handle any remaining factors beyond the precomputed prime list
+    div = 101
+    step = 2
+
+    while div * div <= value:
+        exp = 0
+        while value % div == 0:
+            exp += 1
+            value //= div
+
+        if exp != 0:
+            yield div, exp
+
+        div += step
+        # Alternate between steps of 2 and 4
+        step = 6 - step
+
+    if value != 1:
+        yield value, 1

{units_lib-0.2.0 → units_lib-0.3.0}/units_lib.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: units-lib
-Version: 0.2.0
+Version: 0.3.0
 Summary: Library for managing calculations of quantities with units.
 Author-email: blm34 <pypi.escalate394@passmail.net>
 License-Expression: GPL-3.0-or-later

{units_lib-0.2.0 → units_lib-0.3.0}/units_lib.egg-info/SOURCES.txt

@@ -9,16 +9,22 @@ uv.lock
 tests/__init__.py
 tests/hypothesis/__init__.py
 tests/hypothesis/test_dimension.py
+tests/hypothesis/test_scale.py
+tests/hypothesis/utils/test_factors.py
 tests/unit/__init__.py
 tests/unit/conftest.py
 tests/unit/test_dimension.py
 tests/unit/test_kind.py
+tests/unit/test_scale.py
+tests/unit/utils/test_factors.py
 units_lib/__init__.py
 units_lib/dimensions.py
 units_lib/kind.py
+units_lib/scale.py
 units_lib.egg-info/PKG-INFO
 units_lib.egg-info/SOURCES.txt
 units_lib.egg-info/dependency_links.txt
 units_lib.egg-info/scm_file_list.json
 units_lib.egg-info/scm_version.json
-units_lib.egg-info/top_level.txt
+units_lib.egg-info/top_level.txt
+units_lib/utils/factors.py

{units_lib-0.2.0 → units_lib-0.3.0}/units_lib.egg-info/scm_file_list.json

@@ -10,13 +10,19 @@
     "tests/__init__.py",
     "tests/hypothesis/__init__.py",
     "tests/hypothesis/test_dimension.py",
+    "tests/hypothesis/test_scale.py",
+    "tests/hypothesis/utils/test_factors.py",
     "tests/unit/__init__.py",
     "tests/unit/conftest.py",
     "tests/unit/test_dimension.py",
     "tests/unit/test_kind.py",
+    "tests/unit/test_scale.py",
+    "tests/unit/utils/test_factors.py",
     "units_lib/__init__.py",
     "units_lib/dimensions.py",
     "units_lib/kind.py",
+    "units_lib/scale.py",
+    "units_lib/utils/factors.py",
     "uv.lock"
   ]
 }

units_lib-0.3.0/units_lib.egg-info/scm_version.json

@@ -0,0 +1,8 @@
+{
+  "tag": "0.3.0",
+  "distance": 0,
+  "node": "g33eda42578972c80b88fff334a28234ffffa89ef",
+  "dirty": false,
+  "branch": "HEAD",
+  "node_date": "2026-10-31"
+}

units_lib-0.2.0/units_lib.egg-info/scm_version.json

@@ -1,8 +0,0 @@
-{
-  "tag": "0.2.0",
-  "distance": 0,
-  "node": "g36791160c361d61bc58edf2c9ea01a1e1db39e68",
-  "dirty": false,
-  "branch": "HEAD",
-  "node_date": "2026-10-25"
-}