frequenz-quantities 1.0.0__py3-none-any.whl

frequenz/quantities/_reactive_power.py

@@ -0,0 +1,235 @@
+# License: MIT
+# Copyright © 2024 Frequenz Energy-as-a-Service GmbH
+
+"""Types for holding reactive 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 ReactivePower(
+    Quantity,
+    metaclass=NoDefaultConstructible,
+    exponent_unit_map={
+        -3: "mVAR",
+        0: "VAR",
+        3: "kVAR",
+        6: "MVAR",
+    },
+):
+    """A reactive 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_reactive(cls, value: float) -> Self:
+        """Initialize a new reactive power quantity.
+
+        Args:
+            value: The reactive power in volt-amperes reactive (VAR).
+
+        Returns:
+            A new reactive power quantity.
+        """
+        return cls._new(value)
+
+    @classmethod
+    def from_milli_volt_amperes_reactive(cls, mvars: float) -> Self:
+        """Initialize a new reactive power quantity.
+
+        Args:
+            mvars: The reactive power in millivolt-amperes reactive (mVAR).
+
+        Returns:
+            A new reactive power quantity.
+        """
+        return cls._new(mvars, exponent=-3)
+
+    @classmethod
+    def from_kilo_volt_amperes_reactive(cls, kvars: float) -> Self:
+        """Initialize a new reactive power quantity.
+
+        Args:
+            kvars: The reactive power in kilovolt-amperes reactive (kVAR).
+
+        Returns:
+            A new reactive power quantity.
+        """
+        return cls._new(kvars, exponent=3)
+
+    @classmethod
+    def from_mega_volt_amperes_reactive(cls, mvars: float) -> Self:
+        """Initialize a new reactive power quantity.
+
+        Args:
+            mvars: The reactive power in megavolt-amperes reactive (MVAR).
+
+        Returns:
+            A new reactive power quantity.
+        """
+        return cls._new(mvars, exponent=6)
+
+    def as_volt_amperes_reactive(self) -> float:
+        """Return the reactive power in volt-amperes reactive (VAR).
+
+        Returns:
+            The reactive power in volt-amperes reactive (VAR).
+        """
+        return self._base_value
+
+    def as_milli_volt_amperes_reactive(self) -> float:
+        """Return the reactive power in millivolt-amperes reactive (mVAR).
+
+        Returns:
+            The reactive power in millivolt-amperes reactive (mVAR).
+        """
+        return self._base_value * 1e3
+
+    def as_kilo_volt_amperes_reactive(self) -> float:
+        """Return the reactive power in kilovolt-amperes reactive (kVAR).
+
+        Returns:
+            The reactive power in kilovolt-amperes reactive (kVAR).
+        """
+        return self._base_value / 1e3
+
+    def as_mega_volt_amperes_reactive(self) -> float:
+        """Return the reactive power in megavolt-amperes reactive (MVAR).
+
+        Returns:
+            The reactive power in megavolt-amperes reactive (MVAR).
+        """
+        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 ReactivePower():
+                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/_temperature.py

@@ -0,0 +1,39 @@
+# License: MIT
+# Copyright © 2022 Frequenz Energy-as-a-Service GmbH
+
+"""Types for holding quantities with units."""
+
+
+from typing import Self
+
+from ._quantity import NoDefaultConstructible, Quantity
+
+
+class Temperature(
+    Quantity,
+    metaclass=NoDefaultConstructible,
+    exponent_unit_map={
+        0: "°C",
+    },
+):
+    """A temperature quantity (in degrees Celsius)."""
+
+    @classmethod
+    def from_celsius(cls, value: float) -> Self:
+        """Initialize a new temperature quantity.
+
+        Args:
+            value: The temperature in degrees Celsius.
+
+        Returns:
+            A new temperature quantity.
+        """
+        return cls._new(value)
+
+    def as_celsius(self) -> float:
+        """Return the temperature in degrees Celsius.
+
+        Returns:
+            The temperature in degrees Celsius.
+        """
+        return self._base_value

frequenz/quantities/_voltage.py

