datamax-dpl 0.1.0__py3-none-any.whl

datamax_dpl/__init__.py

@@ -0,0 +1,96 @@
+"""datamax-dpl: build, check and print Datamax DPL label jobs.
+
+The library surface, in the order a caller usually needs it:
+
+* the label model (:class:`Label` and its elements) and its enums;
+* :func:`render` (raises on an error finding) and :func:`build_job` (reports every finding);
+* :func:`render_batch` and :func:`fill_label` for one label per data record;
+* :func:`open_printer` to send the bytes, :func:`explain` to read DPL back;
+* :func:`get_profile` / :func:`list_profiles` for the printer models;
+* :func:`render_preview_png` for a picture of the label.
+
+Example:
+    >>> from datamax_dpl import Label, RenderOptions, Text, render
+    >>> job = render(Label(elements=[Text(x=5, y=5, text="Hello")]), RenderOptions(model="dmx-600"))
+    >>> job.data[:3]
+    b'\\x02L\\r'
+"""
+
+from __future__ import annotations
+
+from .__init__conf__ import print_info
+from .adapters.preview import render_preview_png
+from .adapters.transport import open_printer
+from .application.use_cases import BatchResult, render_batch
+from .composition import get_config
+from .domain.decoder import explain
+from .domain.enums import Attribute, FallbackPolicy, FillPattern, MediaSensor, Rotation, Severity, SpeedCode, Unit
+from .domain.errors import LabelRejectedError, TransportError
+from .domain.findings import Finding
+from .domain.label import (
+    Barcode,
+    Box,
+    Circle,
+    Counter,
+    Cut,
+    DataMatrixOptions,
+    DotSize,
+    Image,
+    Label,
+    Line,
+    Pdf417Options,
+    Point,
+    Polygon,
+    ScalableText,
+    Text,
+)
+from .domain.placeholders import fill_label
+from .domain.profiles import PrinterProfile, get_profile, list_profiles
+from .domain.render import RenderResult, build_job, render
+from .domain.render_context import RenderOptions
+from .domain.symbology import Symbology
+
+__all__ = [
+    "Attribute",
+    "Barcode",
+    "BatchResult",
+    "Box",
+    "Circle",
+    "Counter",
+    "Cut",
+    "DataMatrixOptions",
+    "DotSize",
+    "FallbackPolicy",
+    "FillPattern",
+    "Finding",
+    "Image",
+    "Label",
+    "LabelRejectedError",
+    "Line",
+    "MediaSensor",
+    "Pdf417Options",
+    "Point",
+    "Polygon",
+    "PrinterProfile",
+    "RenderOptions",
+    "RenderResult",
+    "Rotation",
+    "ScalableText",
+    "Severity",
+    "SpeedCode",
+    "Symbology",
+    "Text",
+    "TransportError",
+    "Unit",
+    "build_job",
+    "explain",
+    "fill_label",
+    "get_config",
+    "get_profile",
+    "list_profiles",
+    "open_printer",
+    "print_info",
+    "render",
+    "render_batch",
+    "render_preview_png",
+]

datamax_dpl/__init__conf__.py

@@ -0,0 +1,90 @@
+"""Static package metadata surfaced to CLI commands and documentation.
+
+Purpose
+-------
+Expose the current project metadata as simple constants. These values are kept
+in sync with ``pyproject.toml`` by development automation (tests, push
+pipelines), so runtime code does not query packaging metadata.
+
+Contents
+--------
+* Module-level constants describing the published package.
+* :func:`print_info` rendering the constants for the CLI ``info`` command.
+
+System Role
+-----------
+Lives in the adapters/platform layer; CLI transports import these constants to
+present authoritative project information without invoking packaging APIs.
+"""
+
+from __future__ import annotations
+
+import sys
+
+__all__ = [
+    "LAYEREDCONF_APP",
+    "LAYEREDCONF_SLUG",
+    "LAYEREDCONF_VENDOR",
+    "author",
+    "author_email",
+    "homepage",
+    "name",
+    "print_info",
+    "shell_command",
+    "title",
+    "version",
+]
+
+#: Distribution name declared in ``pyproject.toml``.
+name = "datamax-dpl"
+#: Human-readable summary shown in CLI help output.
+title = "Datamax DPL label printing: library, CLI and LLM-friendly JSON, with per-model capability checks"
+#: Current release version pulled from ``pyproject.toml`` by automation.
+version = "0.1.0"
+#: Repository homepage presented to users.
+homepage = "https://github.com/bitranox/datamax-dpl"
+#: Author attribution surfaced in CLI output.
+author = "bitranox"
+#: Contact email surfaced in CLI output.
+author_email = "bitranox@gmail.com"
+#: Console-script name published by the package.
+shell_command = "datamax-dpl"
+
+#: Vendor identifier for lib_layered_config paths (macOS/Windows)
+LAYEREDCONF_VENDOR: str = "bitranox"
+#: Application display name for lib_layered_config paths (macOS/Windows)
+LAYEREDCONF_APP: str = "datamax_dpl"
+#: Configuration slug for lib_layered_config Linux paths and environment variables
+LAYEREDCONF_SLUG: str = "datamax-dpl"
+
+
+def print_info() -> None:
+    """Print the summarised metadata block used by the CLI ``info`` command.
+
+    Why
+        Provides a single, auditable rendering function so documentation and
+        CLI output always match the system design reference.
+
+    Side Effects
+        Writes to ``stdout``.
+
+    Examples
+    --------
+    >>> print_info()  # doctest: +ELLIPSIS
+    Info for datamax-dpl:
+    ...
+    """
+
+    fields = [
+        ("name", name),
+        ("title", title),
+        ("version", version),
+        ("homepage", homepage),
+        ("author", author),
+        ("author_email", author_email),
+        ("shell_command", shell_command),
+    ]
+    pad = max(len(label) for label, _ in fields)
+    lines = [f"Info for {name}:", ""]
+    lines.extend(f"    {label.ljust(pad)} = {value}" for label, value in fields)
+    sys.stdout.write("\n".join(lines) + "\n")

