scanloop 2026.11.11.0__py3-none-any.whl

scanloop/main.py

@@ -0,0 +1,205 @@
+#!/usr/bin/python3
+
+"""A scanner front-end to efficiently scan several multi-page documents."""
+
+import argparse
+import logging
+import os
+import re
+import shutil
+import subprocess
+import sys
+import time
+
+
+try:
+    from .version import __version__
+except Exception as ex:
+    logging.error("unable to determine version: %s", ex)
+    __version__ = "unknown"
+
+
+def command_exists(command):
+    """Returns true if the given command is available in the system."""
+    return shutil.which(command) is not None
+
+
+class ScanLoop(object):
+    """Scans documents in a loop."""
+
+    def __init__(self, quality_percent, scan_cmd,
+                 scan_format, output_format, pdf_viewer):
+        self.quality_percent = quality_percent
+        scan_cmd = scan_cmd or ScanLoop.guess_scan_command()
+        # None if no scanner was found; check_requirements reports it.
+        self.scan_command = scan_cmd.split() if scan_cmd else None
+        self.pdf_viewer = pdf_viewer # allow setting no pdf viewer
+        self.scan_format = scan_format
+        self.output_format = output_format
+
+
+    @staticmethod
+    def guess_scan_command():
+        """Attempts to guess the scan command."""
+        env_cmd = os.getenv("SCAN_CMD")
+        if env_cmd:
+            return env_cmd
+        logging.info("checking scanner availability via scanimage...")
+        if command_exists("imagescan"):
+            return "{} {}".format("imagescan", " --no-interface")
+        if command_exists("scanimage") and subprocess.call(
+                ["sudo", "scanimage", "-L"]) == 0:
+            return "sudo scanimage"
+        return None
+
+
+    @staticmethod
+    def guess_pdf_viewer():
+        """Attempts to guess the PDF viewer."""
+        for pdf_viewer in ("zathura", "evince", "gv", "open"):
+            if command_exists(pdf_viewer):
+                return pdf_viewer
+        logging.warning("no pdf viewer could be guessed")
+        return None
+
+
+    def check_requirements(self):
+        """Check all requirements are satisfied before scanning."""
+        if not command_exists("convert"):
+            raise Exception(
+                "missing imagemagick convert. hint: {apt-get,brew} install imagemagick")
+        if not self.scan_command:
+            raise Exception("no scan command detected")
+
+
+    def list_ordered_pages(self, extension=None):
+        """Lists pages in the cwd as a two-tuple: (page_num, page_fname)."""
+        if not extension:
+            extension = self.scan_format
+        return sorted(
+            (int(fname.split(".")[0]), fname)
+            for fname in os.listdir(os.getcwd())
+            if re.match("^[0-9]+[.]{}$".format(extension), fname))
+
+
+    def scan_page(self, fname_output):
+        """Scan a single page to the given output filename."""
+        logging.info("scanning page to %s. Ctrl+C to stop...", fname_output)
+        attempts = 0
+        try:
+            while True:
+                attempts += 1
+                with open(fname_output, "wb") as fh:
+                    p = subprocess.Popen(self.scan_command,
+                                         stdout=fh,
+                                         stderr=subprocess.PIPE)
+                # communicate() reads stderr while waiting; wait() alone
+                # could block forever once the stderr pipe fills up.
+                _, stderr = p.communicate()
+                if p.returncode == 0:
+                    logging.info("successfully scanned %s", fname_output)
+                    return True
+                sys.stdout.write("\rscan attempt {}. Ctrl+C to stop...".format(
+                    attempts))
+                sys.stdout.write(" " + stderr.decode().replace("\n", " "))
+                sys.stdout.flush()
+
+                time.sleep(1)
+        except KeyboardInterrupt:
+            try:
+                os.remove(fname_output)
+            except FileNotFoundError:
+                pass
+            return False
+
+
+    def merge_pages(self, output):
+        """Merge multiple page scans into a single output file."""
+        for (_, pnm) in self.list_ordered_pages(extension=self.scan_format):
+            # need intermediate jpg conversion to enforce "-quality" space savings
+            jpg = "{}.jpg".format(pnm.split(".")[0])
+            cmd = ["convert", pnm, "-quality", str(self.quality_percent), jpg]
+            ret = subprocess.call(cmd)
+            if ret != 0:
+                raise Exception("non-zero exit status: {} of {}".format(
+                    ret, " ".join(cmd)))
+
+        cmd = (["convert"] +
+               [fname for (_, fname) in self.list_ordered_pages(extension="jpg")] +
+               [output])
+        logging.info("convert command: %s", " ".join(cmd))
+        ret = subprocess.call(cmd)
+        if ret != 0:
+            raise Exception("non-zero exit status: {} of {}".format(
+                ret, " ".join(cmd)))
+        if self.pdf_viewer:
+            subprocess.call([self.pdf_viewer, output])
+
+    def scan_doc(self, doc_name):
+        """Create a scan of a doc containing one or more pages."""
+        pages = self.list_ordered_pages()
+        page_no = pages[-1][0] + 1 if pages else 1
+        while True:
+            page = "{}.{}".format(page_no, self.scan_format)
+            expect_more_pages = self.scan_page(page)
+            if expect_more_pages:
+                page_no += 1
+            else:
+                break
+        if not self.list_ordered_pages():
+            logging.error("no pages scanned.")
+            return
+        output = "{}.{}".format(doc_name, self.output_format)
+        self.merge_pages(output)
+        logging.info("successfully merged pages to %s", output)
+
+    def start(self):
+        """Scan documents indefinitely."""
+        orig_dir = os.getcwd()
+        while True:
+            os.chdir(orig_dir)
+            try:
+                doc_name = input("enter new doc name, q to quit: ")
+            except EOFError:
+                # Ctrl+D quits too
+                break
+            if doc_name == "q":
+                break
+            if not doc_name:
+                continue
+            assert "/" not in doc_name, "invalid filename"
+            try:
+                os.mkdir(doc_name)
+            except FileExistsError:
+                pass
+            os.chdir(doc_name)
+            self.scan_doc(doc_name)
+
+def main():
+    """Main."""
+    logging.root.setLevel(logging.INFO)
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--quality-percent",
+                        help="The imagemagick -quality of merged document.",
+                        default=30)
+    parser.add_argument("--scan-cmd",
+                        help="command used to scan a single page to stdout.")
+    parser.add_argument("--scan-format", default="pnm",
+                        help="The file-format extension of the scan command output.")
+    parser.add_argument("--output-format", default="pdf",
+                        help="The file-format extension of the merged document.")
+    parser.add_argument("--pdf-viewer", help="Command to open the output files.",
+                        default=ScanLoop.guess_pdf_viewer())
+    parser.add_argument("--version", action="version", version=__version__)
+
+
+    args = vars(parser.parse_args())
+
+    logging.info("version: %s", __version__)
+
+    scan_loop = ScanLoop(**args)
+    scan_loop.check_requirements()
+    scan_loop.start()
+
+if __name__ == "__main__":
+    main()

