pyconvertx 1.0.0__py3-none-any.whl

pyconvert/__init__.py

@@ -0,0 +1,110 @@
+"""PyConvert -- a lightweight unit and number-base conversion library.
+
+Install as ``pyconvertx``, import as ``pyconvert``::
+
+    pip install pyconvertx
+
+Unit conversion takes a value and two unit symbols. There is no category
+argument: every symbol is unique across the registry, so the category is looked
+up for you, and converting across categories is an error rather than a wrong
+number.
+
+    >>> import pyconvert
+    >>> pyconvert.convert(100, "km", "mi")
+    62.13711922373339
+    >>> pyconvert.convert(100, "celsius", "fahrenheit")
+    212.0
+    >>> pyconvert.convert(1024, "MiB", "GiB")
+    1.0
+
+Number bases go from 2 to 36, and always come back as a string:
+
+    >>> pyconvert.convert_base(100, 10, 2)
+    '1100100'
+    >>> pyconvert.convert_base("FF", 16, 10)
+    '255'
+
+Lookup is case-sensitive, because it has to be -- ``mW`` is a milliwatt and
+``MW`` a megawatt, ``KB`` and ``KiB`` differ by 2.4%. Alternative spellings are
+handled by aliases instead, so ``kilometre``, ``kilometer`` and ``km`` all work,
+as do the typeable forms of awkward symbols (``m2`` for m2, ``degC`` for degC,
+``us`` for microseconds).
+"""
+
+from __future__ import annotations
+
+from .bases import DIGITS, MAX_BASE, MIN_BASE, convert_base
+from .exceptions import (
+    IncompatibleUnitsError,
+    InvalidBaseError,
+    InvalidDigitError,
+    PyConvertError,
+    RegistryError,
+    UnknownCategoryError,
+    UnknownUnitError,
+)
+from .registry import AMBIGUOUS, BASE_UNITS, CATEGORIES
+from .units import (
+    base_unit,
+    category_of,
+    convert,
+    convert_all,
+    is_convertible,
+    list_categories,
+    list_units,
+)
+
+__author__ = "cobrapy-x"
+__license__ = "MIT"
+
+__all__ = [
+    # unit conversion
+    "convert",
+    "convert_all",
+    "is_convertible",
+    # number bases
+    "convert_base",
+    "MIN_BASE",
+    "MAX_BASE",
+    "DIGITS",
+    # introspection
+    "list_categories",
+    "list_units",
+    "category_of",
+    "base_unit",
+    "CATEGORIES",
+    "BASE_UNITS",
+    "AMBIGUOUS",
+    # errors
+    "PyConvertError",
+    "UnknownUnitError",
+    "UnknownCategoryError",
+    "IncompatibleUnitsError",
+    "InvalidBaseError",
+    "InvalidDigitError",
+    "RegistryError",
+    # metadata
+    "__version__",
+]
+
+
+def __getattr__(name: str) -> str:
+    """Resolve ``__version__`` on first access rather than at import.
+
+    ``importlib.metadata`` is the only way to read the installed version, but
+    importing it costs around 12 ms -- more than half of this package's import
+    time -- because it pulls in ``email.message``. Almost nobody reads
+    ``__version__``, so it is looked up lazily and then cached in the module
+    namespace. See PEP 562 for module-level ``__getattr__``.
+    """
+    if name == "__version__":
+        try:
+            from importlib.metadata import version
+
+            resolved = version("pyconvertx")
+        except Exception:
+            # Running from a source checkout that was never pip-installed.
+            resolved = "0.0.0+source"
+        globals()["__version__"] = resolved
+        return resolved
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

pyconvert/bases.py

