phomemo 0.3.0__py3-none-any.whl

phomemo/bridge/client.py

@@ -0,0 +1,310 @@
+# This file is part of phomemo.
+# Copyright (C) 2026 Paul Bütof, Passionate Bytes Solutions
+#
+# phomemo is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# phomemo is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with phomemo.  If not, see <https://www.gnu.org/licenses/>.
+
+"""Client for the bridge socket, used by the CLI and by printer-application tests."""
+
+import asyncio
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any, Self
+
+from PIL import Image
+
+from phomemo.bridge.protocol import encode_message, read_message
+
+MEDIA = {
+    "a4": (297.0, False),
+    "a5": (148.0, True),
+    "roll": (None, False),
+}
+QUALITY = {"draft": "low", "normal": "medium", "high": "high"}
+_ROWS_PER_MESSAGE = 64
+
+
+class BridgeError(RuntimeError):
+    """The bridge refused or failed a command; the message is its ``error``."""
+
+
+class BridgeClient:
+    """One connection to the bridge.
+
+    Args:
+        socket_path: The bridge's unix socket.
+        on_event: Called with each pushed event while a reply is pending.
+    """
+
+    def __init__(
+        self,
+        socket_path: Path,
+        on_event: Callable[[dict[str, Any]], None] | None = None,
+    ) -> None:
+        self._path = socket_path
+        self._on_event = on_event
+        self._reader: asyncio.StreamReader | None = None
+        self._writer: asyncio.StreamWriter | None = None
+        self._pending: str | None = None
+
+    async def __aenter__(self) -> Self:
+        await self.connect()
+        return self
+
+    async def __aexit__(self, *_exc: object) -> None:
+        await self.disconnect()
+
+    async def connect(self) -> None:
+        """Open the socket connection."""
+        self._reader, self._writer = await asyncio.open_unix_connection(str(self._path))
+
+    async def disconnect(self) -> None:
+        """Close the socket connection."""
+        if self._writer is not None:
+            self._writer.close()
+            await self._writer.wait_closed()
+            self._writer = None
+            self._reader = None
+
+    async def send(self, obj: dict[str, Any], payload: bytes = b"") -> None:
+        """Send a command without waiting for its reply."""
+        assert self._writer is not None, "not connected"
+        if obj.get("cmd") != "abort":
+            self._pending = obj.get("cmd")
+        self._writer.write(encode_message(obj, payload))
+        await self._writer.drain()
+
+    async def reply(self) -> dict[str, Any]:
+        """Read the reply to the pending command, dispatching events on the way.
+
+        The bridge acknowledges an ``abort`` sent while another command is
+        pending before it answers that command; the acknowledgement is
+        skipped here.
+
+        Raises:
+            BridgeError: If the reply reports ``ok: false``.
+        """
+        assert self._reader is not None, "not connected"
+        while True:
+            obj, _ = await read_message(self._reader)
+            if "event" in obj:
+                if self._on_event is not None:
+                    self._on_event(obj)
+                continue
+            if obj.get("cmd") == "abort" and self._pending != "abort":
+                continue
+            if not obj.get("ok"):
+                raise BridgeError(obj.get("error", "unknown error"))
+            return obj
+
+    async def call(self, obj: dict[str, Any], payload: bytes = b"") -> dict[str, Any]:
+        """Send a command and return its reply."""
+        await self.send(obj, payload)
+        return await self.reply()
+
+    async def discover(self, timeout: float = 5.0) -> list[dict[str, str]]:
+        return (await self.call({"cmd": "discover", "timeout": timeout}))["printers"]
+
+    async def open(self, address: str | None = None) -> dict[str, Any]:
+        """Bring the printer connection up.
+
+        Args:
+            address: Printer to connect to; ``None`` keeps the bridge's choice
+                (configured address, the last printer, or a name scan).
+
+        Returns:
+            ``connected`` and, when that is false, the ``reason``.
+        """
+        obj: dict[str, Any] = {"cmd": "open"}
+        if address is not None:
+            obj["address"] = address
+        reply = await self.call(obj)
+        return {k: v for k, v in reply.items() if k not in ("ok", "cmd")}
+
+    async def drop_link(self) -> None:
+        """Drop the printer connection now instead of after the idle timeout."""
+        await self.call({"cmd": "disconnect"})
+
+    async def info(self) -> dict[str, Any]:
+        """Device details and sensors of the linked printer."""
+        reply = await self.call({"cmd": "info"})
+        return {k: v for k, v in reply.items() if k not in ("ok", "cmd")}
+
+    async def auto_off(self, minutes: int | None = None) -> int | None:
+        """Read the linked printer's auto-off timer, setting it first if given.
+
+        Args:
+            minutes: New timeout, a multiple of 5; 0 = never switch off.
+
+        Returns:
+            The timer in minutes as the printer reports it.
+        """
+        obj: dict[str, Any] = {"cmd": "auto_off"}
+        if minutes is not None:
+            obj["minutes"] = minutes
+        return (await self.call(obj))["auto_off_minutes"]
+
+    async def close(self) -> None:
+        await self.call({"cmd": "close"})
+
+    async def status(self, address: str | None = None) -> dict[str, Any]:
+        """Connection state and sensors; ``last_seen`` values without a connection.
+
+        Args:
+            address: Printer to report on; ``None`` means the linked or
+                last linked one.
+        """
+        obj: dict[str, Any] = {"cmd": "status"}
+        if address is not None:
+            obj["address"] = address
+        reply = await self.call(obj)
+        return {k: v for k, v in reply.items() if k not in ("ok", "cmd")}
+
+    async def wait_ready(self, settle: float | None = None) -> None:
+        obj: dict[str, Any] = {"cmd": "wait_ready"}
+        if settle is not None:
+            obj["settle"] = settle
+        await self.call(obj)
+
+    async def page_begin(
+        self,
+        width: int,
+        length_rows: int,
+        bits: int = 8,
+        tone: str = "auto",
+        content: str = "auto",
+        density: str = "medium",
+        media_length_mm: float | None = 297.0,
+        rotate: bool = False,
+    ) -> None:
+        await self.call(
+            {
+                "cmd": "page_begin",
+                "width": width,
+                "length_rows": length_rows,
+                "bits": bits,
+                "tone": tone,
+                "content": content,
+                "density": density,
+                "media_length_mm": media_length_mm,
+                "rotate": rotate,
+            }
+        )
+
+    async def lines(self, count: int, payload: bytes) -> None:
+        await self.call({"cmd": "lines", "count": count}, payload)
+
+    async def page_end(self) -> int:
+        return int((await self.call({"cmd": "page_end"}))["impressions"])
+
+    async def eject(self) -> bool:
+        return bool((await self.call({"cmd": "eject"}))["ejected"])
+
+    async def identify(self) -> None:
+        """Eject a loaded sheet, then pulse the feed three times."""
+        await self.call({"cmd": "identify"})
+
+    async def test_page(self, versions: dict[str, str] | None = None) -> Path:
+        """Render the test page and return the PNG's path.
+
+        Args:
+            versions: Component versions to print, by name.
+        """
+        reply = await self.call(
+            {
+                "cmd": "test_page",
+                "printer_name": "Phomemo M08F",
+                "versions": versions or {},
+            }
+        )
+        return Path(reply["path"])
+
+    async def print_test_page(self, quality: str = "normal") -> int:
+        """Render the test page and print it through the bridge.
+
+        The page covers the area below the sheet's unprintable lead, so it
+        gets that lead as white rows on top before the normal page
+        preparation drops them again.
+
+        Args:
+            quality: ``draft``, ``normal`` or ``high``.
+
+        Returns:
+            Impressions printed (1).
+        """
+        path = await self.test_page()
+        page = Image.open(path).convert("L")
+        lead = round(10 / 25.4 * 203)
+        canvas = Image.new("L", (page.width, page.height + lead), 255)
+        canvas.paste(page, (0, lead))
+        padded = path.with_name("phomemo-testpage-sheet.png")
+        canvas.save(padded)
+        return await self.print_image(padded, media="a4", quality=quality)
+
+    async def abort(self) -> None:
+        await self.call({"cmd": "abort"})
+
+    async def print_image(
+        self,
+        path: Path,
+        media: str = "a4",
+        tone: str = "auto",
+        quality: str = "normal",
+        content: str = "auto",
+        abort_after: float | None = None,
+    ) -> int:
+        """Print an image file as one page: open, wait for a sheet, stream, end.
+
+        Args:
+            path: Image file readable by Pillow.
+            media: ``a4``, ``a5`` (fed long edge first, page rotated) or ``roll``.
+            tone: ``auto`` or a ``ToneMode`` value.
+            quality: ``draft``, ``normal`` or ``high`` (maps to density).
+            content: ``auto``, ``text``, ``graphic`` or ``photo``.
+            abort_after: Seconds after ``page_end`` to send ``abort``; for testing.
+
+        Returns:
+            Impressions printed (1).
+
+        Raises:
+            BridgeError: If any step fails.
+            KeyError: If ``media`` or ``quality`` is not known.
+        """
+        length_mm, rotate = MEDIA[media]
+        density = QUALITY[quality]
+        img = Image.open(path).convert("L")
+        await self.open()
+        await self.wait_ready()
+        await self.page_begin(
+            img.width,
+            img.height,
+            bits=8,
+            tone=tone,
+            content=content,
+            density=density,
+            media_length_mm=length_mm,
+            rotate=rotate,
+        )
+        raw = img.tobytes()
+        for start in range(0, img.height, _ROWS_PER_MESSAGE):
+            count = min(_ROWS_PER_MESSAGE, img.height - start)
+            await self.lines(
+                count, raw[start * img.width : (start + count) * img.width]
+            )
+        await self.send({"cmd": "page_end"})
+        if abort_after is not None:
+            await asyncio.sleep(abort_after)
+            await self.send({"cmd": "abort"})
+        reply = await self.reply()
+        await self.close()
+        return int(reply["impressions"])

