Metadata-Version: 2.4
Name: larzunits
Version: 0.1.0
Summary: Unit conversion with dimensional checking (length, mass, time, temperature, data, volume) and a Quantity type. Pure Python, zero dependencies.
Author: larz-scripter
License: MIT
Project-URL: Homepage, https://github.com/larz-scripter/larzunits
Project-URL: Repository, https://github.com/larz-scripter/larzunits
Project-URL: Issues, https://github.com/larz-scripter/larzunits/issues
Keywords: units,unit-conversion,measurement,dimensional-analysis,temperature,quantity,pint-alternative,conversion,zero-dependency
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# larzunits

**Unit conversion with dimensional checking. Pure Python, zero dependencies.**

Convert between units and refuse nonsense: metres to feet is fine, metres to
kilograms raises. Handles the affine temperature scales (C/F/K) correctly, and a
`Quantity` type carries a value-with-unit so you can add and compare safely.

```python
from larzunits import convert, Quantity

convert(5, "km", "mi")                 # 3.106...
convert(100, "C", "F")                 # 212.0
convert(1, "KiB", "byte")              # 1024.0

Quantity(5, "m") + Quantity(30, "cm")  # 5.3 m
Quantity(1, "km") > Quantity(500, "m") # True
Quantity(60, "mi") + Quantity(1, "kg") # raises IncompatibleUnits
```

## Why

- **Catches mistakes.** Converting or adding across dimensions raises
  `IncompatibleUnits` instead of silently returning garbage.
- **Temperature done right.** C/F/K are affine (offsets, not just factors) —
  `0 °C = 32 °F = 273.15 K` — and larzunits handles that, where a naive
  factor table gets it wrong.
- **Batteries of units.** Length, mass, time, temperature, data (decimal `kb`
  *and* binary `KiB`), and volume — imperial and metric.
- **A real `Quantity` type.** `to()`, `+`/`-` (dimension-checked), scalar `*`/`/`,
  quantity/quantity ratio, equality and ordering by underlying value.
- **Zero dependencies.** No `pint`, no `quantities`.

## Install

```bash
pip install larzunits
```

## Usage

```python
from larzunits import convert, Quantity, compatible, dimension

convert(12, "in", "ft")           # 1.0
compatible("m", "ft")             # True
dimension("mph") if False else dimension("m")   # 'length'

q = Quantity(90, "min")
q.to("h").value                   # 1.5
(Quantity(1, "km") / Quantity(250, "m"))   # 4.0  (dimensionless)
```

Units: length (`m km cm mm um nm mi yd ft in nmi`), mass (`kg g mg t lb oz st`),
time (`s ms min h day week`), temperature (`K C F`), data
(`bit byte kb mb gb tb KiB MiB GiB TiB`), volume (`l ml cl gal pt cup`).

## Tests

```bash
python -m unittest discover -s tests -v   # 21 tests incl. temperature + errors
```

## The Larz stack

One of 30+ pure-Python, zero-dependency libraries at
[github.com/larz-scripter](https://github.com/larz-scripter).

## License

MIT © larz-scripter