datamax_dpl/__main__.py

@@ -0,0 +1,9 @@
+"""Module entry point for ``python -m datamax_dpl``."""
+
+from __future__ import annotations
+
+from .adapters.cli.main import main
+from .composition import build_production
+
+if __name__ == "__main__":
+    raise SystemExit(main(services_factory=build_production))

datamax_dpl/adapters/__init__.py

@@ -0,0 +1,14 @@
+"""Adapters layer - infrastructure and framework integrations.
+
+Contains adapter implementations that connect the application to external
+systems and frameworks (CLI, configuration, logging).
+
+Contents:
+    * :mod:`.config` - Configuration loading, deployment, and display
+    * :mod:`.logging` - Logging setup with lib_log_rich
+    * :mod:`.cli` - Click CLI framework integration
+"""
+
+from __future__ import annotations
+
+__all__: list[str] = []

datamax_dpl/adapters/camera/__init__.py

@@ -0,0 +1,117 @@
+"""Camera adapters: take one photo of a printed label with the configured camera.
+
+:func:`capture_image` implements the :class:`~datamax_dpl.application.ports.CaptureImage` port
+and dispatches on ``[camera] kind``:
+
+* ``command`` - :mod:`.command` runs a capture program that writes the image itself.
+* ``http`` - :mod:`.http` fetches a snapshot URL.
+* ``file`` - :mod:`.file` picks up the newest image a camera drops into a folder.
+
+Every image is stored in ``output_dir`` as ``capture-<UTC timestamp>.<ext>``. Waiting
+``settle_seconds`` after the print is the caller's job; the adapters take the photo at once.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import TYPE_CHECKING, Protocol
+
+from ...domain.camera import CameraKind, CapturedImage
+from ...domain.errors import CameraError
+from .command import capture_with_command
+from .file import MEDIA_TYPE_BY_SUFFIX, capture_from_directory
+from .http import capture_with_http
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from ...domain.camera import CameraSettings
+
+
+class _Capture(Protocol):
+    """One capture strategy: write the image next to ``stem`` and return its path."""
+
+    def __call__(self, settings: CameraSettings, *, stem: Path) -> Path: ...
+
+
+_CAPTURE_BY_KIND: dict[CameraKind, _Capture] = {
+    CameraKind.COMMAND: capture_with_command,
+    CameraKind.HTTP: capture_with_http,
+    CameraKind.FILE: capture_from_directory,
+}
+
+#: strftime pattern of the timestamp in an image file name; microseconds keep names unique.
+CAPTURE_STAMP_FORMAT = "%Y%m%dT%H%M%S%fZ"
+
+
+def capture_image(settings: CameraSettings, *, output_dir: Path) -> CapturedImage:
+    """Take one photo with the configured camera and store it in ``output_dir``.
+
+    Args:
+        settings: The ``[camera]`` section.
+        output_dir: Folder for the image; created when missing.
+
+    Returns:
+        The stored image with its media type and the (UTC) moment the capture finished.
+
+    Raises:
+        CameraError: No camera is configured, ``output_dir`` cannot be created, or the camera
+            could not deliver an image.
+
+    Example:
+        >>> from pathlib import Path
+        >>> from datamax_dpl.domain.camera import CameraSettings
+        >>> capture_image(CameraSettings(), output_dir=Path("unused"))
+        Traceback (most recent call last):
+        ...
+        datamax_dpl.domain.errors.CameraError: no camera configured: set [camera] kind
+    """
+    capture = _CAPTURE_BY_KIND.get(settings.kind)
+    if capture is None:
+        raise CameraError("no camera configured: set [camera] kind")
+    try:
+        output_dir.mkdir(parents=True, exist_ok=True)
+    except OSError as exc:
+        raise CameraError(f"image folder {output_dir} cannot be created: {exc.strerror or exc}") from exc
+    stem = output_dir / f"capture-{datetime.now(timezone.utc).strftime(CAPTURE_STAMP_FORMAT)}"
+    path = capture(settings, stem=stem)
+    return CapturedImage(path=path, media_type=media_type_for(path), captured_at=datetime.now(timezone.utc))
+
+
+def media_type_for(path: Path) -> str:
+    """Return the media type of an image file from its suffix.
+
+    Args:
+        path: An image path ending in ``.jpg``, ``.jpeg`` or ``.png`` (any case).
+
+    Returns:
+        ``image/jpeg`` or ``image/png``.
+
+    Raises:
+        CameraError: The suffix is not an image suffix this package writes.
+
+    Example:
+        >>> from pathlib import Path
+        >>> media_type_for(Path("capture.PNG"))
+        'image/png'
+    """
+    media_type = MEDIA_TYPE_BY_SUFFIX.get(path.suffix.lower())
+    if media_type is None:
+        raise CameraError(f"{path.name} is not a JPEG or PNG file name")
+    return media_type
+
+
+if TYPE_CHECKING:
+    from ...application.ports import CaptureImage
+
+    _assert_capture_image: CaptureImage = capture_image
+
+
+__all__ = [
+    "CAPTURE_STAMP_FORMAT",
+    "capture_from_directory",
+    "capture_image",
+    "capture_with_command",
+    "capture_with_http",
+    "media_type_for",
+]

datamax_dpl/adapters/camera/command.py

@@ -0,0 +1,144 @@
+"""Take a photo by running an external capture program (``[camera] kind = "command"``).
+
+The configured argv is run directly, never through a shell. Every occurrence of
+:data:`~datamax_dpl.domain.camera.OUTPUT_PLACEHOLDER` is replaced by the image path.
+
+Extension rule:
+    The image is a ``.jpg`` unless the argv writes the placeholder immediately followed by an
+    image suffix, as in ``"{output}.png"``: then that suffix (``.png``, ``.jpg`` or ``.jpeg``,
+    any case) becomes the file's extension and the placeholder plus suffix is replaced by the
+    full path. ``["fswebcam", "{output}"]`` writes ``capture-<stamp>.jpg``;
+    ``["grab", "-o", "{output}.png"]`` writes ``capture-<stamp>.png``. Two different suffixes
+    in one argv are refused, since only one file is collected.
+"""
+
+from __future__ import annotations
+
+import re
+import shutil
+import subprocess  # nosec B404 # running the operator's capture program is this module's job
+from typing import TYPE_CHECKING
+
+from ...domain.camera import OUTPUT_PLACEHOLDER
+from ...domain.errors import CameraError
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from ...domain.camera import CameraSettings
+
+#: Extension used when the argv does not name one next to the placeholder.
+DEFAULT_EXTENSION = ".jpg"
+
+#: How many trailing characters of the program's stderr an error message carries.
+STDERR_TAIL_CHARS = 500
+
+_PLACEHOLDER_PATTERN = re.compile(re.escape(OUTPUT_PLACEHOLDER) + r"(\.(?:png|jpe?g))?", re.IGNORECASE)
+
+
+def capture_with_command(settings: CameraSettings, *, stem: Path) -> Path:
+    """Run ``settings.command`` and return the image it wrote.
+
+    Args:
+        settings: The camera settings; ``command`` and ``timeout`` are used.
+        stem: Output path without extension; the extension follows the rule in the module
+            docstring.
+
+    Returns:
+        The path of the non-empty image file the program wrote.
+
+    Raises:
+        CameraError: The argv is empty or lacks the placeholder, the program is missing, it
+            timed out, exited non-zero, or left no non-empty image behind.
+
+    Example:
+        >>> import sys, tempfile
+        >>> from pathlib import Path
+        >>> from datamax_dpl.domain.camera import CameraKind, CameraSettings
+        >>> script = "import sys; open(sys.argv[1], 'wb').write(b'img')"
+        >>> settings = CameraSettings(kind=CameraKind.COMMAND, command=[sys.executable, "-c", script, "{output}"])
+        >>> with tempfile.TemporaryDirectory() as tmp:
+        ...     capture_with_command(settings, stem=Path(tmp) / "capture").name
+        'capture.jpg'
+    """
+    argv = list(settings.command)
+    if not argv:
+        raise CameraError("no camera command configured: set [camera] command")
+    output = stem.with_suffix(_extension(argv))
+    resolved = [_resolve_program(argv[0]), *(_substitute(arg, output=output) for arg in argv[1:])]
+    _run(resolved, program=argv[0], timeout=settings.timeout)
+    _require_image(output, program=argv[0])
+    return output
+
+
+def _extension(argv: list[str]) -> str:
+    """Return the image extension the argv asks for, refusing an argv without the placeholder."""
+    matches = [match for arg in argv for match in _PLACEHOLDER_PATTERN.finditer(arg)]
+    if not matches:
+        raise CameraError(f"camera command has no {OUTPUT_PLACEHOLDER} argument to receive the image path")
+    suffixes = {_normalise_suffix(match.group(1)) for match in matches if match.group(1)}
+    if len(suffixes) > 1:
+        raise CameraError(f"camera command names conflicting image suffixes: {sorted(suffixes)}")
+    return suffixes.pop() if suffixes else DEFAULT_EXTENSION
+
+
+def _normalise_suffix(suffix: str) -> str:
+    """Lower-case a suffix so ``.PNG`` and ``.png`` name the same file type."""
+    return suffix.lower()
+
+
+def _substitute(arg: str, *, output: Path) -> str:
+    """Replace every placeholder (with its optional suffix) in ``arg`` by the output path."""
+    # A lambda keeps re from parsing the path as a replacement template: a Windows path's
+    # backslashes would otherwise be read as escapes or group references.
+    return _PLACEHOLDER_PATTERN.sub(lambda _match: str(output), arg)
+
+
+def _resolve_program(program: str) -> str:
+    """Return the absolute path of ``program``.
+
+    Windows CreateProcess searches the parent's PATH rather than the child's, so the program is
+    resolved here with the same PATH on every platform.
+    """
+    resolved = shutil.which(program)
+    if resolved is None:
+        raise CameraError(f"camera program not found: {program!r}")
+    return resolved
+
+
+def _run(argv: list[str], *, program: str, timeout: float) -> None:
+    """Run ``argv`` to completion, turning every failure into a :class:`CameraError`."""
+    try:
+        completed = subprocess.run(  # noqa: S603 - operator-configured argv, no shell # nosec B603
+            argv,
+            stdin=subprocess.DEVNULL,
+            capture_output=True,
+            timeout=timeout,
+            check=False,
+        )
+    except subprocess.TimeoutExpired as exc:
+        raise CameraError(f"camera program {program!r} timed out after {timeout:g} s") from exc
+    except OSError as exc:
+        raise CameraError(f"camera program {program!r} could not be started: {exc.strerror or exc}") from exc
+    if completed.returncode != 0:
+        tail = _stderr_tail(completed.stderr)
+        raise CameraError(f"camera program {program!r} exited with status {completed.returncode}: {tail}")
+
+
+def _stderr_tail(stderr: bytes) -> str:
+    """Return the last :data:`STDERR_TAIL_CHARS` characters of ``stderr``, decoded leniently."""
+    text = stderr.decode("utf-8", errors="replace").strip()
+    return text[-STDERR_TAIL_CHARS:] if text else "(no stderr output)"
+
+
+def _require_image(output: Path, *, program: str) -> None:
+    """Refuse a run that left no image, or an empty one, at ``output``."""
+    try:
+        size = output.stat().st_size
+    except OSError as exc:
+        raise CameraError(f"camera program {program!r} wrote no image to {output}") from exc
+    if size == 0:
+        raise CameraError(f"camera program {program!r} wrote an empty image to {output}")
+
+
+__all__ = ["DEFAULT_EXTENSION", "STDERR_TAIL_CHARS", "capture_with_command"]

datamax_dpl/adapters/camera/file.py

@@ -0,0 +1,138 @@
+"""Take a photo by picking up the newest image a camera drops into a folder (``kind = "file"``).
+
+Cameras and phone apps that upload into a watched folder are handled here: the newest
+``.jpg``/``.jpeg``/``.png`` whose modification time is at or after the moment the capture began
+(minus :data:`MTIME_GRACE_SECONDS`, for coarse file-system timestamps and clock skew of a
+network share) is copied into the output directory. A file is taken only once its size has
+been the same on two consecutive polls, so an upload still in progress is not collected half
+written.
+"""
+
+from __future__ import annotations
+
+import shutil
+import stat
+import time
+from pathlib import Path
+from typing import TYPE_CHECKING, NamedTuple
+
+from ...domain.errors import CameraError
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from ...domain.camera import CameraSettings
+
+#: Image file suffixes picked up, and the media type each one is reported with.
+MEDIA_TYPE_BY_SUFFIX: dict[str, str] = {
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".png": "image/png",
+}
+
+#: A file this many seconds older than the start of the capture still counts as new.
+MTIME_GRACE_SECONDS = 1.0
+
+#: Pause between two looks at the folder.
+POLL_INTERVAL_SECONDS = 0.25
+
+
+class _Candidate(NamedTuple):
+    """One image file seen in the folder, with the size it had when seen."""
+
+    path: Path
+    size: int
+
+
+def capture_from_directory(
+    settings: CameraSettings,
+    *,
+    stem: Path,
+    sleep: Callable[[float], None] = time.sleep,
+    clock: Callable[[], float] = time.monotonic,
+) -> Path:
+    """Wait for a new image in ``settings.directory`` and copy it next to ``stem``.
+
+    Args:
+        settings: The camera settings; ``directory`` and ``timeout`` are used.
+        stem: Output path without extension; the source file's (lower-cased) suffix is kept.
+        sleep: Pause between polls; injected so tests do not wait. Typed as a plain callable
+            because ``time.sleep`` takes its argument positional-only, which the
+            ``ports.Sleep`` Protocol (keyword-capable ``seconds``) does not accept.
+        clock: Monotonic seconds for the deadline; injected so tests control time.
+
+    Returns:
+        The path of the copy.
+
+    Raises:
+        CameraError: No directory is configured, it cannot be read, or no new complete image
+            appeared within ``settings.timeout`` seconds.
+    """
+    directory = _directory(settings)
+    since = time.time() - MTIME_GRACE_SECONDS
+    deadline = clock() + settings.timeout
+    previous: _Candidate | None = None
+    while True:
+        current = _newest_image(directory, since=since)
+        if current is not None and current == previous:
+            return _copy(current.path, stem=stem)
+        if clock() >= deadline:
+            raise CameraError(f"no new complete image appeared in {directory} within {settings.timeout:g} s")
+        previous = current
+        sleep(POLL_INTERVAL_SECONDS)
+
+
+def _directory(settings: CameraSettings) -> Path:
+    """Return the configured folder, refusing an empty setting or a path that is not a folder."""
+    if not settings.directory:
+        raise CameraError("no camera directory configured: set [camera] directory")
+    directory = Path(settings.directory)
+    if not directory.is_dir():
+        raise CameraError(f"camera directory {directory} does not exist or is not a directory")
+    return directory
+
+
+def _newest_image(directory: Path, *, since: float) -> _Candidate | None:
+    """Return the newest non-empty image modified at or after ``since``, or None."""
+    try:
+        entries = list(directory.iterdir())
+    except OSError as exc:
+        raise CameraError(f"camera directory {directory} cannot be read: {exc.strerror or exc}") from exc
+    best: tuple[float, _Candidate] | None = None
+    for entry in entries:
+        seen = _image_stat(entry, since=since)
+        if seen is not None and (best is None or seen[0] > best[0]):
+            best = seen
+    return None if best is None else best[1]
+
+
+def _image_stat(entry: Path, *, since: float) -> tuple[float, _Candidate] | None:
+    """Return ``(mtime, candidate)`` for a new, non-empty image file, else None."""
+    if entry.suffix.lower() not in MEDIA_TYPE_BY_SUFFIX:
+        return None
+    try:
+        info = entry.stat()
+    except OSError:
+        # The camera software may rename or delete a file between the listing and the stat.
+        return None
+    if not stat.S_ISREG(info.st_mode) or info.st_mtime < since or info.st_size == 0:
+        return None
+    return info.st_mtime, _Candidate(path=entry, size=info.st_size)
+
+
+def _copy(source: Path, *, stem: Path) -> Path:
+    """Copy ``source`` to ``stem`` with the source's lower-cased suffix."""
+    output = stem.with_suffix(source.suffix.lower())
+    try:
+        shutil.copyfile(source, output)
+    except OSError as exc:
+        raise CameraError(f"camera image {source} could not be copied: {exc.strerror or exc}") from exc
+    return output
+
+
+__all__ = [
+    "MEDIA_TYPE_BY_SUFFIX",
+    "MTIME_GRACE_SECONDS",
+    "POLL_INTERVAL_SECONDS",
+    "capture_from_directory",
+]