phomemo/bridge/config.py

@@ -0,0 +1,184 @@
+# This file is part of phomemo.
+# Copyright (C) 2026 Paul Bütof, Passionate Bytes Solutions
+#
+# phomemo is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# phomemo is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with phomemo.  If not, see <https://www.gnu.org/licenses/>.
+
+"""Bridge configuration: TOML files layered under environment overrides."""
+
+import logging
+import os
+import tomllib
+from collections.abc import Mapping
+from dataclasses import fields
+from pathlib import Path
+from typing import Any
+
+from phomemo.bridge.server import BridgeConfig
+from phomemo.printer import AUTO_OFF_MAX_MINUTES
+
+logger = logging.getLogger(__name__)
+
+SYSTEM_CONFIG = Path("/etc/phomemo/bridge.toml")
+SYSTEM_SOCKET = Path("/run/phomemo/bridge.sock")
+SOCKET_NAME = "phomemo-bridge.sock"
+SOCKET_ENV = "PHOMEMO_BRIDGE_SOCKET"
+
+_NUMERIC = {
+    "idle_disconnect_minutes",
+    "settle_seconds",
+    "completion_timeout",
+    "drain_seconds",
+}
+_STRING = {"socket_path"}
+
+
+class _Invalid(ValueError):
+    """A configuration value that cannot be used; the message says why."""
+
+
+class ConfigError(ValueError):
+    """A configuration file named explicitly does not exist."""
+
+
+def default_paths(env: Mapping[str, str]) -> list[Path]:
+    """System file first, then the user's XDG config file.
+
+    Args:
+        env: Environment to read ``XDG_CONFIG_HOME`` and ``HOME`` from.
+
+    Returns:
+        Candidate paths in override order; missing files are skipped later.
+    """
+    xdg = env.get("XDG_CONFIG_HOME") or os.path.join(env.get("HOME", "~"), ".config")
+    return [SYSTEM_CONFIG, Path(xdg).expanduser() / "phomemo" / "bridge.toml"]
+
+
+def default_socket(env: Mapping[str, str], system_socket: Path | None = None) -> Path:
+    """The system bridge's socket when it exists, else one under ``XDG_RUNTIME_DIR``.
+
+    The system service listens at ``/run/phomemo/bridge.sock``; a user's
+    command line talks to it when it is there. Without it (development, a
+    user service) the socket lives in the user's runtime directory.
+
+    Args:
+        env: Environment providing ``XDG_RUNTIME_DIR``.
+        system_socket: The system bridge's socket; ``SYSTEM_SOCKET`` by default.
+
+    Returns:
+        The socket path to listen on or connect to.
+    """
+    system_socket = system_socket or SYSTEM_SOCKET
+    if system_socket.exists():
+        return system_socket
+    runtime = env.get("XDG_RUNTIME_DIR")
+    return Path(runtime) / SOCKET_NAME if runtime else system_socket
+
+
+def _auto_off(value: Any) -> tuple[int, str | None]:
+    """The timer for a configured value, and a note when it had to be adjusted."""
+    if isinstance(value, bool) or not isinstance(value, int | float) or value < 0:
+        raise _Invalid(
+            f"expected minutes as a number between 0 and {AUTO_OFF_MAX_MINUTES}, "
+            f"got {value!r}"
+        )
+    if value == 0:
+        minutes = 0
+    else:
+        minutes = min(max(5, int(value / 5 + 0.5) * 5), AUTO_OFF_MAX_MINUTES)
+    if minutes == value and isinstance(value, int):
+        return minutes, None
+    return minutes, f"{value!r} is not a valid timer (5-minute steps), using {minutes}"
+
+
+def _check(key: str, value: Any) -> tuple[Any, str | None]:
+    """The usable value for ``key``, and a note when it was adjusted.
+
+    Raises:
+        _Invalid: If the value cannot be used.
+    """
+    if key == "auto_off_minutes":
+        return _auto_off(value)
+    if key in _NUMERIC:
+        if isinstance(value, bool) or not isinstance(value, int | float):
+            raise _Invalid(f"expected a number, got {value!r}")
+        if value < 0:
+            raise _Invalid(f"must not be negative, got {value!r}")
+        return float(value), None
+    if key in _STRING:
+        if not isinstance(value, str):
+            raise _Invalid(f"expected a string, got {value!r}")
+        return value, None
+    raise _Invalid("unknown key")
+
+
+def _read(path: Path) -> dict[str, Any]:
+    """The usable settings of one file; every problem is logged, not raised."""
+    try:
+        data = tomllib.loads(path.read_text())
+    except (OSError, UnicodeDecodeError, tomllib.TOMLDecodeError) as exc:
+        logger.warning("%s: cannot read the file (%s); ignored", path, exc)
+        return {}
+    values: dict[str, Any] = {}
+    for key, value in data.items():
+        try:
+            values[key], note = _check(key, value)
+        except _Invalid as exc:
+            logger.warning("%s: %s: %s; ignored", path, key, exc)
+            continue
+        if note is not None:
+            logger.warning("%s: %s: %s", path, key, note)
+    return values
+
+
+def load_config(
+    paths: list[Path] | None = None,
+    env: Mapping[str, str] = os.environ,
+    require_files: bool = False,
+) -> BridgeConfig:
+    """Build the bridge configuration.
+
+    Later files override earlier ones; ``PHOMEMO_BRIDGE_SOCKET`` overrides
+    the socket path from any file.
+
+    Args:
+        paths: Files to read in override order; ``None`` means the system
+            file then the user's XDG file.
+        env: Environment for the socket override and default locations.
+        require_files: Treat a missing file in ``paths`` as an error (for
+            a path the user named explicitly).
+
+    Returns:
+        The merged configuration.
+
+    Problems inside a file (unknown keys, wrong types, out-of-range values,
+    a file that does not parse) are logged as warnings and the affected
+    setting keeps its default.
+
+    Raises:
+        ConfigError: If a file in ``paths`` is missing and ``require_files``
+            is set.
+    """
+    merged: dict[str, Any] = {}
+    for path in default_paths(env) if paths is None else paths:
+        if path.is_file():
+            merged.update(_read(path))
+        elif require_files:
+            raise ConfigError(f"{path}: no such file")
+    if SOCKET_ENV in env:
+        merged["socket_path"] = env[SOCKET_ENV]
+    socket_path = Path(merged.pop("socket_path", default_socket(env)))
+    known = {f.name for f in fields(BridgeConfig)}
+    return BridgeConfig(
+        socket_path=socket_path, **{k: v for k, v in merged.items() if k in known}
+    )

