Skip to content

Index

frequenz.client.common.grid ¤

Grid definitions for the energy market.

Classes¤

frequenz.client.common.grid.BaseDeliveryArea dataclass ¤

A base class for all delivery areas.

This is the common supertype of both well-formed DeliveryArea instances and InvalidDeliveryArea instances that carry malformed wire data. It cannot be instantiated directly; use one of its concrete subclasses instead.

Source code in src/frequenz/client/common/grid/_delivery_area.py 
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
@dataclass(frozen=True, kw_only=True)
class BaseDeliveryArea:
    """A base class for all delivery areas.

    This is the common supertype of both well-formed
    [`DeliveryArea`][..DeliveryArea] instances and
    [`InvalidDeliveryArea`][..InvalidDeliveryArea] instances that carry
    malformed wire data. It cannot be instantiated directly; use one of
    its concrete subclasses instead.
    """

    code: str | None
    """The code representing the unique identifier for the delivery area.

    Warning: Using `None` is deprecated
        This field is required for a well-formed `DeliveryArea`, so we are
        making this more explicit by deprecating the use of `None` here. In the
        future, `| None` will be removed so passing `None` will fail type
        checking.
    """

    code_type: EnergyMarketCodeType | int
    """Type of code used for identifying the delivery area itself.

    This code could be extended in the future, in case an unknown code type is
    encountered, a plain integer value is used to represent it.

    Tip:
        This is the lower-level accessor; when working with a valid
        [`DeliveryArea`][...DeliveryArea], prefer
        [`get_code_type`][...DeliveryArea.get_code_type] to obtain a known
        member or a clear error.
    """

    # pylint: disable-next=unused-argument
    def __new__(cls, *args: Any, **kwargs: Any) -> Self:
        """Prevent instantiation of this class."""
        if cls is BaseDeliveryArea:
            raise TypeError(f"Cannot instantiate {cls.__name__} directly")
        return super().__new__(cls)

    def __post_init__(self) -> None:
        """Warn if this instance carries invalid data."""
        if self.code is None:
            warnings.warn(
                "Using `None` for `code` is deprecated and will be "
                "removed in a future release.",
                DeprecationWarning,
                stacklevel=3,
            )
Attributes¤
code instance-attribute ¤
code: str | None

The code representing the unique identifier for the delivery area.

Using None is deprecated

This field is required for a well-formed DeliveryArea, so we are making this more explicit by deprecating the use of None here. In the future, | None will be removed so passing None will fail type checking.

code_type instance-attribute ¤
code_type: EnergyMarketCodeType | int

Type of code used for identifying the delivery area itself.

This code could be extended in the future, in case an unknown code type is encountered, a plain integer value is used to represent it.

Tip

This is the lower-level accessor; when working with a valid DeliveryArea, prefer get_code_type to obtain a known member or a clear error.

Methods:¤
__new__ ¤
__new__(*args: Any, **kwargs: Any) -> Self

Prevent instantiation of this class.

Source code in src/frequenz/client/common/grid/_delivery_area.py 
 96
 97
 98
 99
100
def __new__(cls, *args: Any, **kwargs: Any) -> Self:
    """Prevent instantiation of this class."""
    if cls is BaseDeliveryArea:
        raise TypeError(f"Cannot instantiate {cls.__name__} directly")
    return super().__new__(cls)
__post_init__ ¤
__post_init__() -> None

Warn if this instance carries invalid data.

Source code in src/frequenz/client/common/grid/_delivery_area.py 
102
103
104
105
106
107
108
109
110
def __post_init__(self) -> None:
    """Warn if this instance carries invalid data."""
    if self.code is None:
        warnings.warn(
            "Using `None` for `code` is deprecated and will be "
            "removed in a future release.",
            DeprecationWarning,
            stacklevel=3,
        )

frequenz.client.common.grid.DeliveryArea dataclass ¤

Bases: BaseDeliveryArea

