Conversion Foundations

0.4.0 - 2026-05-08

0.4.0 introduces the first Phase 10 conversion foundations. The release adds explicit scale-only conversions, common SI-prefixed units, and small extractor helpers while preserving strict unit-compatibility rules for arithmetic.

Added

• Quantity.to(target_unit) for explicit same-dimension multiplicative conversions.
• convert(quantity, target_unit) as a helper equivalent to quantity.to(target_unit).
• Extractor helpers:
  • value(quantity)
  • unit(quantity)
  • multiplier(quantity_or_unit)
• Common prefixed and scaled units:
  • length: kilometre, centimetre, millimetre, micrometre, nanometre
  • mass: gram, milligram, microgram, tonne
  • time: minute, hour, millisecond, microsecond, nanosecond
  • electrical and power units: milliampere, kiloampere, millivolt, kilovolt, milliwatt, kilowatt, megawatt

Changed

• Multiplication, division, and powers now account for unit conversion factors so scaled-unit arithmetic produces canonical base magnitudes.
• Composite scaled-unit arithmetic renders in canonical SI dimensions to avoid silently displaying scaled values as base units.
• README now opens with a Mars Climate Orbiter-style unit-boundary example and includes examples for familiar composite display units such as km·hr^-1.

Compatibility

• Addition, subtraction, and modulo still require identical units.
• Affine conversions such as degree_celcius <-> kelvin remain out of scope until the next conversion phase.
• Deprecated compatibility helpers from 0.3.0 remain available with DeprecationWarning.

Verification

• pytest tests/unit tests/integration
• 62 passed

Compatibility Deprecation Policy

0.3.0 - 2026-05-08

0.3.0 implements the compatibility deprecation policy for the modern API transition. Preferred code should use Quantity, scalar-by-unit construction, and the *_quantity conversion helpers.

Changed

• Bumped the package version to 0.3.0.
• Unit remains a deprecated compatibility alias for Quantity and is scheduled for removal in 1.0.0.
• Legacy conversion helpers int_unit, float_unit, long_unit, complex_unit, and long_quantity now emit DeprecationWarning when called.

Compatibility

• Deprecated compatibility paths remain available in this release.
• Deprecated compatibility paths are scheduled for removal in 1.0.0.
• Unit remains a true alias, so Unit is Quantity and isinstance(value, Unit) keep working until the breaking release.
• Preferred APIs do not emit deprecation warnings.

Modernized API

v0.2.0

0.2.0 is the first release in the modernized API line.

This release keeps legacy code working while introducing a clearer and more ergonomic public API, a
stronger internal architecture, and a modern Python-only packaging and test workflow.

Preferred API

from units import Quantity
from units.si import metre, second, newton

distance = 10 * metre
time = 2 * second
speed = distance / time
force = 5 * newton

The explicit constructor remains fully supported:

distance = Quantity(10, metre)

Legacy compatibility is still preserved in this release:

import units as u
distance = u.Unit(10, u.metre)

Added

• Quantity as the preferred quantity type
• units.si as the canonical import location for SI and derived units
• scalar-by-unit construction, such as 3 * metre
• exponent support for units and quantities, such as 5 * metre ** 3
• immutable Dimension and DimensionSystem models
• registry-backed canonicalization for unambiguous SI derived units
• support for custom unit systems through CustomUnitBase
• GitHub Actions CI and publishing workflows
• pyproject.toml packaging metadata
• pytest-based unit tests and integration tests
• layered source structure under src/api, src/core, src/models, and src/utils
• contributor guidance and a maintained project plan

Changed

• the package is now Python 3-only
• the preferred construction style is now scalar-by-unit multiplication instead of always calling
  Quantity(...)
• the runtime package has been refactored into a layered architecture while preserving the units facade
• documentation is now centered on README.md with real-world engineering examples
• test and build workflows now reflect the src layout and modern Python packaging

Fixed

• explicit typed validation replaced assert-based validation
• fragile arithmetic paths and unsupported operand handling were corrected
• reverse arithmetic and dimensionless handling were tightened
• custom unit systems were restored after the dimensional refactor and kept separate from SI
  canonicalization

Compatibility

• Unit remains available as a compatibility alias for Quantity
• top-level unit exports remain available during the transition
• legacy helper names such as long_unit and long_quantity still exist for compatibility
• deprecation warnings are not yet emitted in this release

Current state

• public facade in src/units
• layered implementation in src/api, src/core, src/models, and src/utils
• intentionally empty src/services and src/adapters packages reserved for future growth
• Python 3.10+ support
• pytest unit and integration coverage
• current verified total coverage of 92%
• preferred API based on 3 * metre style quantity construction
• explicit constructor support retained through Quantity(value, unit)
• legacy API still available for migration

Next steps

• implement compatibility deprecation policy
• add low-noise warnings for legacy aliases
• define removal timing for legacy paths in a future breaking release