frequenz-quantities 1.0.0__py3-none-any.whl

frequenz/quantities/experimental/marshmallow.py

@@ -0,0 +1,271 @@
+# License: All rights reserved
+# Copyright © 2024 Frequenz Energy-as-a-Service GmbH
+
+"""Custom marshmallow fields and schema.
+
+This module provides custom marshmallow fields for quantities and
+a [QuantitySchema][frequenz.quantities.experimental.marshmallow.QuantitySchema] class to
+be used as base schema for dataclasses containing quantities.
+
+Danger:
+    This module 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.
+"""
+
+from typing import Any, Type
+
+from marshmallow import Schema, ValidationError, fields
+
+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
+
+
+class _QuantityField(fields.Field):
+    """Custom field for Quantity objects supporting per-field serialization configuration.
+
+    This class handles serialization and deserialization of ALL Quantity
+    subclasses.
+    The specific Quantity subclass is determined by the field_type attribute.
+
+    * Deserialization auto-detects the type of deserialization (float or string)
+      based on the input type.
+    * Serialization uses either the schema's default or the per-field
+      configuration found in the metadata.
+
+    We need distinct QuantityField subclasses for each Quantity subclass, so
+    they can be used in the TYPE_MAPPING in the `QuantitySchema`.
+    Which means this class is not intended to be used directly.
+
+    Instead, we use the specific QuantityField subclasses for each Quantity.
+    Each field subclass simply sets the field_type attribute to the corresponding
+    Quantity subclass.
+
+    Those subclasses are generated and stored in the QUANTITY_FIELD_CLASSES
+    mapping and are used for the TYPE_MAPPING in the `QuantitySchema`.
+    """
+
+    field_type: Type[Quantity] | None = None
+    """The specific Quantity subclass."""
+
+    def _serialize(
+        self, value: Quantity, attr: str | None, obj: Any, **kwargs: Any
+    ) -> Any:
+        """Serialize the Quantity object based on per-field configuration."""
+        if self.field_type is None or not issubclass(self.field_type, Quantity):
+            raise TypeError(
+                "field_type must be set to a Quantity subclass in the subclass."
+            )
+
+        assert self.parent is not None
+
+        # Determine the serialization format
+        serialize_as_string = self.metadata.get(
+            "serialize_as_string",
+            self.parent.context.get("serialize_as_string_default", False),
+        )
+
+        if serialize_as_string:
+            # Use the Quantity's native string representation (includes unit)
+            return str(value)
+
+        # Serialize as float using the Quantity's base value
+        return value.base_value
+
+    def _deserialize(
+        self, value: Any, attr: str | None, data: Any, **kwargs: Any
+    ) -> Quantity:
+        """Deserialize the Quantity object from float or string."""
+        if self.field_type is None or not issubclass(self.field_type, Quantity):
+            raise TypeError(
+                "field_type must be set to a Quantity subclass in the subclass."
+            )
+
+        if isinstance(value, str):
+            # Use the Quantity's from_string method
+            try:
+                return self.field_type.from_string(value)
+            except Exception as error:  # pylint: disable=broad-except
+                raise ValidationError(str(error)) from error
+        if isinstance(value, (float, int)):
+            try:
+                # Use `_new` method for creating instance from base value
+                return self.field_type._new(  # pylint: disable=protected-access
+                    float(value)
+                )
+            except Exception as error:  # pylint: disable=broad-except
+                raise ValidationError(str(error)) from error
+
+        raise ValidationError("Invalid input type for QuantityField.")
+
+
+_QUANTITY_SUBCLASSES = [
+    ApparentPower,
+    Current,
+    Energy,
+    Frequency,
+    Percentage,
+    Power,
+    ReactivePower,
+    Temperature,
+    Voltage,
+]
+
+
+class ApparentPowerField(_QuantityField):
+    """Custom field for ApparentPower objects."""
+
+    field_type = ApparentPower
+
+
+class CurrentField(_QuantityField):
+    """Custom field for Current objects."""
+
+    field_type = Current
+
+
+class EnergyField(_QuantityField):
+    """Custom field for Energy objects."""
+
+    field_type = Energy
+
+
+class FrequencyField(_QuantityField):
+    """Custom field for Frequency objects."""
+
+    field_type = Frequency
+
+
+class PercentageField(_QuantityField):
+    """Custom field for Percentage objects."""
+
+    field_type = Percentage
+
+
+class PowerField(_QuantityField):
+    """Custom field for Power objects."""
+
+    field_type = Power
+
+
+class ReactivePowerField(_QuantityField):
+    """Custom field for ReactivePower objects."""
+
+    field_type = ReactivePower
+
+
+class TemperatureField(_QuantityField):
+    """Custom field for Temperature objects."""
+
+    field_type = Temperature
+
+
+class VoltageField(_QuantityField):
+    """Custom field for Voltage objects."""
+
+    field_type = Voltage
+
+
+QUANTITY_FIELD_CLASSES: dict[type[Quantity], type[fields.Field]] = {
+    ApparentPower: ApparentPowerField,
+    Current: CurrentField,
+    Energy: EnergyField,
+    Frequency: FrequencyField,
+    Percentage: PercentageField,
+    Power: PowerField,
+    ReactivePower: ReactivePowerField,
+    Temperature: TemperatureField,
+    Voltage: VoltageField,
+}
+"""Mapping of Quantity subclasses to their corresponding QuantityField subclasses.
+
+This mapping is used in the `QuantitySchema` to determine the correct field
+class for each Quantity subclass.
+
+The keys are Quantity subclasses (e.g., Percentage, Energy) and the values are
+the corresponding QuantityField subclasses.
+"""
+
+
+class QuantitySchema(Schema):
+    """A schema for quantities.
+
+    Example usage:
+
+    ```python
+    from dataclasses import dataclass, field
+    from marshmallow_dataclass import class_schema
+    from marshmallow.validate import Range
+    from frequenz.quantities import Percentage
+    from frequenz.quantities.experimental.marshmallow import QuantitySchema
+    from typing import cast
+
+    @dataclass
+    class Config:
+        percentage_always_as_string: Percentage = field(
+            default_factory=lambda: Percentage.from_percent(25.0),
+            metadata={
+                "metadata": {
+                    "description": "A percentage field",
+                },
+                "validate": Range(Percentage.zero(), Percentage.from_percent(100.0)),
+                "serialize_as_string": True,
+            },
+        )
+
+        percentage_always_as_float: Percentage = field(
+            default_factory=lambda: Percentage.from_percent(25.0),
+            metadata={
+                "metadata": {
+                    "description": "A percentage field",
+                },
+                "validate": Range(Percentage.zero(), Percentage.from_percent(100.0)),
+                "serialize_as_string": False,
+            },
+        )
+
+        percentage_serialized_as_schema_default: Percentage = field(
+            default_factory=lambda: Percentage.from_percent(25.0),
+            metadata={
+                "metadata": {
+                    "description": "A percentage field",
+                },
+                "validate": Range(Percentage.zero(), Percentage.from_percent(100.0)),
+            },
+        )
+
+        @classmethod
+        def load(cls, config: dict[str, Any]) -> "Config":
+            schema = class_schema(cls, base_schema=QuantitySchema)(
+                serialize_as_string_default=True # type: ignore[call-arg]
+            )
+            return cast(Config, schema.load(config))
+    ```
+    """
+
+    TYPE_MAPPING: dict[type[Quantity], type[fields.Field]] = QUANTITY_FIELD_CLASSES
+
+    def __init__(
+        self, *args: Any, serialize_as_string_default: bool = False, **kwargs: Any
+    ) -> None:
+        """
+        Initialize the schema with a default serialization format.
+
+        Args:
+            *args: Additional positional arguments.
+            serialize_as_string_default: Default serialization format for quantities.
+                If True, quantities are serialized as strings with units.
+                If False, quantities are serialized as floats.
+            **kwargs: Additional keyword arguments.
+        """
+        super().__init__(*args, **kwargs)
+        self.context["serialize_as_string_default"] = serialize_as_string_default