A geographical or administrative region where electricity deliveries occur.

DeliveryArea represents the geographical or administrative region, usually defined and maintained by a Transmission System Operator (TSO), where electricity deliveries for a contract occur.

The concept is important to energy trading as it delineates the agreed-upon delivery location. Delivery areas can have different codes based on the jurisdiction in which they operate.

Construction of invalid instances is deprecated

A well-formed DeliveryArea carries a non-empty code and a specified code_type. Constructing one with data that violates this invariant is deprecated, and will raise a ValueError in a future release.

You can temporarily use the _raise_on_invalid keyword argument to get the upcoming behavior now (raising instead of deprecation warning).

Use InvalidDeliveryArea if you need to represent a malformed message.

Jurisdictional Differences

This is typically represented by specific codes according to local jurisdiction.

In Europe, this is represented by an EIC (Energy Identification Code). List of EICs.

Source code in src/frequenz/client/common/grid/_delivery_area.py 
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
@dataclass(frozen=True, kw_only=True)
class DeliveryArea(BaseDeliveryArea):
    """A geographical or administrative region where electricity deliveries occur.

    DeliveryArea represents the geographical or administrative region, usually defined
    and maintained by a Transmission System Operator (TSO), where electricity deliveries
    for a contract occur.

    The concept is important to energy trading as it delineates the agreed-upon delivery
    location. Delivery areas can have different codes based on the jurisdiction in
    which they operate.

    Warning: Construction of invalid instances is deprecated
        A well-formed `DeliveryArea` carries a non-empty [`code`][.code] and a
        specified [`code_type`][.code_type]. Constructing one with data that
        violates this invariant is **deprecated**, and will raise a
        [`ValueError`][] in a future release.

        You can temporarily use the `_raise_on_invalid` keyword argument to get
        the upcoming behavior now (raising instead of deprecation warning).

        Use [`InvalidDeliveryArea`][..InvalidDeliveryArea] if you need to
        represent a malformed message.

    Note: Jurisdictional Differences
        This is typically represented by specific codes according to local jurisdiction.

        In Europe, this is represented by an
        [EIC](https://en.wikipedia.org/wiki/Energy_Identification_Code) (Energy
        Identification Code). [List of
        EICs](https://www.entsoe.eu/data/energy-identification-codes-eic/eic-approved-codes/).
    """

    _raise_on_invalid: InitVar[bool] = False
    """Whether to raise a `ValueError` on invalid data.

    This will be removed in a future release and always raise on invalid data.
    """

    # pylint: disable-next=arguments-differ
    def __post_init__(self, _raise_on_invalid: bool) -> None:
        """Warn if this instance carries invalid data."""
        if not self.code:
            if _raise_on_invalid:
                raise ValueError("`code` cannot be None or empty")
            warnings.warn(
                "Constructing a DeliveryArea without a `code` is deprecated and will raise "
                "a `ValueError` in a future release. Use `InvalidDeliveryArea` instead.",
                DeprecationWarning,
                stacklevel=3,
            )
        with warnings.catch_warnings():
            warnings.filterwarnings("ignore", category=DeprecationWarning)
            unspecified_code_type = EnergyMarketCodeType.UNSPECIFIED
        if self.code_type in (0, unspecified_code_type):
            if _raise_on_invalid:
                raise ValueError("`code_type` cannot be 0 (UNSPECIFIED)")
            warnings.warn(
                "Constructing a DeliveryArea with `code_type=0` is deprecated and will raise "
                "a `ValueError` in a future release. Use `InvalidDeliveryArea` instead.",
                DeprecationWarning,
                stacklevel=3,
            )

    def __str__(self) -> str:
        """Return a human-readable string representation of this instance."""
        code_type = (
            f"type={self.code_type}"
            if isinstance(self.code_type, int)
            else self.code_type.name
        )
        return f"{self.code}[{code_type}]"

    def get_code_type(self) -> EnergyMarketCodeType:
        """Return the code type as a known enum member.

        This is the higher-level accessor for the `code_type` attribute: it
        resolves the value to a known `EnergyMarketCodeType` member or raises a
        clear, catchable error.

        Returns:
            The code type, when it is a known `EnergyMarketCodeType` member.

        Raises:
            UnspecifiedEnumValueError: If the code type is unspecified.
            UnrecognizedEnumValueError: If the code type is a value not
                recognized by this version of the client. The raw value is
                available on the exception's `value` attribute.
        """
        # Suppressing the deprecation warning can be removed when UNSPECIFIED is removed
        with warnings.catch_warnings():
            warnings.filterwarnings("ignore", category=DeprecationWarning)
            match self.code_type:
                case 0 | EnergyMarketCodeType.UNSPECIFIED:
                    raise UnspecifiedEnumValueError(self, "code_type")
                case EnergyMarketCodeType() as code_type:
                    return code_type
                case int() as code_type:
                    raise UnrecognizedEnumValueError(self, "code_type", code_type)
                case unknown:
                    assert_never(unknown)
