frequenz-quantities 1.0.0__py3-none-any.whl

frequenz/quantities/__init__.py

@@ -0,0 +1,112 @@
+# License: MIT
+# Copyright © 2024 Frequenz Energy-as-a-Service GmbH
+
+"""Types for holding quantities with units.
+
+This library provide types for holding quantities with units. The main goal is to avoid
+mistakes while working with different types of quantities, for example avoiding adding
+a length to a time.
+
+It also prevents mistakes when operating between the same quantity but in different
+units, like adding a power in Joules to a power in Watts without converting one of them.
+
+Quantities store the value in a base unit, and then provide methods to get that quantity
+as a particular unit. They can only be constructed using special constructors with the
+form `Quantity.from_<unit>`, for example
+[`Power.from_watts(10.0)`][frequenz.quantities.Power.from_watts].
+
+Internally quantities store values as `float`s, so regular [float issues and limitations
+apply](https://docs.python.org/3/tutorial/floatingpoint.html), although some of them are
+tried to be mitigated.
+
+Quantities are also immutable, so operations between quantities return a new instance of
+the quantity.
+
+This library provides the following types:
+
+- [ApparentPower][frequenz.quantities.ApparentPower]: A quantity representing apparent
+  power.
+- [Current][frequenz.quantities.Current]: A quantity representing an electric current.
+- [Energy][frequenz.quantities.Energy]: A quantity representing energy.
+- [Frequency][frequenz.quantities.Frequency]: A quantity representing frequency.
+- [Percentage][frequenz.quantities.Percentage]: A quantity representing a percentage.
+- [Power][frequenz.quantities.Power]: A quantity representing power.
+- [ReactivePower][frequenz.quantities.ReactivePower]: A quantity representing reactive
+  power.
+- [Temperature][frequenz.quantities.Temperature]: A quantity representing temperature.
+- [Voltage][frequenz.quantities.Voltage]: A quantity representing electric voltage.
+
+There is also the unitless [Quantity][frequenz.quantities.Quantity] class. All
+quantities are subclasses of this class and it can be used as a base to create new
+quantities. Using the `Quantity` class directly is discouraged, as it doesn't provide
+any unit conversion methods.
+
+Example:
+    ```python
+    from datetime import timedelta
+    from frequenz.quantities import Power, Voltage, Current, Energy
+
+    # Create a power quantity
+    power = Power.from_watts(230.0)
+
+    # Printing uses a unit to make the string as short as possible
+    print(f"Power: {power}")  # Power: 230.0 W
+    # The precision can be changed
+    print(f"Power: {power:0.3}")  # Power: 230.000 W
+    # The conversion methods can be used to get the value in a particular unit
+    print(f"Power in MW: {power.as_megawatt()}")  # Power in MW: 0.00023 MW
+
+    # Create a voltage quantity
+    voltage = Voltage.from_volts(230.0)
+
+    # Calculate the current
+    current = power / voltage
+    assert isinstance(current, Current)
+    print(f"Current: {current}")  # Current: 1.0 A
+    assert current.isclose(Current.from_amperes(1.0))
+
+    # Calculate the energy
+    energy = power * timedelta(hours=1)
+    assert isinstance(energy, Energy)
+    print(f"Energy: {energy}")  # Energy: 230.0 Wh
+    print(f"Energy in kWh: {energy.as_kilowatt_hours()}") # Energy in kWh: 0.23
+
+    # Invalid operations are not permitted
+    # (when using a type hinting linter like mypy, this will be caught at linting time)
+    try:
+        power + voltage
+    except TypeError as e:
+        print(f"Error: {e}")  # Error: unsupported operand type(s) for +: 'Power' and 'Voltage'
+    ```
+
+This library also provides an [**experimental** module with marshmallow fields and
+a base schema][frequenz.quantities.experimental.marshmallow] to serialize and
+deserialize quantities using the marshmallow library. To use it, you need to make sure
+to install this package with the `marshmallow` optional dependencies (e.g.
+`pip install frequenz-quantities[marshmallow]`).
+"""
+
+
+from ._apparent_power import ApparentPower
+from ._current import Current
+from ._energy import Energy
+from ._frequency import Frequency
+from ._percentage import Percentage
+from ._power import Power
+from ._quantity import Quantity
+from ._reactive_power import ReactivePower
+from ._temperature import Temperature
+from ._voltage import Voltage
+
+__all__ = [
+    "ApparentPower",
+    "Current",
+    "Energy",
+    "Frequency",
+    "Percentage",
+    "Power",
+    "Quantity",
+    "ReactivePower",
+    "Temperature",
+    "Voltage",
+]

