Skip to content

yggdrasil.enums.units

units

Physical-unit enums for cross-source curated views.

Curated and dash_* tables routinely need to carry both the source-emitted value (in whatever unit the upstream feed publishes — MWh, MW, BTU, mi …) and a standardised equivalent in a uniform canonical unit so downstream BI / ML can group, sum, and compare across vendors without re-parsing strings at the call site. :class:~yggdrasil.fxrate.FxRate already handles currency conversion; this module is the matching surface for physical quantities.

Each enum carries the (symbol, factor, offset) triple where the canonical member has factor=1 and offset=0. Conversion between any two members of the same family is::

canonical = value * src.factor + src.offset
target_value = (canonical - tgt.offset) / tgt.factor

Linear families (energy, power, mass, length, volume, pressure) ride through with offset=0; :class:TemperatureUnit is affine — °C → K is offset 273.15, °F → K is scaled+offset.

Public surface is uniform across every unit enum:

  • :meth:Unit.from_ — forgiving coercion (member / symbol / alias / case-insensitive variants);
  • :meth:Unit.is_valid — boolean probe;
  • :meth:Unit.convert(value, source, target) — scalar conversion;
  • :meth:Unit.to_canonical(value) / :meth:Unit.from_canonical(value) — single-unit instance helpers;
  • :attr:Unit.symbol — canonical short token ("MWh" / "kg" / "°C");
  • :attr:Unit.factor, :attr:Unit.offset — exposed so vectorised callers in :mod:yggdrasil.databricks.standardize can build per-row Polars / Spark expressions without re-deriving the math.

The canonical token per family is the SI base where one exists: joule (J) for energy, watt (W) for power, kilogram (kg) for mass, metre (m) for length, cubic metre (m³) for volume, kelvin (K) for temperature, pascal (Pa) for pressure.

Aliases live in a module-level <Family>._ALIASES dict assigned after the class body — Python's Enum metaclass would otherwise treat a dict-valued class-body attribute as an enum member.

Unit 

Unit(symbol: str, factor: float, offset: float = 0.0)

Mixin providing :meth:from_ / :meth:convert / scalar helpers.

Subclasses combine this with :class:Enum and declare members as (symbol, factor_to_canonical, offset_to_canonical) tuples (or (symbol, factor) — offset defaults to 0.0). The canonical member of each family has factor=1.0 and offset=0.0; conversion goes through that canonical pivot.

Extra spellings ("megawatthours" → MWH) live in a <Family>._ALIASES dict assigned outside the enum body — the enum metaclass would treat a class-body dict as a member.

from_ classmethod 

from_(value: Any, *, default: Any = ...) -> 'Unit'

Coerce value to a member of this unit family.

Accepts: a member (passed through), a known symbol ("MWh" / "°C" / "psi"), the enum member name ("KWH"), or any alias the per-family _ALIASES dict knows ("megawatthours" / "celsius" / "pound"). Lookup is case-insensitive.

Pass default to swallow unknown / unparseable input; without it, unknown strings raise :class:ValueError with a hint listing the valid symbols, and non-string non-member input raises :class:TypeError.

is_valid classmethod 

is_valid(value: Any) -> bool

True when :meth:from_ would resolve value.

convert classmethod 

convert(value: float, source: Any, target: Any) -> float

Convert value from source unit to target unit (scalar).

to_canonical 

to_canonical(value: float) -> float

Convert value in self's unit to the family's canonical unit.

from_canonical 

from_canonical(value: float) -> float

Convert value in the canonical unit to self's unit.

canonical classmethod 

canonical() -> 'Unit'

The family's canonical member (factor=1.0, offset=0.0).

factor_map classmethod 

factor_map() -> dict[str, float]

{symbol: factor} for every member + alias, for per-row maps.

offset_map classmethod 

offset_map() -> dict[str, float]

{symbol: offset} for every member + alias, for per-row maps.

EnergyUnit 

EnergyUnit(symbol: str, factor: float, offset: float = 0.0)

Bases: Unit, Enum

Energy unit (canonical = joule).