Attributes¤
code instance-attribute ¤
code: str | None

The code representing the unique identifier for the delivery area.

Using None is deprecated

This field is required for a well-formed DeliveryArea, so we are making this more explicit by deprecating the use of None here. In the future, | None will be removed so passing None will fail type checking.

code_type instance-attribute ¤
code_type: EnergyMarketCodeType | int

Type of code used for identifying the delivery area itself.

This code could be extended in the future, in case an unknown code type is encountered, a plain integer value is used to represent it.

Tip

This is the lower-level accessor; when working with a valid DeliveryArea, prefer get_code_type to obtain a known member or a clear error.

Methods:¤
__new__ ¤
__new__(*args: Any, **kwargs: Any) -> Self

Prevent instantiation of this class.

Source code in src/frequenz/client/common/grid/_delivery_area.py 
 96
 97
 98
 99
100
def __new__(cls, *args: Any, **kwargs: Any) -> Self:
    """Prevent instantiation of this class."""
    if cls is BaseDeliveryArea:
        raise TypeError(f"Cannot instantiate {cls.__name__} directly")
    return super().__new__(cls)
__post_init__ ¤
__post_init__(_raise_on_invalid: bool) -> None

Warn if this instance carries invalid data.

Source code in src/frequenz/client/common/grid/_delivery_area.py 
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
def __post_init__(self, _raise_on_invalid: bool) -> None:
    """Warn if this instance carries invalid data."""
    if not self.code:
        if _raise_on_invalid:
            raise ValueError("`code` cannot be None or empty")
        warnings.warn(
            "Constructing a DeliveryArea without a `code` is deprecated and will raise "
            "a `ValueError` in a future release. Use `InvalidDeliveryArea` instead.",
            DeprecationWarning,
            stacklevel=3,
        )
    with warnings.catch_warnings():
        warnings.filterwarnings("ignore", category=DeprecationWarning)
        unspecified_code_type = EnergyMarketCodeType.UNSPECIFIED
    if self.code_type in (0, unspecified_code_type):
        if _raise_on_invalid:
            raise ValueError("`code_type` cannot be 0 (UNSPECIFIED)")
        warnings.warn(
            "Constructing a DeliveryArea with `code_type=0` is deprecated and will raise "
            "a `ValueError` in a future release. Use `InvalidDeliveryArea` instead.",
            DeprecationWarning,
            stacklevel=3,
        )
__str__ ¤
__str__() -> str

Return a human-readable string representation of this instance.

Source code in src/frequenz/client/common/grid/_delivery_area.py 
177
178
179
180
181
182
183
184
def __str__(self) -> str:
    """Return a human-readable string representation of this instance."""
    code_type = (
        f"type={self.code_type}"
        if isinstance(self.code_type, int)
        else self.code_type.name
    )
    return f"{self.code}[{code_type}]"
