paperang-cli 0.1.0__py3-none-any.whl

paperang_cli/__init__.py

@@ -0,0 +1,3 @@
+"""paperang-cli package."""
+
+__version__ = "0.1.0"

paperang_cli/__main__.py

@@ -0,0 +1,5 @@
+from paperang_cli.cli import main
+
+
+if __name__ == "__main__":
+    main()

paperang_cli/cli.py

@@ -0,0 +1,82 @@
+"""Standalone paperang-cli entrypoint."""
+
+from __future__ import annotations
+
+import json
+import logging
+from pathlib import Path
+
+import click
+
+from paperang_cli import __version__
+from paperang_cli.commands.battery import battery_command
+from paperang_cli.commands.config_cmd import config_group
+from paperang_cli.commands.discover import discover_command
+from paperang_cli.commands.mac import mac_command
+from paperang_cli.commands.print_cmd import print_group
+from paperang_cli.commands.probe import probe_command
+from paperang_cli.commands.status import status_command
+from paperang_cli.config import load_config
+from paperang_cli.errors import PaperangCliError
+
+
+def configure_logging(debug: bool) -> None:
+    level = logging.DEBUG if debug else logging.INFO
+    logging.basicConfig(level=level, format="%(asctime)s %(levelname)s %(name)s: %(message)s")
+
+
+@click.group(context_settings={"help_option_names": ["-h", "--help"]})
+@click.option(
+    "--config",
+    "config_path",
+    type=click.Path(path_type=Path, dir_okay=False),
+    help="Path to a paperang-cli JSON config file.",
+)
+@click.option("--json", "json_output", is_flag=True, help="Emit machine-readable JSON output.")
+@click.option("--debug", is_flag=True, help="Enable verbose logging.")
+@click.version_option(version=__version__)
+@click.pass_context
+def cli(ctx: click.Context, config_path: Path | None, json_output: bool, debug: bool) -> None:
+    """Standalone CLI for Paperang printers."""
+    configure_logging(debug)
+    try:
+        settings, resolved_path, config_exists = load_config(config_path)
+    except PaperangCliError as exc:
+        if json_output:
+            click.echo(
+                json.dumps(
+                    {
+                        "status": "error",
+                        "code": exc.code,
+                        "message": str(exc),
+                        "exit_code": exc.exit_code,
+                    },
+                    indent=2,
+                    ensure_ascii=False,
+                    sort_keys=True,
+                ),
+                err=True,
+            )
+            raise SystemExit(exc.exit_code)
+        raise click.ClickException(str(exc)) from exc
+
+    ctx.obj = {
+        "settings": settings,
+        "config_path": resolved_path,
+        "config_exists": config_exists,
+        "json_output": json_output,
+        "debug": debug,
+    }
+
+
+cli.add_command(status_command)
+cli.add_command(battery_command)
+cli.add_command(mac_command)
+cli.add_command(probe_command)
+cli.add_command(discover_command)
+cli.add_command(print_group)
+cli.add_command(config_group)
+
+
+def main() -> None:
+    cli()

paperang_cli/commands/__init__.py

@@ -0,0 +1 @@
+"""CLI commands."""

paperang_cli/commands/battery.py

@@ -0,0 +1,28 @@
+"""Battery command."""
+
+from __future__ import annotations
+
+import click
+
+from paperang_cli.drivers import registry
+from paperang_cli.output import cli_error_boundary, emit_result
+
+
+@click.command("battery")
+@click.option("--address", type=str, help="Optional printer MAC address override.")
+@click.pass_context
+def battery_command(ctx: click.Context, address: str | None) -> None:
+    """Query only the current printer battery level without printing."""
+    with cli_error_boundary(ctx):
+        driver = registry.get_driver(ctx.obj["settings"])
+        battery = driver.battery(address=address)
+        emit_result(
+            ctx,
+            {"status": "ok", "result": battery.to_dict()},
+            [
+                f"Model: {battery.model}",
+                f"Address: {battery.address}",
+                f"Connected: {battery.connected}",
+                f"Battery: {battery.battery_percent}",
+            ],
+        )

paperang_cli/commands/config_cmd.py

