pyconvertx 1.0.0__tar.gz

pyconvertx-1.0.0/CHANGELOG.md

@@ -0,0 +1,103 @@
+# Changelog
+
+All notable changes to this project are documented here.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [1.0.0] - 2026-10-11
+
+The first release that actually works. Version 0.1.0 could not be imported at
+all (see below), so although this is a complete rewrite of the public API,
+nothing can have depended on the old one.
+
+Published on PyPI as **`pyconvertx`**; the import name remains `pyconvert`.
+
+### Added
+
+- 182 units across 15 categories: length, mass, speed, area, volume, energy,
+  power, temperature, time, pressure, frequency, digital storage, angle,
+  electric current and electric potential. Temperature, time, pressure,
+  frequency, storage, angle, current and potential are all new.
+- 390 aliases, so long names, plurals and typeable forms of awkward symbols
+  resolve to the same unit (`kilometre`, `kilometer`, `km`; `m2`, `m²`;
+  `degC`, `°C`).
+- Both Unicode micro signs — MICRO SIGN (U+00B5) and GREEK SMALL LETTER MU
+  (U+03BC) — are mapped onto the ASCII spelling. They are visually identical
+  but different characters, so a plain dictionary lookup would accept one
+  user's `μs` and reject another's.
+- `convert_base(number, from_base, to_base, precision=16)` for bases 2 to 36,
+  with support for fractional parts, negative values, mixed-case input and
+  underscore separators.
+- An exception hierarchy rooted at `PyConvertError`, where each error also
+  subclasses the builtin you would expect (`KeyError`, `ValueError`,
+  `RuntimeError`).
+- Error messages that suggest a fix: wrong case is detected and offered back,
+  near misses are fuzzy-matched, and deliberately ambiguous spellings explain
+  what to write instead.
+- `convert_all`, `is_convertible`, `list_categories`, `list_units`,
+  `category_of` and `base_unit`.
+- Type hints throughout, with a `py.typed` marker so type checkers use them.
+- A test suite of 1072 tests, including every docstring example.
+
+### Changed
+
+- **The conversion API is entirely new.** `convert(value, from_unit, to_unit)`
+  replaces `convert(qty, units, value)`. The category argument is gone, and
+  unit pairs are no longer expressed as arrow strings:
+
+  ```python
+  # 0.1.0
+  convert('weight', 'gram-->kilogram', 500)
+  # 1.0.0
+  convert(500, 'gram', 'kilogram')
+  ```
+
+- **Conversion factors are now stored relative to a base unit per category**
+  rather than as explicit pairs. Every pair within a category therefore works,
+  including ones nobody wrote down. The old design needed one entry per
+  direction per pair, which would have required roughly 1,700 entries to cover
+  these 15 categories; the registry holds 182.
+- `convertnumber(base, number)` is replaced by
+  `convert_base(number, from_base, to_base)`, with the value first and both
+  bases given explicitly.
+- `convert_base` always returns a string, including when the target base is 10.
+- The package is now `pyconvert.registry`, `pyconvert.units`,
+  `pyconvert.bases` and `pyconvert.exceptions`; the single
+  `pyconvert.pyconvert` module is gone.
+- Packaging moved from `setup.py` to `pyproject.toml`.
+
+### Fixed
+
+- **The package could not be imported.** `__init__.py` did
+  `from .pyconvert import convert, convert_number`, but the function was named
+  `convertnumber`, so `import pyconvert` raised `ImportError` for every user of
+  0.1.0.
+- **`meter-->feet` was inverted.** It held 0.3048, the number of metres in a
+  foot, so converting metres to feet divided by 3.28 instead of multiplying.
+  The base-relative registry makes this class of mistake impossible to express,
+  and a test pins it.
+- **`quintal-->kilogram` was 1000.** A quintal is 100 kg, so the factor was
+  wrong by a factor of ten.
+- Missing reverse conversions: `solarmass-->kilogram` and `amu-->gram` had no
+  inverse, so those conversions failed in one direction. All pairs are now
+  symmetric by construction.
+
+### Security
+
+- Nothing applicable; the library performs arithmetic on numbers and strings
+  and makes no network, filesystem or subprocess calls.
+
+## [0.1.0] - 2025-10-20
+
+Initial release, kept as the `v0.1.0` git tag for history. Never published to
+PyPI.
+
+- Unit conversion across length, weight, speed, area, energy, power and volume
+  via a dictionary of `from-->to` pairs.
+- `convertnumber` for converting a decimal number into any base from 2 to 36.
+- **Known broken:** `import pyconvert` raised `ImportError`, so the package was
+  unusable as published. See the Fixed section above.
+
+[1.0.0]: https://github.com/cobrapy-x/pyconvert-package/releases/tag/v1.0.0
+[0.1.0]: https://github.com/cobrapy-x/pyconvert-package/releases/tag/v0.1.0

