Skip to main content
`Ctrl`+`K`

# Source code for astropy.units.format.base

    # Licensed under a 3-clause BSD style license - see LICENSE.rst

    import warnings
    from collections.abc import Iterable
    from typing import ClassVar, Literal, assert_never

    import numpy as np

    from ply.lex import LexToken
    from astropy.units.core import (
        CompositeUnit,
        NamedUnit,
        Unit,
        UnitBase,
        get_current_unit_registry,
    )
    from astropy.units.enums import DeprecatedUnitAction
    from astropy.units.errors import UnitsError, UnitsWarning
    from astropy.units.typing import UnitPower, UnitScale
    from astropy.units.utils import maybe_simple_fraction
    from astropy.utils.misc import did_you_mean

    class Base:
        """
        The abstract base class of all unit formats.
        """

        registry: ClassVar[dict[str, type["Base"]]] = {}
        _space: ClassVar[str] = " "
        _scale_unit_separator: ClassVar[str] = " "
        _times: ClassVar[str] = "*"
        name: ClassVar[str]  # Set by __init_subclass__ by the latest

        def __new__(cls, *args, **kwargs):
            # This __new__ is to make it clear that there is no reason to
            # instantiate a Formatter--if you try to you'll just get back the
            # class
            return cls

        def __init_subclass__(cls, **kwargs):
            # Keep a registry of all formats.  Key by the class name unless a name
            # is explicitly set (i.e., one *not* inherited from a superclass).
            if "name" not in cls.__dict__:
                cls.name = cls.__name__.lower()

            Base.registry[cls.name] = cls
            super().__init_subclass__(**kwargs)

        @classmethod
        def format_exponential_notation(
            cls, val: UnitScale | np.number, format_spec: str = ".8g"
        ) -> str:
            """
            Formats a value in exponential notation.

            Parameters
            ----------
            val : number
                The value to be formatted

            format_spec : str, optional
                Format used to split up mantissa and exponent

            Returns
            -------
            str
                The value in exponential notation in a this class's format.
            """
            x = format(val, format_spec).split("e")
            if len(x) != 2:
                return cls._format_mantissa(x[0])  # no exponent
            ex = x[1].lstrip("0+")
            if not ex:
                return cls._format_mantissa(x[0])  # exponent was zero
            if ex.startswith("-"):
                ex = "-" + ex[1:].lstrip("0")
            ex = f"10{cls._format_superscript(ex)}"
            m = cls._format_mantissa("" if x[0].rstrip("0") == "1." else x[0])
            return f"{m}{cls._times}{ex}" if m else ex

        @classmethod
        def _format_mantissa(cls, m: str) -> str:
            return m

        @classmethod
        def _format_superscript(cls, number: str) -> str:
            return f"({number})" if "/" in number or "." in number else number

        @classmethod
        def _format_unit_power(cls, unit: NamedUnit, power: UnitPower = 1) -> str:
            """Format the unit for this format class raised to the given power.

            This is overridden in Latex where the name of the unit can depend on the power
            (e.g., for degrees).
            """
            name = unit._get_format_name(cls.name)
            return name if power == 1 else name + cls._format_power(power)

        @classmethod
        def _format_power(cls, power: UnitPower) -> str:
            # If the denominator of `power` is a power of 2 then `power` is stored
            # as a `float` (see `units.utils.sanitize_power()`), but we still want
            # to display it as a fraction.
            return cls._format_superscript(
                str(maybe_simple_fraction(power) if isinstance(power, float) else power)
            )

        @classmethod
        def _format_unit_list(cls, units: Iterable[tuple[NamedUnit, UnitPower]]) -> str:
            return cls._space.join(
                cls._format_unit_power(base_, power) for base_, power in units
            )

        @classmethod
        def _format_inline_fraction(
            cls, scale: str, numerator: str, denominator: str
        ) -> str:
            if cls._space in denominator:
                denominator = f"({denominator})"
            if scale and numerator == "1":
                return f"{scale}/ {denominator}"
            return f"{scale}{numerator} / {denominator}"

        @classmethod
        def _format_multiline_fraction(
            cls, scale: str, numerator: str, denominator: str
        ) -> str:
            # By default, we just warn that we do not have a multiline format.
            warnings.warn(
                f"{cls.name!r} format does not support multiline "
                "fractions; using inline instead.",
                UnitsWarning,
            )
            return cls._format_inline_fraction(scale, numerator, denominator)

        @classmethod
        def to_string(
            cls,
            unit: UnitBase,
            *,
            deprecations: DeprecatedUnitAction = DeprecatedUnitAction.WARN,
            fraction: bool | Literal["inline", "multiline"] = True,
        ) -> str:
            """Convert a unit to its string representation.

            Implementation for `~astropy.units.UnitBase.to_string`.

            Parameters
            ----------
            unit : |Unit|
                The unit to convert.
            deprecations : {"warn", "silent", "raise", "convert"}, optional, keyword-only
                Whether deprecated units should emit a warning, be handled
                silently or raise an error. The "convert" option replaces
                the deprecated unit if possible and emits a warning otherwise.
            fraction : {False|True|'inline'|'multiline'}, optional
                Options are as follows:

                - `False` : display unit bases with negative powers as they are
                  (e.g., ``km s-1``);
                - 'inline' or `True` : use a single-line fraction (e.g., ``km / s``);
                - 'multiline' : use a multiline fraction if possible (available for
                  the ``latex``, ``console`` and ``unicode`` formats; e.g.,
                  ``$\\mathrm{\\frac{km}{s}}$``). If not possible, use 'inline'.

            Raises
            ------
            ValueError
                If ``fraction`` is not recognized.
            """
            # First the scale.  Normally unity, in which case we omit
            # it, but non-unity scale can happen, e.g., in decompositions
            # like u.Ry.decompose(), which gives "2.17987e-18 kg m2 / s2".
            s = "" if unit.scale == 1.0 else cls.format_exponential_notation(unit.scale)

            # dimensionless does not have any bases, but can have a scale;
            # e.g., u.percent.decompose() gives "0.01".
            if not unit.bases:
                return s

            if s:
                s += cls._scale_unit_separator
            # Unit powers are monotonically decreasing
            if not fraction or unit.powers[-1] > 0:
                return s + cls._format_unit_list(zip(unit.bases, unit.powers, strict=True))

            if fraction is True or fraction == "inline":
                formatter = cls._format_inline_fraction
            elif fraction == "multiline":
                formatter = cls._format_multiline_fraction
            else:
                raise ValueError(
                    "fraction can only be False, 'inline', or 'multiline', "
                    f"not {fraction!r}."
                )

            positive = []
            negative = []
            for base, power in zip(unit.bases, unit.powers, strict=True):
                if power > 0:
                    positive.append((base, power))
                else:
                    negative.append((base, -power))
            return formatter(
                s, cls._format_unit_list(positive) or "1", cls._format_unit_list(negative)
            )

        @classmethod
        def parse(cls, s: str) -> UnitBase:
            """
            Convert a string to a unit object.
            """
            raise NotImplementedError(f"Cannot parse with {cls.__name__} format")

    class _ParsingFormatMixin:
        """Provides private methods used in the formats that parse units."""

        _deprecated_units: ClassVar[frozenset[str]] = frozenset()

        @classmethod
        def _do_parse(cls, s: str, debug: bool = False) -> UnitBase:
            try:
                return cls._parser.parse(s, lexer=cls._lexer, debug=debug)
            except ValueError as e:
                if str(e):
                    raise
                else:
                    raise ValueError(f"Syntax error parsing unit '{s}'")

        @classmethod
        def _get_unit(cls, t: LexToken) -> UnitBase:
            try:
                return cls._validate_unit(t.value)
            except KeyError:
                registry = get_current_unit_registry()
                if t.value in registry.aliases:
                    return registry.aliases[t.value]

                raise ValueError(
                    f"At col {t.lexpos}, {cls._invalid_unit_error_message(t.value)}"
                ) from None

        @classmethod
        def _fix_deprecated(cls, x: str) -> list[str]:
            return [x + " (deprecated)" if x in cls._deprecated_units else x]

        @classmethod
        def _did_you_mean_units(cls, unit: str) -> str:
            """
            A wrapper around `astropy.utils.misc.did_you_mean` that deals with
            the display of deprecated units.

            Parameters
            ----------
            unit : str
                The invalid unit string

            Returns
            -------
            msg : str
                A message with alternatives, or the empty string.
            """
            return did_you_mean(unit, cls._units, fix=cls._fix_deprecated)

        @classmethod
        def _validate_unit(
            cls, s: str, deprecations: DeprecatedUnitAction = DeprecatedUnitAction.WARN
        ) -> UnitBase:
            if s in cls._deprecated_units:
                alternative = (
                    unit.represents if isinstance(unit := cls._units[s], Unit) else None
                )
                msg = f"The unit {s!r} has been deprecated in the {cls.__name__} standard."
                if alternative:
                    msg += f" Suggested: {cls.to_string(alternative)}."

                match DeprecatedUnitAction(deprecations):
                    case DeprecatedUnitAction.CONVERT:
                        if alternative:
                            return alternative
                        warnings.warn(
                            msg + " It cannot be automatically converted.", UnitsWarning
                        )
                    case DeprecatedUnitAction.WARN:
                        warnings.warn(msg, UnitsWarning)
                    case DeprecatedUnitAction.RAISE:
                        raise UnitsError(msg)
                    case DeprecatedUnitAction.SILENT:
                        pass
                    case _:
                        assert_never(deprecations)

            return cls._units[s]

        @classmethod
        def _invalid_unit_error_message(cls, unit: str) -> str:
            return (
                f"Unit '{unit}' not supported by the {cls.__name__} standard. "
                + cls._did_you_mean_units(unit)
            )

        @classmethod
        def _decompose_to_known_units(
            cls,
            unit: CompositeUnit | NamedUnit,
            deprecations: DeprecatedUnitAction = DeprecatedUnitAction.WARN,
        ) -> UnitBase:
            """
            Partially decomposes a unit so it is only composed of units that
            are "known" to a given format.
            """
            if isinstance(unit, CompositeUnit):
                return CompositeUnit(
                    unit.scale,
                    [
                        cls._decompose_to_known_units(base, deprecations)
                        for base in unit.bases
                    ],
                    unit.powers,
                    _error_check=False,
                )
            if isinstance(unit, NamedUnit):
                name = unit._get_format_name(cls.name)
                try:
                    return cls._validate_unit(name, deprecations=deprecations)
                except KeyError:
                    if isinstance(unit, Unit):
                        return cls._decompose_to_known_units(unit._represents, deprecations)
                    raise ValueError(cls._invalid_unit_error_message(name)) from None
            raise TypeError(
                f"unit argument must be a 'NamedUnit' or 'CompositeUnit', not {type(unit)}"
            )