diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md index f0b649c..3ff6bb1 100644 --- a/RELEASE_NOTES.md +++ b/RELEASE_NOTES.md @@ -15,3 +15,5 @@ ## Bug Fixes + +- Fix a cross-reference that broke downstream strict doc builds. diff --git a/src/frequenz/quantities/experimental/marshmallow.py b/src/frequenz/quantities/experimental/marshmallow.py index 9e4bf21..15b102f 100644 --- a/src/frequenz/quantities/experimental/marshmallow.py +++ b/src/frequenz/quantities/experimental/marshmallow.py @@ -4,7 +4,7 @@ """Custom marshmallow fields and schema. This module provides custom marshmallow fields for quantities and -a [`QuantitySchema`][.QuantitySchema] class to +a [`QuantitySchema`][frequenz.quantities.experimental.marshmallow.QuantitySchema] class to be used as base schema for dataclasses containing quantities. Danger: @@ -43,14 +43,15 @@ class _QuantityField(Field[Quantity]): - """A custom field for [`Quantity`][....Quantity] objects. + """A custom field for [`Quantity`][frequenz.quantities.Quantity] objects. Supports per-field serialization configuration. This class handles serialization and deserialization of ALL - [`Quantity`][....Quantity] subclasses. - The specific [`Quantity`][....Quantity] subclass is determined by the - [`.field_type`][.field_type] attribute. + [`Quantity`][frequenz.quantities.Quantity] subclasses. + The specific [`Quantity`][frequenz.quantities.Quantity] subclass is determined by the + [`.field_type`][frequenz.quantities.experimental.marshmallow._QuantityField.field_type] + attribute. * Deserialization auto-detects the type of deserialization (float or string) based on the input type. @@ -58,23 +59,29 @@ class _QuantityField(Field[Quantity]): configuration found in the metadata. We need distinct `_QuantityField` subclasses for each - [`Quantity`][....Quantity] subclass, so - they can be used in the [`TYPE_MAPPING`][..QuantitySchema.TYPE_MAPPING] in - [`QuantitySchema`][..QuantitySchema]. + [`Quantity`][frequenz.quantities.Quantity] subclass, so + they can be used in the + [`TYPE_MAPPING`][frequenz.quantities.experimental.marshmallow.QuantitySchema.TYPE_MAPPING] + in + [`QuantitySchema`][frequenz.quantities.experimental.marshmallow.QuantitySchema]. This class is not intended to be used directly. Instead, we use the specific `_QuantityField` subclasses for each - [`Quantity`][....Quantity]. - Each field subclass simply sets the [`.field_type`][.field_type] - attribute to the corresponding [`Quantity`][....Quantity] subclass. - - Those subclasses are stored in [`QUANTITY_FIELD_CLASSES`][..QUANTITY_FIELD_CLASSES] - and are used for the [`TYPE_MAPPING`][..QuantitySchema.TYPE_MAPPING] in - [`QuantitySchema`][..QuantitySchema]. + [`Quantity`][frequenz.quantities.Quantity]. + Each field subclass simply sets the + [`.field_type`][frequenz.quantities.experimental.marshmallow._QuantityField.field_type] + attribute to the corresponding [`Quantity`][frequenz.quantities.Quantity] subclass. + + Those subclasses are stored in + [`QUANTITY_FIELD_CLASSES`][frequenz.quantities.experimental.marshmallow.QUANTITY_FIELD_CLASSES] + and are used for the + [`TYPE_MAPPING`][frequenz.quantities.experimental.marshmallow.QuantitySchema.TYPE_MAPPING] + in + [`QuantitySchema`][frequenz.quantities.experimental.marshmallow.QuantitySchema]. """ field_type: Type[Quantity] | None = None - """The specific [`Quantity`][.....Quantity] subclass.""" + """The specific [`Quantity`][frequenz.quantities.Quantity] subclass.""" def __init__(self, *args: Any, **kwargs: Any) -> None: """Initialize the field.""" @@ -84,7 +91,7 @@ def __init__(self, *args: Any, **kwargs: Any) -> None: def _serialize( self, value: Quantity | None, attr: str | None, obj: Any, **kwargs: Any ) -> Any: - """Serialize a [`Quantity`][.....Quantity] based on per-field configuration. + """Serialize a [`Quantity`][frequenz.quantities.Quantity] based on per-field configuration. Args: value: The quantity to serialize, or `None`. @@ -97,9 +104,11 @@ def _serialize( the raw base float value otherwise. `None` if `value` is `None`. Raises: - TypeError: If [`..field_type`][..field_type] is not set to a - [`Quantity`][.....Quantity] subclass, or if - `value` is not a [`Quantity`][.....Quantity] + TypeError: If + [`.field_type`][frequenz.quantities.experimental.marshmallow._QuantityField.field_type] + is not set to a + [`Quantity`][frequenz.quantities.Quantity] subclass, or if + `value` is not a [`Quantity`][frequenz.quantities.Quantity] instance. """ if self.field_type is None or not issubclass(self.field_type, Quantity): @@ -132,7 +141,7 @@ def _serialize( def _deserialize( self, value: Any, attr: str | None, data: Any, **kwargs: Any ) -> Quantity: - """Deserialize a [`Quantity`][.....Quantity] from a float, int, or string. + """Deserialize a [`Quantity`][frequenz.quantities.Quantity] from a float, int, or string. Args: value: The raw value to deserialize (float, int, or string). @@ -144,8 +153,10 @@ def _deserialize( The deserialized quantity instance. Raises: - TypeError: If [`..field_type`][..field_type] is not set to a - [`Quantity`][.....Quantity] subclass. + TypeError: If + [`.field_type`][frequenz.quantities.experimental.marshmallow._QuantityField.field_type] + is not set to a + [`Quantity`][frequenz.quantities.Quantity] subclass. ValidationError: If the input type is invalid or parsing fails (see [`marshmallow.ValidationError`][marshmallow.ValidationError]). """ @@ -186,55 +197,55 @@ def _deserialize( class ApparentPowerField(_QuantityField): - """A custom field for [`ApparentPower`][....ApparentPower] objects.""" + """A custom field for [`ApparentPower`][frequenz.quantities.ApparentPower] objects.""" field_type = ApparentPower class CurrentField(_QuantityField): - """A custom field for [`Current`][....Current] objects.""" + """A custom field for [`Current`][frequenz.quantities.Current] objects.""" field_type = Current class EnergyField(_QuantityField): - """A custom field for [`Energy`][....Energy] objects.""" + """A custom field for [`Energy`][frequenz.quantities.Energy] objects.""" field_type = Energy class FrequencyField(_QuantityField): - """A custom field for [`Frequency`][....Frequency] objects.""" + """A custom field for [`Frequency`][frequenz.quantities.Frequency] objects.""" field_type = Frequency class PercentageField(_QuantityField): - """A custom field for [`Percentage`][....Percentage] objects.""" + """A custom field for [`Percentage`][frequenz.quantities.Percentage] objects.""" field_type = Percentage class PowerField(_QuantityField): - """A custom field for [`Power`][....Power] objects.""" + """A custom field for [`Power`][frequenz.quantities.Power] objects.""" field_type = Power class ReactivePowerField(_QuantityField): - """A custom field for [`ReactivePower`][....ReactivePower] objects.""" + """A custom field for [`ReactivePower`][frequenz.quantities.ReactivePower] objects.""" field_type = ReactivePower class TemperatureField(_QuantityField): - """A custom field for [`Temperature`][....Temperature] objects.""" + """A custom field for [`Temperature`][frequenz.quantities.Temperature] objects.""" field_type = Temperature class VoltageField(_QuantityField): - """A custom field for [`Voltage`][....Voltage] objects.""" + """A custom field for [`Voltage`][frequenz.quantities.Voltage] objects.""" field_type = Voltage @@ -250,10 +261,13 @@ class VoltageField(_QuantityField): Temperature: TemperatureField, Voltage: VoltageField, } -"""The mapping from [`Quantity`][....Quantity] subclasses to their corresponding field subclasses. +"""The mapping from [`Quantity`][frequenz.quantities.Quantity] subclasses +to their corresponding field subclasses. -This mapping is used in [`QuantitySchema.TYPE_MAPPING`][..QuantitySchema.TYPE_MAPPING] to -determine the correct field class for each [`Quantity`][....Quantity] +This mapping is used in +[`QuantitySchema.TYPE_MAPPING`][frequenz.quantities.experimental.marshmallow.QuantitySchema.TYPE_MAPPING] +to +determine the correct field class for each [`Quantity`][frequenz.quantities.Quantity] subclass. """ @@ -327,4 +341,4 @@ class Config: """ TYPE_MAPPING: dict[type, type[Field[Any]]] = QUANTITY_FIELD_CLASSES - """The field class to use for each [`Quantity`][.....Quantity] subclass.""" + """The field class to use for each [`Quantity`][frequenz.quantities.Quantity] subclass."""