frequenz/quantities/_apparent_power.py

@@ -0,0 +1,234 @@
+# License: MIT
+# Copyright © 2024 Frequenz Energy-as-a-Service GmbH
+
+"""Types for holding apparent power quantities with units."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Self, overload
+
+from ._quantity import NoDefaultConstructible, Quantity
+
+if TYPE_CHECKING:
+    from ._current import Current
+    from ._percentage import Percentage
+    from ._voltage import Voltage
+
+
+class ApparentPower(
+    Quantity,
+    metaclass=NoDefaultConstructible,
+    exponent_unit_map={
+        -3: "mVA",
+        0: "VA",
+        3: "kVA",
+        6: "MVA",
+    },
+):
+    """A apparent power quantity.
+
+    Objects of this type are wrappers around `float` values and are immutable.
+
+    The constructors accept a single `float` value, the `as_*()` methods return a
+    `float` value, and each of the arithmetic operators supported by this type are
+    actually implemented using floating-point arithmetic.
+
+    So all considerations about floating-point arithmetic apply to this type as well.
+    """
+
+    @classmethod
+    def from_volt_amperes(cls, value: float) -> Self:
+        """Initialize a new apparent power quantity.
+
+        Args:
+            value: The apparent power in volt-amperes (VA).
+
+        Returns:
+            A new apparent power quantity.
+        """
+        return cls._new(value)
+
+    @classmethod
+    def from_milli_volt_amperes(cls, mva: float) -> Self:
+        """Initialize a new apparent power quantity.
+
+        Args:
+            mva: The apparent power in millivolt-amperes (mVA).
+
+        Returns:
+            A new apparent power quantity.
+        """
+        return cls._new(mva, exponent=-3)
+
+    @classmethod
+    def from_kilo_volt_amperes(cls, kva: float) -> Self:
+        """Initialize a new apparent power quantity.
+
+        Args:
+            kva: The apparent power in kilovolt-amperes (kVA).
+
+        Returns:
+            A new apparent power quantity.
+        """
+        return cls._new(kva, exponent=3)
+
+    @classmethod
+    def from_mega_volt_amperes(cls, mva: float) -> Self:
+        """Initialize a new apparent power quantity.
+
+        Args:
+            mva: The apparent power in megavolt-amperes (MVA).
+
+        Returns:
+            A new apparent power quantity.
+        """
+        return cls._new(mva, exponent=6)
+
+    def as_volt_amperes(self) -> float:
+        """Return the apparent power in volt-amperes (VA).
+
+        Returns:
+            The apparent power in volt-amperes (VA).
+        """
+        return self._base_value
+
+    def as_milli_volt_amperes(self) -> float:
+        """Return the apparent power in millivolt-amperes (mVA).
+
+        Returns:
+            The apparent power in millivolt-amperes (mVA).
+        """
+        return self._base_value * 1e3
+
+    def as_kilo_volt_amperes(self) -> float:
+        """Return the apparent power in kilovolt-amperes (kVA).
+
+        Returns:
+            The apparent power in kilovolt-amperes (kVA).
+        """
+        return self._base_value / 1e3
+
+    def as_mega_volt_amperes(self) -> float:
+        """Return the apparent power in megavolt-amperes (MVA).
+
+        Returns:
+            The apparent power in megavolt-amperes (MVA).
+        """
+        return self._base_value / 1e6
+
+    @overload
+    def __mul__(self, scalar: float, /) -> Self:
+        """Scale this power by a scalar.
+
+        Args:
+            scalar: The scalar by which to scale this power.
+
+        Returns:
+            The scaled power.
+        """
+
+    @overload
+    def __mul__(self, percent: Percentage, /) -> Self:
+        """Scale this power by a percentage.
+
+        Args:
+            percent: The percentage by which to scale this power.
+
+        Returns:
+            The scaled power.
+        """
+
+    def __mul__(self, other: float | Percentage, /) -> Self:
+        """Return a power or energy from multiplying this power by the given value.
+
+        Args:
+            other: The scalar, percentage or duration to multiply by.
+
+        Returns:
+            A power or energy.
+        """
+        from ._percentage import Percentage  # pylint: disable=import-outside-toplevel
+
+        match other:
+            case float() | Percentage():
+                return super().__mul__(other)
+            case _:
+                return NotImplemented
+
+    # We need the ignore here because otherwise mypy will give this error:
+    # > Overloaded operator methods can't have wider argument types in overrides
+    # The problem seems to be when the other type implements an **incompatible**
+    # __rmul__ method, which is not the case here, so we should be safe.
+    # Please see this example:
+    # https://github.com/python/mypy/blob/c26f1297d4f19d2d1124a30efc97caebb8c28616/test-data/unit/check-overloading.test#L4738C1-L4769C55
+    # And a discussion in a mypy issue here:
+    # https://github.com/python/mypy/issues/4985#issuecomment-389692396
+    @overload  # type: ignore[override]
+    def __truediv__(self, other: float, /) -> Self:
+        """Divide this power by a scalar.
+
+        Args:
+            other: The scalar to divide this power by.
+
+        Returns:
+            The divided power.
+        """
+
+    @overload
+    def __truediv__(self, other: Self, /) -> float:
+        """Return the ratio of this power to another.
+
+        Args:
+            other: The other power.
+
+        Returns:
+            The ratio of this power to another.
+        """
+
+    @overload
+    def __truediv__(self, current: Current, /) -> Voltage:
+        """Return a voltage from dividing this power by the given current.
+
+        Args:
+            current: The current to divide by.
+
+        Returns:
+            A voltage from dividing this power by the a current.
+        """
+
+    @overload
+    def __truediv__(self, voltage: Voltage, /) -> Current:
+        """Return a current from dividing this power by the given voltage.
+
+        Args:
+            voltage: The voltage to divide by.
+
+        Returns:
+            A current from dividing this power by a voltage.
+        """
+
+    def __truediv__(
+        self, other: float | Self | Current | Voltage, /
+    ) -> Self | float | Voltage | Current:
+        """Return a current or voltage from dividing this power by the given value.
+
+        Args:
+            other: The scalar, power, current or voltage to divide by.
+
+        Returns:
+            A current or voltage from dividing this power by the given value.
+        """
+        from ._current import Current  # pylint: disable=import-outside-toplevel
+        from ._voltage import Voltage  # pylint: disable=import-outside-toplevel
+
+        match other:
+            case float():
+                return super().__truediv__(other)
+            case ApparentPower():
+                return self._base_value / other._base_value
+            case Current():
+                return Voltage._new(self._base_value / other._base_value)
+            case Voltage():
+                return Current._new(self._base_value / other._base_value)
+            case _:
+                return NotImplemented

frequenz/quantities/_current.py

@@ -0,0 +1,131 @@
+# License: MIT
+# Copyright © 2022 Frequenz Energy-as-a-Service GmbH
+
+"""Types for holding quantities with units."""
+
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Self, overload
+
+from ._quantity import NoDefaultConstructible, Quantity
+
+if TYPE_CHECKING:
+    from ._percentage import Percentage
+    from ._power import Power
+    from ._voltage import Voltage
+
+
+class Current(
+    Quantity,
+    metaclass=NoDefaultConstructible,
+    exponent_unit_map={
+        -3: "mA",
+        0: "A",
+    },
+):
+    """A current quantity.
+
+    Objects of this type are wrappers around `float` values and are immutable.
+
+    The constructors accept a single `float` value, the `as_*()` methods return a
+    `float` value, and each of the arithmetic operators supported by this type are
+    actually implemented using floating-point arithmetic.
+
+    So all considerations about floating-point arithmetic apply to this type as well.
+    """
+
+    @classmethod
+    def from_amperes(cls, amperes: float) -> Self:
+        """Initialize a new current quantity.
+
+        Args:
+            amperes: The current in amperes.
+
+        Returns:
+            A new current quantity.
+        """
+        return cls._new(amperes)
+
+    @classmethod
+    def from_milliamperes(cls, milliamperes: float) -> Self:
+        """Initialize a new current quantity.
+
+        Args:
+            milliamperes: The current in milliamperes.
+
+        Returns:
+            A new current quantity.
+        """
+        return cls._new(milliamperes, exponent=-3)
+
+    def as_amperes(self) -> float:
+        """Return the current in amperes.
+
+        Returns:
+            The current in amperes.
+        """
+        return self._base_value
+
+    def as_milliamperes(self) -> float:
+        """Return the current in milliamperes.
+
+        Returns:
+            The current in milliamperes.
+        """
+        return self._base_value * 1e3
+
+    # See comment for Power.__mul__ for why we need the ignore here.
+    @overload  # type: ignore[override]
+    def __mul__(self, scalar: float, /) -> Self:
+        """Scale this current by a scalar.
+
+        Args:
+            scalar: The scalar by which to scale this current.
+
+        Returns:
+            The scaled current.
+        """
+
+    @overload
+    def __mul__(self, percent: Percentage, /) -> Self:
+        """Scale this current by a percentage.
+
+        Args:
+            percent: The percentage by which to scale this current.
+
+        Returns:
+            The scaled current.
+        """
+
+    @overload
+    def __mul__(self, other: Voltage, /) -> Power:
+        """Multiply the current by a voltage to get a power.
+
+        Args:
+            other: The voltage.
+
+        Returns:
+            The calculated power.
+        """
+
+    def __mul__(self, other: float | Percentage | Voltage, /) -> Self | Power:
+        """Return a current or power from multiplying this current by the given value.
+
+        Args:
+            other: The scalar, percentage or voltage to multiply by.
+
+        Returns:
+            A current or power.
+        """
+        from ._percentage import Percentage  # pylint: disable=import-outside-toplevel
+        from ._power import Power  # pylint: disable=import-outside-toplevel
+        from ._voltage import Voltage  # pylint: disable=import-outside-toplevel
+
+        match other:
+            case float() | Percentage():
+                return super().__mul__(other)
+            case Voltage():
+                return Power._new(self._base_value * other._base_value)
+            case _:
+                return NotImplemented

frequenz/quantities/_energy.py

@@ -0,0 +1,188 @@
+# License: MIT
+# Copyright © 2022 Frequenz Energy-as-a-Service GmbH
+
+"""Types for holding quantities with units."""
+
+
+from __future__ import annotations
+
+from datetime import timedelta
+from typing import TYPE_CHECKING, Self, overload
+
+from ._quantity import NoDefaultConstructible, Quantity
+
+if TYPE_CHECKING:
+    from ._percentage import Percentage
+    from ._power import Power
+
+
+class Energy(
+    Quantity,
+    metaclass=NoDefaultConstructible,
+    exponent_unit_map={
+        0: "Wh",
+        3: "kWh",
+        6: "MWh",
+    },
+):
+    """An energy quantity.
+
+    Objects of this type are wrappers around `float` values and are immutable.
+
+    The constructors accept a single `float` value, the `as_*()` methods return a
+    `float` value, and each of the arithmetic operators supported by this type are
+    actually implemented using floating-point arithmetic.
+
+    So all considerations about floating-point arithmetic apply to this type as well.
+    """
+
+    @classmethod
+    def from_watt_hours(cls, watt_hours: float) -> Self:
+        """Initialize a new energy quantity.
+
+        Args:
+            watt_hours: The energy in watt hours.
+
+        Returns:
+            A new energy quantity.
+        """
+        return cls._new(watt_hours)
+
+    @classmethod
+    def from_kilowatt_hours(cls, kilowatt_hours: float) -> Self:
+        """Initialize a new energy quantity.
+
+        Args:
+            kilowatt_hours: The energy in kilowatt hours.
+
+        Returns:
+            A new energy quantity.
+        """
+        return cls._new(kilowatt_hours, exponent=3)
+
+    @classmethod
+    def from_megawatt_hours(cls, megawatt_hours: float) -> Self:
+        """Initialize a new energy quantity.
+
+        Args:
+            megawatt_hours: The energy in megawatt hours.
+
+        Returns:
+            A new energy quantity.
+        """
+        return cls._new(megawatt_hours, exponent=6)
+
+    def as_watt_hours(self) -> float:
+        """Return the energy in watt hours.
+
+        Returns:
+            The energy in watt hours.
+        """
+        return self._base_value
+
+    def as_kilowatt_hours(self) -> float:
+        """Return the energy in kilowatt hours.
+
+        Returns:
+            The energy in kilowatt hours.
+        """
+        return self._base_value / 1e3
+
+    def as_megawatt_hours(self) -> float:
+        """Return the energy in megawatt hours.
+
+        Returns:
+            The energy in megawatt hours.
+        """
+        return self._base_value / 1e6
+
+    def __mul__(self, other: float | Percentage) -> Self:
+        """Scale this energy by a percentage.
+
+        Args:
+            other: The percentage by which to scale this energy.
+
+        Returns:
+            The scaled energy.
+        """
+        from ._percentage import Percentage  # pylint: disable=import-outside-toplevel
+
+        match other:
+            case float():
+                return self._new(self._base_value * other)
+            case Percentage():
+                return self._new(self._base_value * other.as_fraction())
+            case _:
+                return NotImplemented
+
+    # See the comment for Power.__mul__ for why we need the ignore here.
+    @overload  # type: ignore[override]
+    def __truediv__(self, other: float, /) -> Self:
+        """Divide this energy by a scalar.
+
+        Args:
+            other: The scalar to divide this energy by.
+
+        Returns:
+            The divided energy.
+        """
+
+    @overload
+    def __truediv__(self, other: Self, /) -> float:
+        """Return the ratio of this energy to another.
+
+        Args:
+            other: The other energy.
+
+        Returns:
+            The ratio of this energy to another.
+        """
+
+    @overload
+    def __truediv__(self, duration: timedelta, /) -> Power:
+        """Return a power from dividing this energy by the given duration.
+
+        Args:
+            duration: The duration to divide by.
+
+        Returns:
+            A power from dividing this energy by the given duration.
+        """
+
+    @overload
+    def __truediv__(self, power: Power, /) -> timedelta:
+        """Return a duration from dividing this energy by the given power.
+
+        Args:
+            power: The power to divide by.
+
+        Returns:
+            A duration from dividing this energy by the given power.
+        """
+
+    def __truediv__(
+        self, other: float | Self | timedelta | Power, /
+    ) -> Self | float | Power | timedelta:
+        """Return a power or duration from dividing this energy by the given value.
+
+        Args:
+            other: The scalar, energy, power or duration to divide by.
+
+        Returns:
+            A power or duration from dividing this energy by the given value.
+        """
+        from ._power import Power  # pylint: disable=import-outside-toplevel
+
+        match other:
+            case float():
+                return super().__truediv__(other)
+            case Energy():
+                return self._base_value / other._base_value
+            case timedelta():
+                return Power._new(self._base_value / (other.total_seconds() / 3600.0))
+            case Power():
+                return timedelta(
+                    seconds=(self._base_value / other._base_value) * 3600.0
+                )
+            case _:
+                return NotImplemented