get_code_type ¤
get_code_type() -> EnergyMarketCodeType

Return the code type as a known enum member.

This is the higher-level accessor for the code_type attribute: it resolves the value to a known EnergyMarketCodeType member or raises a clear, catchable error.

RETURNS DESCRIPTION
EnergyMarketCodeType

The code type, when it is a known EnergyMarketCodeType member.
RAISES DESCRIPTION
UnspecifiedEnumValueError

If the code type is unspecified.
UnrecognizedEnumValueError

If the code type is a value not recognized by this version of the client. The raw value is available on the exception's value attribute.
Source code in src/frequenz/client/common/grid/_delivery_area.py 
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
def get_code_type(self) -> EnergyMarketCodeType:
    """Return the code type as a known enum member.

    This is the higher-level accessor for the `code_type` attribute: it
    resolves the value to a known `EnergyMarketCodeType` member or raises a
    clear, catchable error.

    Returns:
        The code type, when it is a known `EnergyMarketCodeType` member.

    Raises:
        UnspecifiedEnumValueError: If the code type is unspecified.
        UnrecognizedEnumValueError: If the code type is a value not
            recognized by this version of the client. The raw value is
            available on the exception's `value` attribute.
    """
    # Suppressing the deprecation warning can be removed when UNSPECIFIED is removed
    with warnings.catch_warnings():
        warnings.filterwarnings("ignore", category=DeprecationWarning)
        match self.code_type:
            case 0 | EnergyMarketCodeType.UNSPECIFIED:
                raise UnspecifiedEnumValueError(self, "code_type")
            case EnergyMarketCodeType() as code_type:
                return code_type
            case int() as code_type:
                raise UnrecognizedEnumValueError(self, "code_type", code_type)
            case unknown:
                assert_never(unknown)

frequenz.client.common.grid.EnergyMarketCodeType ¤

Bases: Enum

The identification code types used in the energy market.

CodeType specifies the type of identification code used for uniquely identifying various entities such as delivery areas, market participants, and grid components within the energy market.

This enumeration aims to offer compatibility across different jurisdictional standards.

Understanding Code Types

Different regions or countries may have their own standards for uniquely identifying various entities within the energy market. For example, in Europe, the Energy Identification Code (EIC) is commonly used for this purpose.

Extensibility

New code types can be added to this enum to accommodate additional regional standards, enhancing the API's adaptability.

Validation Required

The chosen code type should correspond correctly with the code field in the relevant message objects, such as DeliveryArea or Counterparty. Failure to match the code type with the correct code could lead to processing errors.

Source code in src/frequenz/client/common/grid/_delivery_area.py 
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
@unique
class EnergyMarketCodeType(Enum):
    """The identification code types used in the energy market.

    CodeType specifies the type of identification code used for uniquely
    identifying various entities such as delivery areas, market participants,
    and grid components within the energy market.

    This enumeration aims to
    offer compatibility across different jurisdictional standards.

    Note: Understanding Code Types
        Different regions or countries may have their own standards for uniquely
        identifying various entities within the energy market. For example, in
        Europe, the Energy Identification Code (EIC) is commonly used for this
        purpose.

    Note: Extensibility
        New code types can be added to this enum to accommodate additional regional
        standards, enhancing the API's adaptability.

    Danger: Validation Required
        The chosen code type should correspond correctly with the `code` field in
        the relevant message objects, such as `DeliveryArea` or `Counterparty`.
        Failure to match the code type with the correct code could lead to
        processing errors.
    """

    UNSPECIFIED = deprecated_member(
        0,
        "EnergyMarketCodeType.UNSPECIFIED is deprecated; use the `int` value `0` "
        "instead if you really need to check for this low-level value.",
    )
    """Unspecified type. This value is a placeholder and should not be used."""

    EUROPE_EIC = 1
    """European Energy Identification Code Standard."""

    US_NERC = 2
    """North American Electric Reliability Corporation identifiers."""