pyconvertx-1.0.0/CONTRIBUTING.md

@@ -0,0 +1,130 @@
+# Contributing to PyConvert
+
+Thanks for your interest. This is a small library, so the bar is simple: a
+change should be correct, covered by a test, and leave `pytest` and
+`ruff check .` green.
+
+## Getting set up
+
+```bash
+git clone https://github.com/cobrapy-x/pyconvert-package.git
+cd pyconvert-package
+python -m pip install -e ".[dev]"
+
+pytest           # 1072 tests, including every docstring example
+ruff check .
+```
+
+`pytest` with no arguments runs the suite in `tests/` *and* the doctests in
+`pyconvert/`, because the examples in the docstrings are the same ones in the
+README — they are checked rather than trusted.
+
+## How the library is laid out
+
+| File | Responsibility |
+|---|---|
+| `pyconvert/registry.py` | The data: all 15 category tables, the aliases, and the index built from them |
+| `pyconvert/units.py` | The conversion engine and the introspection helpers |
+| `pyconvert/bases.py` | Number-base conversion |
+| `pyconvert/exceptions.py` | The error hierarchy |
+
+`bases.py` is named that way rather than `numbers.py` because the standard
+library already has a `numbers` module — the one holding `numbers.Real`, which
+`units.py` imports.
+
+## Adding a unit
+
+Units are stored as **how big one of them is, in the category's base unit**.
+That is the whole trick: a conversion is then one ratio,
+`value * f_source / f_target`, and every pair in the category works without
+being written down.
+
+1. Add an entry to the right table in `registry.py`. One nautical mile is
+   1852 metres, so under `LENGTH` it is `"nmi": 1852.0`.
+
+2. **If the factor is exact by definition, write the definition, not the
+   decimal.** An inch *is* 25.4 mm — that is a definition, not a measurement.
+   Those are built from exact rationals and rounded to `float` once:
+
+   ```python
+   "ac": float(4840 * _YD_Q ** 2),     # an acre is 4840 square yards, exactly
+   ```
+
+   Computing the same thing in floating point gives a different answer:
+   `231 * 0.0254 ** 3` is `0.0037854117839999997`, three roundings away from
+   the correctly rounded `0.003785411784`. Mark genuinely measured values
+   (particle masses, the solar mass) with a comment saying so.
+
+3. **Add aliases** for the spellings people will actually type — the long name,
+   the plural, and an ASCII form if the symbol needs a character they cannot
+   easily reach. Micro-prefixed units get their Unicode variants generated
+   automatically; do not add those by hand.
+
+4. **Check the symbol is not already taken.** All 15 categories share one
+   namespace. If it collides, `import pyconvert` fails immediately with a
+   `RegistryError` naming both categories — that check runs at import, so you
+   will know in one second rather than from a bug report.
+
+5. **If the spelling is genuinely ambiguous, do not pick a winner.** Add it to
+   `AMBIGUOUS` with a message saying what to use instead. `ton` means three
+   masses that differ by up to 12%; `oz` is both a mass and a volume. Returning
+   one of them silently is worse than refusing.
+
+6. Add a test. The most valuable kind asserts a relationship fixed by
+   definition and independent of the metre or the kilogram:
+
+   ```python
+   (1, "mi", "ft", 5280),
+   (1, "gal_us", "in3", 231),
+   ```
+
+   An inverted factor still round-trips perfectly, so a round-trip test will
+   not catch it — but `1 mi == 5280 ft` will. That is exactly the bug that
+   shipped in 0.1.0.
+
+## Adding a category
+
+Add the table, add it to `CATEGORIES`, and declare its base unit in
+`BASE_UNITS`. The base unit must have scale 1 and offset 0; `build_index`
+enforces that at import.
+
+If any unit in the category needs an **offset** rather than just a scale (as
+temperature does), store its entry as a `(scale, offset)` tuple of
+`Fraction`s, where `base_value = x * scale + offset`. The engine routes any
+conversion involving a tuple entry through exact rational arithmetic, which is
+what makes `100 °C → °F` return exactly `212.0` instead of
+`211.99999999999997`.
+
+## Invariants the suite enforces
+
+These hold for every unit, and the tests will tell you if a change breaks one:
+
+- Every unit round-trips through its category's base unit.
+- For every pair `a`, `b` in a multiplicative category,
+  `convert(1, a, b) * convert(1, b, a) == 1`.
+- Conversion is transitive: `a → c` agrees with `a → b → c`.
+- No symbol is claimed by two categories, no alias shadows a canonical symbol,
+  and no alias points at a unit that does not exist.
+- Every cross-category pair raises `IncompatibleUnitsError`.
+- Every spelling in `AMBIGUOUS` is genuinely unresolvable, so its hint is
+  reachable.
+- Every unit symbol appears in `README.md`.
+
+## Style
+
+`ruff check .` is the whole style guide; its configuration lives in
+`pyproject.toml`. Comments are welcome where they explain *why* — a surprising
+factor, a definition chosen over an alternative, a deliberate refusal. Prefer
+those over comments restating what the code does.
+
+## Submitting
+
+1. Fork the repository and branch off `main`.
+2. Make the change, with tests.
+3. Run `pytest` and `ruff check .`.
+4. Add a line to `CHANGELOG.md` under an `## [Unreleased]` heading.
+5. Open a pull request describing what changed and why.
+
+Bug reports are just as useful as patches. For a wrong conversion factor,
+please include the units, the result you got, the result you expected, and a
+source for the correct value.