@@ -0,0 +1,199 @@
+"""Number-base conversion between any two bases from 2 to 36.
+
+The public entry point is :func:`convert_base`::
+
+    >>> convert_base(100, 10, 2)
+    '1100100'
+    >>> convert_base("10101111", 2, 16)
+    'AF'
+    >>> convert_base("FF", 16, 10)
+    '255'
+    >>> convert_base(1000, 10, 36)
+    'RS'
+
+The result is always a string, including when the target base is 10. A base-10
+result is a string too because that is the only answer type that is true for
+every base: once ``'AF'`` and ``'1100100'`` are strings, returning an ``int``
+for base 10 alone would make the return type depend on an argument's value.
+Call ``int(...)`` on it if you want a number back.
+
+This module is named ``bases`` rather than ``numbers`` because Python's standard
+library already has a ``numbers`` module -- the one holding ``numbers.Real``,
+which :mod:`pyconvert.units` imports.
+"""
+
+from __future__ import annotations
+
+from fractions import Fraction
+
+from .exceptions import InvalidBaseError, InvalidDigitError
+
+__all__ = ["DIGITS", "MAX_BASE", "MIN_BASE", "convert_base"]
+
+#: The digit alphabet: 0-9 then A-Z, which is what caps the base at 36.
+DIGITS = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ"
+
+MIN_BASE = 2
+MAX_BASE = 36
+
+#: Digit character -> value, accepting either case on input.
+_VALUES = {character: value for value, character in enumerate(DIGITS)}
+_VALUES.update({character.lower(): value for value, character in enumerate(DIGITS)})
+
+#: Default number of fractional digits produced for a non-terminating result.
+DEFAULT_PRECISION = 16
+
+
+def _check_base(base: object, argument: str) -> int:
+    """Validate a base, rejecting bools along with everything else non-integer."""
+    if isinstance(base, bool) or not isinstance(base, int):
+        raise InvalidBaseError(base, MIN_BASE, MAX_BASE)
+    if not MIN_BASE <= base <= MAX_BASE:
+        raise InvalidBaseError(base, MIN_BASE, MAX_BASE)
+    return base
+
+
+def _parse(number: object, base: int) -> Fraction:
+    """Read *number* in *base* and return its exact value as a ``Fraction``.
+
+    Exact on purpose: a fractional part converted through ``float`` would pick
+    up binary rounding error before the output digits are even generated.
+    """
+    if isinstance(number, str):
+        text = number.strip().replace("_", "")
+    elif isinstance(number, int) and not isinstance(number, bool):
+        # An int is read as its written digits, so convert_base(1100100, 2, 10)
+        # treats those digits as binary, matching the string form.
+        text = str(number)
+    else:
+        raise TypeError(
+            "number must be an int or a str, got "
+            f"{type(number).__name__}"
+            + (
+                " -- pass a fractional value as a string, e.g. '10.5'"
+                if isinstance(number, float)
+                else ""
+            )
+        )
+
+    sign = 1
+    if text[:1] in ("+", "-"):
+        if text[0] == "-":
+            sign = -1
+        text = text[1:]
+
+    if text.count(".") > 1:
+        raise InvalidDigitError(".", base, number)
+
+    whole_text, _, fraction_text = text.partition(".")
+    if not whole_text and not fraction_text:
+        raise InvalidDigitError(text, base, number)
+
+    total = Fraction(0)
+    for character in whole_text:
+        value = _VALUES.get(character)
+        if value is None or value >= base:
+            raise InvalidDigitError(character, base, number)
+        total = total * base + value
+
+    if fraction_text:
+        place = Fraction(1)
+        for character in fraction_text:
+            value = _VALUES.get(character)
+            if value is None or value >= base:
+                raise InvalidDigitError(character, base, number)
+            place /= base
+            total += value * place
+
+    return sign * total
+
+
+def _format(quantity: Fraction, base: int, precision: int) -> str:
+    """Render an exact *quantity* in *base*, to at most *precision* fraction digits."""
+    sign = "-" if quantity < 0 else ""
+    quantity = abs(quantity)
+
+    whole = quantity.numerator // quantity.denominator
+    remainder = quantity - whole
+
+    if whole == 0:
+        digits = "0"
+    else:
+        collected = []
+        while whole:
+            whole, digit = divmod(whole, base)
+            collected.append(DIGITS[digit])
+        digits = "".join(reversed(collected))
+
+    if remainder:
+        collected = []
+        for _ in range(precision):
+            remainder *= base
+            digit = remainder.numerator // remainder.denominator
+            collected.append(DIGITS[digit])
+            remainder -= digit
+            if remainder == 0:
+                break
+        fraction_digits = "".join(collected).rstrip("0")
+        if fraction_digits:
+            digits += "." + fraction_digits
+
+    return sign + digits
+
+
+def convert_base(
+    number: int | str,
+    from_base: int,
+    to_base: int,
+    precision: int = DEFAULT_PRECISION,
+) -> str:
+    """Convert *number* from one base to another and return a string.
+
+    *number* is an ``int`` or a ``str``. Input digits may be either case;
+    output digits are always uppercase. Underscores are allowed as separators,
+    as in Python's own numeric literals.
+
+    >>> convert_base(100, 10, 2)
+    '1100100'
+    >>> convert_base("10101111", 2, 16)
+    'AF'
+    >>> convert_base("FF", 16, 10)
+    '255'
+    >>> convert_base(1000, 10, 36)
+    'RS'
+
+    Lowercase input and separators are fine, and so are negatives:
+
+    >>> convert_base("ff", 16, 2)
+    '11111111'
+    >>> convert_base("1111_1111", 2, 16)
+    'FF'
+    >>> convert_base(-255, 10, 16)
+    '-FF'
+
+    Fractional parts are converted too, exactly where the result terminates:
+
+    >>> convert_base("0.5", 10, 2)
+    '0.1'
+    >>> convert_base("A.8", 16, 10)
+    '10.5'
+    >>> 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.
+
+    >>> convert_base("0.1", 10, 2, precision=4)
+    '0.0001'
+
+    :param precision: maximum fractional digits for a non-terminating result.
+    :raises InvalidBaseError: if either base is not an integer from 2 to 36.
+    :raises InvalidDigitError: if a digit is not valid in *from_base*.
+    :raises TypeError: if *number* is neither an ``int`` nor a ``str``.
+    """
+    _check_base(from_base, "from_base")
+    _check_base(to_base, "to_base")
+    if isinstance(precision, bool) or not isinstance(precision, int) or precision < 0:
+        raise ValueError(f"precision must be a non-negative integer, got {precision!r}")
+
+    return _format(_parse(number, from_base), to_base, precision)