@@ -0,0 +1,80 @@
+"""Config commands."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import click
+
+from paperang_cli.config import write_example_config
+from paperang_cli.drivers.registry import supported_models
+from paperang_cli.output import cli_error_boundary, emit_result
+
+
+@click.group("config")
+def config_group() -> None:
+    """Inspect or initialize paperang-cli configuration."""
+
+
+@config_group.command("show")
+@click.pass_context
+def show_config_command(ctx: click.Context) -> None:
+    """Show the resolved config and whether it came from a file."""
+    settings = ctx.obj["settings"]
+    config_path = ctx.obj["config_path"]
+    config_exists = ctx.obj["config_exists"]
+    emit_result(
+        ctx,
+        {
+            "status": "ok",
+            "result": {
+                "config_path": str(config_path),
+                "config_exists": config_exists,
+                "config": settings.to_dict(),
+                "supported_models": supported_models(),
+            },
+        },
+        [
+            f"Config path: {config_path}",
+            f"Config exists: {config_exists}",
+            f"Model: {settings.model}",
+            f"MAC address: {settings.macaddress or '<unset>'}",
+            f"Printer width: {settings.printerwidth}",
+            f"Print density: {settings.print_density}",
+            f"Post-print feed mm: {settings.post_print_feed_mm}",
+            f"Supported models: {', '.join(supported_models())}",
+        ],
+    )
+
+
+@config_group.command("path")
+@click.pass_context
+def config_path_command(ctx: click.Context) -> None:
+    """Show the resolved config path."""
+    config_path = ctx.obj["config_path"]
+    emit_result(
+        ctx,
+        {"status": "ok", "result": {"config_path": str(config_path)}},
+        [str(config_path)],
+    )
+
+
+@config_group.command("init")
+@click.option(
+    "--path",
+    "destination",
+    type=click.Path(path_type=Path, dir_okay=False),
+    help="Write the example config to a custom destination.",
+)
+@click.option("--force", is_flag=True, help="Overwrite an existing destination if present.")
+@click.pass_context
+def config_init_command(ctx: click.Context, destination: Path | None, force: bool) -> None:
+    """Write an example config file for the standalone CLI project."""
+    with cli_error_boundary(ctx):
+        target = destination or ctx.obj["config_path"]
+        written_path = write_example_config(target, overwrite=force)
+        emit_result(
+            ctx,
+            {"status": "ok", "result": {"config_path": str(written_path)}},
+            [f"Wrote example config to {written_path}"],
+        )

paperang_cli/commands/discover.py

@@ -0,0 +1,23 @@
+"""Discover command."""
+
+from __future__ import annotations
+
+import click
+
+from paperang_cli.drivers import registry
+from paperang_cli.output import cli_error_boundary, emit_result
+
+
+@click.command("discover")
+@click.pass_context
+def discover_command(ctx: click.Context) -> None:
+    """Discover nearby supported printers without printing."""
+    with cli_error_boundary(ctx):
+        driver = registry.get_driver(ctx.obj["settings"])
+        devices = driver.discover()
+        payload = [device.to_dict() for device in devices]
+        if devices:
+            human_lines = [f"{device.name} [{device.address}]" for device in devices]
+        else:
+            human_lines = ["No supported printers discovered."]
+        emit_result(ctx, {"status": "ok", "result": payload}, human_lines)

paperang_cli/commands/mac.py

@@ -0,0 +1,28 @@
+"""Bluetooth MAC command."""
+
+from __future__ import annotations
+
+import click
+
+from paperang_cli.drivers import registry
+from paperang_cli.output import cli_error_boundary, emit_result
+
+
+@click.command("mac")
+@click.option("--address", type=str, help="Optional printer MAC address override.")
+@click.pass_context
+def mac_command(ctx: click.Context, address: str | None) -> None:
+    """Query the printer-reported Bluetooth MAC address without printing."""
+    with cli_error_boundary(ctx):
+        driver = registry.get_driver(ctx.obj["settings"])
+        mac_status = driver.bluetooth_mac(address=address)
+        emit_result(
+            ctx,
+            {"status": "ok", "result": mac_status.to_dict()},
+            [
+                f"Model: {mac_status.model}",
+                f"Address: {mac_status.address}",
+                f"Connected: {mac_status.connected}",
+                f"Bluetooth MAC: {mac_status.bluetooth_mac}",
+            ],
+        )

paperang_cli/commands/print_cmd.py

@@ -0,0 +1,260 @@
+"""Printing commands."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import click
+
+from paperang_cli.drivers import registry
+from paperang_cli.output import cli_error_boundary, emit_result
+from paperang_cli.render import resolve_image_conversion
+
+
+@click.group("print")
+def print_group() -> None:
+    """Print text, print images, or run the built-in self-test."""
+
+
+@print_group.command("text")
+@click.argument("text")
+@click.option("--address", type=str, help="Optional printer MAC address override.")
+@click.option("--font-size", type=int, help="Override font size for this print job.")
+@click.option("--feed-mm", type=float, help="Override post-print feed in millimeters.")
+@click.option("--allow-paper-use", is_flag=True, help="Permit a real paper-consuming print.")
+@click.option("--dry-run", is_flag=True, help="Render and validate without sending anything to the printer.")
+@click.pass_context
+def print_text_command(
+    ctx: click.Context,
+    text: str,
+    address: str | None,
+    font_size: int | None,
+    feed_mm: float | None,
+    allow_paper_use: bool,
+    dry_run: bool,
+) -> None:
+    """Print a single line or short block of text."""
+    _run_print(
+        ctx,
+        text=text,
+        paragraph=False,
+        address=address,
+        font_size=font_size,
+        feed_mm=feed_mm,
+        allow_paper_use=allow_paper_use,
+        dry_run=dry_run,
+    )
+
+
+@print_group.command("paragraph")
+@click.argument("text")
+@click.option("--address", type=str, help="Optional printer MAC address override.")
+@click.option("--font-size", type=int, help="Override font size for this print job.")
+@click.option("--feed-mm", type=float, help="Override post-print feed in millimeters.")
+@click.option("--allow-paper-use", is_flag=True, help="Permit a real paper-consuming print.")
+@click.option("--dry-run", is_flag=True, help="Render and validate without sending anything to the printer.")
+@click.pass_context
+def print_paragraph_command(
+    ctx: click.Context,
+    text: str,
+    address: str | None,
+    font_size: int | None,
+    feed_mm: float | None,
+    allow_paper_use: bool,
+    dry_run: bool,
+) -> None:
+    """Print a wrapped paragraph using the paragraph rendering mode."""
+    _run_print(
+        ctx,
+        text=text,
+        paragraph=True,
+        address=address,
+        font_size=font_size,
+        feed_mm=feed_mm,
+        allow_paper_use=allow_paper_use,
+        dry_run=dry_run,
+    )
+
+
+def _run_print(
+    ctx: click.Context,
+    *,
+    text: str,
+    paragraph: bool,
+    address: str | None,
+    font_size: int | None,
+    feed_mm: float | None,
+    allow_paper_use: bool,
+    dry_run: bool,
+) -> None:
+    with cli_error_boundary(ctx):
+        driver = registry.get_driver(ctx.obj["settings"])
+        result = driver.print_text(
+            text,
+            paragraph=paragraph,
+            font_size=font_size,
+            feed_mm=feed_mm,
+            allow_paper_use=allow_paper_use,
+            dry_run=dry_run,
+            address=address,
+        )
+        _emit_print_result(ctx, result)
+
+
+@print_group.command("image")
+@click.argument("image_path", type=click.Path(exists=True, dir_okay=False, path_type=Path))
+@click.option("--address", type=str, help="Optional printer MAC address override.")
+@click.option("--feed-mm", type=float, help="Override post-print feed in millimeters.")
+@click.option(
+    "--mode",
+    type=click.Choice(["sticker", "photo"], case_sensitive=False),
+    default="sticker",
+    show_default=True,
+    help="High-level image preset. Sticker uses hard contrast, while photo uses dithering.",
+)
+@click.option(
+    "--conversion",
+    type=click.Choice(["threshold", "edge", "dither"], case_sensitive=False),
+    default=None,
+    help="Optional low-level conversion override. When provided, it takes precedence over --mode.",
+)
+@click.option("--allow-paper-use", is_flag=True, help="Permit a real paper-consuming image print.")
+@click.option("--dry-run", is_flag=True, help="Render and validate without sending anything to the printer.")
+@click.pass_context
+def print_image_command(
+    ctx: click.Context,
+    image_path: Path,
+    address: str | None,
+    feed_mm: float | None,
+    mode: str,
+    conversion: str,
+    allow_paper_use: bool,
+    dry_run: bool,
+) -> None:
+    """Print a local image file after converting it to a monochrome printer bitstream."""
+    with cli_error_boundary(ctx):
+        driver = registry.get_driver(ctx.obj["settings"])
+        resolved_conversion = resolve_image_conversion(mode=mode, conversion=conversion)
+        result = driver.print_image(
+            image_path,
+            conversion=resolved_conversion,
+            feed_mm=feed_mm,
+            allow_paper_use=allow_paper_use,
+            dry_run=dry_run,
+            address=address,
+        )
+        _emit_print_result(ctx, result)
+
+
+@print_group.command("compose")
+@click.argument("text")
+@click.argument("image_path", type=click.Path(exists=True, dir_okay=False, path_type=Path))
+@click.option("--address", type=str, help="Optional printer MAC address override.")
+@click.option("--font-size", type=int, help="Override font size for the text block.")
+@click.option("--feed-mm", type=float, help="Override post-print feed in millimeters.")
+@click.option(
+    "--layout",
+    type=click.Choice(["text-above", "image-above"], case_sensitive=False),
+    default="text-above",
+    show_default=True,
+    help="Vertical arrangement for the composed print.",
+)
+@click.option(
+    "--mode",
+    type=click.Choice(["sticker", "photo"], case_sensitive=False),
+    default="sticker",
+    show_default=True,
+    help="Image preset for the image part of the composed print.",
+)
+@click.option(
+    "--conversion",
+    type=click.Choice(["threshold", "edge", "dither"], case_sensitive=False),
+    default=None,
+    help="Optional low-level conversion override for the image part. When provided, it takes precedence over --mode.",
+)
+@click.option("--allow-paper-use", is_flag=True, help="Permit a real paper-consuming composed print.")
+@click.option("--dry-run", is_flag=True, help="Render and validate without sending anything to the printer.")
+@click.pass_context
+def print_compose_command(
+    ctx: click.Context,
+    text: str,
+    image_path: Path,
+    address: str | None,
+    font_size: int | None,
+    feed_mm: float | None,
+    layout: str,
+    mode: str,
+    conversion: str,
+    allow_paper_use: bool,
+    dry_run: bool,
+) -> None:
+    """Print wrapped text together with a local image in one combined layout."""
+    with cli_error_boundary(ctx):
+        driver = registry.get_driver(ctx.obj["settings"])
+        resolved_conversion = resolve_image_conversion(mode=mode, conversion=conversion)
+        result = driver.print_compose(
+            text,
+            image_path,
+            layout=layout.lower(),
+            font_size=font_size,
+            conversion=resolved_conversion,
+            feed_mm=feed_mm,
+            allow_paper_use=allow_paper_use,
+            dry_run=dry_run,
+            address=address,
+        )
+        _emit_print_result(ctx, result)
+
+
+@print_group.command("self-test")
+@click.option("--address", type=str, help="Optional printer MAC address override.")
+@click.option(
+    "--allow-large-paper-use",
+    is_flag=True,
+    help="Permit the built-in self-test, which consumes substantially more paper than ordinary prints.",
+)
+@click.option("--dry-run", is_flag=True, help="Validate the command path without sending the self-test to the printer.")
+@click.pass_context
+def print_self_test_command(
+    ctx: click.Context,
+    address: str | None,
+    allow_large_paper_use: bool,
+    dry_run: bool,
+) -> None:
+    """Run the printer self-test with an explicit large-paper-use warning."""
+    with cli_error_boundary(ctx):
+        driver = registry.get_driver(ctx.obj["settings"])
+        result = driver.self_test(
+            allow_large_paper_use=allow_large_paper_use,
+            dry_run=dry_run,
+            address=address,
+        )
+        _emit_print_result(ctx, result)
+
+
+def _emit_print_result(ctx: click.Context, result) -> None:
+    human_lines = [
+        f"Operation: {result.operation}",
+        f"Dry run: {result.dry_run}",
+        f"Address: {result.address}",
+    ]
+    if result.warning:
+        human_lines.append(f"Warning: {result.warning}")
+    if result.source_path:
+        human_lines.append(f"Source path: {result.source_path}")
+    if result.conversion:
+        human_lines.append(f"Conversion: {result.conversion}")
+    if result.layout:
+        human_lines.append(f"Layout: {result.layout}")
+    if result.feed_mm is not None:
+        human_lines.append(f"Feed mm: {result.feed_mm}")
+    if result.feed_units is not None:
+        human_lines.append(f"Feed units: {result.feed_units}")
+    if result.font_size is not None:
+        human_lines.append(f"Font size: {result.font_size}")
+    if result.bytes_sent is not None:
+        human_lines.append(f"Bytes prepared: {result.bytes_sent}")
+    if result.battery_after is not None:
+        human_lines.append(f"Battery after: {result.battery_after}")
+
+    emit_result(ctx, {"status": "ok", "result": result.to_dict()}, human_lines)