pyconvertx-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 cobrapy-x
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

pyconvertx-1.0.0/MANIFEST.in

@@ -0,0 +1,10 @@
+include LICENSE
+include README.md
+include CHANGELOG.md
+include CONTRIBUTING.md
+include conftest.py
+include pyconvert/py.typed
+recursive-include tests *.py
+recursive-include examples *.py
+global-exclude __pycache__
+global-exclude *.py[cod]

pyconvertx-1.0.0/PKG-INFO

@@ -0,0 +1,315 @@
+Metadata-Version: 2.4
+Name: pyconvertx
+Version: 1.0.0
+Summary: A lightweight unit and number-base conversion library with no dependencies
+Author: cobrapy-x
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/cobrapy-x/pyconvert-package
+Project-URL: Repository, https://github.com/cobrapy-x/pyconvert-package
+Project-URL: Issues, https://github.com/cobrapy-x/pyconvert-package/issues
+Project-URL: Changelog, https://github.com/cobrapy-x/pyconvert-package/blob/main/CHANGELOG.md
+Keywords: units,unit-conversion,measurement,convert,converter,temperature,metric,imperial,number-base,radix
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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 :: Scientific/Engineering
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Utilities
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: ruff>=0.5; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+# PyConvert
+
+A lightweight unit and number-base conversion library for Python, with **no
+dependencies** beyond the standard library.
+
+[![Tests](https://github.com/cobrapy-x/pyconvert-package/actions/workflows/tests.yml/badge.svg)](https://github.com/cobrapy-x/pyconvert-package/actions/workflows/tests.yml)
+[![PyPI](https://img.shields.io/pypi/v/pyconvertx.svg)](https://pypi.org/project/pyconvertx/)
+[![Python versions](https://img.shields.io/pypi/pyversions/pyconvertx.svg)](https://pypi.org/project/pyconvertx/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+## Install
+
+```bash
+pip install pyconvertx
+```
+
+> **The install name and the import name differ.**
+> Install **`pyconvertx`**, import **`pyconvert`**.
+>
+> ```python
+> import pyconvert          # not "import pyconvertx"
+> ```
+>
+> The name `pyconvert` was already taken on PyPI in 2015 by an unrelated
+> XML/JSON library, so this project is distributed under `pyconvertx`. A
+> distribution name that differs from the import name is common — `pip install
+> beautifulsoup4` gives you `import bs4`, and `pip install pillow` gives you
+> `import PIL`.
+
+## Quick start
+
+```python
+import pyconvert
+
+pyconvert.convert(100, "km", "mi")                 # 62.13711922373339
+pyconvert.convert(100, "celsius", "fahrenheit")    # 212.0
+pyconvert.convert(1024, "MiB", "GiB")              # 1.0
+pyconvert.convert(1, "gal_us", "L")                # 3.785411784
+
+pyconvert.convert_base(100, 10, 2)                 # '1100100'
+pyconvert.convert_base("10101111", 2, 16)          # 'AF'
+pyconvert.convert_base("FF", 16, 10)               # '255'
+pyconvert.convert_base(1000, 10, 36)               # 'RS'
+```
+
+No setup, no classes to instantiate, no unit objects to construct.
+
+## Unit conversion
+
+```python
+convert(value, from_unit, to_unit) -> float
+```
+
+There is **no category argument**. Every unit symbol is unique across the whole
+library, so the category is looked up from the symbols you give. A consequence
+worth having: mixing categories is an error rather than a plausible-looking
+wrong number.
+
+```python
+>>> pyconvert.convert(1, "kg", "m")
+IncompatibleUnitsError: cannot convert 'kg' to 'm': 'kg' measures mass, 'm' measures length
+```
+
+### Supported units
+
+182 units across 15 categories. Factors are stored relative to
+each category's base unit, so **every pair within a category works**, including
+combinations nobody thought to write down (`furlong` to `nmi`, `therm` to `eV`).
+
+| Category | Base | Units | Count |
+|---|---|---|---|
+| **Length** | `m` | `angstrom`, `au`, `chain`, `cm`, `dam`, `dm`, `fathom`, `ft`, `furlong`, `hm`, `in`, `km`, `ly`, `m`, `mi`, `mm`, `nm`, `nmi`, `pc`, `pm`, `rod`, `thou`, `um`, `yd` | 24 |
+| **Mass** | `kg` | `carat`, `g`, `grain`, `kg`, `lb`, `m_e`, `m_earth`, `m_sun`, `mg`, `oz`, `quintal`, `st`, `t`, `ton_uk`, `ton_us`, `u`, `ug` | 17 |
+| **Speed** | `m/s` | `c`, `cm/s`, `ft/s`, `km/h`, `kn`, `m/s`, `mm/s`, `mph` | 8 |
+| **Area** | `m2` | `ac`, `are`, `cm2`, `ft2`, `ha`, `in2`, `km2`, `m2`, `mi2`, `mm2`, `yd2` | 11 |
+| **Volume** | `m3` | `bbl`, `cL`, `cm3`, `cup_us`, `dL`, `floz_imp`, `floz_us`, `ft3`, `gal_imp`, `gal_us`, `in3`, `kL`, `km3`, `L`, `m3`, `mL`, `mm3`, `pt_imp`, `pt_us`, `qt_imp`, `qt_us`, `tbsp_us`, `tsp_us`, `uL`, `yd3` | 25 |
+| **Energy** | `J` | `BTU`, `cal`, `cal_it`, `erg`, `eV`, `ft_lbf`, `GeV`, `GJ`, `J`, `kcal`, `keV`, `kJ`, `kWh`, `MeV`, `MJ`, `mJ`, `MWh`, `therm`, `Wh` | 19 |
+| **Power** | `W` | `BTU/h`, `GW`, `hp`, `hp_metric`, `kW`, `MW`, `mW`, `TW`, `uW`, `W` | 10 |
+| **Temperature** | `kelvin` | `celsius`, `fahrenheit`, `kelvin`, `rankine` | 4 |
+| **Time** | `s` | `d`, `fortnight`, `h`, `min`, `ms`, `ns`, `ps`, `s`, `us`, `week`, `yr` | 11 |
+| **Pressure** | `Pa` | `atm`, `bar`, `GPa`, `hPa`, `inHg`, `kPa`, `mbar`, `mmHg`, `MPa`, `Pa`, `psi`, `torr` | 12 |
+| **Frequency** | `Hz` | `GHz`, `Hz`, `kHz`, `MHz`, `mHz`, `rpm`, `THz` | 7 |
+| **Digital storage** | `B` | `B`, `bit`, `GB`, `Gbit`, `GiB`, `kB`, `kbit`, `KiB`, `MB`, `Mbit`, `MiB`, `PB`, `PiB`, `TB`, `TiB` | 15 |
+| **Angle** | `rad` | `arcmin`, `arcsec`, `deg`, `grad`, `mrad`, `rad`, `turn` | 7 |
+| **Electric current** | `A` | `A`, `kA`, `mA`, `nA`, `pA`, `uA` | 6 |
+| **Electric potential** | `V` | `kV`, `MV`, `mV`, `nV`, `uV`, `V` | 6 |
+
+### Alternative spellings
+
+Long names, plurals and typeable forms of awkward symbols all resolve to the
+same unit — 390 aliases in total:
+
+```python
+pyconvert.convert(1, "kilometre", "mile")   # British or American spelling
+pyconvert.convert(1, "meters", "feet")      # plurals
+pyconvert.convert(5000, "m2", "hectare")    # ASCII for m^2
+pyconvert.convert(5000, "m²", "hectare")    # or the real character
+pyconvert.convert(100, "degC", "degF")      # ASCII for °C
+pyconvert.convert(100, "°C", "°F")          # or the real character
+pyconvert.convert(500, "μs", "ms")          # either Unicode micro sign
+```
+
+That last one matters more than it looks. The micro prefix is written two ways
+that are visually identical: MICRO SIGN (U+00B5), which is what a Mac's
+`Option-M` produces, and GREEK SMALL LETTER MU (U+03BC). They are different
+characters, so a dictionary treats them as different keys. Both map to the ASCII
+spelling (`us`, `um`, `ug`, `uA`, `uV`, `uW`, `uL`), as does the plain ASCII form.
+
+### Lookup is case-sensitive
+
+It has to be. These pairs are standard notation and differ only by case:
+
+| | | |
+|---|---|---|
+| `mW` milliwatt | `MW` megawatt | factor of 10⁹ |
+| `mHz` millihertz | `MHz` megahertz | factor of 10⁹ |
+| `mV` millivolt | `MV` megavolt | factor of 10⁹ |
+| `kB` kilobyte (1000) | `KiB` kibibyte (1024) | 2.4% apart |
+| `ps` picosecond | `PS` metric horsepower | different categories |
+
+Folding case would make those indistinguishable. Wrong case is caught and
+suggested back instead:
+
+```python
+>>> pyconvert.convert(1, "KM", "mi")
+UnknownUnitError: unknown unit 'KM' (did you mean 'km'?)
+```
+
+### Units this library refuses on purpose
+
+Some spellings have more than one real meaning, and resolving them to one
+arbitrary choice would return a confidently wrong number. These raise with the
+fix in the message rather than guessing:
+
+| Spelling | Why, and what to use |
+|---|---|
+| `C` | use 'celsius' or 'degC' (bare 'C' is the SI symbol for coulomb) |
+| `F` | use 'fahrenheit' or 'degF' (bare 'F' is the SI symbol for farad) |
+| `R` | use 'rankine' or 'degR' (bare 'R' is the symbol for roentgen) |
+| `b` | use 'bit' or 'B' (byte) -- 'b' and 'B' differ only by case |
+| `cal_cap` | use 'kcal' for the food Calorie, or 'cal' for the gram calorie |
+| `fl_ounce` | use 'floz_us' or 'floz_imp' |
+| `gb` | use 'Gbit' (10**9 bits) or 'GB' (10**9 bytes) |
+| `hp_imp` | use 'hp' (mechanical) or 'hp_metric' (PS) |
+| `kb` | use 'kbit' (1000 bits) or 'kB' (1000 bytes) |
+| `mb` | use 'Mbit' (10**6 bits) or 'MB' (10**6 bytes) |
+| `pt` | 'pt' is both point and pint: use 'pt_us' or 'pt_imp' for pints |
+| `tb` | use 'TB' (10**12 bytes) or 'TiB' (2**40 bytes) |
+| `ton` | 'ton' means three different masses: use 't' (tonne, 1000 kg), 'ton_us' (short, 907.18474 kg) or 'ton_uk' (long, 1016.0469088 kg) |
+| `tons` | see 'ton': use 't', 'ton_us' or 'ton_uk' |
+
+`C`, `F` and `R` are also kept free so that charge, capacitance and radiation
+can be added later without a breaking change.
+
+One default *is* chosen: bare `gal`, `gallon`, `quart`, `pint`, `cup`, `floz`,
+`tbsp` and `tsp` mean the **US** measures. The imperial ones are available
+explicitly as `gal_imp`, `qt_imp`, `pt_imp` and `floz_imp`.
+
+Where a unit has competing definitions, the one picked is documented:
+
+| Unit | This library uses | Also available |
+|---|---|---|
+| `cal` | thermochemical, 4.184 J exactly | `cal_it` (4.1868 J) |
+| `hp` | mechanical, 745.6998… W | `hp_metric` / `PS` (735.49875 W) |
+| `BTU` | International Table, 1055.05585262 J | — |
+| `yr` | Julian year, exactly 365.25 days | — |
+| `t` | tonne, 1000 kg | `ton_us`, `ton_uk` |
+
+## Number bases
+
+```python
+convert_base(number, from_base, to_base, precision=16) -> str
+```
+
+Bases 2 to 36. Input may be an `int` or a `str`, in either case, with
+underscores allowed as separators. Output digits are always uppercase.
+
+```python
+pyconvert.convert_base("ff", 16, 2)          # '11111111'
+pyconvert.convert_base("1111_1111", 2, 16)   # 'FF'
+pyconvert.convert_base(-255, 10, 16)         # '-FF'
+pyconvert.convert_base(1100100, 2, 10)       # '100'  (an int is read as its digits)
+```
+
+Fractional parts are converted exactly where the result terminates:
+
+```python
+pyconvert.convert_base("0.5", 10, 2)         # '0.1'
+pyconvert.convert_base("A.8", 16, 10)        # '10.5'
+pyconvert.convert_base("0.1", 10, 2)         # '0.0001100110011001'
+```
+
+That last result is truncated, not wrong — one tenth has no finite binary form,
+so it runs to `precision` digits and stops. Pass `precision` to change that.
+
+**The result is always a string**, including when the target base is 10. Once
+`'AF'` is a string, returning an `int` for base 10 alone would make the return
+*type* depend on an argument's *value*. Call `int(result)` when you want a
+number back.
+
+## Accuracy
+
+Factors that are exact by international definition are stored as exact rationals
+and rounded to `float` once, rather than being computed in floating point. The
+difference is small but real: `231 * 0.0254 ** 3` gives
+`0.0037854117839999997`, three roundings away from the correctly rounded
+`0.003785411784`.
+
+**Temperature is computed in exact rational arithmetic**, because it is the one
+category with an offset, and 5/9 has no finite binary form. In plain floats,
+`100 °C → °F` returns `211.99999999999997`. Here:
+
+```python
+pyconvert.convert(100, "celsius", "fahrenheit")    # 212.0  exactly
+pyconvert.convert(0,   "celsius", "fahrenheit")    # 32.0   exactly
+pyconvert.convert(-40, "celsius", "fahrenheit")    # -40.0  exactly
+pyconvert.convert(0,   "kelvin",  "fahrenheit")    # -459.67 exactly
+```
+
+Everything else uses a single float ratio, which is about ten times faster and
+is what nearly every conversion needs. Results are ordinary IEEE-754 doubles, so
+between two non-base units you can still see a last-digit artefact:
+`convert(1, "gal_imp", "L")` is `4.5460899999999995` rather than `4.54609`.
+Conversions *to* a category's base unit are exact.
+
+## Errors
+
+Everything this library raises derives from `PyConvertError`, so one `except`
+catches all of it. Each error also subclasses the builtin you would expect, so
+existing `except KeyError` or `except ValueError` code keeps working.
+
+```
+PyConvertError
+├── UnknownUnitError        (also KeyError)    unit not in the registry
+├── UnknownCategoryError    (also KeyError)    no such category
+├── IncompatibleUnitsError                     the two units measure different things
+├── InvalidBaseError        (also ValueError)  base outside 2-36
+├── InvalidDigitError       (also ValueError)  digit invalid for its base
+└── RegistryError           (also RuntimeError) the registry itself is inconsistent
+```
+
+`RegistryError` is raised at import time, never from a call. It means two
+categories claim the same symbol, or an alias points at a unit that does not
+exist — a bug in the library, not in your input.
+
+## Introspection
+
+```python
+pyconvert.list_categories()          # ['angle', 'area', 'current', ...]
+pyconvert.list_units("temperature")  # ['celsius', 'fahrenheit', 'kelvin', 'rankine']
+pyconvert.list_units()               # all 182 canonical symbols
+pyconvert.category_of("psi")         # 'pressure'
+pyconvert.base_unit("pressure")      # 'Pa'
+pyconvert.is_convertible("km", "kg") # False
+pyconvert.convert_all([0, 100], "celsius", "fahrenheit")   # [32.0, 212.0]
+```
+
+## Requirements
+
+Python 3.9 or newer. No third-party dependencies.
+
+## Development
+
+```bash
+git clone https://github.com/cobrapy-x/pyconvert-package.git
+cd pyconvert-package
+pip install -e ".[dev]"
+
+pytest          # 1072 tests, including the docstring examples
+ruff check .
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for how to add a unit, and the
+invariants the test suite enforces.
+
+## License
+
+MIT — see [LICENSE](LICENSE).