barcodekit 0.1.2__py3-none-win_amd64.whl

barcodekit/__init__.py

@@ -0,0 +1,201 @@
+"""Generate barcode PNGs with the local barcode-rest CLI."""
+
+from __future__ import annotations
+
+from ._core import BarcodeImage, BarcodeKit
+from ._errors import (
+    BarcodeKitBinaryNotFound,
+    BarcodeKitCommandError,
+    BarcodeKitError,
+    BarcodeKitTimeout,
+    BarcodeKitUnsupportedPlatform,
+)
+from ._version import __version__
+
+_default_kit = BarcodeKit()
+
+
+def generate(symbology: str, text: str, **options: object) -> BarcodeImage:
+    return _default_kit.generate(symbology, text, **options)
+
+
+def datamatrix(
+    text: str,
+    *,
+    size: int | None = 256,
+    module: int | None = None,
+    quiet: int | None = None,
+) -> BarcodeImage:
+    return _default_kit.datamatrix(text, size=size, module=module, quiet=quiet)
+
+
+def qr(
+    text: str,
+    *,
+    size: int | None = 512,
+    module: int | None = None,
+    quiet: int | None = None,
+    level: str = "M",
+) -> BarcodeImage:
+    return _default_kit.qr(text, size=size, module=module, quiet=quiet, level=level)
+
+
+def aztec(
+    text: str,
+    *,
+    size: int | None = 512,
+    module: int | None = None,
+    quiet: int | None = None,
+) -> BarcodeImage:
+    return _default_kit.aztec(text, size=size, module=module, quiet=quiet)
+
+
+def pdf417(
+    text: str,
+    *,
+    module: int | None = None,
+    quiet: int | None = None,
+    level: int | str = 2,
+) -> BarcodeImage:
+    return _default_kit.pdf417(text, module=module, quiet=quiet, level=level)
+
+
+def code128(
+    text: str,
+    *,
+    module: int | None = None,
+    height: int | None = 80,
+    quiet: int | None = None,
+    label: bool = False,
+) -> BarcodeImage:
+    return _default_kit.code128(
+        text, module=module, height=height, quiet=quiet, label=label
+    )
+
+
+def code39(
+    text: str,
+    *,
+    module: int | None = None,
+    height: int | None = 80,
+    quiet: int | None = None,
+    label: bool = False,
+    fullascii: bool = False,
+) -> BarcodeImage:
+    return _default_kit.code39(
+        text,
+        module=module,
+        height=height,
+        quiet=quiet,
+        label=label,
+        fullascii=fullascii,
+    )
+
+
+def code93(
+    text: str,
+    *,
+    module: int | None = None,
+    height: int | None = 80,
+    quiet: int | None = None,
+    label: bool = False,
+    fullascii: bool = False,
+) -> BarcodeImage:
+    return _default_kit.code93(
+        text,
+        module=module,
+        height=height,
+        quiet=quiet,
+        label=label,
+        fullascii=fullascii,
+    )
+
+
+def codabar(
+    text: str,
+    *,
+    module: int | None = None,
+    height: int | None = 80,
+    quiet: int | None = None,
+    label: bool = False,
+) -> BarcodeImage:
+    return _default_kit.codabar(
+        text, module=module, height=height, quiet=quiet, label=label
+    )
+
+
+def itf(
+    text: str,
+    *,
+    module: int | None = None,
+    height: int | None = 80,
+    quiet: int | None = None,
+    label: bool = False,
+) -> BarcodeImage:
+    return _default_kit.itf(
+        text, module=module, height=height, quiet=quiet, label=label
+    )
+
+
+def code25(
+    text: str,
+    *,
+    module: int | None = None,
+    height: int | None = 80,
+    quiet: int | None = None,
+    label: bool = False,
+) -> BarcodeImage:
+    return _default_kit.code25(
+        text, module=module, height=height, quiet=quiet, label=label
+    )
+
+
+def ean13(
+    text: str,
+    *,
+    module: int | None = None,
+    height: int | None = 80,
+    quiet: int | None = None,
+    label: bool = False,
+) -> BarcodeImage:
+    return _default_kit.ean13(
+        text, module=module, height=height, quiet=quiet, label=label
+    )
+
+
+def ean8(
+    text: str,
+    *,
+    module: int | None = None,
+    height: int | None = 80,
+    quiet: int | None = None,
+    label: bool = False,
+) -> BarcodeImage:
+    return _default_kit.ean8(
+        text, module=module, height=height, quiet=quiet, label=label
+    )
+
+
+__all__ = [
+    "BarcodeImage",
+    "BarcodeKit",
+    "BarcodeKitBinaryNotFound",
+    "BarcodeKitCommandError",
+    "BarcodeKitError",
+    "BarcodeKitTimeout",
+    "BarcodeKitUnsupportedPlatform",
+    "__version__",
+    "aztec",
+    "codabar",
+    "code25",
+    "code39",
+    "code93",
+    "code128",
+    "datamatrix",
+    "ean8",
+    "ean13",
+    "generate",
+    "itf",
+    "pdf417",
+    "qr",
+]

