bytesz 0.2.0__py3-none-any.whl

bytesz/__init__.py

@@ -0,0 +1,44 @@
+"""Strict two-way conversion between byte counts and human sizes with explicit IEC and SI units.
+
+``parse`` turns "1.5 MiB" into 1572864 and ``format`` turns 1572864 back into
+"1.5 MiB". The unit alone decides the system: IEC units (KiB, MiB) are powers of
+1024 and SI units (kB, MB) are powers of 1000. Ambiguous spellings such as "KB"
+are rejected unless the caller opts into the legacy reading.
+"""
+
+from __future__ import annotations
+
+from ._bits import format_bits, parse_bits
+from ._convert import convert
+from ._errors import (
+    AmbiguousUnitError,
+    ByteszError,
+    FractionalBytesError,
+    InvalidSizeError,
+    SystemMismatchError,
+    UnknownUnitError,
+)
+from ._format import format
+from ._parse import parse
+from ._types import Rounding, System
+from ._units import IEC_SUFFIXES, SI_SUFFIXES
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "IEC_SUFFIXES",
+    "SI_SUFFIXES",
+    "AmbiguousUnitError",
+    "ByteszError",
+    "FractionalBytesError",
+    "InvalidSizeError",
+    "Rounding",
+    "System",
+    "SystemMismatchError",
+    "UnknownUnitError",
+    "convert",
+    "format",
+    "format_bits",
+    "parse",
+    "parse_bits",
+]

bytesz/__main__.py

@@ -0,0 +1,10 @@
+"""Allow ``python -m bytesz``."""
+
+from __future__ import annotations
+
+import sys
+
+from ._cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

bytesz/_bits.py

@@ -0,0 +1,81 @@
+"""Bit counts: the same two systems with the "bit" unit symbol."""
+
+from __future__ import annotations
+
+from ._format import _check_count, _render
+from ._hints import BYTE_SYMBOLS, bit_hint
+from ._parse import _parse_with
+from ._types import Rounding, System
+from ._units import IEC_BIT_UNITS, SI_BIT_UNITS, UPPER_BIT_UNITS
+
+
+def format_bits(
+    count: int,
+    *,
+    system: System | None = None,
+    precision: int = 2,
+    rounding: Rounding = "half-up",
+    unit: str | None = None,
+    signed: bool = False,
+    trailing_zeros: bool = False,
+    decimal_point: str = ".",
+    separator: str = " ",
+) -> str:
+    """Convert a bit count into a human size such as "1.5 Mibit" or "1.5 Mbit".
+
+    Takes the same options as :func:`bytesz.format`. Units are written with the
+    unambiguous "bit" symbol (bit, Kibit, Mibit ... or bit, kbit, Mbit ...).
+
+    >>> format_bits(1_500_000, system="si")
+    '1.5 Mbit'
+    >>> format_bits(1024)
+    '1 Kibit'
+    """
+    return _render(
+        _check_count(count, signed),
+        bits=True,
+        system=system,
+        precision=precision,
+        rounding=rounding,
+        unit=unit,
+        trailing_zeros=trailing_zeros,
+        decimal_point=decimal_point,
+        separator=separator,
+    )
+
+
+def parse_bits(
+    text: str,
+    *,
+    system: System | None = None,
+    rounding: Rounding | None = None,
+    signed: bool = False,
+    decimal_point: str = ".",
+) -> int:
+    """Convert a human bit size such as "100 Mbit" or "1.5 Mib" into a bit count.
+
+    Accepts the "bit" symbol (kbit, Mibit) and the short "b" symbol (kb, Mb, Kib).
+    A bare number, "b" or "bit" is a count of bits. Upper case "Kb" is rejected as
+    ambiguous, just like "KB" in :func:`bytesz.parse`. The other options behave
+    exactly as in :func:`bytesz.parse`.
+
+    >>> parse_bits("100 Mbit")
+    100000000
+    >>> parse_bits("1 Kib")
+    1024
+    """
+    return _parse_with(
+        text,
+        iec=IEC_BIT_UNITS,
+        si=SI_BIT_UNITS,
+        extra={},
+        si_pinned={},
+        upper=UPPER_BIT_UNITS,
+        foreign=BYTE_SYMBOLS,
+        hint=bit_hint,
+        what="bits",
+        system=system,
+        rounding=rounding,
+        signed=signed,
+        decimal_point=decimal_point,
+    )

bytesz/_cli.py