frequenz_quantities-1.0.0.dist-info/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright © 2024 Frequenz Energy-as-a-Service GmbH
+
+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.

frequenz_quantities-1.0.0.dist-info/METADATA

@@ -0,0 +1,103 @@
+Metadata-Version: 2.1
+Name: frequenz-quantities
+Version: 1.0.0
+Summary: Types for holding quantities with units
+Author-email: Frequenz Energy-as-a-Service GmbH <floss@frequenz.com>
+License: MIT
+Project-URL: Documentation, https://frequenz-floss.github.io/frequenz-quantities-python/
+Project-URL: Changelog, https://github.com/frequenz-floss/frequenz-quantities-python/releases
+Project-URL: Issues, https://github.com/frequenz-floss/frequenz-quantities-python/issues
+Project-URL: Repository, https://github.com/frequenz-floss/frequenz-quantities-python
+Project-URL: Support, https://github.com/frequenz-floss/frequenz-quantities-python/discussions/categories/support
+Keywords: frequenz,python,lib,library,quantities,unit,conversion
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: <4,>=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typing-extensions<5,>=4.5.0
+Provides-Extra: dev
+Requires-Dist: frequenz-quantities[dev-flake8,dev-formatting,dev-mkdocs,dev-mypy,dev-noxfile,dev-pylint,dev-pytest,marshmallow]; extra == "dev"
+Provides-Extra: dev-flake8
+Requires-Dist: flake8==7.1.1; extra == "dev-flake8"
+Requires-Dist: flake8-docstrings==1.7.0; extra == "dev-flake8"
+Requires-Dist: flake8-pyproject==1.2.3; extra == "dev-flake8"
+Requires-Dist: pydoclint==0.5.9; extra == "dev-flake8"
+Requires-Dist: pydocstyle==6.3.0; extra == "dev-flake8"
+Provides-Extra: dev-formatting
+Requires-Dist: black==24.10.0; extra == "dev-formatting"
+Requires-Dist: isort==5.13.2; extra == "dev-formatting"
+Provides-Extra: dev-mkdocs
+Requires-Dist: Markdown==3.7; extra == "dev-mkdocs"
+Requires-Dist: black==24.10.0; extra == "dev-mkdocs"
+Requires-Dist: mike==2.1.3; extra == "dev-mkdocs"
+Requires-Dist: mkdocs-gen-files==0.5.0; extra == "dev-mkdocs"
+Requires-Dist: mkdocs-literate-nav==0.6.1; extra == "dev-mkdocs"
+Requires-Dist: mkdocs-macros-plugin==1.3.7; extra == "dev-mkdocs"
+Requires-Dist: mkdocs-material==9.5.43; extra == "dev-mkdocs"
+Requires-Dist: mkdocstrings[python]==0.26.2; extra == "dev-mkdocs"
+Requires-Dist: mkdocstrings-python==1.12.2; extra == "dev-mkdocs"
+Requires-Dist: frequenz-repo-config[lib]==0.10.0; extra == "dev-mkdocs"
+Provides-Extra: dev-mypy
+Requires-Dist: mypy==1.13.0; extra == "dev-mypy"
+Requires-Dist: types-Markdown==3.7.0.20240822; extra == "dev-mypy"
+Requires-Dist: frequenz-quantities[dev-mkdocs,dev-noxfile,dev-pytest,marshmallow]; extra == "dev-mypy"
+Provides-Extra: dev-noxfile
+Requires-Dist: nox==2024.10.9; extra == "dev-noxfile"
+Requires-Dist: frequenz-repo-config[lib]==0.10.0; extra == "dev-noxfile"
+Provides-Extra: dev-pylint
+Requires-Dist: frequenz-quantities[dev-mkdocs,dev-noxfile,dev-pytest,marshmallow]; extra == "dev-pylint"
+Provides-Extra: dev-pytest
+Requires-Dist: pytest==8.3.3; extra == "dev-pytest"
+Requires-Dist: pylint==3.3.1; extra == "dev-pytest"
+Requires-Dist: frequenz-repo-config[extra-lint-examples]==0.10.0; extra == "dev-pytest"
+Requires-Dist: pytest-mock==3.14.0; extra == "dev-pytest"
+Requires-Dist: pytest-asyncio==0.24.0; extra == "dev-pytest"
+Requires-Dist: async-solipsism==0.7; extra == "dev-pytest"
+Requires-Dist: hypothesis==6.116.0; extra == "dev-pytest"
+Requires-Dist: frequenz-quantities[marshmallow]; extra == "dev-pytest"
+Provides-Extra: marshmallow
+Requires-Dist: marshmallow<4,>=3.0.0; extra == "marshmallow"
+Requires-Dist: marshmallow-dataclass<9,>=8.0.0; extra == "marshmallow"
+
+# Frequenz Quantities Library
+
+[![Build Status](https://github.com/frequenz-floss/frequenz-quantities-python/actions/workflows/ci.yaml/badge.svg)](https://github.com/frequenz-floss/frequenz-quantities-python/actions/workflows/ci.yaml)
+[![PyPI Package](https://img.shields.io/pypi/v/frequenz-quantities)](https://pypi.org/project/frequenz-quantities/)
+[![Docs](https://img.shields.io/badge/docs-latest-informational)](https://frequenz-floss.github.io/frequenz-quantities-python/)
+
+## Introduction
+
+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.
+
+## Documentation
+
+For more information on how to use this library and examples, please check the
+[Documentation website](https://frequenz-floss.github.io/frequenz-quantities-python/).
+
+## Supported Platforms
+
+The following platforms are officially supported (tested):
+
+- **Python:** 3.11
+- **Operating System:** Ubuntu Linux 20.04
+- **Architectures:** amd64, arm64
+
+## Contributing
+
+If you want to know how to build this project and contribute to it, please
+check out the [Contributing Guide](CONTRIBUTING.md).

frequenz_quantities-1.0.0.dist-info/RECORD

@@ -0,0 +1,20 @@
+frequenz/quantities/__init__.py,sha256=WCmf6AdoCd6qD25704053TCIWLVkbgT_EgAjBeOWsqY,4420
+frequenz/quantities/_apparent_power.py,sha256=XYWhcAhYIU1a_ciLXwvUPaXTmpSSWsDP3C-W8kpQ4y0,6988
+frequenz/quantities/_current.py,sha256=9y4v9AeZfr4cCkzFLbSzhzh7ZPXje7i5-V6nf0qdIgs,3573
+frequenz/quantities/_energy.py,sha256=jfp2ZMb2bJV3etAZwNP7r3eWw0zcp1IQOI0hpTxVDFI,5274
+frequenz/quantities/_frequency.py,sha256=Y_ljIdd-gBFbyBIFHhPeVeD2JQrPTwOeoHI79B7B-ys,2933
+frequenz/quantities/_percentage.py,sha256=vdf7eBbr5EEHKj-0aPVLL6TSjE6OnFcHGN22knFTrlI,1775
+frequenz/quantities/_power.py,sha256=KtT5hED-BzlGqFgKDZktE8UkudLV5khfBZ80zu0b2Vo,7074
+frequenz/quantities/_quantity.py,sha256=sfYAc5hYRlkVRQ5AAgt-79x2-eZwYN1DrlxVrGxJEWw,17134
+frequenz/quantities/_reactive_power.py,sha256=UiOKvY8oPW_7H2FFCE47FGyPIm-TcimfihK76fSUPFc,7203
+frequenz/quantities/_temperature.py,sha256=PlQnavtvBe395ZmsgHTedh520pOAd9-jSRHkqfjv8-k,868
+frequenz/quantities/_voltage.py,sha256=WuYLfC3FsWdWrHMfqxFYTAJmP1CdIFpPVeeGHlOV-eo,4057
+frequenz/quantities/conftest.py,sha256=kxmvkzTdvGfh7SiDINIFX0FG9PU0EoKROl9YY75zN8w,409
+frequenz/quantities/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+frequenz/quantities/experimental/__init__.py,sha256=nYOmkSXnHz9kqOf1QwawV0xFqRbBwjgKwGqbxFIVGeI,350
+frequenz/quantities/experimental/marshmallow.py,sha256=P9P7GUVf9uE6fZZuPFxzWvsxeyh-bbPegQPG5OZMX5M,8742
+frequenz_quantities-1.0.0.dist-info/LICENSE,sha256=zt0sW1KvE_KWE2ILOabrQYlfOoP0zUZXC3xCLrzGpIA,1089
+frequenz_quantities-1.0.0.dist-info/METADATA,sha256=B9YoeLZd2CqsOS5L3kVt37vPA5y8MLnmhBsMPRGoTDs,5162
+frequenz_quantities-1.0.0.dist-info/WHEEL,sha256=bFJAMchF8aTQGUgMZzHJyDDMPTO3ToJ7x23SLJa1SVo,92
+frequenz_quantities-1.0.0.dist-info/top_level.txt,sha256=x08GRcWytsyKXa2Ayme9e5pg3L5Kcq6lw_BaQmToMO4,9
+frequenz_quantities-1.0.0.dist-info/RECORD,,

frequenz_quantities-1.0.0.dist-info/WHEEL

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

frequenz_quantities-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+frequenz