paperang-cli 0.1.0__tar.gz

paperang_cli-0.1.0/LICENSE

@@ -0,0 +1,23 @@
+MIT License
+
+Copyright (c) 2017 ihc童鞋@提不起劲
+Copyright (c) 2019 BroncoTc
+Copyright (c) 2026 wyrtensi
+
+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.

paperang_cli-0.1.0/PKG-INFO

@@ -0,0 +1,258 @@
+Metadata-Version: 2.4
+Name: paperang-cli
+Version: 0.1.0
+Summary: Standalone CLI for Paperang thermal printers
+Author: wyrtensi
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/wyrtensi/paperang-cli
+Project-URL: Documentation, https://github.com/wyrtensi/paperang-cli/tree/main/docs
+Project-URL: Issues, https://github.com/wyrtensi/paperang-cli/issues
+Project-URL: Source, https://github.com/wyrtensi/paperang-cli
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: System :: Hardware :: Hardware Drivers
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: bleak>=0.21.1
+Requires-Dist: click>=8.1.7
+Requires-Dist: numpy>=1.26.0
+Requires-Dist: Pillow>=10.0.0
+Requires-Dist: scikit-image>=0.20.0
+Requires-Dist: scipy>=1.11.0
+Requires-Dist: numba>=0.58.0
+Requires-Dist: pilkit>=2.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0.0; extra == "dev"
+Provides-Extra: release
+Requires-Dist: build>=1.2.2; extra == "release"
+Requires-Dist: twine>=6.0.0; extra == "release"
+Dynamic: license-file
+
+# paperang-cli
+
+[![CI](https://img.shields.io/github/actions/workflow/status/wyrtensi/paperang-cli/ci.yml?branch=main&label=CI)](https://github.com/wyrtensi/paperang-cli/actions/workflows/ci.yml)
+[![PyPI version](https://img.shields.io/pypi/v/paperang-cli)](https://pypi.org/project/paperang-cli/)
+[![Python versions](https://img.shields.io/pypi/pyversions/paperang-cli)](https://pypi.org/project/paperang-cli/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+![Hardware tested on Windows](https://img.shields.io/badge/hardware_tested-Windows-0078D6?logo=windows11&logoColor=white)
+
+`paperang-cli` is a standalone command-line tool for working with Paperang thermal printers from Python.
+
+It provides a small, script-friendly interface for discovering a printer, checking its status, and printing text or images with explicit safety gates. JSON output is available for automation and agent-driven workflows.
+
+## Current Support
+
+Version `0.1.0` supports:
+
+| Printer | Transport | Status |
+| --- | --- | --- |
+| Paperang P1 | Bluetooth Low Energy (BLE) | Supported |
+
+Local, cable, and USB data transports are not supported for Paperang P1 in this package.
+
+Real printer communication and physical printing have been tested only on Windows. CI runs compatibility checks on Linux and macOS, but those checks do not prove BLE or printer behavior on those platforms.
+
+## Features
+
+- Discover nearby Paperang printers over BLE
+- Check battery level, Bluetooth MAC address, and live printer status
+- Print short text or wrapped paragraphs
+- Print local images with sticker and photo conversion presets
+- Compose text and an image into one print job
+- Preview every print path with `--dry-run`
+- Emit machine-readable JSON with `--json`
+- Use explicit allow flags before any paper-consuming operation
+
+Image and composed printing are available, but remain experimental until you validate physical output on your printer.
+
+## Installation
+
+Python `3.10` or newer is required.
+
+Install the published package from PyPI:
+
+```powershell
+python -m pip install paperang-cli
+```
+
+For local development, clone the repository and install it in editable mode:
+
+```powershell
+git clone https://github.com/wyrtensi/paperang-cli.git
+Set-Location "paperang-cli"
+python -m pip install -e ".[dev]"
+python -m pytest
+```
+
+The package installs two equivalent commands:
+
+- `paperang`
+- `paperang-cli`
+
+Use `paperang` by default. Use `paperang-cli` if the shorter command conflicts with another executable on your system.
+
+## Safe First Run
+
+Start with commands that do not consume paper:
+
+```powershell
+paperang --json config show
+paperang --json discover
+paperang --json probe
+paperang --json battery
+```
+
+Before a real print, run the matching command with `--dry-run`:
+
+```powershell
+paperang --json print text "Hello from Paperang" --dry-run
+```
+
+After checking the result, explicitly allow paper use:
+
+```powershell
+paperang --json print text "Hello from Paperang" --allow-paper-use
+```
+
+Keep the content, image, layout, conversion mode, font size, and feed options the same between dry-run and the real print.
+
+## Printing
+
+### Text
+
+```powershell
+paperang --json print text "Shipping label" --dry-run
+paperang --json print text "Shipping label" --allow-paper-use
+```
+
+### Paragraph
+
+```powershell
+paperang --json print paragraph "A longer wrapped note for the printer." --dry-run
+paperang --json print paragraph "A longer wrapped note for the printer." --allow-paper-use
+```
+
+### Image
+
+Use `--mode sticker` for logos, icons, and line art:
+
+```powershell
+paperang --json print image ".\sample.png" --dry-run --mode sticker
+paperang --json print image ".\sample.png" --allow-paper-use --mode sticker
+```
+
+Use `--mode photo` as a starting point for photographs and smoother grayscale content:
+
+```powershell
+paperang --json print image ".\photo.jpg" --dry-run --mode photo
+```
+
+Image quality depends on the source file and printer. A successful dry-run validates conversion and packaging, not the final paper output.
+
+### Compose
+
+`print compose` combines wrapped text and an image in one vertical layout:
+
+```powershell
+paperang --json print compose "Product label" ".\sample.png" --dry-run --mode sticker
+paperang --json print compose "Product label" ".\sample.png" --allow-paper-use --mode sticker
+```
+
+Use `--layout image-above` when the image should be printed before the text:
+
+```powershell
+paperang --json print compose "Product label" ".\sample.png" --dry-run --layout image-above
+```
+
+Compose printing uses the same experimental image conversion pipeline as `print image`.
+
+### Built-In Self-Test
+
+The printer self-test consumes substantially more paper than an ordinary print. Use it only when you explicitly want the printer's built-in diagnostic page:
+
+```powershell
+paperang --json print self-test --dry-run
+paperang --json print self-test --allow-large-paper-use
+```
+
+The self-test dry-run only validates the CLI path and warning payload. It does not query hidden hardware state.
+
+## Commands
+
+| Command | Purpose |
+| --- | --- |
+| `paperang discover` | Scan for nearby supported printers |
+| `paperang battery` | Query the current battery percentage |
+| `paperang mac` | Query the printer-reported Bluetooth MAC address |
+| `paperang status` | Query live printer information |
+| `paperang probe` | Return a combined readiness summary |
+| `paperang print text` | Print a short text block |
+| `paperang print paragraph` | Print wrapped text |
+| `paperang print image` | Print a local image |
+| `paperang print compose` | Print text and an image as one job |
+| `paperang print self-test` | Print the built-in diagnostic page |
+| `paperang config show` | Show the resolved config and active settings |
+| `paperang config path` | Show the resolved config path |
+| `paperang config init` | Write an example config file |
+
+Run `paperang --help` or `paperang <command> --help` for the available options.
+
+## Configuration
+
+Inspect the active config:
+
+```powershell
+paperang --json config show
+```
+
+Create an example config:
+
+```powershell
+paperang config init
+```
+
+Configuration is resolved in this order:
+
+1. `--config PATH`
+2. `PAPERANG_CLI_CONFIG`
+3. the per-user default config path
+4. built-in defaults
+
+Default paths:
+
+- Windows: `%APPDATA%\paperang-cli\paperang-cli.config.json`
+- Linux and macOS: `$XDG_CONFIG_HOME/paperang-cli/paperang-cli.config.json`, or `~/.config/paperang-cli/paperang-cli.config.json`
+
+See [Configuration](docs/usage/configuration.md) for the full schema.
+
+## Documentation
+
+- [Documentation index](docs/index.md)
+- [Installation guide](docs/installation.md)
+- [Command reference](docs/usage/commands.md)
+- [Configuration](docs/usage/configuration.md)
+- [Troubleshooting](docs/troubleshooting.md)
+- [Agent contract](docs/agents/cli-contract.md)
+- [Publishing runbook for agents](docs/agents/publishing.md)
+
+## Project History And Acknowledgements
+
+This standalone CLI builds on earlier reverse engineering and Paperang P1 control work by:
+
+- `ihc童鞋@提不起劲`
+- `BroncoTc`
+
+The current `paperang-cli` package is maintained by `wyrtensi`.
+
+## License
+
+This package is available under the [MIT License](LICENSE).

paperang_cli-0.1.0/README.md

@@ -0,0 +1,219 @@
+# paperang-cli
+
+[![CI](https://img.shields.io/github/actions/workflow/status/wyrtensi/paperang-cli/ci.yml?branch=main&label=CI)](https://github.com/wyrtensi/paperang-cli/actions/workflows/ci.yml)
+[![PyPI version](https://img.shields.io/pypi/v/paperang-cli)](https://pypi.org/project/paperang-cli/)
+[![Python versions](https://img.shields.io/pypi/pyversions/paperang-cli)](https://pypi.org/project/paperang-cli/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+![Hardware tested on Windows](https://img.shields.io/badge/hardware_tested-Windows-0078D6?logo=windows11&logoColor=white)
+
+`paperang-cli` is a standalone command-line tool for working with Paperang thermal printers from Python.
+
+It provides a small, script-friendly interface for discovering a printer, checking its status, and printing text or images with explicit safety gates. JSON output is available for automation and agent-driven workflows.
+
+## Current Support
+
+Version `0.1.0` supports:
+
+| Printer | Transport | Status |
+| --- | --- | --- |
+| Paperang P1 | Bluetooth Low Energy (BLE) | Supported |
+
+Local, cable, and USB data transports are not supported for Paperang P1 in this package.
+
+Real printer communication and physical printing have been tested only on Windows. CI runs compatibility checks on Linux and macOS, but those checks do not prove BLE or printer behavior on those platforms.
+
+## Features
+
+- Discover nearby Paperang printers over BLE
+- Check battery level, Bluetooth MAC address, and live printer status
+- Print short text or wrapped paragraphs
+- Print local images with sticker and photo conversion presets
+- Compose text and an image into one print job
+- Preview every print path with `--dry-run`
+- Emit machine-readable JSON with `--json`
+- Use explicit allow flags before any paper-consuming operation
+
+Image and composed printing are available, but remain experimental until you validate physical output on your printer.
+
+## Installation
+
+Python `3.10` or newer is required.
+
+Install the published package from PyPI:
+
+```powershell
+python -m pip install paperang-cli
+```
+
+For local development, clone the repository and install it in editable mode:
+
+```powershell
+git clone https://github.com/wyrtensi/paperang-cli.git
+Set-Location "paperang-cli"
+python -m pip install -e ".[dev]"
+python -m pytest
+```
+
+The package installs two equivalent commands:
+
+- `paperang`
+- `paperang-cli`
+
+Use `paperang` by default. Use `paperang-cli` if the shorter command conflicts with another executable on your system.
+
+## Safe First Run
+
+Start with commands that do not consume paper:
+
+```powershell
+paperang --json config show
+paperang --json discover
+paperang --json probe
+paperang --json battery
+```
+
+Before a real print, run the matching command with `--dry-run`:
+
+```powershell
+paperang --json print text "Hello from Paperang" --dry-run
+```
+
+After checking the result, explicitly allow paper use:
+
+```powershell
+paperang --json print text "Hello from Paperang" --allow-paper-use
+```
+
+Keep the content, image, layout, conversion mode, font size, and feed options the same between dry-run and the real print.
+
+## Printing
+
+### Text
+
+```powershell
+paperang --json print text "Shipping label" --dry-run
+paperang --json print text "Shipping label" --allow-paper-use
+```
+
+### Paragraph
+
+```powershell
+paperang --json print paragraph "A longer wrapped note for the printer." --dry-run
+paperang --json print paragraph "A longer wrapped note for the printer." --allow-paper-use
+```
+
+### Image
+
+Use `--mode sticker` for logos, icons, and line art:
+
+```powershell
+paperang --json print image ".\sample.png" --dry-run --mode sticker
+paperang --json print image ".\sample.png" --allow-paper-use --mode sticker
+```
+
+Use `--mode photo` as a starting point for photographs and smoother grayscale content:
+
+```powershell
+paperang --json print image ".\photo.jpg" --dry-run --mode photo
+```
+
+Image quality depends on the source file and printer. A successful dry-run validates conversion and packaging, not the final paper output.
+
+### Compose
+
+`print compose` combines wrapped text and an image in one vertical layout:
+
+```powershell
+paperang --json print compose "Product label" ".\sample.png" --dry-run --mode sticker
+paperang --json print compose "Product label" ".\sample.png" --allow-paper-use --mode sticker
+```
+
+Use `--layout image-above` when the image should be printed before the text:
+
+```powershell
+paperang --json print compose "Product label" ".\sample.png" --dry-run --layout image-above
+```
+
+Compose printing uses the same experimental image conversion pipeline as `print image`.
+
+### Built-In Self-Test
+
+The printer self-test consumes substantially more paper than an ordinary print. Use it only when you explicitly want the printer's built-in diagnostic page:
+
+```powershell
+paperang --json print self-test --dry-run
+paperang --json print self-test --allow-large-paper-use
+```
+
+The self-test dry-run only validates the CLI path and warning payload. It does not query hidden hardware state.
+
+## Commands
+
+| Command | Purpose |
+| --- | --- |
+| `paperang discover` | Scan for nearby supported printers |
+| `paperang battery` | Query the current battery percentage |
+| `paperang mac` | Query the printer-reported Bluetooth MAC address |
+| `paperang status` | Query live printer information |
+| `paperang probe` | Return a combined readiness summary |
+| `paperang print text` | Print a short text block |
+| `paperang print paragraph` | Print wrapped text |
+| `paperang print image` | Print a local image |
+| `paperang print compose` | Print text and an image as one job |
+| `paperang print self-test` | Print the built-in diagnostic page |
+| `paperang config show` | Show the resolved config and active settings |
+| `paperang config path` | Show the resolved config path |
+| `paperang config init` | Write an example config file |
+
+Run `paperang --help` or `paperang <command> --help` for the available options.
+
+## Configuration
+
+Inspect the active config:
+
+```powershell
+paperang --json config show
+```
+
+Create an example config:
+
+```powershell
+paperang config init
+```
+
+Configuration is resolved in this order:
+
+1. `--config PATH`
+2. `PAPERANG_CLI_CONFIG`
+3. the per-user default config path
+4. built-in defaults
+
+Default paths:
+
+- Windows: `%APPDATA%\paperang-cli\paperang-cli.config.json`
+- Linux and macOS: `$XDG_CONFIG_HOME/paperang-cli/paperang-cli.config.json`, or `~/.config/paperang-cli/paperang-cli.config.json`
+
+See [Configuration](docs/usage/configuration.md) for the full schema.
+
+## Documentation
+
+- [Documentation index](docs/index.md)
+- [Installation guide](docs/installation.md)
+- [Command reference](docs/usage/commands.md)
+- [Configuration](docs/usage/configuration.md)
+- [Troubleshooting](docs/troubleshooting.md)
+- [Agent contract](docs/agents/cli-contract.md)
+- [Publishing runbook for agents](docs/agents/publishing.md)
+
+## Project History And Acknowledgements
+
+This standalone CLI builds on earlier reverse engineering and Paperang P1 control work by:
+
+- `ihc童鞋@提不起劲`
+- `BroncoTc`
+
+The current `paperang-cli` package is maintained by `wyrtensi`.
+
+## License
+
+This package is available under the [MIT License](LICENSE).

paperang_cli-0.1.0/pyproject.toml

@@ -0,0 +1,67 @@
+[build-system]
+requires = ["setuptools>=77", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "paperang-cli"
+version = "0.1.0"
+description = "Standalone CLI for Paperang thermal printers"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "wyrtensi" },
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Operating System :: Microsoft :: Windows",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: System :: Hardware :: Hardware Drivers",
+]
+dependencies = [
+    "bleak>=0.21.1",
+    "click>=8.1.7",
+    "numpy>=1.26.0",
+    "Pillow>=10.0.0",
+    "scikit-image>=0.20.0",
+    "scipy>=1.11.0",
+    "numba>=0.58.0",
+    "pilkit>=2.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-cov>=5.0.0",
+]
+release = [
+    "build>=1.2.2",
+    "twine>=6.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/wyrtensi/paperang-cli"
+Documentation = "https://github.com/wyrtensi/paperang-cli/tree/main/docs"
+Issues = "https://github.com/wyrtensi/paperang-cli/issues"
+Source = "https://github.com/wyrtensi/paperang-cli"
+
+[project.scripts]
+paperang = "paperang_cli.cli:main"
+paperang-cli = "paperang_cli.cli:main"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"
+
+[tool.setuptools.package-dir]
+"" = "src"
+
+[tool.setuptools.packages.find]
+where = ["src"]

paperang_cli-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

paperang_cli-0.1.0/src/paperang_cli/__init__.py

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

paperang_cli-0.1.0/src/paperang_cli/__main__.py

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

paperang_cli-0.1.0/src/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-0.1.0/src/paperang_cli/commands/__init__.py

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