Members cover SI scale (J / kJ / MJ / GJ / TJ), the watt-hour family that dominates electricity-market ingestion (Wh / kWh / MWh / GWh / TWh), and the imperial / domestic units (BTU / cal / kcal / therm).

from_ classmethod 

from_(value: Any, *, default: Any = ...) -> 'Unit'

Coerce value to a member of this unit family.

Accepts: a member (passed through), a known symbol ("MWh" / "°C" / "psi"), the enum member name ("KWH"), or any alias the per-family _ALIASES dict knows ("megawatthours" / "celsius" / "pound"). Lookup is case-insensitive.

Pass default to swallow unknown / unparseable input; without it, unknown strings raise :class:ValueError with a hint listing the valid symbols, and non-string non-member input raises :class:TypeError.

is_valid classmethod 

is_valid(value: Any) -> bool

True when :meth:from_ would resolve value.

convert classmethod 

convert(value: float, source: Any, target: Any) -> float

Convert value from source unit to target unit (scalar).

to_canonical 

to_canonical(value: float) -> float

Convert value in self's unit to the family's canonical unit.

from_canonical 

from_canonical(value: float) -> float

Convert value in the canonical unit to self's unit.

canonical classmethod 

canonical() -> 'Unit'

The family's canonical member (factor=1.0, offset=0.0).

factor_map classmethod 

factor_map() -> dict[str, float]

{symbol: factor} for every member + alias, for per-row maps.

offset_map classmethod 

offset_map() -> dict[str, float]

{symbol: offset} for every member + alias, for per-row maps.

PowerUnit 

PowerUnit(symbol: str, factor: float, offset: float = 0.0)

Bases: Unit, Enum

Power unit (canonical = watt).

SI scale (W / kW / MW / GW / TW) plus mechanical horsepower. Energy-market feeds publish capacity in MW, transmission limits in GW, household-scale appliances in W — having one enum cover all of them is what keeps schema-per-source curated views from re-stringing the unit token at every read.

from_ classmethod 

from_(value: Any, *, default: Any = ...) -> 'Unit'

Coerce value to a member of this unit family.

Accepts: a member (passed through), a known symbol ("MWh" / "°C" / "psi"), the enum member name ("KWH"), or any alias the per-family _ALIASES dict knows ("megawatthours" / "celsius" / "pound"). Lookup is case-insensitive.

Pass default to swallow unknown / unparseable input; without it, unknown strings raise :class:ValueError with a hint listing the valid symbols, and non-string non-member input raises :class:TypeError.

is_valid classmethod 

is_valid(value: Any) -> bool

True when :meth:from_ would resolve value.

convert classmethod 

convert(value: float, source: Any, target: Any) -> float

Convert value from source unit to target unit (scalar).

to_canonical 

to_canonical(value: float) -> float

Convert value in self's unit to the family's canonical unit.

from_canonical 

from_canonical(value: float) -> float

Convert value in the canonical unit to self's unit.

canonical classmethod 

canonical() -> 'Unit'

The family's canonical member (factor=1.0, offset=0.0).

factor_map classmethod 

factor_map() -> dict[str, float]

{symbol: factor} for every member + alias, for per-row maps.

offset_map classmethod 

offset_map() -> dict[str, float]

{symbol: offset} for every member + alias, for per-row maps.

MassUnit 

MassUnit(symbol: str, factor: float, offset: float = 0.0)

Bases: Unit, Enum

Mass unit (canonical = kilogram).

SI scale (mg / g / kg / t / Mt) plus the imperial pair (lb / oz) commonly used in commodity feeds.

from_ classmethod 

from_(value: Any, *, default: Any = ...) -> 'Unit'

Coerce value to a member of this unit family.

Accepts: a member (passed through), a known symbol ("MWh" / "°C" / "psi"), the enum member name ("KWH"), or any alias the per-family _ALIASES dict knows ("megawatthours" / "celsius" / "pound"). Lookup is case-insensitive.

Pass default to swallow unknown / unparseable input; without it, unknown strings raise :class:ValueError with a hint listing the valid symbols, and non-string non-member input raises :class:TypeError.

