sercomm-printserver 0.1.0__py3-none-any.whl

sercomm_printserver/__init__.py

@@ -0,0 +1,101 @@
+"""Public package surface: talk to a SerComm print server from Python.
+
+Typical use::
+
+    from sercomm_printserver import DeviceEndpoint, PrintJob, open_print_server
+
+    server = open_print_server(DeviceEndpoint(host="192.0.2.52"))
+    server.print_lpd("L1", PrintJob(data=b"hello\\r\\n\\f", name="greeting"))
+    print(server.info().firmware_version)
+
+Finding devices: :func:`discover_print_servers`. Reaching a device by its MAC through a borrowed
+address (the ARP trick, needs admin rights): :mod:`arp_trick` with :class:`IpscoutNeighborTable`.
+Every failure is one of the exceptions exported here; see each method's ``Raises``.
+"""
+
+from __future__ import annotations
+
+from ipaddress import IPv4Network
+
+# Metadata
+from .__init__conf__ import print_info
+from .adapters.discovery import FtpBannerScanner
+from .adapters.neighbors import IpscoutNeighborTable
+from .application import arp_trick
+from .application.discovery import DiscoveredDevice, DiscoveryReport, discover
+from .application.print_server import ConfigWriteResult, PrintServer
+
+# Composition exports (wired adapters)
+from .composition import get_config, open_print_server
+from .domain.config_codec import ConfigChange, parse_config, render_config, with_value
+from .domain.config_model import DeviceConfig
+from .domain.device_info import DeviceInfo, MacAddress, normalise_mac
+from .domain.endpoint import DeviceEndpoint, PrintJob
+from .domain.errors import (
+    AuthenticationRequiredError,
+    ConfigFormatError,
+    ConfigurationError,
+    ConfirmationRequiredError,
+    DeviceResponseError,
+    DeviceUnavailableError,
+    HostPrivilegeError,
+    NeighborTableError,
+)
+from .domain.port_status import PortStatus
+
+
+def discover_print_servers(*, networks: list[str] | None = None, timeout: float = 3.0) -> DiscoveryReport:
+    """Find the family's print servers by their FTP greeting; never logs in, never prints.
+
+    Args:
+        networks: CIDR networks to search (``"192.0.2.0/24"``); None searches this host's own.
+        timeout: Seconds to wait for each host's greeting.
+
+    Returns:
+        The devices found, with the MAC this host's neighbour cache holds for each.
+
+    Raises:
+        ValueError: A network is not an IPv4 CIDR.
+    """
+    chosen = [_network(network) for network in networks] if networks else None
+    return discover(FtpBannerScanner(), networks=chosen, timeout=timeout)
+
+
+def _network(text: str) -> IPv4Network:
+    try:
+        return IPv4Network(text.strip(), strict=False)
+    except ValueError as error:
+        raise ValueError(f"{text!r} is not an IPv4 network: {error}") from error
+
+
+__all__ = [
+    "AuthenticationRequiredError",
+    "ConfigChange",
+    "ConfigFormatError",
+    "ConfigWriteResult",
+    "ConfigurationError",
+    "ConfirmationRequiredError",
+    "DeviceConfig",
+    "DeviceEndpoint",
+    "DeviceInfo",
+    "DeviceResponseError",
+    "DeviceUnavailableError",
+    "DiscoveredDevice",
+    "DiscoveryReport",
+    "HostPrivilegeError",
+    "IpscoutNeighborTable",
+    "MacAddress",
+    "NeighborTableError",
+    "PortStatus",
+    "PrintJob",
+    "PrintServer",
+    "arp_trick",
+    "discover_print_servers",
+    "get_config",
+    "normalise_mac",
+    "open_print_server",
+    "parse_config",
+    "print_info",
+    "render_config",
+    "with_value",
+]

