py-printer-server 0.0.0__tar.gz → 0.1.0__tar.gz

py_printer_server-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.log
+dist/
+build/
+*.egg-info/
+spool/
+jobs/
+config.json
+
+# Temporary files
+SCRATCHPAD.md
+scratchpad/

py_printer_server-0.1.0/DISCLAIMER.md

@@ -0,0 +1,31 @@
+# Disclaimer
+
+py-printer-server is provided **AS IS**, without warranty of any kind, express
+or implied. **Use it entirely at your own risk.**
+
+This tool binds a network port on the machine it runs on and lets anyone who
+can log in upload files and send them to a physical printer attached to that
+machine. Used carelessly it can spend a stranger's paper and ink, expose
+uploaded files to your network, or leave a printer's settings changed if a job
+is interrupted.
+
+The author accepts no liability for data loss, data corruption, wasted
+consumables, hardware damage, unauthorised access or disclosure of files,
+business interruption, or any other direct or consequential damages arising
+from the use of this software.
+
+You are responsible for:
+
+- setting `ADMIN_PASSWORD` to a strong value; the server refuses to start
+  without it;
+- restricting the server to a network you trust (it binds all interfaces);
+- verifying the printer and paper tray before printing anything you did not
+  author yourself;
+- keeping tested backups of anything uploaded through the spool;
+- being authorised to print the files you are printing.
+
+This software is not certified for regulated, forensic, safety-critical or
+high-assurance use.
+
+`LICENSE` is the governing legal text and prevails wherever it and this
+plain-language summary differ.

py_printer_server-0.1.0/PKG-INFO