pyconvert/exceptions.py

@@ -0,0 +1,139 @@
+"""Exception hierarchy for PyConvert.
+
+Every error raised by this library derives from :class:`PyConvertError`, so a
+caller who does not care about the distinction can write::
+
+    try:
+        pyconvert.convert(1, "kg", "m")
+    except pyconvert.PyConvertError as exc:
+        print(exc)
+"""
+
+from __future__ import annotations
+
+import difflib
+
+__all__ = [
+    "IncompatibleUnitsError",
+    "InvalidBaseError",
+    "InvalidDigitError",
+    "PyConvertError",
+    "RegistryError",
+    "UnknownCategoryError",
+    "UnknownUnitError",
+]
+
+
+class PyConvertError(Exception):
+    """Base class for every error raised by PyConvert."""
+
+
+class UnknownUnitError(PyConvertError, KeyError):
+    """A unit symbol is not present in the registry.
+
+    Also inherits :class:`KeyError` so that code written against a plain dict
+    lookup keeps working.
+    """
+
+    def __init__(
+        self,
+        unit: object,
+        known: list[str] | None = None,
+        hint: str | None = None,
+    ) -> None:
+        self.unit = unit
+        self.hint = hint
+        self.suggestions: list[str] = []
+        message = f"unknown unit {unit!r}"
+
+        if hint:
+            # A spelling the registry refuses on purpose, because it is
+            # ambiguous. Say what to write instead; skip fuzzy matching, which
+            # would only offer something unrelated that happens to look close.
+            super().__init__(f"{message}: {hint}")
+            return
+
+        if known and isinstance(unit, str):
+            # Case-insensitive near misses first: "KM" -> "km" is the single
+            # most common mistake, and a case-sensitive ratio misses it.
+            lowered = {k.lower(): k for k in known}
+            if unit.lower() in lowered and lowered[unit.lower()] != unit:
+                self.suggestions = [lowered[unit.lower()]]
+            else:
+                self.suggestions = difflib.get_close_matches(
+                    unit, known, n=3, cutoff=0.6
+                )
+
+        if self.suggestions:
+            offered = " or ".join(repr(s) for s in self.suggestions)
+            message += f" (did you mean {offered}?)"
+
+        super().__init__(message)
+
+    def __str__(self) -> str:  # KeyError.__str__ would re-quote the message
+        return self.args[0]
+
+
+class UnknownCategoryError(PyConvertError, KeyError):
+    """A category name is not one of the registry's categories."""
+
+    def __init__(self, category: object, known: list[str] | None = None) -> None:
+        self.category = category
+        message = f"unknown category {category!r}"
+        if known:
+            message += " (available: " + ", ".join(sorted(known)) + ")"
+        super().__init__(message)
+
+    def __str__(self) -> str:
+        return self.args[0]
+
+
+class IncompatibleUnitsError(PyConvertError):
+    """Two units are both valid but measure different kinds of quantity."""
+
+    def __init__(
+        self,
+        source: str,
+        target: str,
+        source_category: str,
+        target_category: str,
+    ) -> None:
+        self.source = source
+        self.target = target
+        self.source_category = source_category
+        self.target_category = target_category
+        super().__init__(
+            f"cannot convert {source!r} to {target!r}: "
+            f"{source!r} measures {source_category}, "
+            f"{target!r} measures {target_category}"
+        )
+
+
+class InvalidBaseError(PyConvertError, ValueError):
+    """A numeric base is outside the supported range."""
+
+    def __init__(self, base: object, low: int = 2, high: int = 36) -> None:
+        self.base = base
+        super().__init__(f"base must be an integer from {low} to {high}, got {base!r}")
+
+
+class InvalidDigitError(PyConvertError, ValueError):
+    """A digit in the input is not valid for the base it was given in."""
+
+    def __init__(self, digit: str, base: int, number: object = None) -> None:
+        self.digit = digit
+        self.base = base
+        self.number = number
+        if not digit:
+            super().__init__(f"no digits to convert in {number!r}")
+        else:
+            super().__init__(f"{digit!r} is not a valid digit in base {base}")
+
+
+class RegistryError(PyConvertError, RuntimeError):
+    """The unit registry itself is inconsistent.
+
+    Raised at import time, not at call time: it means two categories claim the
+    same symbol, or an alias points at a unit that does not exist. This is a bug
+    in PyConvert (or in a locally edited registry), never in user input.
+    """