Skip to content

ucon.parsing

String parsing for human-readable quantity expressions.

ucon.parsing

Recursive-descent parsers for ucon's string forms.

Public surface

  • :func:parse — quantity string → :class:~ucon.core.Number (e.g., "60 mph", "1.234 ± 0.005 m").
  • :func:parse_dimension — dimension string → :class:~ucon.dimension.Dimension (e.g., "M", "velocity", "M·L/T²").
  • :func:parse_unit_expression — power-user entry point for unit-expression parsing; called by :func:ucon.resolver.parse_unit for compound forms.
  • :class:ParseError — raised on malformed input.

Internal layout

  • :mod:ucon.parsing.lexer — shared tokenizer (_Tokenizer, _TokenType, _Token, ParseError).
  • :mod:ucon.parsing.quantity — quantity-string :func:parse entry point.
  • :mod:ucon.parsing.units — unit-expression grammar.
  • :mod:ucon.parsing.dimensions — dimension-expression grammar.

The dimensions submodule is loaded lazily (PEP 562 __getattr__) to avoid a load-time cycle through ucon.units → ucon.resolver → ucon.parsing: by the time anyone calls :func:parse_dimension, :mod:ucon.dimension is fully loaded.

Tokenizer privates (_Tokenizer, _Token, _TokenType) are re-exported here for backward compatibility with code that previously imported them from the single-file ucon.parsing module. New code should import them from :mod:ucon.parsing.lexer directly.

ParseError

Bases: ValueError

Raised when expression parsing fails.

parse_unit_expression(expression, lookup_fn, unit_factor_cls, unit_product_cls)

Parse a unit expression string into a UnitProduct.

This is the main entry point for parsing complex unit expressions.

Parameters:

Name Type Description Default
expression str

The unit expression (e.g., "W/(m²*K)", "mg/kg/d").

 required
lookup_fn Callable[[str], Tuple['Unit', 'Scale']]

Function to resolve unit names to (Unit, Scale) tuples.

 required
unit_factor_cls type

The UnitFactor class.

 required
unit_product_cls type

The UnitProduct class.

 required

Returns:

Type Description
'UnitProduct'

A UnitProduct representing the parsed expression.

Raises:

Type Description
ParseError

If the expression is malformed.

Examples:

>>> parse_unit_expression("m/s²", lookup_fn, UnitFactor, UnitProduct)
<UnitProduct m/s²>

__getattr__(name)

PEP 562 lazy attribute access.

Loading ucon.parsing.dimensions eagerly would force ucon.dimension to be evaluated whenever ucon.parsing is imported, including the early-bootstrap path ucon.units → ucon.resolver → ucon.parsing where the dimension module has not yet finished registering its attributes. The kind, formula, and aspect parsers are deferred for the same reason: keeping ucon.kinds, ucon.formulas, and ucon.aspects out of the bootstrap path.