scanloop/version.py

@@ -0,0 +1 @@
+__version__ = "2026.11.11.0"

scanloop-2026.11.11.0.dist-info/METADATA

@@ -0,0 +1,48 @@
+Metadata-Version: 2.4
+Name: scanloop
+Version: 2026.11.11.0
+Summary: A scanner front-end to efficiently scan several multi-page documents.
+Author-email: Ernesto Alfonso <erjoalgo@gmail.com>
+License-Expression: GPL-3.0-or-later
+Project-URL: Homepage, https://github.com/erjoalgo/scanloop
+Project-URL: Repository, https://github.com/erjoalgo/scanloop
+Project-URL: Bug Tracker, https://github.com/erjoalgo/scanloop/issues
+Keywords: scanner,imagemagick
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Topic :: Multimedia :: Graphics :: Capture :: Scanners
+Classifier: Topic :: Utilities
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+A scanner front-end to efficiently scan several multi-page documents.
+
+For each document, enter a name, then feed pages to the scanner one at a time.
+scanloop keeps scanning a page whenever the scanner is ready; press Ctrl+C when
+the document is done. The pages are merged into `NAME/NAME.pdf`, which opens
+in a PDF viewer, and scanloop asks for the next document's name (`q` to quit).
+
+Requirements:
+
+- A scan command that writes one page to stdout: `scanimage` (from SANE,
+  `$ sudo apt install sane-utils`) or Epson's `imagescan` are detected
+  automatically. scanimage is run with sudo. To use another, pass `--scan-cmd`
+  or set `SCAN_CMD`.
+- ImageMagick's `convert` (`$ sudo apt install imagemagick`). On Debian and
+  Ubuntu, ImageMagick's default security policy blocks writing PDFs; to allow
+  it, remove or comment out the `pattern="PDF"` line in
+  `/etc/ImageMagick-6/policy.xml`.
+
+To install:
+
+`$ pip install scanloop`
+
+To run:
+
+`$ scanloop`
+
+See `scanloop --help` for options, such as the output quality and format.

scanloop-2026.11.11.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+scanloop/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+scanloop/main.py,sha256=EYsIUlGWWOEA7UIXS_b6cZ1s20-LzrLhrlhLqOhkQnk,7382
+scanloop/version.py,sha256=oxvJO6m4HZ26FmsIBz71bZe0nyAyGoFagBVWCymoqXM,29
+scanloop-2026.11.11.0.dist-info/METADATA,sha256=7-wdjXKjQbcSx07bULbvOJH2Ub8haVJcvLVktGqeMOU,1919
+scanloop-2026.11.11.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+scanloop-2026.11.11.0.dist-info/entry_points.txt,sha256=pMTjlsQGn0wOLuvefygaa2OJvgmKhRbmfq0conVJOdA,48
+scanloop-2026.11.11.0.dist-info/top_level.txt,sha256=Ez79TO6DEDa7GxyFiWAQjA1fcN2U9-EvblXZ2ljjsho,9
+scanloop-2026.11.11.0.dist-info/RECORD,,

scanloop-2026.11.11.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

scanloop-2026.11.11.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+scanloop = scanloop.main:main

scanloop-2026.11.11.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+scanloop