@@ -0,0 +1,163 @@
+"""Command line interface: ``bytesz format`` and ``bytesz parse``."""
+
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from collections.abc import Callable, Sequence
+
+from . import __version__
+from ._bits import format_bits, parse_bits
+from ._cli_support import INTEGER, check_usage, cli_words, inputs, stop_on_closed_pipe
+from ._errors import ByteszError
+from ._format import format as format_size
+from ._parse import parse
+from ._types import ROUNDING_MODES
+
+_EPILOG = """\
+examples:
+  bytesz format 1572864                 # 1.5 MiB
+  bytesz format --system si 1234567     # 1.23 MB
+  bytesz format --unit MiB 1000000      # 0.95 MiB
+  bytesz parse "1.5 MiB" 2GB            # 1572864 and 2000000000
+  bytesz parse --legacy 4KB             # 4096
+  bytesz parse --bits 100Mbit           # 100000000
+  du -b * | bytesz format --field 1     # rewrite the first column, like numfmt
+
+Values come from the arguments, or one per line from stdin when there are none.
+With --field N only the Nth whitespace separated field of each line is converted
+and the rest of the line is kept as it is. Errors go to stderr with exit status 1.
+"""
+
+
+def _common(sub: argparse.ArgumentParser) -> None:
+    sub.add_argument("values", nargs="*", help="values to convert (default: read stdin)")
+    sub.add_argument("--rounding", choices=sorted(ROUNDING_MODES), help="rounding mode")
+    sub.add_argument("--signed", action="store_true", help="allow negative values")
+    sub.add_argument(
+        "--decimal-point",
+        default=".",
+        choices=[".", ","],
+        metavar="{.|,}",
+        help="decimal separator: . (default) or ,",
+    )
+    sub.add_argument("--bits", action="store_true", help="count bits instead of bytes")
+    sub.add_argument("--field", type=int, metavar="N", help="convert only field N (1 based)")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Return the argument parser for the ``bytesz`` command."""
+    parser = argparse.ArgumentParser(
+        prog="bytesz",
+        description="Convert byte counts to and from human sizes (IEC KiB or SI kB).",
+        epilog=_EPILOG,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument("--version", action="version", version=f"bytesz {__version__}")
+    subs = parser.add_subparsers(dest="command", required=True, metavar="{format,parse}")
+    fmt = subs.add_parser(
+        "format",
+        help="byte count to human size",
+        epilog=_EPILOG,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    fmt.add_argument("--system", choices=["iec", "si"], help="default: from --unit, else iec")
+    fmt.add_argument("--precision", type=int, default=2, help="decimals (default: 2)")
+    fmt.add_argument("--unit", help="force one unit, such as MiB")
+    fmt.add_argument("--trailing-zeros", action="store_true", help="keep zeros, as in 1.50")
+    fmt.add_argument("--separator", default=" ", help="text between number and unit")
+    _common(fmt)
+    par = subs.add_parser(
+        "parse",
+        help="human size to byte count",
+        epilog=_EPILOG,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    par.add_argument("--system", choices=["iec", "si"], help="accept only this system")
+    par.add_argument("--legacy", action="store_true", help="read KB, MB, GB as powers of 1024")
+    _common(par)
+    return parser
+
+
+def _converter(args: argparse.Namespace) -> Callable[[str], str]:
+    if args.command == "format":
+        render = format_bits if args.bits else format_size
+
+        def convert_format(token: str) -> str:
+            token = token.strip()
+            if not INTEGER.fullmatch(token):
+                raise ByteszError(f"not an integer count: {token!r}")
+            if token.startswith("+") and not args.signed:
+                raise ByteszError(f"{token!r} has a sign; pass --signed to allow it")
+            return render(
+                int(token),
+                system=args.system,
+                precision=args.precision,
+                rounding=args.rounding or "half-up",
+                unit=args.unit,
+                signed=args.signed,
+                trailing_zeros=args.trailing_zeros,
+                decimal_point=args.decimal_point,
+                separator=args.separator,
+            )
+
+        return convert_format
+
+    def convert_parse(token: str) -> str:
+        if args.bits:
+            value = parse_bits(
+                token,
+                system=args.system,
+                rounding=args.rounding,
+                signed=args.signed,
+                decimal_point=args.decimal_point,
+            )
+        else:
+            value = parse(
+                token,
+                system=args.system,
+                rounding=args.rounding,
+                signed=args.signed,
+                decimal_point=args.decimal_point,
+                legacy=args.legacy,
+            )
+        return str(value)
+
+    return convert_parse
+
+
+def _replace_field(line: str, field: int, convert: Callable[[str], str]) -> str:
+    if not line.strip():
+        return line
+    spans = [m.span() for m in re.finditer(r"\S+", line)]
+    if field > len(spans):
+        raise ByteszError(f"line has no field {field}: {line!r}")
+    start, end = spans[field - 1]
+    return line[:start] + convert(line[start:end]) + line[end:]
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Run the command line interface and return the exit status."""
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    check_usage(parser, args)
+    convert = _converter(args)
+    try:
+        for item in inputs(args.values, sys.stdin):
+            field = args.field
+            if not item.strip():
+                out = item  # blank lines pass through
+            elif field is None:
+                out = convert(item)
+            else:
+                out = _replace_field(item, field, convert)
+            sys.stdout.write(out + "\n")
+        sys.stdout.flush()
+    except (ByteszError, ValueError) as error:
+        sys.stdout.flush()
+        sys.stderr.write(f"bytesz: error: {cli_words(str(error))}\n")
+        return 1
+    except OSError as error:
+        return stop_on_closed_pipe(error)
+    return 0

bytesz/_cli_support.py

@@ -0,0 +1,74 @@
+"""Helpers for the command line: input lines, usage checks, wording, closed pipes."""
+
+from __future__ import annotations
+
+import argparse
+import errno
+import os
+import re
+import sys
+from collections.abc import Iterator, Sequence
+from typing import Final, TextIO
+
+from ._units import IEC_BIT_SUFFIXES, IEC_SUFFIXES, SI_BIT_SUFFIXES, SI_SUFFIXES
+
+INTEGER: Final = re.compile(r"[+-]?[0-9]+")
+
+_UNITS: Final[dict[tuple[bool, str | None], tuple[str, ...]]] = {
+    (False, "iec"): IEC_SUFFIXES,
+    (False, "si"): SI_SUFFIXES,
+    (False, None): IEC_SUFFIXES + SI_SUFFIXES[1:],
+    (True, "iec"): IEC_BIT_SUFFIXES,
+    (True, "si"): SI_BIT_SUFFIXES,
+    (True, None): IEC_BIT_SUFFIXES + SI_BIT_SUFFIXES[1:],
+}
+
+# Library messages name keyword arguments; the command line names flags.
+_CLI_WORDS: Final = (
+    ("signed=True", "--signed"),
+    ("legacy=True", "--legacy"),
+    ("system='si'", "--system si"),
+    ("system='iec'", "--system iec"),
+    ("system is 'si'", "--system is si"),
+    ("system is 'iec'", "--system is iec"),
+    ("use parse_bits for bits", "add --bits for bits"),
+    ("see parse_bits", "see --bits"),
+    ("use parse for bytes", "drop --bits for bytes"),
+)
+
+
+def inputs(values: Sequence[str], stdin: TextIO) -> Iterator[str]:
+    """Yield the argument values, or each stdin line without its line end or a BOM."""
+    if values:
+        yield from values
+        return
+    for number, line in enumerate(stdin):
+        yield (line.removeprefix("\ufeff") if number == 0 else line).rstrip("\r\n")
+
+
+def cli_words(message: str) -> str:
+    """Say option names the way the command line spells them."""
+    for api, flag in _CLI_WORDS:
+        message = message.replace(api, flag)
+    return message
+
+
+def check_usage(parser: argparse.ArgumentParser, args: argparse.Namespace) -> None:
+    """Reject bad option values as usage errors (exit status 2)."""
+    if args.field is not None and args.field < 1:
+        parser.error("--field must be 1 or more")
+    if args.command != "format":
+        return
+    if args.precision < 0:
+        parser.error("--precision must be 0 or more")
+    units = _UNITS[(args.bits, args.system)]
+    if args.unit is not None and args.unit not in units:
+        parser.error(f"--unit {args.unit!r} is not one of: {', '.join(units)}")
+
+
+def stop_on_closed_pipe(error: OSError) -> int:
+    """Stop quietly when the reader went away (``| head``), as Python's docs advise."""
+    if not isinstance(error, BrokenPipeError) and error.errno not in (errno.EPIPE, errno.EINVAL):
+        raise error
+    os.dup2(os.open(os.devnull, os.O_WRONLY), sys.stdout.fileno())
+    return 1

