Skip to content

marshmallow

frequenz.quantities.experimental.marshmallow ¤

Custom marshmallow fields and schema.

This module provides custom marshmallow fields for quantities and a 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.

Attributes¤

frequenz.quantities.experimental.marshmallow.QUANTITY_FIELD_CLASSES module-attribute ¤

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.

frequenz.quantities.experimental.marshmallow.serialize_as_string_default module-attribute ¤

serialize_as_string_default: ContextVar[bool] = ContextVar(
    "serialize_as_string_default", default=False
)

Context variable to control the default serialization format for quantities.

If True, quantities are serialized as strings with units. If False, quantities are serialized as floats.

This can be overridden on a per-field basis using the serialize_as_string metadata attribute.

Classes¤

frequenz.quantities.experimental.marshmallow.ApparentPowerField ¤

Bases: _QuantityField

Custom field for ApparentPower objects.

Source code in frequenz/quantities/experimental/marshmallow.py
class ApparentPowerField(_QuantityField):
    """Custom field for ApparentPower objects."""

    field_type = ApparentPower
Functions¤
__init__ ¤
__init__(*args: Any, **kwargs: Any) -> None

Initialize the field.

Source code in frequenz/quantities/experimental/marshmallow.py
def __init__(self, *args: Any, **kwargs: Any) -> None:
    """Initialize the field."""
    self.serialize_as_string_override = kwargs.pop("serialize_as_string", None)
    super().__init__(*args, **kwargs)

frequenz.quantities.experimental.marshmallow.CurrentField ¤

Bases: _QuantityField

Custom field for Current objects.

Source code in frequenz/quantities/experimental/marshmallow.py
class CurrentField(_QuantityField):
    """Custom field for Current objects."""

    field_type = Current
Functions¤
__init__ ¤
__init__(*args: Any, **kwargs: Any) -> None

Initialize the field.

Source code in frequenz/quantities/experimental/marshmallow.py
def __init__(self, *args: Any, **kwargs: Any) -> None:
    """Initialize the field."""
    self.serialize_as_string_override = kwargs.pop("serialize_as_string", None)
    super().__init__(*args, **kwargs)

frequenz.quantities.experimental.marshmallow.EnergyField ¤

Bases: _QuantityField

Custom field for Energy objects.

Source code in frequenz/quantities/experimental/marshmallow.py
class EnergyField(_QuantityField):
    """Custom field for Energy objects."""

    field_type = Energy
Functions¤
__init__ ¤
__init__(*args: Any, **kwargs: Any) -> None

Initialize the field.

Source code in frequenz/quantities/experimental/marshmallow.py
def __init__(self, *args: Any, **kwargs: Any) -> None:
    """Initialize the field."""
    self.serialize_as_string_override = kwargs.pop("serialize_as_string", None)
    super().__init__(*args, **kwargs)

frequenz.quantities.experimental.marshmallow.FrequencyField ¤

Bases: _QuantityField

Custom field for Frequency objects.

Source code in frequenz/quantities/experimental/marshmallow.py
class FrequencyField(_QuantityField):
    """Custom field for Frequency objects."""

    field_type = Frequency
Functions¤
__init__ ¤
__init__(*args: Any, **kwargs: Any) -> None

Initialize the field.

Source code in frequenz/quantities/experimental/marshmallow.py
def __init__(self, *args: Any, **kwargs: Any) -> None:
    """Initialize the field."""
    self.serialize_as_string_override = kwargs.pop("serialize_as_string", None)
    super().__init__(*args, **kwargs)

frequenz.quantities.experimental.marshmallow.PercentageField ¤

Bases: _QuantityField

Custom field for Percentage objects.

Source code in frequenz/quantities/experimental/marshmallow.py
class PercentageField(_QuantityField):
    """Custom field for Percentage objects."""

    field_type = Percentage
Functions¤
__init__ ¤
__init__(*args: Any, **kwargs: Any) -> None

Initialize the field.

Source code in frequenz/quantities/experimental/marshmallow.py
def __init__(self, *args: Any, **kwargs: Any) -> None:
    """Initialize the field."""
    self.serialize_as_string_override = kwargs.pop("serialize_as_string", None)
    super().__init__(*args, **kwargs)

frequenz.quantities.experimental.marshmallow.PowerField ¤

Bases: _QuantityField

Custom field for Power objects.

