pyunit/
├─ README.md
├─ pyproject.toml
├─ .pre-commit-config.yaml
├─ src/
│  └─ pyunit/
│     ├─ __init__.py
│     ├─ cli.py
│     ├─ convert.py
│     ├─ config.py
│     └─ history.py
└─ tests/
   ├─ test_convert.py
   ├─ test_cli.py
   └─ data/

# pyunit — A simple, testable CLI unit converter

pyunit converts between common units for length, mass, and temperature. It demonstrates solid Python fundamentals: CLI design, control flow, file I/O, configuration, packaging, and testing.

## Features
- Convert length, mass, temperature with clear errors for unsupported pairs
- CLI with `argparse` and helpful `--help`
- Config file for defaults (precision, default from/to units)
- JSON history log for every conversion with timestamps
- Packaged with `pyproject.toml` and console script entry point
- Test suite with `pytest` and property-based tests for temperature sanity
- Optional: currency via pluggable provider interface (mock adapter by default)

## Quick start

## Configuration
pyunit looks for a config file in this order:
1. `--config /path/to/config.toml` if provided
2. `PYUNIT_CONFIG` env var
3. `~/.config/pyunit/config.toml` (Linux/macOS) or `%APPDATA%\\pyunit\\config.toml` (Windows)

Example `config.toml`:

## History log
A JSON Lines file records each conversion:
- Default location: `~/.local/share/pyunit/history.jsonl` (Linux/macOS) or `%APPDATA%\\pyunit\\history.jsonl` (Windows)
- One record per line with ISO timestamp, from unit, to unit, input value, output value

## Units supported
- Length: m, km, cm, mm, in, ft, yd, mi
- Mass: g, kg, lb, oz
- Temperature: C, F, K

Unsupported pairs return a clear error. Temperature conversions are nonlinear and handled specially.

## Design
- `convert.py` — conversion registry and algorithms
- `config.py` — config discovery and parsing (TOML)
- `history.py` — append-only JSONL logger
- `cli.py` — argument parsing, I/O, and wiring

## Testing

Key tests:
- Numeric stability and round-trip sanity for temperature
- Known reference conversions for length and mass
- CLI argument validation and error messages

## Development
- Formatting and linting are managed via `pre-commit`

## Roadmap
- Currency conversion via provider interface
- Interactive mode with prompt and history search
- Additional unit systems and custom user-defined units

[build-system]
requires = ["setuptools>=68", "wheel"]
build-backend = "setuptools.build_meta"

[project]
name = "pyunit"
version = "0.1.0"
description = "A simple, testable CLI unit converter"
authors = [{ name = "Teslim Adeyanju" }]
requires-python = ">=3.10"
readme = "README.md"
license = { text = "MIT" }
dependencies = [
  "tomli; python_version < '3.11'"
]

[project.optional-dependencies]
dev = [
  "pytest>=7.0",
  "pytest-cov>=4.1",
  "hypothesis>=6.0",
  "ruff>=0.5.0",
]

[project.scripts]
pyunit = "pyunit.cli:main"

[tool.setuptools]
package-dir = {"" = "src"}

[tool.setuptools.packages.find]
where = ["src"]

[tool.ruff]
line-length = 100
select = ["E", "F", "I"]

repos:
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.5.7
    hooks:
      - id: ruff
        args: ["--fix"]
  - repo: https://github.com/psf/black
    rev: 24.8.0
    hooks:
      - id: black
        language_version: python3

__all__ = ["convert", "config", "history"]

from __future__ import annotations
from typing import Callable, Dict, Tuple

# --- Length conversions relative to meters ---
_LENGTH_TO_M = {
    "m": 1.0,
    "km": 1000.0,
    "cm": 0.01,
    "mm": 0.001,
    "in": 0.0254,
    "ft": 0.3048,
    "yd": 0.9144,
    "mi": 1609.344,
}

# --- Mass conversions relative to grams ---
_MASS_TO_G = {
    "g": 1.0,
    "kg": 1000.0,
    "lb": 453.59237,
    "oz": 28.349523125,
}

# Temperature conversions use explicit formulas

def _c_to_f(x: float) -> float: return x * 9.0 / 5.0 + 32.0