bytesz/_convert.py

@@ -0,0 +1,50 @@
+"""Exact conversion of a byte or bit count into one named unit."""
+
+from __future__ import annotations
+
+from decimal import Decimal
+
+from ._errors import InvalidSizeError, UnknownUnitError
+from ._format import _exact
+from ._units import (
+    IEC_BASE,
+    IEC_BIT_SUFFIXES,
+    IEC_SUFFIXES,
+    SI_BASE,
+    SI_BIT_SUFFIXES,
+    SI_SUFFIXES,
+)
+
+_UNITS: dict[str, tuple[int, int]] = {
+    **{unit: (IEC_BASE, exp) for exp, unit in enumerate(IEC_SUFFIXES)},
+    **{unit: (SI_BASE, exp) for exp, unit in enumerate(SI_SUFFIXES)},
+    **{unit: (IEC_BASE, exp) for exp, unit in enumerate(IEC_BIT_SUFFIXES)},
+    **{unit: (SI_BASE, exp) for exp, unit in enumerate(SI_BIT_SUFFIXES)},
+}
+
+
+def convert(count: int, unit: str) -> Decimal:
+    """Return ``count`` expressed in ``unit`` as an exact :class:`~decimal.Decimal`.
+
+    ``unit`` is any IEC or SI byte unit ("KiB", "MB", "QiB") or bit unit ("Mibit",
+    "kbit"); for a bit unit, ``count`` is a number of bits. Nothing is rounded:
+    every power of 1000 or 1024 divides into a terminating decimal. Negative counts
+    are allowed because the result is a plain number, not a size label.
+
+    >>> convert(1536, "KiB")
+    Decimal('1.5')
+    >>> convert(1, "KiB")
+    Decimal('0.0009765625')
+    """
+    if isinstance(count, bool) or not isinstance(count, int):
+        raise InvalidSizeError("count must be an int")
+    if unit not in _UNITS:
+        raise UnknownUnitError(f"unknown size unit {unit!r}", unit=unit)
+    base, exponent = _UNITS[unit]
+    if count == 0:
+        return Decimal(0)
+    # Plain notation: keep integer digits, drop only zeros after the point.
+    text = f"{_exact(count, base, exponent):f}"
+    if "." in text:
+        text = text.rstrip("0").rstrip(".")
+    return Decimal(text)

bytesz/_errors.py

@@ -0,0 +1,42 @@
+"""Exceptions raised by bytesz.
+
+Every input error is a ``ValueError`` through :class:`ByteszError`, so callers
+that only care about "bad input" can catch one class. Bad option values raise a
+plain ``ValueError`` and a non-string input raises ``TypeError``. The narrower classes carry the
+offending ``text`` and ``unit`` for messages and logs.
+"""
+
+from __future__ import annotations
+
+
+class ByteszError(ValueError):
+    """Base class for every error raised by bytesz.
+
+    ``text`` is the input that failed, when there was one, and ``unit`` the unit
+    involved, when there was one. Both default to ``None``.
+    """
+
+    def __init__(self, message: str, *, text: str | None = None, unit: str | None = None) -> None:
+        super().__init__(message)
+        self.text = text
+        self.unit = unit
+
+
+class InvalidSizeError(ByteszError):
+    """The input is malformed, negative, or not a whole number of bytes."""
+
+
+class AmbiguousUnitError(ByteszError):
+    """The unit does not name one system unambiguously, for example 'KB'."""
+
+
+class UnknownUnitError(InvalidSizeError):
+    """The unit is not a size unit at all, for example 'furlongs'."""
+
+
+class SystemMismatchError(InvalidSizeError):
+    """The unit belongs to the other system than the one the caller pinned."""
+
+
+class FractionalBytesError(InvalidSizeError):
+    """The value does not land on a whole byte (or bit) and no rounding was asked for."""

bytesz/_format.py

