ucon.packages¶
Unit package loading from TOML files.
ucon.packages¶
UnitPackage loading and composition for domain-specific unit extensions.
This module provides the infrastructure for defining custom units and conversions in TOML config files that can be loaded at application startup.
Classes¶
- :class:
UnitDef— Serializable unit definition. - :class:
EdgeDef— Serializable conversion edge definition. - :class:
ConstantDef— Serializable constant definition. - :class:
UnitPackage— Immutable bundle of units and conversions.
Functions¶
- :func:
load_package— Load a UnitPackage from a TOML file.
Exceptions¶
- :class:
PackageLoadError— Raised when package loading fails.
Example¶
from ucon.packages import load_package from ucon import get_default_graph
aero = load_package("aerospace.ucon.toml") graph = get_default_graph().with_package(aero)
PackageLoadError
¶
Bases: Exception
Raised when a package file cannot be loaded or validated.
UnitDef
dataclass
¶
Serializable unit definition.
Attributes¶
name : str
Canonical name of the unit (e.g., "slug").
dimension : str
Dimension enum name (e.g., "mass", "length").
aliases : tuple[str, ...]
Optional shorthand symbols (e.g., ("slug",)).
shorthand : str | None
Explicit display symbol (e.g., "nmi"). When provided, this is
prepended to aliases so it becomes Unit.shorthand. When
None, the first alias (or name) is used as before.
EdgeDef
dataclass
¶
Serializable conversion edge definition.
Edges can be specified in two ways:
Shorthand (linear/affine): uses factor and optional offset.
Explicit map: uses map_spec dict with a type key and
constructor parameters. Supported types: linear, affine,
log, reciprocal.
When map_spec is provided, it takes precedence over
factor/offset.
Attributes¶
src : str
Source unit name or composite expression.
dst : str
Destination unit name or composite expression.
factor : float
Multiplier (dst = factor * src + offset). Ignored when
map_spec is provided.
offset : float
Additive offset for affine conversions (default 0.0).
Ignored when map_spec is provided.
map_spec : dict | None
Explicit map specification. When provided, must contain a
type key ("linear", "affine", "log",
"reciprocal"). Remaining keys are constructor arguments.
ConstantDef
dataclass
¶
Serializable constant definition.
Attributes¶
symbol : str
Standard symbol (e.g., "vs", "Eg").
name : str
Full descriptive name (e.g., "speed of sound in dry air at 20C").
value : float
Numeric value in the specified unit.
unit : str
Unit expression string (e.g., "m/s", "J", "kg*m/s^2").
Resolved via get_unit_by_name() during materialization.
uncertainty : float | None
Standard uncertainty. None for exact values.
source : str
Data source reference.
category : str
Category: "exact", "derived", "measured", or "session".
UnitPackage
dataclass
¶
Immutable bundle of domain-specific units and conversions.
Attributes¶
name : str Package name (e.g., "aerospace"). version : str Semantic version string (e.g., "1.0.0"). description : str Human-readable description. units : tuple[UnitDef, ...] Unit definitions. edges : tuple[EdgeDef, ...] Conversion edge definitions. constants : tuple[ConstantDef, ...] Constant definitions. requires : tuple[str, ...] Names of required packages (for future dependency resolution).
__post_init__()
¶
Validate package contents.
load_package(path)
¶
Load a UnitPackage from a TOML file.
Parameters¶
path : str or Path Path to a .toml or .ucon.toml file.
Returns¶
UnitPackage Frozen package ready for use with ConversionGraph.with_package().
Raises¶
PackageLoadError If file cannot be read or contains invalid definitions.
Example¶
pkg = load_package("aerospace.ucon.toml") print(pkg.name, pkg.version) aerospace 1.0.0