paperang_cli/commands/probe.py

@@ -0,0 +1,57 @@
+"""Probe command."""
+
+from __future__ import annotations
+
+import click
+
+from paperang_cli.drivers import registry
+from paperang_cli.models import ProbeResult
+from paperang_cli.output import cli_error_boundary, emit_result
+
+LOCAL_TRANSPORT_NOTE = "Paperang P1 currently has no validated cable/local data mode in this project. Use Bluetooth for live printer communication."
+
+
+@click.command("probe")
+@click.option("--address", type=str, help="Optional printer MAC address override.")
+@click.pass_context
+def probe_command(ctx: click.Context, address: str | None) -> None:
+    """Run a safe multi-query probe and summarize the current printer state."""
+    with cli_error_boundary(ctx):
+        driver = registry.get_driver(ctx.obj["settings"])
+        status = driver.status(address=address)
+        bluetooth_mac = driver.bluetooth_mac(address=address)
+        result = ProbeResult(
+            model=status.model,
+            address=status.address,
+            transport=status.transport,
+            connected=status.connected,
+            battery_percent=status.battery_percent,
+            serial_number=status.serial_number,
+            firmware_version=status.firmware_version,
+            hardware_info=status.hardware_info,
+            density=status.density,
+            power_off_time=status.power_off_time,
+            bluetooth_mac=bluetooth_mac.bluetooth_mac,
+            local_transport_supported=False,
+            local_transport_note=LOCAL_TRANSPORT_NOTE,
+            raw=dict(status.raw),
+        )
+        emit_result(
+            ctx,
+            {"status": "ok", "result": result.to_dict()},
+            [
+                f"Model: {result.model}",
+                f"Address: {result.address}",
+                f"Transport: {result.transport}",
+                f"Connected: {result.connected}",
+                f"Battery: {result.battery_percent}",
+                f"Serial: {result.serial_number}",
+                f"Firmware: {result.firmware_version}",
+                f"Density: {result.density}",
+                f"Power-off time: {result.power_off_time}",
+                f"Hardware info: {result.hardware_info}",
+                f"Bluetooth MAC: {result.bluetooth_mac}",
+                f"Local transport supported: {result.local_transport_supported}",
+                f"Local transport note: {result.local_transport_note}",
+            ],
+        )

paperang_cli/commands/status.py

@@ -0,0 +1,33 @@
+"""Status command."""
+
+from __future__ import annotations
+
+import click
+
+from paperang_cli.drivers import registry
+from paperang_cli.output import cli_error_boundary, emit_result
+
+
+@click.command("status")
+@click.option("--address", type=str, help="Optional printer MAC address override.")
+@click.pass_context
+def status_command(ctx: click.Context, address: str | None) -> None:
+    """Query printer status without printing."""
+    with cli_error_boundary(ctx):
+        driver = registry.get_driver(ctx.obj["settings"])
+        status = driver.status(address=address)
+        emit_result(
+            ctx,
+            {"status": "ok", "result": status.to_dict()},
+            [
+                f"Model: {status.model}",
+                f"Address: {status.address}",
+                f"Connected: {status.connected}",
+                f"Battery: {status.battery_percent}",
+                f"Serial: {status.serial_number}",
+                f"Firmware: {status.firmware_version}",
+                f"Density: {status.density}",
+                f"Power-off time: {status.power_off_time}",
+                f"Hardware info: {status.hardware_info}",
+            ],
+        )