@@ -0,0 +1,126 @@
+Metadata-Version: 2.5
+Name: py-printer-server
+Version: 0.1.0
+Summary: Remote print server for a USB-connected printer. No third-party dependencies.
+Author-email: Pandiyaraj Karuppasamy <pandiyarajk@live.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: http,print-server,printer,spool,windows
+Classifier: Development Status :: 3 - Alpha
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# py-printer-server
+
+[![PyPI](https://img.shields.io/pypi/v/py-printer-server)](https://pypi.org/project/py-printer-server/)
+[![Python versions](https://img.shields.io/pypi/pyversions/py-printer-server)](https://pypi.org/project/py-printer-server/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Dependencies: none](https://img.shields.io/badge/dependencies-none-brightgreen)](pyproject.toml)
+
+Remote print server for a USB-connected printer. Python 3.11+, no third-party
+dependencies. Runs on the machine your printer is plugged into; phones and
+laptops on the same network upload files to it and print them.
+
+> **Disclaimer.** Provided **AS IS**, without warranty of any kind, express or
+> implied. **Use entirely at your own risk.** This tool binds a network port on
+> the machine it runs on and lets an authenticated user upload files and send
+> them to a physical printer attached to that machine. The author accepts no
+> liability for data loss, wasted paper or ink, hardware damage, unauthorised
+> access or disclosure, business interruption, or consequential damages. You are
+> responsible for setting a strong `ADMIN_PASSWORD` (the server refuses to start
+> without one), limiting the server to a network you trust, verifying the
+> printer and paper tray before printing, and being authorised to print the
+> files you upload. Not certified for regulated, forensic, safety-critical or
+> high-assurance use. See [DISCLAIMER.md](DISCLAIMER.md);
+> [LICENSE](LICENSE) is the governing text and prevails where the two differ.
+
+## Install
+
+```bash
+pip install py-printer-server
+```
+
+## Run
+
+```powershell
+$env:ADMIN_PASSWORD = "your-strong-password"
+py-printer-server
+```
+
+`pps` is installed as a shorter alias for the same command. No `ADMIN_PASSWORD`
+set? Get a suggestion with:
+
+```powershell
+py-printer-server --generate-password
+```
+
+The server prints its LAN URL on startup, e.g. `http://192.168.1.24:8114` --
+open that from a phone on the same Wi-Fi, log in, and upload a file.
+
+### Options
+
+```
+--port PORT        Port (default: 8114)
+--spool DIR         Spool folder for uploaded files (default: ./spool)
+--jobs DIR          Archive folder for printed jobs (default: ./jobs)
+--list-printers      List installed printers (hardware vs virtual) and exit
+--dry-run            Log what would be printed instead of sending jobs to a printer
+--generate-password  Print a strong random ADMIN_PASSWORD suggestion and exit
+```
+
+## How it works
+
+1. Upload one or more files from any device on the network -- they land in a
+   single flat spool folder. There is no folder browsing; uploading is the
+   whole interaction.
+2. Tick the files you want (or "Print all"), pick a printer, colour/mono, A4,
+   copies and duplex, and press Print.
+3. Printed files are **moved**, not deleted, into
+   `jobs\print-job-<timestamp>-<id>\`, alongside a `job.json` recording what
+   was printed and how -- so nothing needs re-uploading to print again.
+   A file that failed or could not be printed **stays in the spool** so you
+   can retry it; only successfully printed files are archived.
+
+A job is reported `done` only when every file actually printed. A mixed result
+is `partial`, and the jobs panel shows the reason next to each file that did
+not print.
+
+Only real hardware printers are shown by default (a "Show all printers"
+checkbox reveals software sinks like Microsoft Print to PDF).
+
+## Supported files
+
+| Type | Path |
+|---|---|
+| Plain text / code (`.txt .log .csv .md .py .json ...`) | Printed directly by this tool -- full control over colour, copies and duplex. |
+| PDF and images (`.pdf .png .jpg .tif .bmp .gif`) | Handed to Windows' registered handler for that file type via the shell's print verb. |
+| Office documents (`.docx .xlsx .pptx .doc .xls .ppt`) | Same shell handoff, via Word/Excel/PowerPoint. |
+
+**Colour, copies and duplex apply fully only to the text path.** PDFs, images
+and Office documents are printed by whichever application Windows has
+associated with them, and that application builds its own print settings, so
+those files follow the printer's standing defaults instead. This is a real
+limitation of printing without a bundled renderer, not a bug.
+
+## No third-party dependencies
+
+Everything, including Win32 printer access, uses only the Python standard
+library (`ctypes` bindings to `winspool.drv`/`shell32.dll`, `http.server`,
+`socketserver`). This is a deliberate choice, matching the companion project
+[py-file-server](https://pypi.org/project/py-file-server/): fewer things that
+can go missing or need a security update on a machine you may not touch again
+for a year.
+
+## Security
+
+- The server refuses to start unless `ADMIN_PASSWORD` is set.
+- Login attempts are rate-limited (5 failures locks an IP out for 5 minutes).
+- Sessions use `HttpOnly`, `SameSite=Strict` cookies with CSRF tokens on every
+  state-changing request.
+- Windows-only: printer access is unavailable on any other OS.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

py_printer_server-0.1.0/README.md

@@ -0,0 +1,112 @@
+# py-printer-server
+
+[![PyPI](https://img.shields.io/pypi/v/py-printer-server)](https://pypi.org/project/py-printer-server/)
+[![Python versions](https://img.shields.io/pypi/pyversions/py-printer-server)](https://pypi.org/project/py-printer-server/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Dependencies: none](https://img.shields.io/badge/dependencies-none-brightgreen)](pyproject.toml)
+
+Remote print server for a USB-connected printer. Python 3.11+, no third-party
+dependencies. Runs on the machine your printer is plugged into; phones and
+laptops on the same network upload files to it and print them.
+
+> **Disclaimer.** Provided **AS IS**, without warranty of any kind, express or
+> implied. **Use entirely at your own risk.** This tool binds a network port on
+> the machine it runs on and lets an authenticated user upload files and send
+> them to a physical printer attached to that machine. The author accepts no
+> liability for data loss, wasted paper or ink, hardware damage, unauthorised
+> access or disclosure, business interruption, or consequential damages. You are
+> responsible for setting a strong `ADMIN_PASSWORD` (the server refuses to start
+> without one), limiting the server to a network you trust, verifying the
+> printer and paper tray before printing, and being authorised to print the
+> files you upload. Not certified for regulated, forensic, safety-critical or
+> high-assurance use. See [DISCLAIMER.md](DISCLAIMER.md);
+> [LICENSE](LICENSE) is the governing text and prevails where the two differ.
+
+## Install
+
+```bash
+pip install py-printer-server
+```
+
+## Run
+
+```powershell
+$env:ADMIN_PASSWORD = "your-strong-password"
+py-printer-server
+```
+
+`pps` is installed as a shorter alias for the same command. No `ADMIN_PASSWORD`
+set? Get a suggestion with:
+
+```powershell
+py-printer-server --generate-password
+```
+
+The server prints its LAN URL on startup, e.g. `http://192.168.1.24:8114` --
+open that from a phone on the same Wi-Fi, log in, and upload a file.
+
+### Options
+
+```
+--port PORT        Port (default: 8114)
+--spool DIR         Spool folder for uploaded files (default: ./spool)
+--jobs DIR          Archive folder for printed jobs (default: ./jobs)
+--list-printers      List installed printers (hardware vs virtual) and exit
+--dry-run            Log what would be printed instead of sending jobs to a printer
+--generate-password  Print a strong random ADMIN_PASSWORD suggestion and exit
+```
+
+## How it works
+
+1. Upload one or more files from any device on the network -- they land in a
+   single flat spool folder. There is no folder browsing; uploading is the
+   whole interaction.
+2. Tick the files you want (or "Print all"), pick a printer, colour/mono, A4,
+   copies and duplex, and press Print.
+3. Printed files are **moved**, not deleted, into
+   `jobs\print-job-<timestamp>-<id>\`, alongside a `job.json` recording what
+   was printed and how -- so nothing needs re-uploading to print again.
+   A file that failed or could not be printed **stays in the spool** so you
+   can retry it; only successfully printed files are archived.
+
+A job is reported `done` only when every file actually printed. A mixed result
+is `partial`, and the jobs panel shows the reason next to each file that did
+not print.
+
+Only real hardware printers are shown by default (a "Show all printers"
+checkbox reveals software sinks like Microsoft Print to PDF).
+
+## Supported files
+
+| Type | Path |
+|---|---|
+| Plain text / code (`.txt .log .csv .md .py .json ...`) | Printed directly by this tool -- full control over colour, copies and duplex. |
+| PDF and images (`.pdf .png .jpg .tif .bmp .gif`) | Handed to Windows' registered handler for that file type via the shell's print verb. |
+| Office documents (`.docx .xlsx .pptx .doc .xls .ppt`) | Same shell handoff, via Word/Excel/PowerPoint. |
+
+**Colour, copies and duplex apply fully only to the text path.** PDFs, images
+and Office documents are printed by whichever application Windows has
+associated with them, and that application builds its own print settings, so
+those files follow the printer's standing defaults instead. This is a real
+limitation of printing without a bundled renderer, not a bug.
+
+## No third-party dependencies
+
+Everything, including Win32 printer access, uses only the Python standard
+library (`ctypes` bindings to `winspool.drv`/`shell32.dll`, `http.server`,
+`socketserver`). This is a deliberate choice, matching the companion project
+[py-file-server](https://pypi.org/project/py-file-server/): fewer things that
+can go missing or need a security update on a machine you may not touch again
+for a year.
+
+## Security
+
+- The server refuses to start unless `ADMIN_PASSWORD` is set.
+- Login attempts are rate-limited (5 failures locks an IP out for 5 minutes).
+- Sessions use `HttpOnly`, `SameSite=Strict` cookies with CSRF tokens on every
+  state-changing request.
+- Windows-only: printer access is unavailable on any other OS.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

py_printer_server-0.1.0/py_printer_server/__init__.py

@@ -0,0 +1,10 @@
+"""py-printer-server: remote print server for a USB-connected printer.
+
+Author: Pandiyaraj Karuppasamy
+Date: Sep-14-2026
+"""
+
+from py_printer_server.server import main
+
+__version__ = "0.1.0"
+__all__ = ["main", "__version__"]

py_printer_server-0.1.0/py_printer_server/__main__.py

@@ -0,0 +1,9 @@
+"""Entry point for `python -m py_printer_server`.
+
+Author: Pandiyaraj Karuppasamy
+Date: Sep-14-2026
+"""
+
+from py_printer_server import main
+
+raise SystemExit(main())

py_printer_server-0.1.0/py_printer_server/config.py

@@ -0,0 +1,150 @@
+"""Runtime configuration for py-printer-server.
+
+Author: Pandiyaraj Karuppasamy
+Date: Sep-14-2026
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import threading
+
+DEFAULT_CONFIG = {
+    "max_upload_mb": 100,
+    "blocked_extensions": [".exe", ".bat", ".cmd", ".ps1", ".sh"],
+    "default_printer": "",
+    "default_color": True,
+    "default_paper": "A4",
+    "default_duplex": False,
+    "default_copies": 1,
+    "show_virtual_printers": False,
+}
+
+
+class Config:
+    """
+    Runtime settings editable by the admin via the settings page.
+
+    Settings are loaded from config.json (inside the spool directory) at
+    startup and saved back on every admin update, so they survive server
+    restarts. Ported from file-share's Config class, with upload keys kept
+    and print-default keys added.
+    """
+
+    _lock = threading.Lock()
+    _config_file: str | None = None
+
+    max_upload_mb: int = DEFAULT_CONFIG["max_upload_mb"]
+    blocked_extensions: set = set(DEFAULT_CONFIG["blocked_extensions"])
+    default_printer: str = DEFAULT_CONFIG["default_printer"]
+    default_color: bool = DEFAULT_CONFIG["default_color"]
+    default_paper: str = DEFAULT_CONFIG["default_paper"]
+    default_duplex: bool = DEFAULT_CONFIG["default_duplex"]
+    default_copies: int = DEFAULT_CONFIG["default_copies"]
+    show_virtual_printers: bool = DEFAULT_CONFIG["show_virtual_printers"]
+
+    @classmethod
+    def set_config_file(cls, path: str) -> None:
+        """Point the config at a specific file (called once at startup)."""
+        cls._config_file = path
+
+    @classmethod
+    def _apply(cls, data: dict) -> None:
+        with cls._lock:
+            cls.max_upload_mb = int(data.get("max_upload_mb", DEFAULT_CONFIG["max_upload_mb"]))
+            cls.blocked_extensions = {
+                e.lower() for e in data.get("blocked_extensions", DEFAULT_CONFIG["blocked_extensions"])
+            }
+            cls.default_printer = str(data.get("default_printer", DEFAULT_CONFIG["default_printer"]))
+            cls.default_color = bool(data.get("default_color", DEFAULT_CONFIG["default_color"]))
+            cls.default_paper = str(data.get("default_paper", DEFAULT_CONFIG["default_paper"]))
+            cls.default_duplex = bool(data.get("default_duplex", DEFAULT_CONFIG["default_duplex"]))
+            cls.default_copies = max(1, int(data.get("default_copies", DEFAULT_CONFIG["default_copies"])))
+            cls.show_virtual_printers = bool(
+                data.get("show_virtual_printers", DEFAULT_CONFIG["show_virtual_printers"])
+            )
+
+    @classmethod
+    def ensure_config(cls) -> None:
+        """Create config.json with defaults if it does not exist."""
+        if cls._config_file is None or os.path.isfile(cls._config_file):
+            return
+        try:
+            with open(cls._config_file, "w", encoding="utf-8") as f:
+                json.dump(DEFAULT_CONFIG, f, indent=2)
+                f.write("\n")
+        except OSError as exc:
+            print(f"Warning: could not create {cls._config_file}: {exc}")
+
+    @classmethod
+    def load(cls) -> None:
+        """Load settings from the config file, creating it with defaults if missing."""
+        cls.ensure_config()
+        if cls._config_file is None:
+            cls._apply(DEFAULT_CONFIG)
+            return
+        try:
+            with open(cls._config_file, encoding="utf-8") as f:
+                cls._apply(json.load(f))
+        except (OSError, ValueError) as exc:
+            print(f"Warning: could not load {cls._config_file}: {exc}")
+            cls._apply(DEFAULT_CONFIG)
+
+    @classmethod
+    def save(cls) -> None:
+        """Persist current settings to the config file."""
+        if cls._config_file is None:
+            return
+        with cls._lock:
+            data = {
+                "max_upload_mb": cls.max_upload_mb,
+                "blocked_extensions": sorted(cls.blocked_extensions),
+                "default_printer": cls.default_printer,
+                "default_color": cls.default_color,
+                "default_paper": cls.default_paper,
+                "default_duplex": cls.default_duplex,
+                "default_copies": cls.default_copies,
+                "show_virtual_printers": cls.show_virtual_printers,
+            }
+        try:
+            with open(cls._config_file, "w", encoding="utf-8") as f:
+                json.dump(data, f, indent=2)
+                f.write("\n")
+        except OSError as exc:
+            print(f"Warning: could not save {cls._config_file}: {exc}")
+
+    @classmethod
+    def update(cls, **kwargs) -> None:
+        """Apply new settings and persist them immediately."""
+        with cls._lock:
+            for key, value in kwargs.items():
+                if hasattr(cls, key):
+                    setattr(cls, key, value)
+        cls.save()
+
+    # Multipart bodies carry part headers and boundaries on top of the file
+    # itself, so the body cap is the per-file cap plus a fixed allowance.
+    BODY_OVERHEAD = 1024 * 1024
+
+    @classmethod
+    def max_body_bytes(cls) -> int:
+        """Largest request body to accept, or 0 when uploads are uncapped."""
+        with cls._lock:
+            if not cls.max_upload_mb:
+                return 0
+            return cls.max_upload_mb * 1024 * 1024 + cls.BODY_OVERHEAD
+
+    @classmethod
+    def check_upload(cls, filename: str, size: int) -> str | None:
+        """
+        Validate a pending upload against current restrictions.
+        Returns an error message string if rejected, or None if allowed.
+        """
+        with cls._lock:
+            if cls.max_upload_mb and size > cls.max_upload_mb * 1024 * 1024:
+                return f"File too large (max {cls.max_upload_mb} MB)"
+            ext = os.path.splitext(filename)[1].lower()
+            if ext in cls.blocked_extensions:
+                return f"Extension '{ext}' is blocked"
+        return None

py_printer_server-0.1.0/py_printer_server/printers.py

@@ -0,0 +1,110 @@
+"""Printer discovery and the hardware/virtual split.
+
+Author: Pandiyaraj Karuppasamy
+Date: Sep-14-2026
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+from py_printer_server import winspool
+
+# Heuristic, not a hardcoded name list: OEM virtual-printer drivers vary too
+# much (PDFCreator, CutePDF, Foxit, novaPDF, ...) to enumerate exhaustively,
+# but they consistently either use a "prompt"/null/software port, or carry
+# one of these words in their driver or printer name.
+_VIRTUAL_PORT_PREFIXES = ("PORTPROMPT:", "NUL:", "SHRFAX:", "XPSPORT", "ONENOTE")
+_VIRTUAL_NAME_PATTERN = re.compile(
+    r"print to pdf|xps document writer|onenote|fax|pdfcreator|cutepdf|"
+    r"foxit.*pdf|novapdf|document writer|send to.*driver",
+    re.IGNORECASE,
+)
+# A real USB/parallel/serial/network printer reports one of these port shapes.
+_HARDWARE_PORT_PATTERN = re.compile(r"^(USB|LPT|COM|WSD-|\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})", re.IGNORECASE)
+
+
+@dataclass(frozen=True)
+class PrinterInfo:
+    name: str
+    port: str
+    driver: str
+    is_virtual: bool
+    is_default: bool
+    supports_color: bool
+
+
+def is_virtual_printer(name: str, port: str, driver: str) -> bool:
+    """Decide whether a printer is a virtual/software sink rather than
+    physical hardware, so the UI can hide "Microsoft Print to PDF" etc. by
+    default without a maintained blocklist of every OEM driver name."""
+    port_upper = (port or "").upper()
+    if any(port_upper.startswith(p) for p in _VIRTUAL_PORT_PREFIXES):
+        return True
+    if _HARDWARE_PORT_PATTERN.match(port or ""):
+        return False
+    haystack = f"{name} {driver}"
+    return bool(_VIRTUAL_NAME_PATTERN.search(haystack))
+
+
+def supports_color(name: str, port: str) -> bool:
+    """Return True if the driver reports colour capability.
+
+    Used to grey out the colour toggle for a mono-only printer rather than
+    silently ignoring the setting -- DeviceCapabilitiesW returns -1 on error,
+    which is treated as "assume colour" (the safer default: a toggle that
+    exists but has no effect is less confusing than one that is missing when
+    it should be there).
+    """
+    result = winspool.device_capabilities(name, port, winspool.DC_COLORDEVICE)
+    if result < 0:
+        return True
+    # DC_COLORDEVICE's contract is "nonzero means colour-capable", not
+    # specifically 1 -- some drivers (confirmed on an HP inkjet) return other
+    # nonzero values, so treat any nonzero as True rather than matching 1.
+    return result != 0
+
+
+def list_printers(show_virtual: bool = False) -> list[PrinterInfo]:
+    """Enumerate installed printers, hardware first, alphabetically.
+
+    Args:
+        show_virtual: include software sinks (Print to PDF, XPS, OneNote,
+            Fax, ...) in the result. Default False, matching the UI's
+            "hardware only" default.
+    """
+    buf, count = winspool.enum_printers_raw(
+        winspool.PRINTER_ENUM_LOCAL | winspool.PRINTER_ENUM_CONNECTIONS
+    )
+    raw = winspool.parse_printer_info_2w(buf, count)
+    default_name = winspool.get_default_printer()
+
+    printers = []
+    for p in raw:
+        name = p.pPrinterName or ""
+        port = p.pPortName or ""
+        driver = p.pDriverName or ""
+        if not name:
+            continue
+        virtual = is_virtual_printer(name, port, driver)
+        if virtual and not show_virtual:
+            continue
+        printers.append(
+            PrinterInfo(
+                name=name,
+                port=port,
+                driver=driver,
+                is_virtual=virtual,
+                is_default=(name == default_name),
+                supports_color=supports_color(name, port),
+            )
+        )
+
+    printers.sort(key=lambda p: (p.is_virtual, p.name.lower()))
+    return printers
+
+
+def get_default_printer_name() -> str | None:
+    """Return the system default printer's name, or None if unset."""
+    return winspool.get_default_printer()