a4-printer-webserver 0.1.0__tar.gz

a4_printer_webserver-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 GGN_2015
+
+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.

a4_printer_webserver-0.1.0/PKG-INFO

@@ -0,0 +1,106 @@
+Metadata-Version: 2.4
+Name: a4-printer-webserver
+Version: 0.1.0
+Summary: A password-protected Flask and WebSocket frontend for a4-printer-interface
+Author-email: GGN_2015 <neko@jlulug.org>
+License-Expression: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: a4-printer-interface
+Requires-Dist: Flask<4.0,>=3.1
+Requires-Dist: flask-sock<1.0,>=0.7
+Dynamic: license-file
+
+# a4_printer_webserver
+
+A single-printer web interface built with Flask and native WebSockets. It uses
+[`a4-printer-interface`](https://pypi.org/project/a4-printer-interface/) to
+discover the printer, monitor its activity, and submit PDF documents or images.
+
+## Installation
+
+Python 3.10 or newer is required. The target printer must already be configured
+in the operating system.
+
+```powershell
+python -m pip install a4_printer_webserver
+```
+
+First, list the available printers and their UUIDs:
+
+```powershell
+python -m a4_printer_interface
+```
+
+Then start the website:
+
+```powershell
+python -m a4_printer_webserver `
+  --uuid "printer uuid" `
+  --password "your password"
+```
+
+The server listens on <http://127.0.0.1:5000> by default, and the default page
+title is `Printer Website`. To use a custom title:
+
+```powershell
+python -m a4_printer_webserver `
+  --uuid "8fd0d51f-12c8-5b50-a2f1-4f64641ae77c" `
+  --password "your password" `
+  --title "New Title"
+```
+
+Both `--uuid` and `--password` are required. An empty password is rejected.
+The following options are also available:
+
+- `--host 127.0.0.1`: Address on which the server listens. Use `0.0.0.0` to
+  allow access from the local network.
+- `--port 5000`: TCP port on which the server listens.
+- `--data-dir printer_data`: Directory for uploaded files, the SQLite queue,
+  and print history.
+- `--max-upload-mb 100`: Maximum size of one uploaded file, in MiB.
+- `--auto-delete DAYS`: Automatically delete submitted document files after a
+  positive number of days. Automatic deletion is disabled when this option is
+  omitted.
+
+When exposing the service to a local network or the internet, place it behind
+an HTTPS-enabled reverse proxy. Passwords and documents should not cross an
+untrusted network over plain HTTP.
+
+## Behavior
+
+- Unauthenticated users can only access the login page. They cannot view the
+  queue, download previously submitted files, or establish an authenticated
+  WebSocket connection.
+- Uploading a document does not print it immediately. The user must click
+  `Print` before the document enters the queue.
+- The `Print test page` button asks for confirmation before adding the built-in
+  test page to the queue. It can be canceled until printing starts.
+- `Pause printing` prevents queued jobs from starting. It does not interrupt a
+  job that is already printing, and the paused state resets when the server
+  restarts.
+- Documents that have not started printing can be canceled. A document in the
+  `printing` state cannot be canceled.
+- After the printing library returns successfully, the job is shown as
+  `Submitted`. This means that the operating system accepted the job; it does
+  not guarantee that the physical pages have finished printing.
+- A green light means the printer is idle, yellow means the printer or the
+  current submission is busy, and red means that the configured UUID cannot be
+  found or the print service status cannot be read.
+- While the printer reports that it is busy, the most recently submitted job
+  remains in History but is displayed as `Printing`. It returns to `Submitted`
+  when the printer becomes idle.
+- A submitted document can be deleted manually after confirmation. Manual and
+  automatic deletion remove only the stored file; the History entry remains.
+  Its Download button is then shown as disabled. Files for jobs currently shown
+  as `Printing`, and built-in test-page jobs, do not offer a Delete button.
+- The queue and history are stored in SQLite. If the server stops unexpectedly,
+  a job that was being submitted is marked as failed and is not printed again
+  automatically.
+
+## Tests
+
+```powershell
+python -m unittest discover -s tests -v
+```

a4_printer_webserver-0.1.0/README.md

@@ -0,0 +1,92 @@
+# a4_printer_webserver
+
+A single-printer web interface built with Flask and native WebSockets. It uses
+[`a4-printer-interface`](https://pypi.org/project/a4-printer-interface/) to
+discover the printer, monitor its activity, and submit PDF documents or images.
+
+## Installation
+
+Python 3.10 or newer is required. The target printer must already be configured
+in the operating system.
+
+```powershell
+python -m pip install a4_printer_webserver
+```
+
+First, list the available printers and their UUIDs:
+
+```powershell
+python -m a4_printer_interface
+```
+
+Then start the website:
+
+```powershell
+python -m a4_printer_webserver `
+  --uuid "printer uuid" `
+  --password "your password"
+```
+
+The server listens on <http://127.0.0.1:5000> by default, and the default page
+title is `Printer Website`. To use a custom title:
+
+```powershell
+python -m a4_printer_webserver `
+  --uuid "8fd0d51f-12c8-5b50-a2f1-4f64641ae77c" `
+  --password "your password" `
+  --title "New Title"
+```
+
+Both `--uuid` and `--password` are required. An empty password is rejected.
+The following options are also available:
+
+- `--host 127.0.0.1`: Address on which the server listens. Use `0.0.0.0` to
+  allow access from the local network.
+- `--port 5000`: TCP port on which the server listens.
+- `--data-dir printer_data`: Directory for uploaded files, the SQLite queue,
+  and print history.
+- `--max-upload-mb 100`: Maximum size of one uploaded file, in MiB.
+- `--auto-delete DAYS`: Automatically delete submitted document files after a
+  positive number of days. Automatic deletion is disabled when this option is
+  omitted.
+
+When exposing the service to a local network or the internet, place it behind
+an HTTPS-enabled reverse proxy. Passwords and documents should not cross an
+untrusted network over plain HTTP.
+
+## Behavior
+
+- Unauthenticated users can only access the login page. They cannot view the
+  queue, download previously submitted files, or establish an authenticated
+  WebSocket connection.
+- Uploading a document does not print it immediately. The user must click
+  `Print` before the document enters the queue.
+- The `Print test page` button asks for confirmation before adding the built-in
+  test page to the queue. It can be canceled until printing starts.
+- `Pause printing` prevents queued jobs from starting. It does not interrupt a
+  job that is already printing, and the paused state resets when the server
+  restarts.
+- Documents that have not started printing can be canceled. A document in the
+  `printing` state cannot be canceled.
+- After the printing library returns successfully, the job is shown as
+  `Submitted`. This means that the operating system accepted the job; it does
+  not guarantee that the physical pages have finished printing.
+- A green light means the printer is idle, yellow means the printer or the
+  current submission is busy, and red means that the configured UUID cannot be
+  found or the print service status cannot be read.
+- While the printer reports that it is busy, the most recently submitted job
+  remains in History but is displayed as `Printing`. It returns to `Submitted`
+  when the printer becomes idle.
+- A submitted document can be deleted manually after confirmation. Manual and
+  automatic deletion remove only the stored file; the History entry remains.
+  Its Download button is then shown as disabled. Files for jobs currently shown
+  as `Printing`, and built-in test-page jobs, do not offer a Delete button.
+- The queue and history are stored in SQLite. If the server stops unexpectedly,
+  a job that was being submitted is marked as failed and is not printed again
+  automatically.
+
+## Tests
+
+```powershell
+python -m unittest discover -s tests -v
+```

a4_printer_webserver-0.1.0/a4_printer_webserver/__init__.py

@@ -0,0 +1,5 @@
+"""A password-protected web interface for an A4 printer."""
+
+from .app import create_app
+
+__all__ = ["create_app"]

a4_printer_webserver-0.1.0/a4_printer_webserver/__main__.py

@@ -0,0 +1,96 @@
+"""Run the web server with ``python -m a4_printer_webserver``."""
+
+from __future__ import annotations
+
+import argparse
+import logging
+import uuid
+from pathlib import Path
+
+from .app import create_app
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        description="Serve a password-protected web interface for one A4 printer."
+    )
+    parser.add_argument(
+        "--uuid",
+        required=True,
+        type=_printer_uuid,
+        help="UUID reported by a4-printer-interface for the target printer",
+    )
+    parser.add_argument(
+        "--password",
+        required=True,
+        help="password required to access the website",
+    )
+    parser.add_argument("--title", default="Printer Website", help="website title")
+    parser.add_argument("--host", default="127.0.0.1", help="address to listen on")
+    parser.add_argument("--port", default=5000, type=int, help="TCP port to listen on")
+    parser.add_argument(
+        "--data-dir",
+        type=Path,
+        default=Path("printer_data"),
+        help="directory used for uploaded files and queue history",
+    )
+    parser.add_argument(
+        "--max-upload-mb",
+        default=100,
+        type=_positive_integer,
+        help="maximum size of one uploaded file in MiB",
+    )
+    parser.add_argument(
+        "--auto-delete",
+        metavar="DAYS",
+        type=_positive_integer,
+        help="delete submitted document files after this many days",
+    )
+    return parser
+
+
+def main() -> None:
+    args = build_parser().parse_args()
+    if not args.password:
+        raise SystemExit("--password cannot be empty")
+    if not 1 <= args.port <= 65535:
+        raise SystemExit("--port must be between 1 and 65535")
+
+    logging.basicConfig(
+        level=logging.INFO,
+        format="%(asctime)s %(levelname)s %(name)s: %(message)s",
+    )
+    app = create_app(
+        printer_uuid=args.uuid,
+        password=args.password,
+        title=args.title,
+        data_dir=args.data_dir,
+        max_upload_mb=args.max_upload_mb,
+        auto_delete_days=args.auto_delete,
+    )
+    service = app.extensions["printer_service"]
+    try:
+        app.run(host=args.host, port=args.port, threaded=True, use_reloader=False)
+    finally:
+        service.stop()
+
+
+def _printer_uuid(value: str) -> str:
+    try:
+        return str(uuid.UUID(value))
+    except ValueError:
+        raise argparse.ArgumentTypeError("must be a valid UUID") from None
+
+
+def _positive_integer(value: str) -> int:
+    try:
+        result = int(value)
+    except ValueError:
+        raise argparse.ArgumentTypeError("must be an integer") from None
+    if result <= 0:
+        raise argparse.ArgumentTypeError("must be greater than zero")
+    return result
+
+
+if __name__ == "__main__":
+    main()