Attributes¤
EUROPE_EIC class-attribute instance-attribute ¤
EUROPE_EIC = 1

European Energy Identification Code Standard.

UNSPECIFIED class-attribute instance-attribute ¤
UNSPECIFIED = deprecated_member(
    0,
    "EnergyMarketCodeType.UNSPECIFIED is deprecated; use the `int` value `0` instead if you really need to check for this low-level value.",
)

Unspecified type. This value is a placeholder and should not be used.

US_NERC class-attribute instance-attribute ¤
US_NERC = 2

North American Electric Reliability Corporation identifiers.

frequenz.client.common.grid.InvalidDeliveryArea dataclass ¤

Bases: BaseDeliveryArea

A delivery area with malformed data received from the wire.

Represents delivery area data that fails the invariants required for a well-formed DeliveryArea. Callers can inspect the raw fields to recover partial information.

This class does not enforce any invariants on construction.

Source code in src/frequenz/client/common/grid/_delivery_area.py 
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
@dataclass(frozen=True, kw_only=True)
class InvalidDeliveryArea(BaseDeliveryArea):
    """A delivery area with malformed data received from the wire.

    Represents delivery area data that fails the invariants required for a
    well-formed [`DeliveryArea`][..DeliveryArea]. Callers can inspect the raw
    fields to recover partial information.

    This class does not enforce any invariants on construction.
    """

    def __str__(self) -> str:
        """Return a human-readable string representation of this instance."""
        # Suppressing the deprecation warning can be removed when UNSPECIFIED
        # is removed
        with warnings.catch_warnings():
            warnings.filterwarnings("ignore", category=DeprecationWarning)
            match self.code_type:
                case 0 | EnergyMarketCodeType.UNSPECIFIED:
                    code_type = "type=<invalid:0>"
                case EnergyMarketCodeType() as enum_code:
                    code_type = enum_code.name
                case int() as int_code:
                    code_type = f"type={int_code}"
                case unexpected:
                    assert_never(unexpected)
        code = self.code or f"<invalid:{self.code!r}>"
        return f"{code}[{code_type}]"
Attributes¤
code instance-attribute ¤
code: str | None

The code representing the unique identifier for the delivery area.

Using None is deprecated

This field is required for a well-formed DeliveryArea, so we are making this more explicit by deprecating the use of None here. In the future, | None will be removed so passing None will fail type checking.

code_type instance-attribute ¤
code_type: EnergyMarketCodeType | int

Type of code used for identifying the delivery area itself.

This code could be extended in the future, in case an unknown code type is encountered, a plain integer value is used to represent it.

Tip

This is the lower-level accessor; when working with a valid DeliveryArea, prefer get_code_type to obtain a known member or a clear error.

Methods:¤
__new__ ¤
__new__(*args: Any, **kwargs: Any) -> Self

Prevent instantiation of this class.

Source code in src/frequenz/client/common/grid/_delivery_area.py 
 96
 97
 98
 99
100
def __new__(cls, *args: Any, **kwargs: Any) -> Self:
    """Prevent instantiation of this class."""
    if cls is BaseDeliveryArea:
        raise TypeError(f"Cannot instantiate {cls.__name__} directly")
    return super().__new__(cls)
__post_init__ ¤
__post_init__() -> None

Warn if this instance carries invalid data.

Source code in src/frequenz/client/common/grid/_delivery_area.py 
102
103
104
105
106
107
108
109
110
def __post_init__(self) -> None:
    """Warn if this instance carries invalid data."""
    if self.code is None:
        warnings.warn(
            "Using `None` for `code` is deprecated and will be "
            "removed in a future release.",
            DeprecationWarning,
            stacklevel=3,
        )
__str__ ¤
__str__() -> str

Return a human-readable string representation of this instance.