@@ -0,0 +1,159 @@
+"""Render an exact integer number of bytes (or bits) as a human readable size."""
+
+from __future__ import annotations
+
+from decimal import Decimal, localcontext
+
+from ._errors import InvalidSizeError, SystemMismatchError, UnknownUnitError
+from ._types import (
+    Rounding,
+    System,
+    check_decimal_point,
+    check_system,
+    digit_count,
+    exact_context,
+    rounding_mode,
+)
+from ._units import (
+    IEC_BASE,
+    IEC_BIT_SUFFIXES,
+    IEC_SUFFIXES,
+    SI_BASE,
+    SI_BIT_SUFFIXES,
+    SI_SUFFIXES,
+)
+
+
+def _table(system: str | None, bits: bool, unit: str | None) -> tuple[str, int, tuple[str, ...]]:
+    """Pick the system (inferred from ``unit`` when not given), its base and suffixes."""
+    iec = IEC_BIT_SUFFIXES if bits else IEC_SUFFIXES
+    si = SI_BIT_SUFFIXES if bits else SI_SUFFIXES
+    if system is not None:
+        check_system(system)
+    if unit is not None:
+        if unit not in iec and unit not in si:
+            kind = "bit" if bits else "size"
+            raise UnknownUnitError(f"unknown {kind} unit {unit!r}", unit=unit)
+        owner = "iec" if unit in iec else "si"
+        if system is None or unit in (iec if system == "iec" else si):
+            system = system or owner
+        else:
+            name = "an IEC" if owner == "iec" else "an SI"
+            raise SystemMismatchError(
+                f"{unit!r} is {name} unit but system is {system!r}", unit=unit
+            )
+    if system == "si":
+        return "si", SI_BASE, si
+    return "iec", IEC_BASE, iec
+
+
+def _exact(count: int, base: int, exponent: int) -> Decimal:
+    """Return count / base**exponent exactly; every such quotient terminates."""
+    with localcontext(exact_context(digit_count(count) + 10 * exponent + 2)):
+        return Decimal(count) / (Decimal(base) ** exponent)
+
+
+def _check_count(count: object, signed: bool) -> int:
+    if isinstance(count, bool) or not isinstance(count, int):
+        raise InvalidSizeError("byte count must be an int")
+    if count < 0 and not signed:
+        raise InvalidSizeError("byte count must not be negative; pass signed=True to allow it")
+    return count
+
+
+def _text(value: Decimal, trailing_zeros: bool, decimal_point: str) -> str:
+    """Render a decimal without exponent notation, optionally trimming zeros."""
+    text = f"{value:f}"
+    if not trailing_zeros and "." in text:
+        text = text.rstrip("0").rstrip(".")
+    if text.lstrip("-").strip("0.") == "":
+        text = text.lstrip("-")  # never print "-0"
+    return text.replace(".", decimal_point)
+
+
+def _render(
+    count: int,
+    *,
+    bits: bool,
+    system: str | None,
+    precision: int,
+    rounding: str,
+    unit: str | None,
+    trailing_zeros: bool,
+    decimal_point: str,
+    separator: str,
+) -> str:
+    system, base, suffixes = _table(system, bits, unit)
+    if isinstance(precision, bool) or not isinstance(precision, int) or precision < 0:
+        raise ValueError("precision must be a non-negative int")
+    mode = rounding_mode(rounding)
+    check_decimal_point(decimal_point)
+    step = Decimal((0, (1,), -precision))
+
+    if unit is not None:
+        exponent = suffixes.index(unit)
+    else:
+        exponent = 0
+        magnitude = abs(count)
+        while exponent < len(suffixes) - 1 and base ** (exponent + 1) <= magnitude:
+            exponent += 1
+
+    while True:
+        scaled = _exact(count, base, exponent)
+        with localcontext(exact_context(digit_count(count) + precision + 2)):
+            rounded = scaled.quantize(step, rounding=mode)
+            reached = rounded.copy_abs() >= base
+        # Carry: 1023.999 KiB rounds to 1024.00 KiB, which is 1 MiB.
+        if unit is None and reached and exponent < len(suffixes) - 1:
+            exponent += 1
+            continue
+        break
+    return f"{_text(rounded, trailing_zeros, decimal_point)}{separator}{suffixes[exponent]}"
+
+
+def format(
+    count: int,
+    *,
+    system: System | None = None,
+    precision: int = 2,
+    rounding: Rounding = "half-up",
+    unit: str | None = None,
+    signed: bool = False,
+    trailing_zeros: bool = False,
+    decimal_point: str = ".",
+    separator: str = " ",
+) -> str:
+    """Convert a byte count into a human size such as "1.5 KiB".
+
+    ``system`` is "iec" (1024 based: KiB, MiB ... QiB) or "si" (1000 based: kB,
+    MB ... QB); when omitted it follows ``unit`` if one is given, else "iec".
+    The largest unit that keeps the number at or above one is chosen, the value
+    is rounded to ``precision`` decimals with ``rounding``, and if the rounded
+    value reaches the next unit it carries over (1048575 is "1 MiB", not
+    "1024 KiB"). Trailing zeros are dropped unless ``trailing_zeros`` is true.
+
+    ``unit`` forces one unit, such as "MiB" or "kB", with no carry; a unit from
+    the other system than an explicit ``system`` raises SystemMismatchError.
+    ``signed`` allows negative counts. ``decimal_point`` is "." or ",".
+    ``separator`` goes between number and unit (" " by default, "" for "1.5KiB").
+
+    >>> format(1572864)
+    '1.5 MiB'
+    >>> format(1234567, system="si")
+    '1.23 MB'
+    >>> format(1048575)
+    '1 MiB'
+    >>> format(1536, unit="B")
+    '1536 B'
+    """
+    return _render(
+        _check_count(count, signed),
+        bits=False,
+        system=system,
+        precision=precision,
+        rounding=rounding,
+        unit=unit,
+        trailing_zeros=trailing_zeros,
+        decimal_point=decimal_point,
+        separator=separator,
+    )

bytesz/_hints.py

@@ -0,0 +1,49 @@
+"""Error hints and cross-family checks for parse and parse_bits."""
+
+from __future__ import annotations
+
+from typing import Final
+
+from ._units import (
+    IEC_BARE,
+    IEC_BIT_SUFFIXES,
+    IEC_SUFFIXES,
+    LEGACY_UNITS,
+    SI_BARE_PINNED,
+    SI_BIT_SUFFIXES,
+    SI_SUFFIXES,
+)
+
+# Units of the other family: a bit unit given to parse, a byte unit to parse_bits.
+BIT_SYMBOLS: Final = {s: "a bit unit; use parse_bits for bits" for s in IEC_BIT_SUFFIXES[1:]}
+BIT_SYMBOLS.update({s: "a bit unit; use parse_bits for bits" for s in SI_BIT_SUFFIXES})
+BYTE_SYMBOLS: Final = {
+    s: "a byte unit; use parse for bytes"
+    for s in (*IEC_SUFFIXES, *SI_SUFFIXES, *IEC_BARE, *(u for u in LEGACY_UNITS if u.endswith("B")))
+}
+
+
+def byte_hint(suffix: str, system: str | None, legacy: bool) -> str:
+    """Explain an ambiguous byte unit, suggesting only options that would work."""
+    if suffix.endswith("b"):
+        return "a lower case 'b' usually means bits (see parse_bits); for bytes use MB or MiB"
+    can_legacy = suffix in LEGACY_UNITS and system != "si" and not legacy
+    if not suffix.endswith("B"):
+        options = []
+        if suffix in SI_BARE_PINNED and system is None and not legacy:
+            options.append("system='si' reads it as a power of 1000")
+        if can_legacy:
+            options.append("legacy=True reads it as a power of 1024")
+        options.append("write a full unit such as kB or KiB")
+        return "it is a bare prefix; " + (
+            ", or ".join(options)
+            if len(options) < 3
+            else f"{options[0]}, {options[1]}, or {options[2]}"
+        )
+    text = "use kB/MB for 1000 or KiB/MiB for 1024"
+    return text + (", or pass legacy=True for the JEDEC reading" if can_legacy else "")
+
+
+def bit_hint(suffix: str, system: str | None, legacy: bool) -> str:
+    """Explain an ambiguous bit unit."""
+    return "use kbit/Mbit (or kb/Mb) for 1000, Kibit/Mibit (or Kib/Mib) for 1024"

