|
ucon
|
A lightweight, unit-aware computation library for Python — built on first-principles.
Documentation · Quickstart · API Reference
What is ucon?
ucon helps Python understand the physical meaning of your numbers. It treats units, dimensions, and scales as first-class objects — enforcing physics, not just labels.
from ucon import units
length = units.meter(5)
time = units.second(2)
speed = length / time # <2.5 m/s>
invalid = length + time # raises: incompatible dimensions
Installation
pip install ucon
With extras:
pip install ucon[pydantic] # Pydantic v2 integration
pip install ucon-tools[mcp] # MCP server for AI agents (separate package)
Quick Examples
Parse Quantities
from ucon import parse
velocity = parse("9.81 m/s^2") # <9.81 m/s²>
measurement = parse("1.234 ± 0.005 m") # <1.234 ± 0.005 m>
Unit Conversion
from ucon import units, Scale
km = Scale.kilo * units.meter
distance = km(5)
print(distance.to(units.mile)) # <3.107... mi>
Dimensional Safety
from ucon import Number, Dimension, enforce_dimensions
@enforce_dimensions
def speed(
distance: Number[Dimension.length],
time: Number[Dimension.time],
) -> Number:
return distance / time
speed(units.meter(100), units.second(10)) # <10.0 m/s>
speed(units.second(100), units.second(10)) # raises ValueError
Pydantic Integration
from pydantic import BaseModel
from ucon.pydantic import Number
class Measurement(BaseModel):
value: Number
m = Measurement(value={"quantity": 9.8, "unit": "m/s^2"})
print(m.model_dump_json())
# {"value": {"quantity": 9.8, "unit": "m/s^2", "uncertainty": null}}
MCP Server for AI Agents
Install ucon-tools and configure in Claude Desktop:
pip install ucon-tools[mcp]
{
"mcpServers": {
"ucon": {
"command": "uvx",
"args": ["--from", "ucon-tools[mcp]", "ucon-mcp"]
}
}
}
AI agents can then convert units, check dimensions, and perform factor-label calculations with dimensional validation at each step.
Features
- Physical constants — CODATA 2022 values with uncertainty propagation (
E = m * c**2) - Custom constants — Define domain-specific constants with uncertainty propagation
- String parsing —
parse("9.81 m/s^2")with uncertainty support (1.234 ± 0.005 m) - Dimensional algebra — Units combine through multiplication/division with automatic dimension tracking
- Scale prefixes — Full SI (kilo, milli, micro, etc.) and binary (kibi, mebi) prefix support
- Uncertainty propagation — Errors propagate through arithmetic and conversions
- Pseudo-dimensions — Semantically isolated handling of angles, ratios, and counts
- Natural units — Custom dimensional bases where c=ℏ=k_B=1 for particle physics
- Logarithmic units — dB, pH, and neper conversions with uncertainty propagation
- Pydantic v2 — Type-safe API validation and JSON serialization
- MCP server — AI agent integration with Claude, Cursor, and other MCP clients
- ConversionGraph — Extensible conversion registry with custom unit support
Roadmap Highlights
| Version | Theme | Status |
|---|---|---|
| 0.3.x | Dimensional Algebra | Complete |
| 0.4.x | Conversion System | Complete |
| 0.5.x | Dimensionless Units + Uncertainty | Complete |
| 0.6.x | Pydantic + MCP Server | Complete |
| 0.7.x | Compute Tool + Extension API | Complete |
| 0.8.x | Basis Abstraction + String Parsing | Complete |
| 0.9.x | Constants + Natural Units | Complete |
| 0.10.x | NumPy/Polars Integration | Planned |
| 1.0.0 | API Stability | Planned |
See full roadmap: ROADMAP.md
Documentation
| Section | Description |
|---|---|
| Getting Started | Why ucon, quickstart, installation |
| Guides | MCP server, Pydantic, custom units, dimensional analysis |
| Reference | API docs, unit tables, MCP tool schemas |
| Architecture | Design principles, ConversionGraph, comparison with Pint |
Contributing
make venv # Create virtual environment
source .ucon-3.12/bin/activate # Activate
make test # Run tests
make test-all # Run tests across all Python versions
When modifying ucon/dimension.py (adding/removing dimensions), regenerate the type stubs:
make stubs # Regenerate ucon/dimension.pyi
make stubs-check # Verify stubs are current (used in CI)
All pull requests must include a CHANGELOG.md entry under the [Unreleased] section:
## [Unreleased]
### Added
- Your new feature description (#PR_NUMBER)
Use the appropriate category: Added, Changed, Deprecated, Removed, Fixed, or Security.
License
Apache 2.0. See LICENSE.
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file ucon-0.9.4.tar.gz.
File metadata
- Download URL: ucon-0.9.4.tar.gz
- Upload date:
- Size: 696.2 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.1.0 CPython/3.13.7
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
5d280964acdfa720cdddb3016a85ce8ced7f6656378ae0494a6a45265f6ca740
|
|
| MD5 |
2603edf4039136a1893a7fca06a7b4c5
|
|
| BLAKE2b-256 |
d992c2478112d5fcef8098fe9fd27ea6854c3700e53f600267b1e13c37bae37e
|
File details
Details for the file ucon-0.9.4-py3-none-any.whl.
File metadata
- Download URL: ucon-0.9.4-py3-none-any.whl
- Upload date:
- Size: 78.8 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.1.0 CPython/3.13.7
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
168875c603bca90637cc700c35800239bdf0ae48757fd559194d1826c66f2b8b
|
|
| MD5 |
60907a59a986bf64257e6c02d80ddd49
|
|
| BLAKE2b-256 |
0a909028c75a60934be6f7b8cca608c81e1fa1433ef4605e15c93bab47b64c4c
|
