# 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
[docs]
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_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)
[docs]
@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)
)
[docs]
@classmethod
def parse(cls, s: str) -> UnitBase:
"""
Convert a string to a unit object.
"""
raise NotImplementedError(f"Can not 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)}"
)