is_valid classmethod 

is_valid(value: Any) -> bool

True when :meth:from_ would resolve value.

convert classmethod 

convert(value: float, source: Any, target: Any) -> float

Convert value from source unit to target unit (scalar).

to_canonical 

to_canonical(value: float) -> float

Convert value in self's unit to the family's canonical unit.

from_canonical 

from_canonical(value: float) -> float

Convert value in the canonical unit to self's unit.

canonical classmethod 

canonical() -> 'Unit'

The family's canonical member (factor=1.0, offset=0.0).

factor_map classmethod 

factor_map() -> dict[str, float]

{symbol: factor} for every member + alias, for per-row maps.

offset_map classmethod 

offset_map() -> dict[str, float]

{symbol: offset} for every member + alias, for per-row maps.

LengthUnit 

LengthUnit(symbol: str, factor: float, offset: float = 0.0)

Bases: Unit, Enum

Length unit (canonical = metre).

SI scale (mm / cm / m / km) plus the common imperial / aviation / maritime tokens (in / ft / yd / mi / nmi).

from_ classmethod 

from_(value: Any, *, default: Any = ...) -> 'Unit'

Coerce value to a member of this unit family.

Accepts: a member (passed through), a known symbol ("MWh" / "°C" / "psi"), the enum member name ("KWH"), or any alias the per-family _ALIASES dict knows ("megawatthours" / "celsius" / "pound"). Lookup is case-insensitive.

Pass default to swallow unknown / unparseable input; without it, unknown strings raise :class:ValueError with a hint listing the valid symbols, and non-string non-member input raises :class:TypeError.

is_valid classmethod 

is_valid(value: Any) -> bool

True when :meth:from_ would resolve value.

convert classmethod 

convert(value: float, source: Any, target: Any) -> float

Convert value from source unit to target unit (scalar).

to_canonical 

to_canonical(value: float) -> float

Convert value in self's unit to the family's canonical unit.

from_canonical 

from_canonical(value: float) -> float

Convert value in the canonical unit to self's unit.

canonical classmethod 

canonical() -> 'Unit'

The family's canonical member (factor=1.0, offset=0.0).

factor_map classmethod 

factor_map() -> dict[str, float]

{symbol: factor} for every member + alias, for per-row maps.

offset_map classmethod 

offset_map() -> dict[str, float]

{symbol: offset} for every member + alias, for per-row maps.

VolumeUnit 

VolumeUnit(symbol: str, factor: float, offset: float = 0.0)

Bases: Unit, Enum

Volume unit (canonical = cubic metre).

SI scale (mL / L / m³) plus the gallon variants and the oil barrel — commodity feeds split between US gallons, UK gallons, and the 42-gallon oil barrel, and a curated view that doesn't keep them straight ships wrong totals.

from_ classmethod 

from_(value: Any, *, default: Any = ...) -> 'Unit'

Coerce value to a member of this unit family.

Accepts: a member (passed through), a known symbol ("MWh" / "°C" / "psi"), the enum member name ("KWH"), or any alias the per-family _ALIASES dict knows ("megawatthours" / "celsius" / "pound"). Lookup is case-insensitive.

Pass default to swallow unknown / unparseable input; without it, unknown strings raise :class:ValueError with a hint listing the valid symbols, and non-string non-member input raises :class:TypeError.

is_valid classmethod 

is_valid(value: Any) -> bool

True when :meth:from_ would resolve value.

convert classmethod 

convert(value: float, source: Any, target: Any) -> float

Convert value from source unit to target unit (scalar).

to_canonical 

to_canonical(value: float) -> float

Convert value in self's unit to the family's canonical unit.

from_canonical 

from_canonical(value: float) -> float

Convert value in the canonical unit to self's unit.

canonical classmethod 

canonical() -> 'Unit'

The family's canonical member (factor=1.0, offset=0.0).

factor_map classmethod 

factor_map() -> dict[str, float]

{symbol: factor} for every member + alias, for per-row maps.