bytesz/_parse.py

@@ -0,0 +1,182 @@
+"""Parse a human readable size into an exact integer number of bytes (or bits)."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Callable, Mapping
+from decimal import Decimal, localcontext
+
+from ._errors import (
+    AmbiguousUnitError,
+    ByteszError,
+    FractionalBytesError,
+    InvalidSizeError,
+    SystemMismatchError,
+    UnknownUnitError,
+)
+from ._hints import BIT_SYMBOLS, byte_hint
+from ._types import Rounding, System, check_decimal_point, digit_count, exact_context, rounding_mode
+from ._units import (
+    IEC_BARE,
+    IEC_BASE,
+    IEC_UNITS,
+    LEGACY_UNITS,
+    SI_BARE_PINNED,
+    SI_BASE,
+    SI_UNITS,
+    UPPER_UNITS,
+)
+
+_PATTERNS = {
+    point: re.compile(
+        rf"^\s*([+-]?)([0-9]+(?:{re.escape(point)}[0-9]+)?)"
+        r"\s*([A-Za-z]*)\s*$"
+    )
+    for point in (".", ",")
+}
+
+
+def _factor(
+    suffix: str,
+    *,
+    iec: Mapping[str, int],
+    si: Mapping[str, int],
+    extra: Mapping[str, int],
+    si_pinned: Mapping[str, int],
+    upper: set[str] | frozenset[str],
+    foreign: Mapping[str, str],
+    system: str | None,
+    hint: Callable[[str, str | None, bool], str],
+) -> int:
+    """Return the multiplier for a suffix, honouring an optional pinned system."""
+    if suffix == "" or iec.get(suffix) == 0 or si.get(suffix) == 0:
+        return 1
+    if suffix in extra:
+        return int(IEC_BASE ** extra[suffix])
+    if suffix in iec:
+        if system == "si":
+            raise SystemMismatchError(f"{suffix!r} is an IEC unit but system is 'si'", unit=suffix)
+        return int(IEC_BASE ** iec[suffix])
+    if system == "si" and suffix in si_pinned:
+        return int(SI_BASE ** si_pinned[suffix])
+    if suffix in si:
+        if system == "iec":
+            raise SystemMismatchError(f"{suffix!r} is an SI unit but system is 'iec'", unit=suffix)
+        return int(SI_BASE ** si[suffix])
+    if suffix in foreign:
+        raise UnknownUnitError(f"{suffix!r} is {foreign[suffix]}", unit=suffix)
+    if suffix.upper() in upper:
+        reason = hint(suffix, system, bool(extra))
+        raise AmbiguousUnitError(f"{suffix!r} is ambiguous; {reason}", unit=suffix)
+    raise UnknownUnitError(f"unknown size unit {suffix!r}", unit=suffix)
+
+
+def _parse_with(
+    text: str,
+    *,
+    iec: Mapping[str, int],
+    si: Mapping[str, int],
+    extra: Mapping[str, int],
+    si_pinned: Mapping[str, int],
+    upper: set[str] | frozenset[str],
+    foreign: Mapping[str, str],
+    hint: Callable[[str, str | None, bool], str],
+    what: str,
+    system: str | None,
+    rounding: str | None,
+    signed: bool,
+    decimal_point: str,
+) -> int:
+    if system not in (None, "iec", "si"):
+        raise ValueError(f"unknown system {system!r}; use 'iec', 'si' or None")
+    check_decimal_point(decimal_point)
+    mode = None if rounding is None else rounding_mode(rounding)
+    if not isinstance(text, str):
+        raise TypeError(f"size must be a str, not {type(text).__name__}")
+
+    match = _PATTERNS[decimal_point].match(text)
+    if match is None:
+        raise InvalidSizeError(f"cannot parse size {text!r}", text=text)
+    sign, number, suffix = match.groups()
+    if sign and not signed:
+        raise InvalidSizeError(f"{text!r} has a sign; pass signed=True to allow it", text=text)
+
+    try:
+        factor = _factor(
+            suffix,
+            iec=iec,
+            si=si,
+            extra=extra,
+            si_pinned=si_pinned,
+            upper=upper,
+            foreign=foreign,
+            system=system,
+            hint=hint,
+        )
+    except ByteszError as error:
+        error.text = text
+        raise
+
+    digits = number.replace(decimal_point, ".")
+    with localcontext(exact_context(len(digits) + digit_count(factor) + 2)):
+        total = Decimal(digits) * factor
+        if sign == "-":
+            total = -total
+        if total != total.to_integral_value():
+            if mode is None:
+                raise FractionalBytesError(
+                    f"{text!r} is not a whole number of {what}", text=text, unit=suffix
+                )
+            total = total.quantize(Decimal(1), rounding=mode)
+    return int(total)
+
+
+def parse(
+    text: str,
+    *,
+    system: System | None = None,
+    rounding: Rounding | None = None,
+    signed: bool = False,
+    decimal_point: str = ".",
+    legacy: bool = False,
+) -> int:
+    """Convert a human size such as "1.5 MiB" into an exact number of bytes.
+
+    The unit decides the system: IEC suffixes (KiB, MiB ... QiB, or the bare
+    Ki, Mi written by ``numfmt --to=iec-i``) use 1024 and SI suffixes (kB, MB ...
+    QB) use 1000. A bare number, or "B", is a count of bytes. Units are case
+    sensitive: "KB", "Mb" and "kib" raise :class:`AmbiguousUnitError`.
+
+    ``system`` accepts one system only; the other raises
+    :class:`SystemMismatchError`. Pinning "si" also accepts bare prefixes such as
+    "1.5M" or "2K", as ``numfmt --from=si`` does.
+
+    ``rounding`` rounds a value that is not a whole byte instead of raising
+    :class:`FractionalBytesError`. ``signed`` allows a leading "+" or "-".
+    ``decimal_point`` is "." or ",". ``legacy`` reads the JEDEC style upper case
+    units (KB, MB, GB ... and bare K, M, G) as powers of 1024; "kB" stays 1000.
+
+    >>> parse("1.5 MiB")
+    1572864
+    >>> parse("1.5 MB")
+    1500000
+    >>> parse("1 MB", legacy=True)
+    1048576
+    """
+    if legacy and system == "si":
+        raise ValueError("legacy=True reads units as powers of 1024; it cannot pin system='si'")
+    return _parse_with(
+        text,
+        iec={**IEC_UNITS, **IEC_BARE},
+        si=SI_UNITS,
+        extra=LEGACY_UNITS if legacy else {},
+        si_pinned=SI_BARE_PINNED,
+        upper=UPPER_UNITS,
+        foreign=BIT_SYMBOLS,
+        hint=byte_hint,
+        what="bytes",
+        system=system,
+        rounding=rounding,
+        signed=signed,
+        decimal_point=decimal_point,
+    )

bytesz/_types.py

@@ -0,0 +1,70 @@
+"""Public type aliases and the rounding mode table."""
+
+from __future__ import annotations
+
+import decimal
+from typing import Final, Literal
+
+System = Literal["iec", "si"]
+"""A size system: "iec" (powers of 1024, KiB) or "si" (powers of 1000, kB)."""
+
+Rounding = Literal["half-up", "half-even", "half-down", "up", "down", "ceiling", "floor"]
+"""How a value is rounded to the requested precision.
+
+"half-up" rounds ties away from zero (numfmt ``nearest``), "half-even" rounds ties
+to the even digit, "half-down" rounds ties toward zero, "up" rounds away from
+zero (numfmt ``from-zero``), "down" truncates toward zero (numfmt
+``towards-zero``), "ceiling" rounds toward positive infinity (numfmt ``up``) and
+"floor" toward negative infinity (numfmt ``down``).
+"""
+
+ROUNDING_MODES: Final[dict[str, str]] = {
+    "half-up": decimal.ROUND_HALF_UP,
+    "half-even": decimal.ROUND_HALF_EVEN,
+    "half-down": decimal.ROUND_HALF_DOWN,
+    "up": decimal.ROUND_UP,
+    "down": decimal.ROUND_DOWN,
+    "ceiling": decimal.ROUND_CEILING,
+    "floor": decimal.ROUND_FLOOR,
+}
+
+
+def rounding_mode(rounding: str) -> str:
+    """Return the ``decimal`` rounding constant for a public rounding name."""
+    try:
+        return ROUNDING_MODES[rounding]
+    except KeyError:
+        names = ", ".join(repr(name) for name in ROUNDING_MODES)
+        raise ValueError(f"unknown rounding {rounding!r}; use one of {names}") from None
+
+
+def check_system(system: object) -> None:
+    """Reject anything that is not "iec" or "si"."""
+    if system not in ("iec", "si"):
+        raise ValueError(f"unknown system {system!r}; use 'iec' or 'si'")
+
+
+def check_decimal_point(decimal_point: object) -> None:
+    """Accept only "." or "," as the decimal separator."""
+    if decimal_point not in (".", ","):
+        raise ValueError(f"decimal_point must be '.' or ',', not {decimal_point!r}")
+
+
+def exact_context(prec: int) -> decimal.Context:
+    """Return a private context that ignores the caller's global decimal settings.
+
+    Precision is set by the caller to be large enough for an exact result, the
+    exponent range is the widest the platform allows, and only real errors trap.
+    """
+    return decimal.Context(
+        prec=max(prec, 1),
+        rounding=decimal.ROUND_HALF_EVEN,
+        Emax=decimal.MAX_EMAX,
+        Emin=decimal.MIN_EMIN,
+        traps=[decimal.InvalidOperation, decimal.DivisionByZero, decimal.Overflow],
+    )
+
+
+def digit_count(number: int) -> int:
+    """Return an upper bound on the decimal digits of ``number``, without str()."""
+    return abs(number).bit_length() * 30103 // 100000 + 2

bytesz/_units.py

@@ -0,0 +1,71 @@
+"""Unit tables for the IEC (1024) and SI (1000) size systems.
+
+Each table is exact and case sensitive. The byte suffix "B" is shared by both
+systems and always sits at exponent zero. The IEC suffixes carry the "i" marker
+(KiB, MiB); the SI suffixes do not (kB, MB). Any other spelling is either an
+unknown unit or an ambiguous one, never a silent guess.
+
+The tables reach the prefixes adopted in 2022 by the CGPM (ronna R = 1000**9,
+quetta Q = 1000**10) and their binary partners from IEC 80000-13:2025 (robi
+Ri = 1024**9, quebi Qi = 1024**10). Sources: https://www.bipm.org/en/measurement-units/si-prefixes
+and https://physics.nist.gov/cuu/Units/binary.html.
+"""
+
+from __future__ import annotations
+
+from typing import Final
+
+IEC_BASE: Final = 1024
+SI_BASE: Final = 1000
+
+IEC_PREFIXES: Final = ("", "Ki", "Mi", "Gi", "Ti", "Pi", "Ei", "Zi", "Yi", "Ri", "Qi")
+SI_PREFIXES: Final = ("", "k", "M", "G", "T", "P", "E", "Z", "Y", "R", "Q")
+
+IEC_SUFFIXES: Final = tuple(prefix + "B" for prefix in IEC_PREFIXES)
+SI_SUFFIXES: Final = tuple(prefix + "B" for prefix in SI_PREFIXES)
+IEC_BIT_SUFFIXES: Final = tuple(prefix + "bit" for prefix in IEC_PREFIXES)
+SI_BIT_SUFFIXES: Final = tuple(prefix + "bit" for prefix in SI_PREFIXES)
+
+IEC_UNITS: Final[dict[str, int]] = {suffix: exp for exp, suffix in enumerate(IEC_SUFFIXES)}
+SI_UNITS: Final[dict[str, int]] = {suffix: exp for exp, suffix in enumerate(SI_SUFFIXES)}
+
+# Bare IEC prefixes ("1.5Mi", as written by `numfmt --to=iec-i`) only ever mean
+# a binary multiple, so they are accepted wherever IEC units are.
+IEC_BARE: Final[dict[str, int]] = {p: exp for exp, p in enumerate(IEC_PREFIXES) if p}
+
+# Bare SI prefixes ("1.5M", as written by `numfmt --to=si`). "M" alone is read
+# as 1024**2 by `numfmt --from=iec`, so these are accepted only when the caller
+# pins system="si". Upper case "K" is accepted there too, as numfmt does.
+SI_BARE: Final[dict[str, int]] = {p: exp for exp, p in enumerate(SI_PREFIXES) if p}
+SI_BARE_PINNED: Final[dict[str, int]] = {**SI_BARE, "K": 1}
+
+# Legacy binary spellings: upper case prefix plus "B", or the bare upper case
+# prefix, read as powers of 1024. JEDEC defines only K, M and G this way "to
+# reflect common usage"; operating systems extend the habit upwards. Used only
+# when the caller opts in with legacy=True.
+_LEGACY_PREFIXES: Final = ("K", "M", "G", "T", "P", "E", "Z", "Y", "R", "Q")
+LEGACY_UNITS: Final[dict[str, int]] = {
+    **{p + "B": exp for exp, p in enumerate(_LEGACY_PREFIXES, start=1)},
+    **{p: exp for exp, p in enumerate(_LEGACY_PREFIXES, start=1)},
+}
+
+# Upper cased spellings, used only to tell an ambiguous casing (KB, Kib) apart
+# from an entirely unknown unit.
+UPPER_UNITS: Final = (
+    {s.upper() for s in IEC_SUFFIXES}
+    | {s.upper() for s in SI_SUFFIXES}
+    | {s.upper() for s in LEGACY_UNITS}
+    | {s.upper() for s in IEC_BARE}
+)
+
+# Bit units for parse_bits: the long "bit" symbol and the short "b" symbol.
+# "Kb" and bare upper case prefixes stay ambiguous, exactly as "KB" does.
+IEC_BIT_UNITS: Final[dict[str, int]] = {
+    **{s: exp for exp, s in enumerate(IEC_BIT_SUFFIXES)},
+    **{p + "b": exp for exp, p in enumerate(IEC_PREFIXES)},
+}
+SI_BIT_UNITS: Final[dict[str, int]] = {
+    **{s: exp for exp, s in enumerate(SI_BIT_SUFFIXES)},
+    **{p + "b": exp for exp, p in enumerate(SI_PREFIXES)},
+}
+UPPER_BIT_UNITS: Final = {s.upper() for s in IEC_BIT_UNITS} | {s.upper() for s in SI_BIT_UNITS}

bytesz-0.2.0.dist-info/METADATA

@@ -0,0 +1,147 @@
+Metadata-Version: 2.5
+Name: bytesz
+Version: 0.2.0
+Summary: Strict two-way conversion between byte counts and human sizes with explicit IEC and SI units
+Project-URL: Homepage, https://lianes8studio.com
+Project-URL: Repository, https://github.com/JaviLianes8/bytesz
+Project-URL: Issues, https://github.com/JaviLianes8/bytesz/issues
+Project-URL: Changelog, https://github.com/JaviLianes8/bytesz/blob/main/CHANGELOG.md
+Project-URL: LinkedIn, https://www.linkedin.com/in/jlianes/
+Project-URL: Funding, https://buymeacoffee.com/jlianesglrs
+Author-email: Javier Lianes <javier@lianes8studio.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: bytes,format,human,iec,kib,mib,numfmt,parse,si,size
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Utilities
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# bytesz
+
+Strict two-way conversion between byte counts and human sizes with explicit IEC and SI units.
+Typed, exact (integer and `Decimal` arithmetic only), zero dependencies, with a small CLI.
+
+## Install
+
+```
+pip install bytesz
+```
+
+## Usage
+
+```python
+from bytesz import format, parse
+
+# Human size to an exact integer number of bytes. The unit picks the system.
+parse("1.5 MiB")  # 1572864     (IEC, 1024 based)
+parse("1.5 MB")  # 1500000     (SI, 1000 based)
+parse("512 B")  # 512
+parse("2048")  # 2048        (a bare number is bytes)
+
+# Bytes back to a human size, for whichever system you ask for.
+format(1572864)  # "1.5 MiB"   (IEC is the default)
+format(1500000, system="si")  # "1.5 MB"
+format(1234567, system="si", precision=2)  # "1.23 MB"
+format(1048575)  # "1 MiB"     (rounding carries into the next unit)
+```
+
+It refuses to guess:
+
+```python
+from bytesz import AmbiguousUnitError, FractionalBytesError, SystemMismatchError, parse
+
+parse("1 KB")  # AmbiguousUnitError: KB could mean kB (1000) or KiB (1024)
+parse("100 Mb")  # AmbiguousUnitError: a lower case b means bits, see parse_bits
+parse("1.5 B")  # FractionalBytesError: not a whole number of bytes
+parse("1 kB", system="iec")  # SystemMismatchError: an SI unit under a pinned IEC system
+```
+
+Every input error is a `ByteszError` (a `ValueError`) carrying `.text` and `.unit`. Bad
+option values raise a plain `ValueError`, and a non-string input to `parse` a `TypeError`.
+
+## Options
+
+```python
+from bytesz import convert, format, format_bits, parse, parse_bits
+
+# Formatting
+format(1250, system="si", precision=1, rounding="half-even")  # "1.2 kB"
+format(1_000_000, unit="MiB")  # "0.95 MiB"
+format(5000, unit="kB")  # "5 kB" (the unit picks the system)
+format(-1536, signed=True)  # "-1.5 KiB"
+format(1536, precision=3, trailing_zeros=True)  # "1.500 KiB"
+format(1536, decimal_point=",", separator="")  # "1,5KiB"
+
+# Parsing
+parse("1.0005 kB", rounding="half-up")  # 1001
+parse("1,5 MiB", decimal_point=",")  # 1572864
+parse("-2 KiB", signed=True)  # -2048
+parse("1.5M", system="si")  # 1500000 (bare prefixes, as numfmt writes them)
+parse("1.5Mi")  # 1572864 (bare IEC prefix)
+parse("4 GB", legacy=True)  # 4294967296 (JEDEC style KB/MB/GB = 1024, opt-in)
+
+# Bits, with the unambiguous "bit" symbol
+parse_bits("100 Mbit")  # 100000000
+format_bits(1_500_000, system="si")  # "1.5 Mbit"
+
+# Exact value in one unit, no rounding at all
+convert(1, "KiB")  # Decimal("0.0009765625")
+```
+
+Rounding modes: `half-up` (default, ties away from zero), `half-even`, `half-down`,
+`up`, `down`, `ceiling`, `floor`. Units reach the 2022 SI prefixes `RB` and `QB` and
+the IEC 80000-13:2025 prefixes `RiB` and `QiB`.
+
+## Command line
+
+```
+bytesz format 1572864                 # 1.5 MiB
+bytesz format --system si 1234567     # 1.23 MB
+bytesz parse "1.5 MiB" 2GB            # 1572864, 2000000000
+bytesz parse --legacy 4KB             # 4096
+du -b * | bytesz format --field 1     # rewrite one column, like numfmt --field
+```
+
+Values come from the arguments or, when there are none, one per line from stdin.
+Errors go to stderr with exit status 1. `bytesz --help` lists every option.
+
+## Why
+
+Human byte sizes are a well known trap: `KB` means 1000 bytes to a disk vendor and
+1024 bytes to an operating system, and most libraries quietly pick one. The popular
+options lean on guessing or only go one way: `humanize` and `hurry.filesize` format
+numbers but do not parse them back, `humanfriendly` parses but treats `KB` and `KiB`
+as the same 1024 based value, and `bitmath` mixes bits and bytes with a broad API.
+
+`bytesz` is deliberately narrow and strict. The unit alone decides the system, both
+directions are exact, and anything ambiguous or fractional is rejected with a clear
+error instead of being rounded, unless you ask for rounding. Reach for it when a
+wrong factor of 1024 would be a real bug, such as quotas, billing, or on-disk
+accounting. With matching `--round` and `--format=%.Nf`, its formatting agrees with
+GNU `numfmt` (checked in the test suite on seeded values), except where `numfmt` itself
+drifts because it divides in floating point.
+
+See [GUIDE.md](GUIDE.md) for the rules in depth.
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+## Links
+
+- Website: https://lianes8studio.com
+- GitHub: https://github.com/JaviLianes8
+- LinkedIn: https://www.linkedin.com/in/jlianes/

bytesz-0.2.0.dist-info/RECORD

@@ -0,0 +1,18 @@
+bytesz/__init__.py,sha256=oZln1aoae8mg8JTPJUafPnl8_V4T6I2hoOoO17r7fdI,1144
+bytesz/__main__.py,sha256=hNCKQrZYNdzffrHvF9XPqvUd8HYnLCmhz6OlC45_f84,155
+bytesz/_bits.py,sha256=3jZvTDWQj10_ffo0RJhg0Qoue-gXSETsUypie7XypKc,2235
+bytesz/_cli.py,sha256=nnzJYt4KnXsiiHOJY8KX1ndGgHquz86h-Z6nb9UmIDk,6215
+bytesz/_cli_support.py,sha256=U9j7Rsq4NWyOnqTGZ_Ed4E5O_IRnz-n5cYQ5lMlv7l8,2617
+bytesz/_convert.py,sha256=xmTh5ojb7oYvt23a6SWxmJGiNAYKuwDe_goIoZilmks,1754
+bytesz/_errors.py,sha256=QcZ9SJVP0EFL4RbKWoNoRnUMU4MfjRzE-nK4loNuFYo,1414
+bytesz/_format.py,sha256=QTYyqXcqFd-iFKiS8ALbsstNE9GhUI1X7i-kkkAKukA,5445
+bytesz/_hints.py,sha256=iY8sif4xmY1MK_VoZ3jrMnZjCllcDIbdyahhTvyUiS4,1938
+bytesz/_parse.py,sha256=2pU4Mrxz25SKSnpk0b8VWywyorczTFN3d7YPuGl73Yc,5868
+bytesz/_types.py,sha256=JSZK0kwk954YwyrIiqqKZF5nl-pS6rf5EV1LCWy-DvI,2588
+bytesz/_units.py,sha256=Serl8u3q2PT_kh6GKBliq5VrCxcnF2faheuZNXhavdc,3410
+bytesz/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+bytesz-0.2.0.dist-info/METADATA,sha256=-s3oQVgZYcom4PuIBMD7PQrKJzVWVk_9WJOHIpqEBEI,5642
+bytesz-0.2.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+bytesz-0.2.0.dist-info/entry_points.txt,sha256=aa3fzZ1Dq_xSnXI9DdkNY1gMIqdVCneKJF-l9n5Wd4A,44
+bytesz-0.2.0.dist-info/licenses/LICENSE,sha256=_WmABlQG__oqlx4Rzp-qDJ10xND5KCLScftbhXbLC_c,1070
+bytesz-0.2.0.dist-info/RECORD,,

bytesz-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

bytesz-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+bytesz = bytesz._cli:main

bytesz-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Javier Lianes
+
+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.