Index

frequenz.client.common.types

Common types.

Classes

frequenz.client.common.types.InvalidCountryCode dataclass

A country code that fails the invariant of exactly 2 characters.

Wraps a raw wire country code that is set but not exactly 2 characters long.

Source code in src/frequenz/client/common/types/_location.py

@dataclass(frozen=True, kw_only=True)
class InvalidCountryCode:
    """A country code that fails the invariant of exactly 2 characters.

    Wraps a raw wire country code that is set but not exactly 2 characters
    long.
    """

    value: str
    """The raw invalid country code."""

    def __str__(self) -> str:
        """Return a compact representation flagging this as an invalid value."""
        return f"<invalid:{self.value!r}>"

Attributes

value instance-attribute

value: str

The raw invalid country code.

Methods:

__str__

__str__() -> str

Return a compact representation flagging this as an invalid value.

Source code in src/frequenz/client/common/types/_location.py

def __str__(self) -> str:
    """Return a compact representation flagging this as an invalid value."""
    return f"<invalid:{self.value!r}>"

frequenz.client.common.types.InvalidCountryCodeError

Bases: InvalidAttributeError

Raised when a semantic accessor sees a country code of length other than 2.

A well-formed country code is an ISO 3166-1 Alpha-2 string, so it must be exactly 2 characters long. The raw string is available as value.

This is also a ValueError for convenience.

Source code in src/frequenz/client/common/types/_location.py

class InvalidCountryCodeError(InvalidAttributeError):
    """Raised when a semantic accessor sees a country code of length other than 2.

    A well-formed country code is an ISO 3166-1 Alpha-2 string, so it must be
    exactly 2 characters long. The raw string is available as `value`.

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

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

        Args:
            instance: The object instance that had the invalid country code.
            attr_name: The name of the attribute that had the invalid country code.
            value: The invalid country code string.
            message: A custom error message. If `None`, a default message
                mentioning the invalid value is used.
        """
        self.value: str = value
        """The invalid country code string."""

        super().__init__(
            instance,
            attr_name,
            (
                message
                if message is not None
                else f"invalid country code {value!r} for attribute {attr_name!r} in "
                f"{instance}; must be exactly 2 characters"
            ),
        )

Attributes

attr_name instance-attribute

attr_name: str = attr_name

The name of the attribute that had an invalid value.

instance instance-attribute

instance: object = instance

The object instance that had an invalid value.

value instance-attribute

value: str = value

The invalid country code string.

Methods:

__init__

__init__(
    instance: object,
    attr_name: str,
    value: str,
    message: str | None = None,
) -> None

Initialize this error.

PARAMETER	DESCRIPTION
instance	The object instance that had the invalid country code. TYPE: object
attr_name	The name of the attribute that had the invalid country code. TYPE: str
value	The invalid country code string. TYPE: str
message	A custom error message. If None, a default message mentioning the invalid value is used. TYPE: str | None DEFAULT: None

