Unit catalogues
Use catalogues directly in formulas; no Registry setup is needed:
>>> from unitx import Quantity, Unit
>>> from unitx.si import si
>>> from unitx.imperial import imperial
>>> (3 * imperial.ft).value_in(si.m)
Fraction(1143, 1250)
>>> imperial.parse('ft/s') == imperial.ft / si.s
True
| Catalogue | Import | Reference |
|---|---|---|
| SI and common scientific units | from unitx.si import si, SI |
Units, constants, prefixes and Unicode spellings |
| Imperial, historical English and US units | from unitx.imperial import imperial, imperial_historical, us |
Length, mass, volume, force and pressure conventions |
The UnitCatalog entry point
si and the immutable imperial namespace share the public UnitCatalog base.
A catalogue exposes unit attributes and a parse() entry point, using its
configured spelling environment. si.parse() uses the existing default
environment; Imperial parsing uses its explicitly configured private environment.
The base preserves the existing non-instantiable, read-only namespace behavior.
UnitCatalog collects public unit attributes after the class body finishes.
Existing objects can also be shared with units=. Use earlier unit objects to
construct later definitions; new spellings become parseable after collection.
See catalogue construction for the
prefix permissions, structured persistence locations and optional class keywords.
A catalogue selects available units and parser spellings. It does not select coherent base units or expand quantities in a chosen unit system.
Default text stays fixed
Quantity(3, 'm') and .to('cm') keep using the default environment. Importing
a catalogue never adds its spellings to that environment. For example, default
gal denotes galileo (acceleration), while Imperial gal denotes gallon:
>>> Unit('gal') == si.Gal
True
>>> imperial.parse('gal') == imperial.gal
True
>>> (1 * imperial.gal).value_in(si.L)
Fraction(454609, 100000)
Pass the catalogue's Unit object to .to() or .value_in(). A source quantity's
dimension never changes the meaning of a target string. Unit objects carry
bound immutable definitions; quantities do not retain a mutable registry.
Compatible quantities from different environments can be added or converted.
For custom units in ordinary code, use with registry.defining():; class
declarations remain available to catalogue maintainers. See
custom units and registries.
For persisted identities, see serialization.
The entry-point design draws on Astropy's separation of directly usable unit objects and enabled parser names. Unlike Pint's registry ownership rule, unitx allows compatible quantities from different environments to interact. It retains unitx's own exact formal identity and numeric rules.