phomemo/bridge/protocol.py

@@ -0,0 +1,82 @@
+# This file is part of phomemo.
+# Copyright (C) 2026 Paul Bütof, Passionate Bytes Solutions
+#
+# phomemo is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# phomemo is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with phomemo.  If not, see <https://www.gnu.org/licenses/>.
+
+"""Wire format of the bridge socket.
+
+Every message is one JSON object on its own line. A message that carries
+raw bytes (raster rows) states their length in ``"bytes"`` and the bytes
+follow the newline immediately. Replies and pushed events use the same
+framing in the other direction.
+"""
+
+import asyncio
+import json
+from typing import Any
+
+MAX_LINE = 64 * 1024
+MAX_PAYLOAD = 16 * 1024 * 1024
+
+
+class ProtocolError(ValueError):
+    """A message violated the wire format."""
+
+
+def encode_message(obj: dict[str, Any], payload: bytes = b"") -> bytes:
+    """Serialise a message, attaching ``payload`` and its ``bytes`` count.
+
+    Args:
+        obj: The message fields.
+        payload: Raw bytes to send after the line.
+
+    Returns:
+        Bytes ready to write to the socket.
+    """
+    if payload:
+        obj = {**obj, "bytes": len(payload)}
+    return json.dumps(obj).encode() + b"\n" + payload
+
+
+async def read_message(reader: asyncio.StreamReader) -> tuple[dict[str, Any], bytes]:
+    """Read one message and its payload, if any.
+
+    Args:
+        reader: Stream to read from.
+
+    Returns:
+        The message object and its raw payload (empty when none).
+
+    Raises:
+        ProtocolError: On malformed JSON, a non-object message, an
+            over-long line, or an out-of-range payload length.
+        asyncio.IncompleteReadError: If the stream ends mid-message.
+    """
+    try:
+        line = await reader.readuntil(b"\n")
+    except asyncio.LimitOverrunError as exc:
+        raise ProtocolError(f"line exceeds {MAX_LINE} bytes") from exc
+    if len(line) > MAX_LINE:
+        raise ProtocolError(f"line exceeds {MAX_LINE} bytes")
+    try:
+        obj = json.loads(line)
+    except ValueError as exc:
+        raise ProtocolError(f"invalid JSON: {exc}") from exc
+    if not isinstance(obj, dict):
+        raise ProtocolError("message must be a JSON object")
+    size = obj.get("bytes", 0)
+    if not isinstance(size, int) or size < 0 or size > MAX_PAYLOAD:
+        raise ProtocolError(f"invalid payload length {size!r}")
+    payload = await reader.readexactly(size) if size else b""
+    return obj, payload