Source code in src/frequenz/client/common/types/_location.py

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

    Args:
        instance: The object instance that had the invalid country code.
        attr_name: The name of the attribute that had the invalid country code.
        value: The invalid country code string.
        message: A custom error message. If `None`, a default message
            mentioning the invalid value is used.
    """
    self.value: str = value
    """The invalid country code string."""

    super().__init__(
        instance,
        attr_name,
        (
            message
            if message is not None
            else f"invalid country code {value!r} for attribute {attr_name!r} in "
            f"{instance}; must be exactly 2 characters"
        ),
    )

frequenz.client.common.types.InvalidLatitude dataclass

A latitude value that fails the invariant of [-90, 90].

Wraps a raw wire latitude that fell outside the well-formed range.

Source code in src/frequenz/client/common/types/_location.py

@dataclass(frozen=True, kw_only=True)
class InvalidLatitude:
    """A latitude value that fails the invariant of `[-90, 90]`.

    Wraps a raw wire latitude that fell outside the well-formed range.
    """

    value: FloatInt
    """The raw out-of-range latitude value."""

    def __str__(self) -> str:
        """Return a compact representation flagging this as an invalid value."""
        return f"<invalid:{self.value:.2f}>"

Attributes

value instance-attribute

value: FloatInt

The raw out-of-range latitude value.

Methods:

__str__

__str__() -> str

Return a compact representation flagging this as an invalid value.

Source code in src/frequenz/client/common/types/_location.py

def __str__(self) -> str:
    """Return a compact representation flagging this as an invalid value."""
    return f"<invalid:{self.value:.2f}>"

frequenz.client.common.types.InvalidLatitudeError

Bases: InvalidAttributeError

Raised when a semantic accessor sees a latitude outside [-90, 90].

A well-formed latitude lies in the closed interval [-90, 90]. The raw out-of-range number is available as value.

This is also a ValueError for convenience.

Source code in src/frequenz/client/common/types/_location.py

class InvalidLatitudeError(InvalidAttributeError):
    """Raised when a semantic accessor sees a latitude outside `[-90, 90]`.

    A well-formed latitude lies in the closed interval `[-90, 90]`. The raw
    out-of-range number is available as `value`.

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

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

        Args:
            instance: The object instance that had the invalid latitude.
            attr_name: The name of the attribute that had the invalid latitude.
            value: The out-of-range latitude value.
            message: A custom error message. If `None`, a default message
                mentioning the invalid value is used.
        """
        self.value: FloatInt = value
        """The out-of-range latitude value."""

        super().__init__(
            instance,
            attr_name,
            (
                message
                if message is not None
                else f"invalid latitude {value} for attribute {attr_name!r} in "
                f"{instance}; must be in [-90, 90]"
            ),
        )

Attributes

attr_name instance-attribute

attr_name: str = attr_name

The name of the attribute that had an invalid value.

instance instance-attribute

instance: object = instance

The object instance that had an invalid value.

value instance-attribute

value: FloatInt = value

The out-of-range latitude value.

Methods:

__init__

__init__(
    instance: object,
    attr_name: str,
    value: FloatInt,
    message: str | None = None,
) -> None

Initialize this error.

PARAMETER	DESCRIPTION
instance	The object instance that had the invalid latitude. TYPE: object
attr_name	The name of the attribute that had the invalid latitude. TYPE: str
value	The out-of-range latitude value. TYPE: FloatInt
message	A custom error message. If None, a default message mentioning the invalid value is used. TYPE: str | None DEFAULT: None

Source code in src/frequenz/client/common/types/_location.py

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

    Args:
        instance: The object instance that had the invalid latitude.
        attr_name: The name of the attribute that had the invalid latitude.
        value: The out-of-range latitude value.
        message: A custom error message. If `None`, a default message
            mentioning the invalid value is used.
    """
    self.value: FloatInt = value
    """The out-of-range latitude value."""

    super().__init__(
        instance,
        attr_name,
        (
            message
            if message is not None
            else f"invalid latitude {value} for attribute {attr_name!r} in "
            f"{instance}; must be in [-90, 90]"
        ),
    )

frequenz.client.common.types.InvalidLongitude dataclass

A longitude value that fails the invariant of [-180, 180].

Wraps a raw wire longitude that fell outside the well-formed range.

Source code in src/frequenz/client/common/types/_location.py

@dataclass(frozen=True, kw_only=True)
class InvalidLongitude:
    """A longitude value that fails the invariant of `[-180, 180]`.

    Wraps a raw wire longitude that fell outside the well-formed range.
    """

    value: FloatInt
    """The raw out-of-range longitude value."""

    def __str__(self) -> str:
        """Return a compact representation flagging this as an invalid value."""
        return f"<invalid:{self.value:.2f}>"

Attributes

value instance-attribute

value: FloatInt

The raw out-of-range longitude value.

Methods:

__str__

__str__() -> str

Return a compact representation flagging this as an invalid value.

Source code in src/frequenz/client/common/types/_location.py

def __str__(self) -> str:
    """Return a compact representation flagging this as an invalid value."""
    return f"<invalid:{self.value:.2f}>"

frequenz.client.common.types.InvalidLongitudeError

Bases: InvalidAttributeError

Raised when a semantic accessor sees a longitude outside [-180, 180].

A well-formed longitude lies in the closed interval [-180, 180]. The raw out-of-range number is available as value.

This is also a ValueError for convenience.

Source code in src/frequenz/client/common/types/_location.py