def _f_to_c(x: float) -> float: return (x - 32.0) * 5.0 / 9.0

def _c_to_k(x: float) -> float: return x + 273.15

def _k_to_c(x: float) -> float: return x - 273.15

def _f_to_k(x: float) -> float: return _c_to_k(_f_to_c(x))

def _k_to_f(x: float) -> float: return _c_to_f(_k_to_c(x))

_TEMP_FUNCS: Dict[Tuple[str, str], Callable[[float], float]] = {
    ("C", "F"): _c_to_f,
    ("F", "C"): _f_to_c,
    ("C", "K"): _c_to_k,
    ("K", "C"): _k_to_c,
    ("F", "K"): _f_to_k,
    ("K", "F"): _k_to_f,
}

_LENGTH_UNITS = set(_LENGTH_TO_M.keys())
_MASS_UNITS = set(_MASS_TO_G.keys())
_TEMP_UNITS = {"C", "F", "K"}

class ConversionError(ValueError):
    pass


def convert(value: float, unit_from: str, unit_to: str) -> float:
    """Convert value from unit_from to unit_to.

    Supports length (m, km, cm, mm, in, ft, yd, mi), mass (g, kg, lb, oz), and
    temperature (C, F, K). Raises ConversionError for unsupported pairs.
    """
    uf, ut = unit_from.strip(), unit_to.strip()

    # Temperature
    if uf in _TEMP_UNITS and ut in _TEMP_UNITS:
        if uf == ut:
            return float(value)
        try:
            return float(_TEMP_FUNCS[(uf, ut)](float(value)))
        except KeyError as exc:
            raise ConversionError(f"Unsupported temperature conversion: {uf} -> {ut}") from exc

    # Length
    if uf in _LENGTH_UNITS and ut in _LENGTH_UNITS:
        # to base (meters) then to target
        meters = float(value) * _LENGTH_TO_M[uf]
        return meters / _LENGTH_TO_M[ut]

    # Mass
    if uf in _MASS_UNITS and ut in _MASS_UNITS:
        grams = float(value) * _MASS_TO_G[uf]
        return grams / _MASS_TO_G[ut]

    raise ConversionError(f"Unsupported conversion: {uf} -> {ut}")

from __future__ import annotations
import os
from dataclasses import dataclass
from pathlib import Path
from typing import Optional, Dict, Any

try:
    import tomllib  # Python 3.11+
except ModuleNotFoundError:  # pragma: no cover
    import tomli as tomllib

XDG_CONFIG = Path(os.environ.get("XDG_CONFIG_HOME", Path.home() / ".config"))
APPDATA = Path(os.environ.get("APPDATA", XDG_CONFIG))

DEFAULT_CONFIG_PATHS = [
    Path(os.environ.get("PYUNIT_CONFIG", "")),
    XDG_CONFIG / "pyunit" / "config.toml",
    APPDATA / "pyunit" / "config.toml",
]

@dataclass
class Settings:
    precision: int = 3
    default_from: Optional[str] = None
    default_to: Optional[str] = None

    @classmethod
    def from_dict(cls, data: Dict[str, Any]) -> "Settings":
        d = data.get("defaults", {}) if isinstance(data, dict) else {}
        return cls(
            precision=int(d.get("precision", 3)),
            default_from=d.get("from"),
            default_to=d.get("to"),
        )


def load_settings(explicit_path: Optional[Path] = None) -> Settings:
    candidates = []
    if explicit_path:
        candidates.append(Path(explicit_path))
    candidates.extend(DEFAULT_CONFIG_PATHS)
    for p in candidates:
        if not p:
            continue
        if Path(p).is_file():
            with open(p, "rb") as f:
                return Settings.from_dict(tomllib.load(f))
    return Settings()

from __future__ import annotations
import json
import os
from dataclasses import dataclass, asdict
from datetime import datetime, timezone
from pathlib import Path

XDG_DATA = Path(os.environ.get("XDG_DATA_HOME", Path.home() / ".local" / "share"))
APPDATA = Path(os.environ.get("APPDATA", XDG_DATA))
DEFAULT_HISTORY = XDG_DATA / "pyunit" / "history.jsonl"
WINDOWS_HISTORY = APPDATA / "pyunit" / "history.jsonl"