Source code in src/frequenz/client/common/grid/_delivery_area.py 
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
def __str__(self) -> str:
    """Return a human-readable string representation of this instance."""
    # Suppressing the deprecation warning can be removed when UNSPECIFIED
    # is removed
    with warnings.catch_warnings():
        warnings.filterwarnings("ignore", category=DeprecationWarning)
        match self.code_type:
            case 0 | EnergyMarketCodeType.UNSPECIFIED:
                code_type = "type=<invalid:0>"
            case EnergyMarketCodeType() as enum_code:
                code_type = enum_code.name
            case int() as int_code:
                code_type = f"type={int_code}"
            case unexpected:
                assert_never(unexpected)
    code = self.code or f"<invalid:{self.code!r}>"
    return f"{code}[{code_type}]"

frequenz.client.common.grid.InvalidDeliveryAreaError ¤

Bases: InvalidAttributeError

Raised when a semantic accessor sees an invalid delivery area.

The offending InvalidDeliveryArea instance is available as the delivery_area attribute so callers can inspect the raw wire data.

This is also a ValueError for convenience.

Source code in src/frequenz/client/common/grid/_delivery_area.py 
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
class InvalidDeliveryAreaError(InvalidAttributeError):
    """Raised when a semantic accessor sees an invalid delivery area.

    The offending [`InvalidDeliveryArea`][..InvalidDeliveryArea] instance
    is available as the `delivery_area` attribute so callers can inspect
    the raw wire data.

    This is also a [`ValueError`][] for convenience.
    """

    def __init__(
        self,
        instance: object,
        attr_name: str,
        delivery_area: InvalidDeliveryArea,
        message: str | None = None,
    ) -> None:
        """Initialize this error.

        Args:
            instance: The instance that was being accessed when this error was raised.
            attr_name: The name of the attribute that was being accessed when this
                error was raised.
            delivery_area: The invalid delivery area instance.
            message: A custom error message. If `None`, a default message
                mentioning the invalid delivery area is used.
        """
        self.delivery_area: InvalidDeliveryArea = delivery_area
        """The invalid delivery area instance that caused this error."""

        message = (
            f"invalid delivery area {delivery_area} for attribute {attr_name!r} in {instance}"
            if message is None
            else message
        )
        super().__init__(instance, attr_name, message)
Attributes¤
attr_name instance-attribute ¤
attr_name: str = attr_name

The name of the attribute that had an invalid value.

delivery_area instance-attribute ¤
delivery_area: InvalidDeliveryArea = delivery_area

The invalid delivery area instance that caused this error.

instance instance-attribute ¤
instance: object = instance

The object instance that had an invalid value.

Methods:¤
__init__ ¤
__init__(
    instance: object,
    attr_name: str,
    delivery_area: InvalidDeliveryArea,
    message: str | None = None,
) -> None

Initialize this error.

PARAMETER DESCRIPTION
instance

The instance that was being accessed when this error was raised.

TYPE: object

attr_name

The name of the attribute that was being accessed when this error was raised.

TYPE: str

delivery_area

The invalid delivery area instance.

TYPE: InvalidDeliveryArea

message

A custom error message. If None, a default message mentioning the invalid delivery area is used.

TYPE: str | None DEFAULT: None

Source code in src/frequenz/client/common/grid/_delivery_area.py 
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
def __init__(
    self,
    instance: object,
    attr_name: str,
    delivery_area: InvalidDeliveryArea,
    message: str | None = None,
) -> None:
    """Initialize this error.

    Args:
        instance: The instance that was being accessed when this error was raised.
        attr_name: The name of the attribute that was being accessed when this
            error was raised.
        delivery_area: The invalid delivery area instance.
        message: A custom error message. If `None`, a default message
            mentioning the invalid delivery area is used.
    """
    self.delivery_area: InvalidDeliveryArea = delivery_area
    """The invalid delivery area instance that caused this error."""

    message = (
        f"invalid delivery area {delivery_area} for attribute {attr_name!r} in {instance}"
        if message is None
        else message
    )
    super().__init__(instance, attr_name, message)