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.
rel_uncertainty : float
Relative uncertainty of the conversion factor. Default 0.0 (exact).
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 parse_unit() during materialization.
uncertainty : float | None
Standard uncertainty. None for exact values.
source : str
Data source reference.
category : str
Category: "exact", "derived", "measured", or "session".
kind : str | None
Optional canonical kind name. Resolved via the active
KindLattice during materialization.
materialize(graph, *, kind_lattice=None)
¶
Resolve unit string and create a Constant.
Parameters¶
graph : ConversionGraph
The graph to resolve unit names against.
kind_lattice : KindLattice | None, optional
Local kind lattice to check before falling back to the ambient
active_kinds(). When loading a package that defines both
novel kinds and constants referencing those kinds, pass the
merged lattice so that resolution succeeds without requiring
the kinds to be registered in the ambient context first.
Returns¶
Constant A new Constant instance.
Raises¶
PackageLoadError If the unit string or kind name cannot be resolved.
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.
kinds : KindLattice | None
Kind-of-quantity lattice parsed from [[kinds]] sections.
None when the package does not define any kinds.
aspects : AspectForest | None
Aspect forest parsed from [[aspects]] sections. None
when the package does not declare any aspects.
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