barcodekit/_bin/.gitkeep

@@ -0,0 +1 @@
+

barcodekit/_binary.py

@@ -0,0 +1,85 @@
+"""Resolve the barcode-rest executable for the current platform."""
+
+from __future__ import annotations
+
+import os
+import platform
+import stat
+from pathlib import Path
+
+from ._errors import BarcodeKitBinaryNotFound, BarcodeKitUnsupportedPlatform
+
+_BINARY_ENV = "BARCODEKIT_BINARY"
+_BINARY_DIR = Path(__file__).parent / "_bin"
+_MACHINE_ALIASES = {
+    "amd64": "amd64",
+    "x86_64": "amd64",
+    "arm64": "arm64",
+    "aarch64": "arm64",
+}
+_SUPPORTED_PLATFORMS = {
+    ("windows", "amd64"): "barcode-rest.exe",
+    ("linux", "amd64"): "barcode-rest",
+    ("linux", "arm64"): "barcode-rest",
+}
+
+
+def _current_platform() -> tuple[str, str]:
+    system = platform.system().lower()
+    raw_machine = platform.machine().lower()
+    return system, _MACHINE_ALIASES.get(raw_machine, raw_machine)
+
+
+def _bundled_binary_name() -> tuple[str, str]:
+    system, machine = _current_platform()
+    name = _SUPPORTED_PLATFORMS.get((system, machine))
+    if name is None:
+        supported = ", ".join(f"{os_name}/{arch}" for os_name, arch in _SUPPORTED_PLATFORMS)
+        raise BarcodeKitUnsupportedPlatform(
+            f"Unsupported platform {system}/{machine}. Supported platforms: {supported}."
+        )
+    return system, name
+
+
+def _require_file(value: str | Path, source: str) -> Path:
+    path = Path(value).expanduser()
+    if not path.is_file():
+        raise BarcodeKitBinaryNotFound(f"{source} does not point to a file: {path}")
+    return path
+
+
+def _ensure_bundled_executable(path: Path, system: str) -> None:
+    if system == "windows":
+        return
+    mode = path.stat().st_mode
+    if mode & stat.S_IXUSR:
+        return
+    try:
+        path.chmod(mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
+    except OSError as exc:
+        raise BarcodeKitBinaryNotFound(
+            f"Bundled binary is not executable and its permissions could not be changed: {path}"
+        ) from exc
+
+
+def resolve_binary(executable: str | Path | None = None) -> Path:
+    """Resolve an explicit, environment-provided, or bundled executable."""
+    system, bundled_name = _bundled_binary_name()
+
+    if executable is not None:
+        return _require_file(executable, "The executable argument")
+
+    environment_path = os.environ.get(_BINARY_ENV)
+    if environment_path:
+        return _require_file(environment_path, _BINARY_ENV)
+
+    bundled = _BINARY_DIR / bundled_name
+    if not bundled.is_file():
+        raise BarcodeKitBinaryNotFound(
+            f"Bundled barcode-rest binary was not found at {bundled}. "
+            f"Install the platform-specific wheel, set {_BINARY_ENV}, "
+            "or pass executable= to BarcodeKit."
+        )
+    _ensure_bundled_executable(bundled, system)
+    return bundled
+

barcodekit/_core.py

@@ -0,0 +1,478 @@
+"""Core barcodekit API."""
+
+from __future__ import annotations
+
+import math
+import re
+import subprocess
+from collections.abc import Mapping
+from dataclasses import dataclass
+from pathlib import Path
+
+from ._binary import resolve_binary
+from ._errors import (
+    BarcodeKitBinaryNotFound,
+    BarcodeKitCommandError,
+    BarcodeKitTimeout,
+)
+
+_PNG_SIGNATURE = b"\x89PNG\r\n\x1a\n"
+_TWO_DIMENSIONAL_LIMITS = {
+    "datamatrix": 128,
+    "qr": 256,
+    "aztec": 256,
+    "pdf417": 256,
+}
+_ONE_DIMENSIONAL = {
+    "code128",
+    "code39",
+    "code93",
+    "codabar",
+    "itf",
+    "code25",
+    "ean13",
+    "ean8",
+}
+_SUPPORTED_SYMBOLOGIES = frozenset(_TWO_DIMENSIONAL_LIMITS) | _ONE_DIMENSIONAL
+_COMMON_2D_OPTIONS = frozenset({"module", "quiet", "size"})
+_COMMON_1D_OPTIONS = frozenset({"module", "height", "quiet", "label"})
+_ALLOWED_OPTIONS = {
+    "datamatrix": _COMMON_2D_OPTIONS,
+    "qr": _COMMON_2D_OPTIONS | {"level"},
+    "aztec": _COMMON_2D_OPTIONS,
+    "pdf417": {"module", "quiet", "level"},
+    "code128": _COMMON_1D_OPTIONS,
+    "code39": _COMMON_1D_OPTIONS | {"fullascii"},
+    "code93": _COMMON_1D_OPTIONS | {"fullascii"},
+    "codabar": _COMMON_1D_OPTIONS,
+    "itf": _COMMON_1D_OPTIONS,
+    "code25": _COMMON_1D_OPTIONS,
+    "ean13": _COMMON_1D_OPTIONS,
+    "ean8": _COMMON_1D_OPTIONS,
+}
+_BASIC_CODE39_CHARACTERS = frozenset("0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ-. $/+%")
+_CODABAR_PATTERN = re.compile(r"^[A-D][0-9\-$:/.+]+[A-D]$")
+
+
+@dataclass(frozen=True)
+class BarcodeImage:
+    """A generated PNG image."""
+
+    png: bytes
+
+    def save(self, path: str | Path) -> Path:
+        """Write the PNG bytes to path and return the resulting Path."""
+        destination = Path(path)
+        destination.write_bytes(self.png)
+        return destination
+
+    def to_bytes(self) -> bytes:
+        """Return the raw PNG bytes."""
+        return self.png
+
+
+def _validate_int(value: object, name: str, minimum: int, maximum: int) -> int:
+    if type(value) is not int:
+        raise TypeError(f"{name} must be an integer")
+    integer = value
+    if not minimum <= integer <= maximum:
+        raise ValueError(f"{name} must be between {minimum} and {maximum}")
+    return integer
+
+
+def _validate_bool(value: object, name: str) -> bool:
+    if type(value) is not bool:
+        raise TypeError(f"{name} must be a boolean")
+    return value
+
+
+def _validate_qr_level(value: object) -> str:
+    if not isinstance(value, str):
+        raise TypeError("level must be a string for QR codes")
+    level = value.upper()
+    if level not in {"L", "M", "Q", "H"}:
+        raise ValueError("QR level must be one of L, M, Q, or H")
+    return level
+
+
+def _validate_pdf417_level(value: object) -> int:
+    if isinstance(value, bool):
+        raise TypeError("level must be an integer or numeric string for PDF417")
+    if isinstance(value, str):
+        if not value.isdigit():
+            raise ValueError("PDF417 level must be between 0 and 8")
+        value = int(value)
+    if not isinstance(value, int):
+        raise TypeError("level must be an integer or numeric string for PDF417")
+    if not 0 <= value <= 8:
+        raise ValueError("PDF417 level must be between 0 and 8")
+    return value
+
+
+def _validate_options(symbology: str, options: Mapping[str, object]) -> dict[str, object]:
+    unknown = set(options) - _ALLOWED_OPTIONS[symbology]
+    if unknown:
+        names = ", ".join(sorted(unknown))
+        raise ValueError(f"Unsupported option(s) for {symbology}: {names}")
+
+    if options.get("size") is not None and options.get("module") is not None:
+        raise ValueError(
+            "size and module cannot be specified together; set size=None to use module"
+        )
+
+    validated: dict[str, object] = {}
+    for name, value in options.items():
+        if value is None:
+            continue
+        if name == "module":
+            validated[name] = _validate_int(value, name, 2, 32)
+        elif name == "quiet":
+            validated[name] = _validate_int(value, name, 0, 16)
+        elif name == "size":
+            validated[name] = _validate_int(value, name, 16, 2048)
+        elif name == "height":
+            validated[name] = _validate_int(value, name, 20, 600)
+        elif name in {"label", "fullascii"}:
+            validated[name] = _validate_bool(value, name)
+        elif name == "level" and symbology == "qr":
+            validated[name] = _validate_qr_level(value)
+        elif name == "level" and symbology == "pdf417":
+            validated[name] = _validate_pdf417_level(value)
+    return validated
+
+
+def _utf8_bytes(text: str) -> bytes:
+    try:
+        return text.encode("utf-8")
+    except UnicodeEncodeError as exc:
+        raise ValueError("text must be valid UTF-8") from exc
+
+
+def _validate_ascii(text: str, symbology: str, maximum: int) -> None:
+    if not text.isascii():
+        raise ValueError(f"{symbology} text must contain ASCII characters only")
+    if len(text) > maximum:
+        raise ValueError(f"{symbology} text must be at most {maximum} characters")
+
+
+def _ean_checksum(body: str) -> str:
+    total = sum(
+        int(digit) * (3 if index % 2 == 0 else 1)
+        for index, digit in enumerate(reversed(body))
+    )
+    return str((10 - total % 10) % 10)
+
+
+def _validate_text(symbology: str, text: str, options: Mapping[str, object]) -> None:
+    if not isinstance(text, str):
+        raise TypeError("text must be a string")
+    if not text:
+        raise ValueError("text must not be empty")
+    if "\x00" in text:
+        raise ValueError("text must not contain NUL characters")
+
+    if symbology in _TWO_DIMENSIONAL_LIMITS:
+        maximum = _TWO_DIMENSIONAL_LIMITS[symbology]
+        if len(_utf8_bytes(text)) > maximum:
+            raise ValueError(f"{symbology} text must be at most {maximum} UTF-8 bytes")
+        return
+
+    if symbology == "code128":
+        _validate_ascii(text, symbology, 80)
+        return
+
+    if symbology in {"code39", "code93"}:
+        _validate_ascii(text, symbology, 128)
+        if not options.get("fullascii", False) and not set(text) <= _BASIC_CODE39_CHARACTERS:
+            raise ValueError(
+                f"{symbology} text contains characters that require fullascii=True"
+            )
+        return
+
+    if symbology == "codabar":
+        _validate_ascii(text, symbology, 128)
+        if _CODABAR_PATTERN.fullmatch(text) is None:
+            raise ValueError(
+                "codabar text must start and end with A-D and contain valid data characters"
+            )
+        return
+
+    if symbology in {"itf", "code25"}:
+        _validate_ascii(text, symbology, 128)
+        if not text.isdigit():
+            raise ValueError(f"{symbology} text must contain digits only")
+        if symbology == "itf" and len(text) % 2:
+            raise ValueError("itf text must contain an even number of digits")
+        return
+
+    required_lengths = (12, 13) if symbology == "ean13" else (7, 8)
+    if not text.isascii() or not text.isdigit() or len(text) not in required_lengths:
+        lengths = " or ".join(str(length) for length in required_lengths)
+        raise ValueError(f"{symbology} text must contain exactly {lengths} digits")
+    if len(text) == required_lengths[1] and text[-1] != _ean_checksum(text[:-1]):
+        raise ValueError(f"{symbology} text has an invalid check digit")
+
+
+def _option_flag(name: str) -> str:
+    return f"--{name.replace('_', '-')}"
+
+
+def _build_option_arguments(options: Mapping[str, object]) -> list[str]:
+    arguments: list[str] = []
+    for name, value in options.items():
+        flag = _option_flag(name)
+        if isinstance(value, bool):
+            if value:
+                arguments.append(flag)
+        else:
+            arguments.extend((flag, str(value)))
+    return arguments
+
+
+def _redact_stderr(stderr: str, text: str) -> str:
+    return stderr.replace(text, "<redacted>") if text else stderr
+
+
+def _is_png(data: bytes) -> bool:
+    if not data.startswith(_PNG_SIGNATURE):
+        return False
+
+    offset = len(_PNG_SIGNATURE)
+    first_chunk = True
+    while offset + 12 <= len(data):
+        length = int.from_bytes(data[offset : offset + 4], "big")
+        chunk_type = data[offset + 4 : offset + 8]
+        chunk_end = offset + 12 + length
+        if chunk_end > len(data):
+            return False
+        if first_chunk and (chunk_type != b"IHDR" or length != 13):
+            return False
+        first_chunk = False
+        if chunk_type == b"IEND":
+            return length == 0 and chunk_end == len(data)
+        offset = chunk_end
+    return False
+
+
+class BarcodeKit:
+    """Generate barcode PNGs by invoking barcode-rest in one-shot CLI mode."""
+
+    def __init__(
+        self,
+        executable: str | Path | None = None,
+        timeout: float = 10.0,
+    ) -> None:
+        if isinstance(timeout, bool) or not isinstance(timeout, (int, float)):
+            raise TypeError("timeout must be a number")
+        if not math.isfinite(timeout) or timeout <= 0:
+            raise ValueError("timeout must be a finite number greater than zero")
+        self._executable = executable
+        self.timeout = float(timeout)
+
+    def generate(self, symbology: str, text: str, **options: object) -> BarcodeImage:
+        """Generate a barcode using a supported symbology."""
+        if not isinstance(symbology, str):
+            raise TypeError("symbology must be a string")
+        if symbology not in _SUPPORTED_SYMBOLOGIES:
+            raise ValueError(f"Unsupported symbology: {symbology}")
+
+        validated_options = _validate_options(symbology, options)
+        _validate_text(symbology, text, validated_options)
+        executable = resolve_binary(self._executable)
+        command = [
+            str(executable),
+            "generate",
+            symbology,
+            "--text",
+            text,
+            "--output",
+            "-",
+            *_build_option_arguments(validated_options),
+        ]
+
+        try:
+            completed = subprocess.run(  # noqa: UP022 - explicit PIPEs are part of the contract
+                command,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+                timeout=self.timeout,
+                check=False,
+                shell=False,
+            )
+        except subprocess.TimeoutExpired as exc:
+            raise BarcodeKitTimeout(self.timeout, command) from exc
+        except FileNotFoundError as exc:
+            raise BarcodeKitBinaryNotFound(
+                f"barcode-rest executable disappeared before it could be run: {executable}"
+            ) from exc
+        except OSError as exc:
+            message = _redact_stderr(str(exc), text)
+            raise BarcodeKitCommandError(None, command, message) from exc
+
+        stderr = _redact_stderr(completed.stderr.decode("utf-8", errors="replace"), text)
+        if completed.returncode != 0:
+            raise BarcodeKitCommandError(completed.returncode, command, stderr)
+        if not _is_png(completed.stdout):
+            raise BarcodeKitCommandError(0, command, "barcode-rest produced invalid PNG output")
+        return BarcodeImage(completed.stdout)
+
+    def datamatrix(
+        self,
+        text: str,
+        *,
+        size: int | None = 256,
+        module: int | None = None,
+        quiet: int | None = None,
+    ) -> BarcodeImage:
+        return self.generate("datamatrix", text, size=size, module=module, quiet=quiet)
+
+    def qr(
+        self,
+        text: str,
+        *,
+        size: int | None = 512,
+        module: int | None = None,
+        quiet: int | None = None,
+        level: str = "M",
+    ) -> BarcodeImage:
+        return self.generate(
+            "qr", text, size=size, module=module, quiet=quiet, level=level
+        )
+
+    def aztec(
+        self,
+        text: str,
+        *,
+        size: int | None = 512,
+        module: int | None = None,
+        quiet: int | None = None,
+    ) -> BarcodeImage:
+        return self.generate("aztec", text, size=size, module=module, quiet=quiet)
+
+    def pdf417(
+        self,
+        text: str,
+        *,
+        module: int | None = None,
+        quiet: int | None = None,
+        level: int | str = 2,
+    ) -> BarcodeImage:
+        return self.generate("pdf417", text, module=module, quiet=quiet, level=level)
+
+    def code128(
+        self,
+        text: str,
+        *,
+        module: int | None = None,
+        height: int | None = 80,
+        quiet: int | None = None,
+        label: bool = False,
+    ) -> BarcodeImage:
+        return self.generate(
+            "code128", text, module=module, height=height, quiet=quiet, label=label
+        )
+
+    def code39(
+        self,
+        text: str,
+        *,
+        module: int | None = None,
+        height: int | None = 80,
+        quiet: int | None = None,
+        label: bool = False,
+        fullascii: bool = False,
+    ) -> BarcodeImage:
+        return self.generate(
+            "code39",
+            text,
+            module=module,
+            height=height,
+            quiet=quiet,
+            label=label,
+            fullascii=fullascii,
+        )
+
+    def code93(
+        self,
+        text: str,
+        *,
+        module: int | None = None,
+        height: int | None = 80,
+        quiet: int | None = None,
+        label: bool = False,
+        fullascii: bool = False,
+    ) -> BarcodeImage:
+        return self.generate(
+            "code93",
+            text,
+            module=module,
+            height=height,
+            quiet=quiet,
+            label=label,
+            fullascii=fullascii,
+        )
+
+    def codabar(
+        self,
+        text: str,
+        *,
+        module: int | None = None,
+        height: int | None = 80,
+        quiet: int | None = None,
+        label: bool = False,
+    ) -> BarcodeImage:
+        return self.generate(
+            "codabar", text, module=module, height=height, quiet=quiet, label=label
+        )
+
+    def itf(
+        self,
+        text: str,
+        *,
+        module: int | None = None,
+        height: int | None = 80,
+        quiet: int | None = None,
+        label: bool = False,
+    ) -> BarcodeImage:
+        return self.generate(
+            "itf", text, module=module, height=height, quiet=quiet, label=label
+        )
+
+    def code25(
+        self,
+        text: str,
+        *,
+        module: int | None = None,
+        height: int | None = 80,
+        quiet: int | None = None,
+        label: bool = False,
+    ) -> BarcodeImage:
+        return self.generate(
+            "code25", text, module=module, height=height, quiet=quiet, label=label
+        )
+
+    def ean13(
+        self,
+        text: str,
+        *,
+        module: int | None = None,
+        height: int | None = 80,
+        quiet: int | None = None,
+        label: bool = False,
+    ) -> BarcodeImage:
+        return self.generate(
+            "ean13", text, module=module, height=height, quiet=quiet, label=label
+        )
+
+    def ean8(
+        self,
+        text: str,
+        *,
+        module: int | None = None,
+        height: int | None = 80,
+        quiet: int | None = None,
+        label: bool = False,
+    ) -> BarcodeImage:
+        return self.generate(
+            "ean8", text, module=module, height=height, quiet=quiet, label=label
+        )

barcodekit/_errors.py

@@ -0,0 +1,64 @@
+"""Public exceptions raised by barcodekit."""
+
+from __future__ import annotations
+
+import os
+import shlex
+import subprocess
+from collections.abc import Sequence
+
+
+def _redact_command(command: Sequence[str]) -> tuple[str, ...]:
+    """Return command arguments with the barcode text removed."""
+    redacted = list(command)
+    for index, argument in enumerate(redacted[:-1]):
+        if argument == "--text":
+            redacted[index + 1] = "<redacted>"
+    return tuple(redacted)
+
+
+def _display_command(command: Sequence[str]) -> str:
+    redacted = _redact_command(command)
+    if os.name == "nt":
+        return subprocess.list2cmdline(redacted)
+    return shlex.join(redacted)
+
+
+class BarcodeKitError(Exception):
+    """Base class for barcodekit errors."""
+
+
+class BarcodeKitBinaryNotFound(BarcodeKitError):
+    """Raised when the configured or bundled executable cannot be found."""
+
+
+class BarcodeKitUnsupportedPlatform(BarcodeKitError):
+    """Raised when barcodekit does not support the current platform."""
+
+
+class BarcodeKitCommandError(BarcodeKitError):
+    """Raised when barcode-rest fails or returns unusable output."""
+
+    def __init__(
+        self,
+        returncode: int | None,
+        command: Sequence[str],
+        stderr: str,
+    ) -> None:
+        self.returncode = returncode
+        self.command = _redact_command(command)
+        self.stderr = stderr
+        code = "could not be started" if returncode is None else f"exited with code {returncode}"
+        detail = stderr.strip() or "no error details"
+        super().__init__(f"barcode-rest {code}: {_display_command(command)}; {detail}")
+
+
+class BarcodeKitTimeout(BarcodeKitError):
+    """Raised when barcode-rest does not finish before the timeout."""
+
+    def __init__(self, timeout: float, command: Sequence[str]) -> None:
+        self.timeout = timeout
+        self.command = _redact_command(command)
+        super().__init__(
+            f"barcode-rest timed out after {timeout:g} seconds: {_display_command(command)}"
+        )

barcodekit/_version.py

@@ -0,0 +1,4 @@
+"""Package version."""
+
+__version__ = "0.1.2"
+

barcodekit/py.typed

@@ -0,0 +1 @@
+

barcodekit-0.1.2.dist-info/METADATA

@@ -0,0 +1,194 @@
+Metadata-Version: 2.4
+Name: barcodekit
+Version: 0.1.2
+Summary: Generate barcode PNGs with the local barcode-rest command-line tool.
+Project-URL: Homepage, https://github.com/Moge800/barcodekit
+Project-URL: Upstream CLI, https://github.com/Moge800/barcode-rest
+Author: Moge800
+License-Expression: MIT
+License-File: LICENSE
+License-File: THIRD_PARTY_NOTICES.md
+License-File: licenses/barcode-rest-MIT.txt
+License-File: licenses/boombuler-barcode-MIT.txt
+License-File: licenses/go-and-x-image-BSD-3-Clause.txt
+Keywords: barcode,barcode-rest,code128,datamatrix,qr
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: Microsoft :: Windows :: Windows 10
+Classifier: Operating System :: Microsoft :: Windows :: Windows 11
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: mypy>=1.14; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.9; extra == 'dev'
+Provides-Extra: release
+Requires-Dist: wheel<1,>=0.45; extra == 'release'
+Description-Content-Type: text/markdown
+
+# barcodekit
+
+[日本語](https://github.com/Moge800/barcodekit/blob/main/README_JP.md)
+
+`barcodekit` generates barcode PNG images from Python by invoking the local
+[`barcode-rest`](https://github.com/Moge800/barcode-rest) executable in its
+one-shot CLI mode.
+
+Despite the upstream executable's name, **barcodekit does not start the REST
+server and does not use HTTP**. Each operation runs only:
+
+```text
+barcode-rest generate <symbology> --text <text> --output -
+```
+
+PNG bytes are read from standard output and returned directly to Python.
+
+## Quick start
+
+Install the platform-specific wheel, then:
+
+```python
+from barcodekit import code128, datamatrix, qr
+
+datamatrix("ABC123", size=256).save("dm.png")
+qr("https://example.com", size=512, level="Q").save("qr.png")
+code128("ABC-123456", label=True).save("c128.png")
+```
+
+An explicit engine object provides the same methods:
+
+```python
+from barcodekit import BarcodeKit
+
+kit = BarcodeKit(timeout=10)
+image = kit.datamatrix("ABC123", size=256)
+
+raw_png = image.to_bytes()
+image.save("dm.png")
+```
+
+For `datamatrix`, `qr`, and `aztec`, `size` and `module` are mutually exclusive.
+Set `size=None` when selecting the module size directly:
+
+```python
+datamatrix("ABC123", size=None, module=8)
+```
+
+## Executable resolution
+
+`barcodekit` resolves the executable when an image is generated, in this order:
+
+1. The file path passed as `BarcodeKit(executable=...)`.
+2. The file path in `BARCODEKIT_BINARY`.
+3. The executable bundled in the installed platform wheel.
+
+An explicit development binary can be used without building a wheel:
+
+```python
+kit = BarcodeKit(executable=r"C:\tools\barcode-rest.exe")
+kit.datamatrix("ABC123").save("dm.png")
+```
+
+Or with an environment variable:
+
+```powershell
+$env:BARCODEKIT_BINARY = "C:\tools\barcode-rest.exe"
+uv run python example.py
+```
+
+```bash
+BARCODEKIT_BINARY=/opt/barcode-rest uv run python example.py
+```
+
+These values must be file paths; barcodekit does not search `PATH`.
+
+## Bundled binary wheels
+
+Each released wheel is intended to contain exactly one matching
+`barcode-rest` executable. It must not contain a collection of executables for
+other operating systems or CPU architectures.
+
+Supported bundled targets:
+
+- Windows amd64
+- Linux amd64 using glibc 2.34 or newer, including Ubuntu 22.04 or newer
+- Linux arm64 using glibc, including 64-bit Ubuntu and 64-bit Raspberry Pi OS
+
+Unsupported targets:
+
+- macOS
+- Windows arm64
+- 32-bit Linux and 32-bit Raspberry Pi OS
+- musl-based Linux distributions such as Alpine Linux
+
+Binary-free source distributions are not intended for release. On the
+supported operating systems and CPU architectures listed above, development
+from a source checkout remains supported with `BARCODEKIT_BINARY` or
+`BarcodeKit(executable=...)`.
+
+Release builds currently pin
+[`barcode-rest` v0.2.0](https://github.com/Moge800/barcode-rest/releases/tag/v0.2.0).
+The expected SHA-256 values are committed in `checksums/v0.2.0.sha256`.
+
+## Supported symbologies
+
+Two-dimensional:
+
+- Data Matrix (`datamatrix`)
+- QR Code (`qr`)
+- Aztec (`aztec`)
+- PDF417 (`pdf417`)
+
+One-dimensional:
+
+- Code 128 (`code128`)
+- Code 39 (`code39`)
+- Code 93 (`code93`)
+- Codabar (`codabar`)
+- Interleaved 2 of 5 (`itf`)
+- Standard 2 of 5 (`code25`)
+- EAN-13 / JAN (`ean13`)
+- EAN-8 (`ean8`)
+
+`barcodekit` validates supported options, numeric ranges, text limits, basic
+character sets, and check digits before starting the executable. Encoding
+constraints that depend on the generated symbol remain the responsibility of
+`barcode-rest`.
+
+## Security and privacy
+
+- No executable or other data is downloaded at runtime.
+- No server is started.
+- The REST API and HTTP are not used.
+- No outbound network connection is made by the wrapper.
+- Barcode text is passed only to the local `barcode-rest` executable.
+- The wrapper does not log barcode text.
+- Commands shown by wrapper exceptions replace the value after `--text` with
+  `<redacted>`. Matching text returned on stderr is also redacted.
+
+The text is necessarily passed through the local process command line because
+that is the upstream CLI interface. It may therefore be temporarily visible to
+users or tools with permission to inspect local process arguments.
+
+## Development with uv
+
+```bash
+uv sync --extra dev
+uv run pytest
+uv run ruff check .
+uv run mypy src/barcodekit
+uv build
+```
+
+Unit tests mock `subprocess.run` and do not need the Go executable. If
+`BARCODEKIT_BINARY` is set, the optional integration test generates a real
+Data Matrix image and checks its PNG output.
+
+## License
+
+`barcodekit` is MIT licensed. Platform wheels also include the notices and
+license texts listed in
+[THIRD_PARTY_NOTICES.md](https://github.com/Moge800/barcodekit/blob/v0.1.2/THIRD_PARTY_NOTICES.md).

barcodekit-0.1.2.dist-info/RECORD

@@ -0,0 +1,16 @@
+barcodekit/__init__.py,sha256=4KLH7Uiauip6QARkFz3jxe4Y4OR4LcRz4NqZgf5wxzI,4409
+barcodekit/_binary.py,sha256=ybYPXUsesaDM3JLbmkfddANsUhDUtMGHCUU0y7l0BJA,2788
+barcodekit/_core.py,sha256=71Isg1W-Aurk1vPSvN0pEQ6qGEndf3WJTSKQZDRCC3Y,15645
+barcodekit/_errors.py,sha256=VzAUUSkhRrTCipUoVeK7Wq6aYplp8Ulj8feAuWMR66g,2082
+barcodekit/_version.py,sha256=e1Iz5EfvRhaCoTklG4I54svyD-fQ1ujsrPto2dSw1cg,51
+barcodekit/py.typed,sha256=frcCV1k9oG9oKj3dpUqdJg1PxRT2RSN_XKdLCPjaYaY,2
+barcodekit/_bin/.gitkeep,sha256=frcCV1k9oG9oKj3dpUqdJg1PxRT2RSN_XKdLCPjaYaY,2
+barcodekit/_bin/barcode-rest.exe,sha256=Qn-mC-IO7VPBILxsdyZc0s_PjOLaMQR4hcuVikjaWsg,9929216
+barcodekit-0.1.2.dist-info/METADATA,sha256=9KKyLb47foSB3Dj-Pl2SEHL1XW6LrQU5q9pU9jNV4qI,6001
+barcodekit-0.1.2.dist-info/WHEEL,sha256=pp_iTzO0EBcCvlZZV2dJYp6L2tdDWBsn1ceo50wEt8Q,94
+barcodekit-0.1.2.dist-info/licenses/LICENSE,sha256=9BmdgGze2TgObLNWUVMlYMK3n_Q76jWnm_bHkdpBvg4,1087
+barcodekit-0.1.2.dist-info/licenses/THIRD_PARTY_NOTICES.md,sha256=sYLLB_bLSGwDMEcQaMu6_UdTt3C-ggFLt0XELYQE5Sw,691
+barcodekit-0.1.2.dist-info/licenses/licenses/barcode-rest-MIT.txt,sha256=9BmdgGze2TgObLNWUVMlYMK3n_Q76jWnm_bHkdpBvg4,1087
+barcodekit-0.1.2.dist-info/licenses/licenses/boombuler-barcode-MIT.txt,sha256=KxADQwMxUj_V8zUg3vQ1VkxxPLZVNLLYMbpQkhcwUe0,1108
+barcodekit-0.1.2.dist-info/licenses/licenses/go-and-x-image-BSD-3-Clause.txt,sha256=JyHS_WMLrAVQohVdq64G2DWGcuUpCauv_SsstFNktYc,1482
+barcodekit-0.1.2.dist-info/RECORD,,

barcodekit-0.1.2.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-win_amd64
+

barcodekit-0.1.2.dist-info/licenses/LICENSE

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

barcodekit-0.1.2.dist-info/licenses/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,15 @@
+# Third-party notices
+
+Platform-specific `barcodekit` wheels bundle the `barcode-rest` executable.
+That executable contains the following software:
+
+| Component | Version | License |
+| --- | --- | --- |
+| [barcode-rest](https://github.com/Moge800/barcode-rest) | v0.2.0 | MIT |
+| [github.com/boombuler/barcode](https://github.com/boombuler/barcode) | v1.0.2 | MIT |
+| [Go](https://go.dev/) runtime and standard library | 1.26 | BSD-3-Clause |
+| [golang.org/x/image](https://pkg.go.dev/golang.org/x/image) | v0.43.0 | BSD-3-Clause |
+
+The corresponding license texts are included in the `licenses` directory.
+`barcodekit` itself is licensed under the MIT License in `LICENSE`.
+

barcodekit-0.1.2.dist-info/licenses/licenses/barcode-rest-MIT.txt

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

barcodekit-0.1.2.dist-info/licenses/licenses/boombuler-barcode-MIT.txt

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2014 Florian Sundermann
+
+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.
+

barcodekit-0.1.2.dist-info/licenses/licenses/go-and-x-image-BSD-3-Clause.txt

@@ -0,0 +1,28 @@
+Copyright 2009 The Go Authors.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+   * Redistributions of source code must retain the above copyright
+notice, this list of conditions and the following disclaimer.
+   * Redistributions in binary form must reproduce the above
+copyright notice, this list of conditions and the following disclaimer
+in the documentation and/or other materials provided with the
+distribution.
+   * Neither the name of Google LLC nor the names of its
+contributors may be used to endorse or promote products derived from
+this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+