printer-cli 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,229 @@
1
+ Metadata-Version: 2.5
2
+ Name: printer-cli
3
+ Version: 0.1.0
4
+ Summary: Your printer's dashboard in the terminal: ink, paper, alerts, nozzle checks, head cleaning, printing and scanning for network printers (IPP, eSCL, SNMP, Epson ESC/P2).
5
+ Project-URL: Homepage, https://github.com/luongnv89/printer-cli
6
+ Project-URL: Repository, https://github.com/luongnv89/printer-cli
7
+ Project-URL: Issues, https://github.com/luongnv89/printer-cli/issues
8
+ Project-URL: Changelog, https://github.com/luongnv89/printer-cli/blob/main/CHANGELOG.md
9
+ Author: Luong NGUYEN
10
+ License-Expression: MIT
11
+ License-File: LICENSE
12
+ Keywords: airprint,cli,epson,escl,ink,ipp,printer,scanner,snmp,tui
13
+ Classifier: Development Status :: 4 - Beta
14
+ Classifier: Environment :: Console
15
+ Classifier: Intended Audience :: End Users/Desktop
16
+ Classifier: Intended Audience :: System Administrators
17
+ Classifier: Operating System :: MacOS
18
+ Classifier: Operating System :: POSIX :: Linux
19
+ Classifier: Programming Language :: Python :: 3
20
+ Classifier: Programming Language :: Python :: 3.11
21
+ Classifier: Programming Language :: Python :: 3.12
22
+ Classifier: Programming Language :: Python :: 3.13
23
+ Classifier: Topic :: Printing
24
+ Classifier: Topic :: System :: Hardware
25
+ Classifier: Topic :: Utilities
26
+ Requires-Python: >=3.11
27
+ Requires-Dist: httpx>=0.27
28
+ Requires-Dist: pillow>=10.1
29
+ Requires-Dist: rich>=13.7
30
+ Requires-Dist: shellingham>=1.5.4
31
+ Requires-Dist: textual>=0.80
32
+ Requires-Dist: typer>=0.12
33
+ Requires-Dist: zeroconf>=0.132
34
+ Description-Content-Type: text/markdown
35
+
36
+ <p align="center"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/luongnv89/printer-cli/main/assets/logo/logo-white.svg"><img src="https://raw.githubusercontent.com/luongnv89/printer-cli/main/assets/logo/logo-black.svg" alt="printer-cli" width="360"></picture></p>
37
+
38
+ <p align="center"><a href="https://pypi.org/project/printer-cli/"><img src="https://img.shields.io/pypi/v/printer-cli" alt="PyPI"></a> <img src="https://img.shields.io/badge/python-3.11%2B-blue" alt="Python 3.11+"> <a href="https://github.com/luongnv89/printer-cli/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="MIT license"></a></p>
39
+
40
+ Check ink, paper and alerts, run nozzle checks and head cleaning, print and scan on network printers, from a scriptable CLI or a full-screen TUI.
41
+
42
+ ## Install
43
+
44
+ ```bash
45
+ uv tool install printer-cli
46
+ ```
47
+
48
+ Requires Python 3.11+. Puts `prt` on your PATH (`printer-cli` works too). Other methods: [Install options](#install-options).
49
+
50
+ ## Quick start
51
+
52
+ Check a printer's ink, paper and alerts. No printer handy? The built-in `demo` printer replays a real Epson XP-6000:
53
+
54
+ ```bash
55
+ prt -p demo status
56
+ ```
57
+
58
+ ```
59
+ ╭─┐EPSON XP-6000 Series · office┌──────────────────────────────────────────╮
60
+ │ ● idle firmware 20.50.NU30Q6 · up 4h02m │
61
+ ├──────────────────────────────────────────────────────────────────────────┤
62
+ │ ink │
63
+ │ Photo Black ■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■···· 92% │
64
+ │ Cyan ········································ 1% ✗ replace │
65
+ │ Magenta ········································ 1% ✗ replace │
66
+ │ Yellow ■■■■···································· 12% ▲ low │
67
+ │ Black ■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■····· 89% │
68
+ ├──────────────────────────────────────────────────────────────────────────┤
69
+ │ paper main A4 ✓ photo 4×6 ✓ disc Disc ✓ (levels not reported) │
70
+ │ waste ▲ almost full — service soon │
71
+ ╰─┘4 alerts · checked 17:42└───────────────────────────────────────────────╯
72
+ ```
73
+
74
+ Next: [Use your own printer](#use-your-own-printer) · [Commands](#commands) · [The TUI](#the-tui) · [Safety](#safety)
75
+
76
+ ## Why printer-cli
77
+
78
+ It started because the Epson XP-6000's web dashboard stopped working. printer-cli talks to the printer directly over standard protocols (IPP, eSCL, SNMP, plus Epson's ESC/P2 remote mode for maintenance). It works with most AirPrint/Mopria printers from any brand, and you can manage several printers from one place.
79
+
80
+ ## Use your own printer
81
+
82
+ ```bash
83
+ prt discover # find printers on the LAN
84
+ prt printers add office EPSON721655.local --default # save one under a short name
85
+ prt status # ink, paper, alerts
86
+ prt tui # full-screen dashboard
87
+ ```
88
+
89
+ Every command also works against the built-in replay: `prt -p demo status`, `prt -p demo tui`.
90
+
91
+ ## Status
92
+
93
+ | | Verified against the real XP-6000 | Covered by tests (replay of its data) |
94
+ |---|---|---|
95
+ | Ink, state, alerts, paper, firmware (IPP) | ✅ read live during development | ✅ |
96
+ | Page counter (SNMP) | ✅ | ✅ |
97
+ | Scanner capabilities (eSCL) | ✅ | ✅ |
98
+ | Scanning a page | ⏳ not yet | ✅ (mocked HTTP) |
99
+ | Printing (IPP / CUPS) | ⏳ not yet | ✅ (fake transport) |
100
+ | Nozzle check / head cleaning (ESC/P2 on 9100) | ⏳ not yet: bytes match gutenprint `escputil`, port 9100 is open | ✅ (byte-exact) |
101
+
102
+ ## Commands
103
+
104
+ | Command | What it does |
105
+ |---|---|
106
+ | `prt status [--watch N]` | State, alerts, ink, paper, waste pad. `--watch` prints one line per sample |
107
+ | `prt ink` | Ink levels only |
108
+ | `prt overview` | System, software and hardware: model, serial, firmware, uptime, page count, formats, media, scanner, capabilities |
109
+ | `prt discover` | mDNS scan for printers and scanners |
110
+ | `prt printers list/add/remove/default` | Manage saved printers |
111
+ | `prt maintain nozzle-check` | Print the nozzle check pattern |
112
+ | `prt maintain clean [--force]` | Head cleaning, with a safety check first (see [Safety](#safety)) |
113
+ | `prt maintain test-page` | Colour test page: ink bars, gradients, grey steps, fine lines |
114
+ | `prt maintain identify` | Flash the printer's panel |
115
+ | `prt print FILE… [-n 2] [--media 4x6] [--tray photo] [--quality high] [--mono] [--duplex]` | Print |
116
+ | `prt jobs [--all]` / `prt jobs cancel ID` | List or cancel jobs |
117
+ | `prt scan [-o file.pdf] [--type jpeg] [--dpi 600] [--mode gray] [--area full]` | Flatbed scan (`-o -` writes to stdout) |
118
+ | `prt tui` | Full-screen dashboard |
119
+
120
+ **Global options**, which can go before or after the command:
121
+ - `-p/--printer NAME|HOST` picks the printer.
122
+ - `-f/--format json` prints machine-readable output.
123
+ - `--no-color` turns colour off.
124
+ - `-q` hides notes and prints only results.
125
+ - `--timeout S` sets the network timeout in seconds.
126
+ - `--config PATH` uses a different config file.
127
+
128
+ ### Scripting
129
+
130
+ ```bash
131
+ prt ink -f json | jq -r '.inks[] | select(.state != "ok") | "\(.name): \(.level)%"'
132
+ prt status | grep '^alert' # piped output is tab-separated, no colour
133
+ prt scan -o - --type jpeg > page.jpg
134
+ ```
135
+
136
+ Exit codes: `0` ok · `1` runtime/network error (also when only cached status is shown) · `2` usage error · `3` bad input file · `130` Ctrl-C.
137
+
138
+ ## The TUI
139
+
140
+ `prt tui` opens a keyboard-driven dashboard. Inks are drawn as vertical tanks in their real cartridge colours, alongside system info, paper and alerts. Tabs: **Dashboard · Maintain · Print · Scan · Jobs**.
141
+
142
+ | Key | Action |
143
+ |---|---|
144
+ | `r` | Refresh (auto-refreshes every 10 s) |
145
+ | `n` / `c` / `i` | Nozzle check / head cleaning (both ask first) / identify |
146
+ | `p` / `s` / `j` | Print, Scan, Jobs tabs |
147
+ | `1`–`9` | Switch between saved printers |
148
+ | `q` | Quit |
149
+
150
+ ## Safety
151
+
152
+ - **Head cleaning is refused** while any ink is at or below its low level, or while the waste ink pad is flagged. Cleaning flushes ink into the pad, and a full pad locks the printer until it's serviced. `--force` overrides this, and the TUI offers "Clean anyway".
153
+ - Nozzle check, cleaning and the test page ask for confirmation first. In scripts, pass `--yes`.
154
+ - printer-cli never resets the waste ink counter or writes to the printer's EEPROM.
155
+
156
+ ## How it talks to printers
157
+
158
+ | Feature | Protocol | Notes |
159
+ |---|---|---|
160
+ | Status, ink, info, jobs, identify | IPP (631) | Small IPP codec built in, no `ipptool` needed |
161
+ | Printing | IPP Print-Job | JPEG/PWG/URF go direct; PNG etc. are converted to JPEG; **PDF and other files go through the local CUPS queue** for the same printer, matched by UUID (the XP-6000 doesn't accept PDF) |
162
+ | Scanning | eSCL / AirScan (443) | Certificate checks are skipped for the scanner host only, because printers ship self-signed certificates |
163
+ | Page counter | SNMP v1 | Printer-MIB lifetime count |
164
+ | Nozzle check, cleaning | ESC/P2 remote mode on 9100 | Byte sequences from gutenprint's `escputil` (Epson only) |
165
+
166
+ When the printer is asleep, `status` and the TUI show the **last known status** from `~/.cache/prt/`, marked as cached.
167
+
168
+ ## Configuration
169
+
170
+ `~/.config/prt/config.toml`. Override the location with `PRT_CONFIG` or `--config`. Priority order: **command-line flags > environment variables (`PRT_PRINTER`, `PRT_TIMEOUT`) > config file > defaults**.
171
+
172
+ ```toml
173
+ default = "office"
174
+
175
+ [printers.office]
176
+ host = "EPSON721655.local"
177
+
178
+ [printers.pantum]
179
+ host = "192.168.1.80"
180
+ driver = "ipp"
181
+ ```
182
+
183
+ ## Install options
184
+
185
+ With pipx:
186
+
187
+ ```bash
188
+ pipx install printer-cli
189
+ ```
190
+
191
+ From source (add `--editable` to track local changes):
192
+
193
+ ```bash
194
+ git clone https://github.com/luongnv89/printer-cli.git && cd printer-cli
195
+ uv tool install .
196
+ ```
197
+
198
+ Optional tab completion for your shell:
199
+
200
+ ```bash
201
+ prt --install-completion
202
+ ```
203
+
204
+ ## Adding a printer brand
205
+
206
+ Drivers live in `src/prt/drivers/`:
207
+ - `IPPDriver` covers any IPP Everywhere / AirPrint printer.
208
+ - `EpsonDriver` adds maintenance and counters on top of it.
209
+ - `FakeDriver` replays a captured fixture, for tests and the demo.
210
+
211
+ To add a vendor, subclass `IPPDriver`, declare its `capabilities`, override what it can do, and register it in `drivers/registry.py`. The CLI and TUI hide actions a driver doesn't support.
212
+
213
+ ## Development
214
+
215
+ ```bash
216
+ uv sync
217
+ uv run pytest # 88 tests, no printer needed
218
+ uv run prt -p demo tui
219
+ ```
220
+
221
+ ## Troubleshooting
222
+
223
+ - **"cannot reach printer"**: the printer is probably asleep. Press any button on it, or check `prt discover`.
224
+ - **Shell completion isn't detected**: write the script out manually, e.g. `_PRT_COMPLETE=source_zsh prt > ~/.zfunc/_prt`.
225
+ - **PDF won't print**: add the printer in System Settings → Printers so a CUPS queue exists, or print a JPEG.
226
+
227
+ ## License
228
+
229
+ [MIT](https://github.com/luongnv89/printer-cli/blob/main/LICENSE) © Luong NGUYEN
@@ -0,0 +1,33 @@
1
+ prt/__init__.py,sha256=tD0rGs_ZRJAaqEE4A66FC5sW19dG-0krMpUyisEEIns,87
2
+ prt/__main__.py,sha256=wYQrrY0UR7lTQpKW6YAtVfOSGWL-d5fIpe4_tHi2hYE,35
3
+ prt/cache.py,sha256=QfQFG2ZL25BxPC-2RnKUTZ_r_5ddPQAMIJRlui-wpHU,1699
4
+ prt/cli.py,sha256=L3Eyv2uGgQOAwONjwFxBB6uZ7yKesvOXyMGYlX8gY6c,35298
5
+ prt/config.py,sha256=Dy-Y_tZJi7djQtnb78z1OhvNU9DRlrqRBAL9D3yAuFk,5162
6
+ prt/discovery.py,sha256=I81pypwdg4AjY8IK0P7haTtiNdi9pIFJHUsOsM-Wow0,4534
7
+ prt/maintenance.py,sha256=LHFrKZjm6GfpaxI9sjPF1JGX0ATkV5Ool1HyWtDZD9o,2152
8
+ prt/media.py,sha256=udpLxOs8f6UmkzaGR4d_YWRRjMSkAUcUUNEuNHw3lvw,2304
9
+ prt/models.py,sha256=nv13TSJeJ15d4yLzrh3kep14E1GVUIzYrrmXSze6E_E,5558
10
+ prt/printing.py,sha256=7N0ceNrlFwHR0PNcZaQCNpdSFoztnhY4QVqe-G1UwvA,4082
11
+ prt/style.py,sha256=KwLyJXSaLYicnWxi79-Uk_Ni9z4yKHAAff1ToUb_9CM,11935
12
+ prt/testpage.py,sha256=2hAjpWlJiqRj8DhhuBw7y0ZYqy1DvGCjFZ8ThwKA0UQ,2663
13
+ prt/drivers/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
14
+ prt/drivers/base.py,sha256=w8tu3pKINeAJb_Tx4Be_zU1umpKV5MSfOBel6KoLmiQ,3061
15
+ prt/drivers/epson.py,sha256=wW_j0bLs-HJaHGjUjCjGVSbP8UmQeSbRqGXYQbZ8tdA,3635
16
+ prt/drivers/fake.py,sha256=AU-YzLSQy2UR2jFpuyC94kA-7DYI4cFPidBvjJjYafQ,3436
17
+ prt/drivers/ipp.py,sha256=TfPQyF72CuN8u7qVJw3XKA8ug3PTu-TC-MJt5q92S94,16324
18
+ prt/drivers/registry.py,sha256=XcGE_LVxkMR32OBSGbSJ4FI3QoAAq1r-SkdwPh0WU3Y,1795
19
+ prt/fixtures/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
20
+ prt/fixtures/epson-xp6000.json,sha256=AxHBB8BBkAEZUcq2x6HuJ0EcclAyQYj351YuJMbVv9M,4640
21
+ prt/transport/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
22
+ prt/transport/escl.py,sha256=8clLNkvObLQ2n2FQc6EUSYLJurhpvZhgJBz0b_Y2lsc,8456
23
+ prt/transport/ipp.py,sha256=VUNAaeRZq2hYd4EqVQoJtnwIZKt1sJ2BAixFsq8PswI,12574
24
+ prt/transport/snmp.py,sha256=ZYmM5mCNSViqC7Bc0NPa6ZifAaGgzhAte9XzkZ4-te4,4433
25
+ prt/tui/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
26
+ prt/tui/app.py,sha256=oG3L16k3OOZnd2w7BxqgBp5RvTy0lo8KcNnXZn9OsbY,23405
27
+ prt/tui/app.tcss,sha256=RVE_CDanDoCbWpuvjxsNXZOnRcgQabbPy4YTtiPtR6U,4841
28
+ prt/tui/widgets.py,sha256=fuBKJSUSArUbz0wifo7CjHUsxX5ng9FKb-pOCaGGEko,7291
29
+ printer_cli-0.1.0.dist-info/METADATA,sha256=74aMzJLR2xAuPMOL8188EiJGvgnjUHFxMYtjumjB6BA,11203
30
+ printer_cli-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
31
+ printer_cli-0.1.0.dist-info/entry_points.txt,sha256=BdJSkpXMX8biqUWDaDLX0oCq3OCPn1muOUnnxc3JUHA,64
32
+ printer_cli-0.1.0.dist-info/licenses/LICENSE,sha256=k5D9uf23aX3vQAyvcUdN2p27Jd-o8Iio6dFspjNto7U,1069
33
+ printer_cli-0.1.0.dist-info/RECORD,,
@@ -0,0 +1,4 @@
1
+ Wheel-Version: 1.0
2
+ Generator: hatchling 1.33.0
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
@@ -0,0 +1,3 @@
1
+ [console_scripts]
2
+ printer-cli = prt.cli:main
3
+ prt = prt.cli:main
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Luong NGUYEN
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
prt/__init__.py ADDED
@@ -0,0 +1,3 @@
1
+ """printer-cli (`prt`) — printer control for the terminal."""
2
+
3
+ __version__ = "0.1.0"
prt/__main__.py ADDED
@@ -0,0 +1,3 @@
1
+ from prt.cli import entry
2
+
3
+ entry()
prt/cache.py ADDED
@@ -0,0 +1,43 @@
1
+ """Last-known-status cache so a sleeping printer still shows something useful."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import json
6
+ from pathlib import Path
7
+
8
+ from prt.config import cache_dir
9
+ from prt.models import Alert, Ink, Severity, Status, Tray, to_dict
10
+
11
+
12
+ def _file(name: str, base: Path | None = None) -> Path:
13
+ safe = "".join(c if c.isalnum() or c in "-_." else "_" for c in name)
14
+ return (base or cache_dir()) / f"status-{safe}.json"
15
+
16
+
17
+ def save(name: str, status: Status, base: Path | None = None) -> None:
18
+ try:
19
+ path = _file(name, base)
20
+ path.parent.mkdir(parents=True, exist_ok=True)
21
+ path.write_text(json.dumps(to_dict(status)))
22
+ except OSError:
23
+ pass # the cache is a convenience; never fail a command over it
24
+
25
+
26
+ def load(name: str, base: Path | None = None) -> Status | None:
27
+ try:
28
+ data = json.loads(_file(name, base).read_text())
29
+ except (OSError, ValueError):
30
+ return None
31
+ try:
32
+ return Status(
33
+ state="offline", accepting=False,
34
+ inks=[Ink(name=i["name"], color=i["color"], level=i["level"], low=i.get("low", 15),
35
+ high=i.get("high", 100), kind=i.get("kind", "ink-cartridge")) for i in data["inks"]],
36
+ trays=[Tray(**t) for t in data.get("trays", [])],
37
+ alerts=[Alert(a["code"], Severity(a["severity"]), a["message"]) for a in data.get("alerts", [])],
38
+ reasons=data.get("reasons", []), waste=data.get("waste"),
39
+ waste_level=data.get("waste_level"), queued_jobs=data.get("queued_jobs", 0),
40
+ checked_at=data.get("checked_at", 0), stale=True,
41
+ )
42
+ except (KeyError, TypeError, ValueError):
43
+ return None