sercomm_printserver/__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 = "sercomm-printserver"
+#: Human-readable summary shown in CLI help output.
+title = "CLI and Python library for SerComm-based network print servers (PS301 and OEM variants)"
+#: Current release version pulled from ``pyproject.toml`` by automation.
+version = "0.1.0"
+#: Repository homepage presented to users.
+homepage = "https://github.com/bitranox/sercomm-printserver"
+#: 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 = "sercomm-printserver"
+
+#: 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 = "sercomm_printserver"
+#: Configuration slug for lib_layered_config Linux paths and environment variables
+LAYEREDCONF_SLUG: str = "sercomm-printserver"
+
+
+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 sercomm-printserver:
+    ...
+    """
+
+    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")

sercomm_printserver/__main__.py

@@ -0,0 +1,9 @@
+"""Module entry point for ``python -m sercomm_printserver``."""
+
+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))

sercomm_printserver/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] = []

sercomm_printserver/adapters/cli/__init__.py

@@ -0,0 +1,80 @@
+"""CLI package providing the command-line interface.
+
+Re-exports all public symbols from submodules for convenient access.
+
+Contents:
+    * Click context helpers and traceback state management from :mod:`.context`
+    * Root command group from :mod:`.root`
+    * Entry point from :mod:`.main`
+    * All command functions from :mod:`.commands`
+
+System Role:
+    Acts as the public facade for the CLI subsystem. Consumers import from here
+    and remain insulated from internal module boundaries.
+"""
+
+from __future__ import annotations
+
+from .commands import (
+    cli_arp,
+    cli_config,
+    cli_config_deploy,
+    cli_config_generate_examples,
+    cli_device_config,
+    cli_device_info,
+    cli_discover,
+    cli_factory_default,
+    cli_firmware,
+    cli_info,
+    cli_password,
+    cli_print,
+    cli_queue,
+    cli_reset,
+    cli_status,
+    cli_store_ip,
+)
+from .constants import CLICK_CONTEXT_SETTINGS, TRACEBACK_SUMMARY_LIMIT, TRACEBACK_VERBOSE_LIMIT
+from .context import (
+    TracebackState,
+    apply_traceback_preferences,
+    restore_traceback_state,
+    snapshot_traceback_state,
+    store_cli_context,
+)
+from .main import main
+from .root import cli
+
+__all__ = [
+    # Constants
+    "CLICK_CONTEXT_SETTINGS",
+    "TRACEBACK_SUMMARY_LIMIT",
+    "TRACEBACK_VERBOSE_LIMIT",
+    # Traceback management
+    "TracebackState",
+    "apply_traceback_preferences",
+    # Root command
+    "cli",
+    # Commands
+    "cli_arp",
+    "cli_config",
+    "cli_config_deploy",
+    "cli_config_generate_examples",
+    "cli_device_config",
+    "cli_device_info",
+    "cli_discover",
+    "cli_factory_default",
+    "cli_firmware",
+    "cli_info",
+    "cli_password",
+    "cli_print",
+    "cli_queue",
+    "cli_reset",
+    "cli_status",
+    "cli_store_ip",
+    # Entry point
+    "main",
+    "restore_traceback_state",
+    "snapshot_traceback_state",
+    # Context helpers
+    "store_cli_context",
+]

sercomm_printserver/adapters/cli/commands/__init__.py

@@ -0,0 +1,49 @@
+"""CLI command implementations.
+
+Collects all subcommand functions and re-exports them for registration
+with the root CLI group.
+
+Contents:
+    * Info commands from :mod:`.info`
+    * App configuration commands from :mod:`.config`
+    * Device commands from :mod:`.device`, :mod:`.device_config` and :mod:`.printing`
+    * ARP-trick commands from :mod:`.arp`
+"""
+
+from __future__ import annotations
+
+from .arp import cli_arp
+from .config import cli_config, cli_config_deploy, cli_config_generate_examples
+from .device import (
+    cli_device_info,
+    cli_factory_default,
+    cli_firmware,
+    cli_password,
+    cli_queue,
+    cli_reset,
+    cli_status,
+    cli_store_ip,
+)
+from .device_config import cli_device_config
+from .discover import cli_discover
+from .info import cli_info
+from .printing import cli_print
+
+__all__ = [
+    "cli_arp",
+    "cli_config",
+    "cli_config_deploy",
+    "cli_config_generate_examples",
+    "cli_device_config",
+    "cli_device_info",
+    "cli_discover",
+    "cli_factory_default",
+    "cli_firmware",
+    "cli_info",
+    "cli_password",
+    "cli_print",
+    "cli_queue",
+    "cli_reset",
+    "cli_status",
+    "cli_store_ip",
+]

sercomm_printserver/adapters/cli/commands/_device.py

@@ -0,0 +1,166 @@
+"""What every device command shares: its options, how it reaches the device, how it answers.
+
+A command supplies only the work (a function of a
+:class:`~sercomm_printserver.application.print_server.PrintServer`) and how to say the result
+to a person. :func:`run_device_command` resolves the device from ``[device]`` and the flags,
+runs the work, prints the envelope or the human text, and turns the known failures into their
+exit codes, so all commands report the same failure the same way.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, TypeVar
+
+import lib_log_rich.runtime
+import rich_click as click
+from pydantic import BaseModel
+
+from sercomm_printserver.adapters.config.device_settings import load_device_settings, resolve_endpoint
+from sercomm_printserver.domain.errors import (
+    AuthenticationRequiredError,
+    ConfigurationError,
+    ConfirmationRequiredError,
+    DeviceResponseError,
+    DeviceUnavailableError,
+    HostPrivilegeError,
+    NeighborTableError,
+)
+
+from .. import safe_console
+from ..config_load import require_config
+from ..context import get_cli_context
+from ..envelope import Envelope, OutputMode, report_failure, write_envelope
+from ..exit_codes import ExitCode
+from ..typed_click import option
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+    from typing import Any
+
+    from sercomm_printserver.adapters.config.device_settings import DeviceSettings
+    from sercomm_printserver.application.print_server import PrintServer
+    from sercomm_printserver.composition import AppServices
+    from sercomm_printserver.domain.endpoint import DeviceEndpoint
+
+    from ..constants import CommandName
+
+_P = TypeVar("_P", bound="BaseModel")
+_F = TypeVar("_F", bound="Callable[..., Any]")
+
+#: Known failures and their exit codes, most specific first: DeviceResponseError and
+#: ConfigFormatError are both ValueErrors, and the refusals and HostPrivilegeError are all
+#: PermissionErrors - only the last says THIS host lacks a right, so it alone exits 13.
+_EXIT_CODES: tuple[tuple[type[Exception], ExitCode], ...] = (
+    (ConfigurationError, ExitCode.CONFIG_ERROR),
+    (DeviceUnavailableError, ExitCode.DEVICE_UNAVAILABLE),
+    (DeviceResponseError, ExitCode.PROTOCOL_ERROR),
+    (HostPrivilegeError, ExitCode.PERMISSION_DENIED),
+    (NeighborTableError, ExitCode.GENERAL_ERROR),
+    (AuthenticationRequiredError, ExitCode.REFUSED),
+    (ConfirmationRequiredError, ExitCode.REFUSED),
+    (ValueError, ExitCode.INVALID_ARGUMENT),
+)
+_HANDLED: tuple[type[Exception], ...] = tuple(error_type for error_type, _ in _EXIT_CODES)
+
+
+def exit_code_for(error: Exception) -> ExitCode:
+    """Return the exit code a known failure maps to.
+
+    Example:
+        >>> exit_code_for(DeviceUnavailableError("down")).value
+        69
+    """
+    for error_type, code in _EXIT_CODES:
+        if isinstance(error, error_type):
+            return code
+    return ExitCode.GENERAL_ERROR
+
+
+def device_options(command: _F) -> _F:
+    """Add ``--host``, ``--timeout``, ``--json`` and ``--json-bare`` to a device command."""
+    host = option("--host", type=str, default=None, help="Print server address (overrides [device] host).")
+    wrapped: Any = host(session_options(command))
+    return wrapped
+
+
+def session_options(command: _F) -> _F:
+    """Add ``--timeout``, ``--json`` and ``--json-bare``: what a command that names its own address needs."""
+    decorators = (
+        option(
+            "--timeout",
+            type=click.FloatRange(min=0.1, max=600),
+            default=None,
+            help="Network timeout per operation in seconds (overrides [device] timeout).",
+        ),
+        option("--json", "as_json", is_flag=True, default=False, help="Answer as an indented JSON envelope."),
+        option("--json-bare", "as_json_bare", is_flag=True, default=False, help="Answer as one-line JSON."),
+    )
+    wrapped: Any = command
+    for decorator in reversed(decorators):
+        wrapped = decorator(wrapped)
+    return wrapped
+
+
+def run_device_command(
+    ctx: click.Context,
+    *,
+    command: CommandName,
+    flags: DeviceFlags,
+    work: Callable[[PrintServer], _P],
+    human: Callable[[_P], str],
+) -> None:
+    """Run ``work`` against the configured device and answer in the requested shape."""
+
+    def on_endpoint(endpoint: DeviceEndpoint, services: AppServices, settings: DeviceSettings) -> _P:
+        return work(services.open_print_server(endpoint, raw_port_base=settings.raw_port_base))
+
+    run_endpoint_command(ctx, command=command, flags=flags, work=on_endpoint, human=human)
+
+
+def run_endpoint_command(
+    ctx: click.Context,
+    *,
+    command: CommandName,
+    flags: DeviceFlags,
+    work: Callable[[DeviceEndpoint, AppServices, DeviceSettings], _P],
+    human: Callable[[_P], str],
+) -> None:
+    """Like :func:`run_device_command`, for work that needs the endpoint and services themselves.
+
+    The ARP trick opens the print server only after this host maps the borrowed address, so it
+    takes the endpoint (``flags.host`` is that address) instead of a ready server.
+    """
+    mode = OutputMode.of(as_json=flags.as_json, as_json_bare=flags.as_json_bare)
+    cli_ctx = get_cli_context(ctx)
+    config = require_config(ctx, cli_ctx)
+    with lib_log_rich.runtime.bind(job_id=f"cli-{command.value}", extra={"command": command.value}):
+        try:
+            settings = load_device_settings(config)
+            endpoint = resolve_endpoint(settings, host=flags.host, timeout=flags.timeout)
+            payload = work(endpoint, cli_ctx.services, settings)
+        except _HANDLED as error:
+            report_failure(error, command=command, mode=mode)
+            ctx.exit(exit_code_for(error))
+    if mode.machine:
+        write_envelope(Envelope.of(command=command, payload=payload), mode=mode)
+    else:
+        safe_console.echo(human(payload))
+
+
+class DeviceFlags(BaseModel, frozen=True, extra="forbid"):
+    """The four options :func:`device_options` adds, as one value."""
+
+    host: str | None
+    timeout: float | None
+    as_json: bool
+    as_json_bare: bool
+
+
+__all__ = [
+    "DeviceFlags",
+    "device_options",
+    "exit_code_for",
+    "run_device_command",
+    "run_endpoint_command",
+    "session_options",
+]