Source code in frequenz/quantities/experimental/marshmallow.py
class PowerField(_QuantityField):
    """Custom field for Power objects."""

    field_type = Power
Functions¤
__init__ ¤
__init__(*args: Any, **kwargs: Any) -> None

Initialize the field.

Source code in frequenz/quantities/experimental/marshmallow.py
def __init__(self, *args: Any, **kwargs: Any) -> None:
    """Initialize the field."""
    self.serialize_as_string_override = kwargs.pop("serialize_as_string", None)
    super().__init__(*args, **kwargs)

frequenz.quantities.experimental.marshmallow.QuantitySchema ¤

Bases: Schema

A schema for quantities.

Example usage:

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,
    serialize_as_string_default,
)

@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)),
        },
    )

config_obj = Config()
Schema = class_schema(Config, base_schema=QuantitySchema)
schema = Schema()

# Default serialization (as float)
result = schema.dump(config_obj)
assert result["percentage_serialized_as_schema_default"] == 25.0

# Override default serialization to string
serialize_as_string_default.set(True)
result = schema.dump(config_obj)
assert result["percentage_serialized_as_schema_default"] == "25.0 %"
serialize_as_string_default.set(False) # Reset context

# Per-field configuration always takes precedence
assert result["percentage_always_as_string"] == "25.0 %"
assert result["percentage_always_as_float"] == 25.0
Source code in frequenz/quantities/experimental/marshmallow.py
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,
        serialize_as_string_default,
    )

    @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)),
            },
        )

    config_obj = Config()
    Schema = class_schema(Config, base_schema=QuantitySchema)
    schema = Schema()

    # Default serialization (as float)
    result = schema.dump(config_obj)
    assert result["percentage_serialized_as_schema_default"] == 25.0

    # Override default serialization to string
    serialize_as_string_default.set(True)
    result = schema.dump(config_obj)
    assert result["percentage_serialized_as_schema_default"] == "25.0 %"
    serialize_as_string_default.set(False) # Reset context

    # Per-field configuration always takes precedence
    assert result["percentage_always_as_string"] == "25.0 %"
    assert result["percentage_always_as_float"] == 25.0
    ```
    """

    TYPE_MAPPING: dict[type, type[Field[Any]]] = QUANTITY_FIELD_CLASSES

frequenz.quantities.experimental.marshmallow.ReactivePowerField ¤

Bases: _QuantityField

Custom field for ReactivePower objects.

Source code in frequenz/quantities/experimental/marshmallow.py
class ReactivePowerField(_QuantityField):
    """Custom field for ReactivePower objects."""

    field_type = ReactivePower
Functions¤
__init__ ¤
__init__(*args: Any, **kwargs: Any) -> None

Initialize the field.

Source code in frequenz/quantities/experimental/marshmallow.py
def __init__(self, *args: Any, **kwargs: Any) -> None:
    """Initialize the field."""
    self.serialize_as_string_override = kwargs.pop("serialize_as_string", None)
    super().__init__(*args, **kwargs)

frequenz.quantities.experimental.marshmallow.TemperatureField ¤

Bases: _QuantityField

Custom field for Temperature objects.

Source code in frequenz/quantities/experimental/marshmallow.py
class TemperatureField(_QuantityField):
    """Custom field for Temperature objects."""

    field_type = Temperature
Functions¤
__init__ ¤
__init__(*args: Any, **kwargs: Any) -> None

Initialize the field.

Source code in frequenz/quantities/experimental/marshmallow.py
def __init__(self, *args: Any, **kwargs: Any) -> None:
    """Initialize the field."""
    self.serialize_as_string_override = kwargs.pop("serialize_as_string", None)
    super().__init__(*args, **kwargs)

frequenz.quantities.experimental.marshmallow.VoltageField ¤

Bases: _QuantityField

Custom field for Voltage objects.

Source code in frequenz/quantities/experimental/marshmallow.py
class VoltageField(_QuantityField):
    """Custom field for Voltage objects."""

    field_type = Voltage
Functions¤
__init__ ¤
__init__(*args: Any, **kwargs: Any) -> None

Initialize the field.

Source code in frequenz/quantities/experimental/marshmallow.py
def __init__(self, *args: Any, **kwargs: Any) -> None:
    """Initialize the field."""
    self.serialize_as_string_override = kwargs.pop("serialize_as_string", None)
    super().__init__(*args, **kwargs)