@dataclass
class Record:
    ts: str
    unit_from: str
    unit_to: str
    value_in: float
    value_out: float


def _history_path() -> Path:
    # Prefer Windows APPDATA when available
    if os.name == "nt":
        return WINDOWS_HISTORY
    return DEFAULT_HISTORY


def append_record(unit_from: str, unit_to: str, value_in: float, value_out: float) -> None:
    path = _history_path()
    path.parent.mkdir(parents=True, exist_ok=True)
    rec = Record(
        ts=datetime.now(timezone.utc).isoformat(),
        unit_from=unit_from,
        unit_to=unit_to,
        value_in=float(value_in),
        value_out=float(value_out),
    )
    with open(path, "a", encoding="utf-8") as f:
        f.write(json.dumps(asdict(rec)) + "\n")

from __future__ import annotations
import argparse
import sys
from .convert import convert, ConversionError
from .config import load_settings
from .history import append_record


def build_parser() -> argparse.ArgumentParser:
    p = argparse.ArgumentParser(prog="pyunit", description="CLI unit converter")
    p.add_argument("--from", dest="unit_from", required=False, help="source unit e.g. m, C, kg")
    p.add_argument("--to", dest="unit_to", required=False, help="target unit e.g. ft, F, lb")
    p.add_argument("--value", type=float, required=False, help="numeric value to convert")
    p.add_argument("--precision", type=int, help="decimal places for output")
    p.add_argument("--config", type=str, help="path to config.toml")
    return p


def main(argv: list[str] | None = None) -> int:
    argv = argv or sys.argv[1:]
    parser = build_parser()
    args = parser.parse_args(argv)

    settings = load_settings(args.config)

    unit_from = args.unit_from or settings.default_from
    unit_to = args.unit_to or settings.default_to
    if unit_from is None or unit_to is None:
        parser.error("--from/--to required (or set defaults in config)")

    if args.value is None:
        parser.error("--value is required")

    precision = args.precision if args.precision is not None else settings.precision

    try:
        out = convert(args.value, unit_from, unit_to)
    except ConversionError as e:
        print(f"Error: {e}", file=sys.stderr)
        return 2

    append_record(unit_from, unit_to, args.value, out)
    print(f"{out:.{precision}f}")
    return 0


if __name__ == "__main__":  # pragma: no cover
    raise SystemExit(main())

from __future__ import annotations
import pytest
from pyunit.convert import convert, ConversionError


def test_length_reference_cases():
    assert pytest.approx(convert(1, "m", "cm"), rel=1e-12) == 100
    assert pytest.approx(convert(1, "km", "m"), rel=1e-12) == 1000
    assert pytest.approx(convert(1, "ft", "in"), rel=1e-12) == 12


def test_mass_reference_cases():
    assert pytest.approx(convert(1000, "g", "kg"), rel=1e-12) == 1
    assert pytest.approx(convert(16, "oz", "lb"), rel=1e-12) == 1


def test_temperature_round_trip():
    # C -> F -> C round-trip
    c = 37.5
    f = convert(c, "C", "F")
    back = convert(f, "F", "C")
    assert pytest.approx(back, abs=1e-9) == c

    # K -> C -> K round-trip
    k = 250.0
    c2 = convert(k, "K", "C")
    back2 = convert(c2, "C", "K")
    assert pytest.approx(back2, abs=1e-9) == k


def test_unsupported_pair():
    with pytest.raises(ConversionError):
        convert(1, "m", "kg")

from __future__ import annotations
import sys
import subprocess

# We invoke the module directly so an editable install isn't mandatory for tests.

def run_cli(args):
    return subprocess.run([sys.executable, "-m", "pyunit.cli", *args], capture_output=True, text=True)


def test_cli_basic_success(tmp_path):
    cfg = tmp_path / "config.toml"
    cfg.write_text(
        """
[defaults]
precision = 2
from = "m"
to = "ft"
""".strip()
    )
    res = run_cli(["--value", "3", "--config", str(cfg)])
    assert res.returncode == 0
    assert res.stdout.strip()  # numeric output present


def test_cli_requires_args(tmp_path):
    res = run_cli(["--value", "2"])  # missing from/to and no config
    assert res.returncode != 0 or "required" in res.stderr.lower()