class InvalidLongitudeError(InvalidAttributeError):
    """Raised when a semantic accessor sees a longitude outside `[-180, 180]`.

    A well-formed longitude lies in the closed interval `[-180, 180]`. The raw
    out-of-range number is available as `value`.

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

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

        Args:
            instance: The object instance that had the invalid longitude.
            attr_name: The name of the attribute that had the invalid longitude.
            value: The out-of-range longitude value.
            message: A custom error message. If `None`, a default message
                mentioning the invalid value is used.
        """
        self.value: FloatInt = value
        """The out-of-range longitude value."""

        super().__init__(
            instance,
            attr_name,
            (
                message
                if message is not None
                else f"invalid longitude {value} for attribute {attr_name!r} in "
                f"{instance}; must be in [-180, 180]"
            ),
        )

Attributes

attr_name instance-attribute

attr_name: str = attr_name

The name of the attribute that had an invalid value.

instance instance-attribute

instance: object = instance

The object instance that had an invalid value.

value instance-attribute

value: FloatInt = value

The out-of-range longitude value.

Methods:

__init__

__init__(
    instance: object,
    attr_name: str,
    value: FloatInt,
    message: str | None = None,
) -> None

Initialize this error.

PARAMETER	DESCRIPTION
instance	The object instance that had the invalid longitude. TYPE: object
attr_name	The name of the attribute that had the invalid longitude. TYPE: str
value	The out-of-range longitude value. TYPE: FloatInt
message	A custom error message. If None, a default message mentioning the invalid value is used. TYPE: str | None DEFAULT: None