@@ -0,0 +1,148 @@
+# 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 ._current import Current
+    from ._percentage import Percentage
+    from ._power import Power
+
+
+class Voltage(
+    Quantity,
+    metaclass=NoDefaultConstructible,
+    exponent_unit_map={0: "V", -3: "mV", 3: "kV"},
+):
+    """A voltage 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_volts(cls, volts: float) -> Self:
+        """Initialize a new voltage quantity.
+
+        Args:
+            volts: The voltage in volts.
+
+        Returns:
+            A new voltage quantity.
+        """
+        return cls._new(volts)
+
+    @classmethod
+    def from_millivolts(cls, millivolts: float) -> Self:
+        """Initialize a new voltage quantity.
+
+        Args:
+            millivolts: The voltage in millivolts.
+
+        Returns:
+            A new voltage quantity.
+        """
+        return cls._new(millivolts, exponent=-3)
+
+    @classmethod
+    def from_kilovolts(cls, kilovolts: float) -> Self:
+        """Initialize a new voltage quantity.
+
+        Args:
+            kilovolts: The voltage in kilovolts.
+
+        Returns:
+            A new voltage quantity.
+        """
+        return cls._new(kilovolts, exponent=3)
+
+    def as_volts(self) -> float:
+        """Return the voltage in volts.
+
+        Returns:
+            The voltage in volts.
+        """
+        return self._base_value
+
+    def as_millivolts(self) -> float:
+        """Return the voltage in millivolts.
+
+        Returns:
+            The voltage in millivolts.
+        """
+        return self._base_value * 1e3
+
+    def as_kilovolts(self) -> float:
+        """Return the voltage in kilovolts.
+
+        Returns:
+            The voltage in kilovolts.
+        """
+        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 voltage by a scalar.
+
+        Args:
+            scalar: The scalar by which to scale this voltage.
+
+        Returns:
+            The scaled voltage.
+        """
+
+    @overload
+    def __mul__(self, percent: Percentage, /) -> Self:
+        """Scale this voltage by a percentage.
+
+        Args:
+            percent: The percentage by which to scale this voltage.
+
+        Returns:
+            The scaled voltage.
+        """
+
+    @overload
+    def __mul__(self, other: Current, /) -> Power:
+        """Multiply the voltage by the current to get the power.
+
+        Args:
+            other: The current to multiply the voltage with.
+
+        Returns:
+            The calculated power.
+        """
+
+    def __mul__(self, other: float | Percentage | Current, /) -> Self | Power:
+        """Return a voltage or power from multiplying this voltage by the given value.
+
+        Args:
+            other: The scalar, percentage or current to multiply by.
+
+        Returns:
+            The calculated voltage or power.
+        """
+        from ._current import Current  # pylint: disable=import-outside-toplevel
+        from ._percentage import Percentage  # pylint: disable=import-outside-toplevel
+        from ._power import Power  # pylint: disable=import-outside-toplevel
+
+        match other:
+            case float() | Percentage():
+                return super().__mul__(other)
+            case Current():
+                return Power._new(self._base_value * other._base_value)
+            case _:
+                return NotImplemented

frequenz/quantities/conftest.py

@@ -0,0 +1,13 @@
+# License: MIT
+# Copyright © 2024 Frequenz Energy-as-a-Service GmbH
+
+"""Validate docstring code examples.
+
+Code examples are often wrapped in triple backticks (```) within docstrings.
+This plugin extracts these code examples and validates them using pylint.
+"""
+
+from frequenz.repo.config.pytest import examples
+from sybil import Sybil
+
+pytest_collect_file = Sybil(**examples.get_sybil_arguments()).pytest()

frequenz/quantities/experimental/__init__.py

@@ -0,0 +1,11 @@
+# License: All rights reserved
+# Copyright © 2024 Frequenz Energy-as-a-Service GmbH
+
+"""Experimental features for quantities.
+
+Danger:
+    This package contains experimental features for which the API is not yet stable.
+
+    Any module or class in this package may be removed or changed in a future release,
+    even in minor or patch releases.
+"""