offset_map classmethod 

offset_map() -> dict[str, float]

{symbol: offset} for every member + alias, for per-row maps.

TemperatureUnit 

TemperatureUnit(symbol: str, factor: float, offset: float = 0.0)

Bases: Unit, Enum

Temperature unit (canonical = kelvin).

The one affine family — Celsius and Fahrenheit have non-zero offsets relative to kelvin, so the conversion is canonical = value * factor + offset (not pure scaling). Symbols use the standard degree glyphs (°C / °F) so the curated tables render legibly in BI tools; aliases cover the plain-ascii forms ("C" / "F" / "K").

from_ classmethod 

from_(value: Any, *, default: Any = ...) -> 'Unit'

Coerce value to a member of this unit family.

Accepts: a member (passed through), a known symbol ("MWh" / "°C" / "psi"), the enum member name ("KWH"), or any alias the per-family _ALIASES dict knows ("megawatthours" / "celsius" / "pound"). Lookup is case-insensitive.

Pass default to swallow unknown / unparseable input; without it, unknown strings raise :class:ValueError with a hint listing the valid symbols, and non-string non-member input raises :class:TypeError.

is_valid classmethod 

is_valid(value: Any) -> bool

True when :meth:from_ would resolve value.

convert classmethod 

convert(value: float, source: Any, target: Any) -> float

Convert value from source unit to target unit (scalar).

to_canonical 

to_canonical(value: float) -> float

Convert value in self's unit to the family's canonical unit.

from_canonical 

from_canonical(value: float) -> float

Convert value in the canonical unit to self's unit.

canonical classmethod 

canonical() -> 'Unit'

The family's canonical member (factor=1.0, offset=0.0).

factor_map classmethod 

factor_map() -> dict[str, float]

{symbol: factor} for every member + alias, for per-row maps.

offset_map classmethod 

offset_map() -> dict[str, float]

{symbol: offset} for every member + alias, for per-row maps.

PressureUnit 

PressureUnit(symbol: str, factor: float, offset: float = 0.0)

Bases: Unit, Enum

Pressure unit (canonical = pascal).

SI scale (Pa / kPa / MPa / hPa) plus the bar family (bar / mbar), atmosphere, psi, and torr. Weather feeds publish in hPa or mbar, oil & gas in psi or bar, process control in kPa or MPa — one enum keeps them aligned.

from_ classmethod 

from_(value: Any, *, default: Any = ...) -> 'Unit'

Coerce value to a member of this unit family.

Accepts: a member (passed through), a known symbol ("MWh" / "°C" / "psi"), the enum member name ("KWH"), or any alias the per-family _ALIASES dict knows ("megawatthours" / "celsius" / "pound"). Lookup is case-insensitive.

Pass default to swallow unknown / unparseable input; without it, unknown strings raise :class:ValueError with a hint listing the valid symbols, and non-string non-member input raises :class:TypeError.

is_valid classmethod 

is_valid(value: Any) -> bool

True when :meth:from_ would resolve value.

convert classmethod 

convert(value: float, source: Any, target: Any) -> float

Convert value from source unit to target unit (scalar).

to_canonical 

to_canonical(value: float) -> float

Convert value in self's unit to the family's canonical unit.

from_canonical 

from_canonical(value: float) -> float

Convert value in the canonical unit to self's unit.

canonical classmethod 

canonical() -> 'Unit'

The family's canonical member (factor=1.0, offset=0.0).

factor_map classmethod 

factor_map() -> dict[str, float]

{symbol: factor} for every member + alias, for per-row maps.

offset_map classmethod 

offset_map() -> dict[str, float]

{symbol: offset} for every member + alias, for per-row maps.

unit_family_for 

unit_family_for(value: Any) -> type[Unit]

Find the unit family that recognises value (member or symbol).

Useful when a curated row carries a free-form unit token and the caller needs to dispatch to the right family without hard-coding a per-source switch. Returns the first family for which :meth:Unit.is_valid returns True; raises :class:ValueError when no family claims the token (the message lists every family that was consulted).