Source code in src/frequenz/client/common/types/_location.py

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

    Args:
        instance: The object instance that had the invalid longitude.
        attr_name: The name of the attribute that had the invalid longitude.
        value: The out-of-range longitude value.
        message: A custom error message. If `None`, a default message
            mentioning the invalid value is used.
    """
    self.value: FloatInt = value
    """The out-of-range longitude value."""

    super().__init__(
        instance,
        attr_name,
        (
            message
            if message is not None
            else f"invalid longitude {value} for attribute {attr_name!r} in "
            f"{instance}; must be in [-180, 180]"
        ),
    )

frequenz.client.common.types.Location dataclass

A location's information.

Instances carry the raw wire values of a protobuf Location message. Invalid or absent field values are expressed in the type system: latitude and longitude may be InvalidLatitude or InvalidLongitude; country_code may be InvalidCountryCode or None when the field was unset on the wire. Users can pattern-match on the fields directly, or call get_latitude(), get_longitude(), get_country_code() and get_country_code_or_none() to obtain a validated value or a clear InvalidAttributeError subclass.

Constructing a Location with a plain number or str that violates its invariant raises ValueError; use the corresponding Invalid* type to represent an out-of-invariant wire value.

Source code in src/frequenz/client/common/types/_location.py

@dataclass(frozen=True, kw_only=True)
class Location:
    """A location's information.

    Instances carry the raw wire values of a protobuf `Location` message.
    Invalid or absent field values are expressed in the type system:
    [`latitude`][.latitude] and [`longitude`][.longitude] may be
    [`InvalidLatitude`][..InvalidLatitude] or
    [`InvalidLongitude`][..InvalidLongitude];
    [`country_code`][.country_code] may be
    [`InvalidCountryCode`][..InvalidCountryCode] or `None` when the field
    was unset on the wire. Users can pattern-match on the fields directly,
    or call [`get_latitude()`][.get_latitude],
    [`get_longitude()`][.get_longitude],
    [`get_country_code()`][.get_country_code] and
    [`get_country_code_or_none()`][.get_country_code_or_none] to obtain a
    validated value or a clear
    [`InvalidAttributeError`][...InvalidAttributeError] subclass.

    Constructing a `Location` with a plain number or `str` that violates
    its invariant raises `ValueError`; use the corresponding `Invalid*`
    type to represent an out-of-invariant wire value.
    """

    latitude: FloatInt | InvalidLatitude
    """The latitude.

    A plain number when well-formed (in `[-90, 90]`); an
    [`InvalidLatitude`][...InvalidLatitude] wrapper when the wire delivered
    an out-of-range value.

    Tip:
        Use [`Location.get_latitude()`][...Location.get_latitude] to obtain
        a validated number or a clear error.
    """

    longitude: FloatInt | InvalidLongitude
    """The longitude.

    A plain number when well-formed (in `[-180, 180]`); an
    [`InvalidLongitude`][...InvalidLongitude] wrapper when the wire
    delivered an out-of-range value.

    Tip:
        Use [`Location.get_longitude()`][...Location.get_longitude] to obtain a
        validated number or a clear error.
    """

    country_code: str | InvalidCountryCode | None
    """The country code.

    A plain `str` (exactly 2 characters, ISO 3166-1 Alpha-2) when
    well-formed; an [`InvalidCountryCode`][...InvalidCountryCode] wrapper
    when the wire delivered a non-empty string of a different length;
    `None` when the field was unset on the wire (an empty string on the
    wire is normalized to `None` by the converter).

    Tip:
        Use [`Location.get_country_code()`][...Location.get_country_code] to
        obtain a validated `str` or a clear error.
    """

    def __post_init__(self) -> None:
        """Enforce that plain (unwrapped) fields respect their invariants.

        Raises:
            ValueError: If `latitude` is a plain number outside `[-90, 90]`;
                if `longitude` is a plain number outside `[-180, 180]`; or
                if `country_code` is a plain `str` not exactly 2 characters
                long. To represent an invalid wire value, wrap it in the
                corresponding `Invalid*` type.
        """
        if not isinstance(self.latitude, InvalidLatitude) and not (
            -90.0 <= self.latitude <= 90.0
        ):
            raise ValueError(
                f"latitude {self.latitude!r} is outside [-90, 90]; wrap in "
                "InvalidLatitude to represent an invalid wire value"
            )
        if not isinstance(self.longitude, InvalidLongitude) and not (
            -180.0 <= self.longitude <= 180.0
        ):
            raise ValueError(
                f"longitude {self.longitude!r} is outside [-180, 180]; wrap "
                "in InvalidLongitude to represent an invalid wire value"
            )
        if (
            self.country_code is not None
            and not isinstance(self.country_code, InvalidCountryCode)
            and len(self.country_code) != 2
        ):
            raise ValueError(
                f"country_code {self.country_code!r} is not exactly 2 "
                "characters; wrap in InvalidCountryCode to represent an "
                "invalid wire value"
            )

    def get_latitude(self) -> FloatInt:
        """Return the latitude as a well-formed number in `[-90, 90]`.

        Returns:
            The latitude, when it is a well-formed number.

        Raises:
            InvalidLatitudeError: If [`latitude`][..latitude] is an
                [`InvalidLatitude`][...InvalidLatitude]. The raw value is
                available on the exception's `value` attribute.
        """
        match self.latitude:
            case InvalidLatitude(value=raw):
                raise InvalidLatitudeError(self, "latitude", raw)
            case float() | int() as valid:
                return valid
            case unknown:
                assert_never(unknown)

    def get_longitude(self) -> FloatInt:
        """Return the longitude as a well-formed number in `[-180, 180]`.

        Returns:
            The longitude, when it is a well-formed number.

        Raises:
            InvalidLongitudeError: If [`longitude`][..longitude] is an
                [`InvalidLongitude`][...InvalidLongitude]. The raw value is
                available on the exception's `value` attribute.
        """
        match self.longitude:
            case InvalidLongitude(value=raw):
                raise InvalidLongitudeError(self, "longitude", raw)
            case float() | int() as valid:
                return valid
            case unknown:
                assert_never(unknown)

    def get_country_code(self) -> str:
        """Return the country code as a well-formed 2-character `str`.

        Returns:
            The country code, when it is a well-formed `str`.

        Raises:
            MissingFieldError: If [`country_code`][..country_code] is
                `None` (the field was not set on the wire).
            InvalidCountryCodeError: If [`country_code`][..country_code] is
                an [`InvalidCountryCode`][...InvalidCountryCode]. The raw
                value is available on the exception's `value` attribute.
        """
        match self.country_code:
            case None:
                raise MissingFieldError(self, "country_code")
            case InvalidCountryCode(value=raw):
                raise InvalidCountryCodeError(self, "country_code", raw)
            case str() as valid:
                return valid
            case unknown:
                assert_never(unknown)

    def get_country_code_or_none(
        self,
    ) -> str | None:
        """Return the country code as a well-formed `str`, or `None` if unset.

        Same as [`get_country_code()`][..get_country_code] but returns
        `None` instead of raising `MissingFieldError` when
        [`country_code`][..country_code] is `None` (the field was not set
        on the wire). Invalid country codes still raise
        `InvalidCountryCodeError`.

        Returns:
            The country code (when well-formed), or `None` (when the field
                was not set on the wire).

        Raises:
            InvalidCountryCodeError: If [`country_code`][..country_code] is
                an [`InvalidCountryCode`][...InvalidCountryCode]. The raw
                value is available on the exception's `value` attribute.
        """
        match self.country_code:
            case None:
                return None
            case InvalidCountryCode(value=raw):
                raise InvalidCountryCodeError(self, "country_code", raw)
            case str() as valid:
                return valid
            case unknown:
                assert_never(unknown)

    def __str__(self) -> str:
        """Return the short string representation of this instance."""
        country = self.country_code or ""
        lat = (
            str(self.latitude)
            if isinstance(self.latitude, InvalidLatitude)
            else f"{self.latitude:.2f}"
        )
        lon = (
            str(self.longitude)
            if isinstance(self.longitude, InvalidLongitude)
            else f"{self.longitude:.2f}"
        )
        return f"{country}({lat},{lon})"

Attributes

country_code instance-attribute

country_code: str | InvalidCountryCode | None

The country code.

A plain str (exactly 2 characters, ISO 3166-1 Alpha-2) when well-formed; an InvalidCountryCode wrapper when the wire delivered a non-empty string of a different length; None when the field was unset on the wire (an empty string on the wire is normalized to None by the converter).

Tip

Use Location.get_country_code() to obtain a validated str or a clear error.

latitude instance-attribute

latitude: FloatInt | InvalidLatitude

The latitude.

A plain number when well-formed (in [-90, 90]); an InvalidLatitude wrapper when the wire delivered an out-of-range value.

Tip

Use Location.get_latitude() to obtain a validated number or a clear error.

longitude instance-attribute

longitude: FloatInt | InvalidLongitude

The longitude.

A plain number when well-formed (in [-180, 180]); an InvalidLongitude wrapper when the wire delivered an out-of-range value.

Tip

Use Location.get_longitude() to obtain a validated number or a clear error.

Methods:

__post_init__

__post_init__() -> None

Enforce that plain (unwrapped) fields respect their invariants.

RAISES	DESCRIPTION
ValueError	If latitude is a plain number outside [-90, 90]; if longitude is a plain number outside [-180, 180]; or if country_code is a plain str not exactly 2 characters long. To represent an invalid wire value, wrap it in the corresponding Invalid* type.

Source code in src/frequenz/client/common/types/_location.py

def __post_init__(self) -> None:
    """Enforce that plain (unwrapped) fields respect their invariants.

    Raises:
        ValueError: If `latitude` is a plain number outside `[-90, 90]`;
            if `longitude` is a plain number outside `[-180, 180]`; or
            if `country_code` is a plain `str` not exactly 2 characters
            long. To represent an invalid wire value, wrap it in the
            corresponding `Invalid*` type.
    """
    if not isinstance(self.latitude, InvalidLatitude) and not (
        -90.0 <= self.latitude <= 90.0
    ):
        raise ValueError(
            f"latitude {self.latitude!r} is outside [-90, 90]; wrap in "
            "InvalidLatitude to represent an invalid wire value"
        )
    if not isinstance(self.longitude, InvalidLongitude) and not (
        -180.0 <= self.longitude <= 180.0
    ):
        raise ValueError(
            f"longitude {self.longitude!r} is outside [-180, 180]; wrap "
            "in InvalidLongitude to represent an invalid wire value"
        )
    if (
        self.country_code is not None
        and not isinstance(self.country_code, InvalidCountryCode)
        and len(self.country_code) != 2
    ):
        raise ValueError(
            f"country_code {self.country_code!r} is not exactly 2 "
            "characters; wrap in InvalidCountryCode to represent an "
            "invalid wire value"
        )

__str__

__str__() -> str

Return the short string representation of this instance.

Source code in src/frequenz/client/common/types/_location.py

def __str__(self) -> str:
    """Return the short string representation of this instance."""
    country = self.country_code or ""
    lat = (
        str(self.latitude)
        if isinstance(self.latitude, InvalidLatitude)
        else f"{self.latitude:.2f}"
    )
    lon = (
        str(self.longitude)
        if isinstance(self.longitude, InvalidLongitude)
        else f"{self.longitude:.2f}"
    )
    return f"{country}({lat},{lon})"

get_country_code

get_country_code() -> str

Return the country code as a well-formed 2-character str.

RETURNS	DESCRIPTION
str	The country code, when it is a well-formed str.

RAISES	DESCRIPTION
MissingFieldError	If country_code is None (the field was not set on the wire).
InvalidCountryCodeError	If country_code is an InvalidCountryCode. The raw value is available on the exception's value attribute.

Source code in src/frequenz/client/common/types/_location.py

def get_country_code(self) -> str:
    """Return the country code as a well-formed 2-character `str`.

    Returns:
        The country code, when it is a well-formed `str`.

    Raises:
        MissingFieldError: If [`country_code`][..country_code] is
            `None` (the field was not set on the wire).
        InvalidCountryCodeError: If [`country_code`][..country_code] is
            an [`InvalidCountryCode`][...InvalidCountryCode]. The raw
            value is available on the exception's `value` attribute.
    """
    match self.country_code:
        case None:
            raise MissingFieldError(self, "country_code")
        case InvalidCountryCode(value=raw):
            raise InvalidCountryCodeError(self, "country_code", raw)
        case str() as valid:
            return valid
        case unknown:
            assert_never(unknown)

get_country_code_or_none

get_country_code_or_none() -> str | None

Return the country code as a well-formed str, or None if unset.

Same as get_country_code() but returns None instead of raising MissingFieldError when country_code is None (the field was not set on the wire). Invalid country codes still raise InvalidCountryCodeError.

RETURNS	DESCRIPTION
str | None	The country code (when well-formed), or None (when the field was not set on the wire).

RAISES	DESCRIPTION
InvalidCountryCodeError	If country_code is an InvalidCountryCode. The raw value is available on the exception's value attribute.

Source code in src/frequenz/client/common/types/_location.py

def get_country_code_or_none(
    self,
) -> str | None:
    """Return the country code as a well-formed `str`, or `None` if unset.

    Same as [`get_country_code()`][..get_country_code] but returns
    `None` instead of raising `MissingFieldError` when
    [`country_code`][..country_code] is `None` (the field was not set
    on the wire). Invalid country codes still raise
    `InvalidCountryCodeError`.

    Returns:
        The country code (when well-formed), or `None` (when the field
            was not set on the wire).

    Raises:
        InvalidCountryCodeError: If [`country_code`][..country_code] is
            an [`InvalidCountryCode`][...InvalidCountryCode]. The raw
            value is available on the exception's `value` attribute.
    """
    match self.country_code:
        case None:
            return None
        case InvalidCountryCode(value=raw):
            raise InvalidCountryCodeError(self, "country_code", raw)
        case str() as valid:
            return valid
        case unknown:
            assert_never(unknown)

get_latitude

get_latitude() -> FloatInt

Return the latitude as a well-formed number in [-90, 90].

RETURNS	DESCRIPTION
FloatInt	The latitude, when it is a well-formed number.

RAISES	DESCRIPTION
InvalidLatitudeError	If latitude is an InvalidLatitude. The raw value is available on the exception's value attribute.

Source code in src/frequenz/client/common/types/_location.py

def get_latitude(self) -> FloatInt:
    """Return the latitude as a well-formed number in `[-90, 90]`.

    Returns:
        The latitude, when it is a well-formed number.

    Raises:
        InvalidLatitudeError: If [`latitude`][..latitude] is an
            [`InvalidLatitude`][...InvalidLatitude]. The raw value is
            available on the exception's `value` attribute.
    """
    match self.latitude:
        case InvalidLatitude(value=raw):
            raise InvalidLatitudeError(self, "latitude", raw)
        case float() | int() as valid:
            return valid
        case unknown:
            assert_never(unknown)

get_longitude

get_longitude() -> FloatInt

Return the longitude as a well-formed number in [-180, 180].

RETURNS	DESCRIPTION
FloatInt	The longitude, when it is a well-formed number.

RAISES	DESCRIPTION
InvalidLongitudeError	If longitude is an InvalidLongitude. The raw value is available on the exception's value attribute.

Source code in src/frequenz/client/common/types/_location.py

def get_longitude(self) -> FloatInt:
    """Return the longitude as a well-formed number in `[-180, 180]`.

    Returns:
        The longitude, when it is a well-formed number.

    Raises:
        InvalidLongitudeError: If [`longitude`][..longitude] is an
            [`InvalidLongitude`][...InvalidLongitude]. The raw value is
            available on the exception's `value` attribute.
    """
    match self.longitude:
        case InvalidLongitude(value=raw):
            raise InvalidLongitudeError(self, "longitude", raw)
        case float() | int() as valid:
            return valid
        case unknown:
            assert_never(unknown)