scanlib 1.3.0__tar.gz → 1.3.1__tar.gz

{scanlib-1.3.0/src/scanlib.egg-info → scanlib-1.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: scanlib
-Version: 1.3.0
+Version: 1.3.1
 Summary: A multiplatform document scanning library for Python
 Author-email: Angelo Mottola <a.mottola@gmail.com>
 License: MIT

{scanlib-1.3.0 → scanlib-1.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "scanlib"
-version = "1.3.0"
+version = "1.3.1"
 description = "A multiplatform document scanning library for Python"
 readme = "README.md"
 license = {text = "MIT"}

{scanlib-1.3.0 → scanlib-1.3.1}/src/scanlib/__init__.py

@@ -26,6 +26,7 @@ from ._types import (
     ScannerBusyError,
     ScannerDefaults,
     ScannerNotOpenError,
+    ScannerUnavailableError,
     ScanOptions,
     ScanSource,
     ScannedDocument,
@@ -54,6 +55,7 @@ __all__ = [
     "ScanError",
     "ScanAborted",
     "ScannerBusyError",
+    "ScannerUnavailableError",
     "FeederEmptyError",
     "NoScannerFoundError",
     "BackendNotAvailableError",

{scanlib-1.3.0 → scanlib-1.3.1}/src/scanlib/_types.py

@@ -47,6 +47,24 @@ class ScannerBusyError(ScanError):
         super().__init__(message)
 
 
+class ScannerUnavailableError(ScanError):
+    """The scanner could not be reached (offline, asleep, or disconnected).
+
+    Unlike :class:`ScannerBusyError`, the device is not held by another
+    session — it simply did not respond.  This is often transient (a network
+    scanner that has gone to sleep) and worth retrying once the device is
+    reachable again.
+    """
+
+    _DEFAULT = (
+        "Scanner is unavailable — it may be offline, asleep, or disconnected. "
+        "Check that it is powered on and reachable, then try again."
+    )
+
+    def __init__(self, message: str = _DEFAULT) -> None:
+        super().__init__(message)
+
+
 class ScannerNotOpenError(ScanLibError):
     """Operation requires an open scanner session."""
 

{scanlib-1.3.0 → scanlib-1.3.1}/src/scanlib/backends/_escl.py

@@ -27,14 +27,17 @@ from collections.abc import Iterator
 from urllib.parse import urlparse
 
 from .._jpeg import decode_jpeg
-from .._mdns import EsclServiceInfo, discover_escl_services, extract_ip_from_uri
+from .._mdns import discover_escl_services
 from .._types import (
     DISCOVERY_TIMEOUT,
     ColorMode,
+    FeederEmptyError,
     ScanAborted,
     ScanArea,
     ScanError,
+    ScanLibError,
     ScannerBusyError,
+    ScannerUnavailableError,
     ScannedPage,
     Scanner,
     ScannerDefaults,
@@ -156,6 +159,26 @@ class _EsclConnection:
             state_el = root.find(_ns(_SCAN_NS, "State"))
         return state_el.text if state_el is not None and state_el.text else "Unknown"
 
+    def get_adf_state(self) -> str | None:
+        """Return the feeder (ADF) state from ScannerStatus, or ``None``.
+
+        eSCL reports ``<scan:AdfState>`` as e.g. ``ScannerAdfProcessing``,
+        ``ScannerAdfLoaded``, or ``ScannerAdfEmpty``.  Returns ``None`` when
+        the scanner doesn't report it (best-effort — not all models do).
+        """
+        conn = self._connect()
+        conn.request("GET", f"{self.base_path}/ScannerStatus")
+        resp = conn.getresponse()
+        body = resp.read()
+        if resp.status != 200:
+            return None
+        try:
+            root = ET.fromstring(body)
+        except ET.ParseError:
+            return None
+        el = next(root.iter(_ns(_SCAN_NS, "AdfState")), None)
+        return el.text.strip() if el is not None and el.text else None
+
     def cancel_active_jobs(self) -> int:
         """Cancel any active jobs on the scanner. Returns count cancelled."""
         conn = self._connect()
@@ -186,7 +209,6 @@ class _EsclConnection:
         """
         import time
 
-        last_status = 0
         for attempt in range(retries):
             conn = self._connect()
             conn.request(
@@ -197,7 +219,6 @@ class _EsclConnection:
             )
             resp = conn.getresponse()
             resp.read()  # drain body
-            last_status = resp.status
             if resp.status in (409, 503):
                 if attempt < retries - 1:
                     # Try cancelling any stale jobs before retrying
@@ -570,11 +591,10 @@ def _decode_png(data: bytes) -> tuple[bytes, int, int, int]:
         raise ValueError(f"Unsupported PNG color type: {color_type}")
 
     row_bytes = width * components
-    # Remove filter byte from each row
+    # Skip the per-row filter byte (decoder assumes filter type 0 / None).
     pixels = bytearray()
     for y in range(height):
         offset = y * (row_bytes + 1)
-        _filter_byte = raw_filtered[offset]
         pixels.extend(raw_filtered[offset + 1 : offset + 1 + row_bytes])
 
     return bytes(pixels), width, height, components
@@ -732,6 +752,17 @@ class EsclBackend:
 
         try:
             caps_xml = conn.get_capabilities()
+        except ScanLibError:
+            # Already a typed scanlib error (busy/unavailable/…) — preserve it.
+            raise
+        except OSError as exc:
+            # Socket-level failure: host unreachable, connection refused, or
+            # timed out — the scanner is offline, asleep, or disconnected.
+            raise ScannerUnavailableError(
+                f"Scanner at {conn.ip}:{conn.port} is unavailable — it may be "
+                "offline, asleep, or disconnected. Check that it is powered on "
+                "and reachable, then try again."
+            ) from exc
         except Exception as exc:
             raise ScanError(f"Failed to get scanner capabilities: {exc}") from exc
 
@@ -769,6 +800,16 @@ class EsclBackend:
 
         check_progress(options.progress, 0)
 
+        # For the feeder, check the ADF state before creating a job.  A
+        # scanner asked to scan from an empty feeder would otherwise
+        # physically engage the ADF and, on some models, keep producing
+        # (blank) pages instead of cleanly reporting "no documents".  This
+        # is best-effort: only an explicit "empty" report short-circuits;
+        # scanners that don't report AdfState fall through to the job (and
+        # the page_num == 0 check below still catches an empty feeder).
+        if is_feeder and conn.get_adf_state() == "ScannerAdfEmpty":
+            raise FeederEmptyError("No documents in feeder")
+
         try:
             job_path = conn.create_job(settings_xml)
         except ScanError:
@@ -812,6 +853,14 @@ class EsclBackend:
                 if not is_feeder:
                     break  # flatbed: one page per job
 
+            if page_num == 0:
+                # A feeder job that produced nothing means the feeder was
+                # empty; a flatbed job with no data is a scan failure.  Match
+                # the SANE/macOS/WIA backends rather than yielding nothing.
+                if is_feeder:
+                    raise FeederEmptyError("No documents in feeder")
+                raise ScanError("Scan completed but no image data was received")
+
         except (ScanAborted, ScanError):
             conn.delete_job(job_path)
             raise

{scanlib-1.3.0 → scanlib-1.3.1}/src/scanlib/backends/_macos.py

@@ -24,6 +24,7 @@ from .._types import (
     ScanAborted,
     ScanError,
     ScannerBusyError,
+    ScannerUnavailableError,
     ScannedPage,
     Scanner,
     ScannerDefaults,
@@ -51,12 +52,38 @@ _COLOR_MODE_TO_PIXEL_DATA_TYPE = {
 # ICScannerTransferMode
 _TRANSFER_MODE_MEMORY_BASED = 1
 
-# NSError codes (in the com.apple.imagecapture domain) that mean the device is
-# already in use by another session/application and cannot be opened.  -47 is
-# the classic macOS ``fBsyErr`` (resource busy), which is what real network
-# scanners (e.g. Brother) return when another app holds the session; the
-# -9924/-9925 ICReturn codes are the documented in-use values.
-_BUSY_ERROR_CODES = frozenset({-47, -9924, -9925})
+# ImageCaptureCore status codes (signed 32-bit), from ICReturnCodes.h.  All
+# error classification is done by code, never by parsing the (localised,
+# vendor-specific) NSError message string.
+_FBSY_ERR = -47  # classic macOS fBsyErr (resource busy)
+_IC_SCAN_OPERATION_CANCELED = -9924  # ICReturnScanOperationCanceled
+_IC_SCANNER_IN_USE_BY_LOCAL_USER = -9925  # ICReturnScannerInUseByLocalUser
+_IC_SCANNER_IN_USE_BY_REMOTE_USER = -9926  # ICReturnScannerInUseByRemoteUser
+# Legacy ICLegacyReturnCode* communication-layer failures.
+_IC_LEGACY_COMMUNICATION_ERR = -9900  # ICLegacyReturnCodeCommunicationErr
+_IC_LEGACY_DEVICE_NOT_FOUND_ERR = -9901  # ICLegacyReturnCodeDeviceNotFoundErr
+_IC_LEGACY_DEVICE_NOT_OPEN_ERR = -9902  # ICLegacyReturnCodeDeviceNotOpenErr
+
+# Device is already in use by another session/application and cannot be opened.
+# -47 is what real network scanners (e.g. Brother) return when another app holds
+# the session; -9925/-9926 are ImageCaptureCore's documented in-use values.
+_BUSY_ERROR_CODES = frozenset(
+    {_FBSY_ERR, _IC_SCANNER_IN_USE_BY_LOCAL_USER, _IC_SCANNER_IN_USE_BY_REMOTE_USER}
+)
+
+# The device object exists (it was discovered) but the hardware can't be
+# reached — offline, asleep, or disconnected.  Distinct from busy: the device
+# isn't held by anyone, it just didn't answer.
+_UNAVAILABLE_ERROR_CODES = frozenset(
+    {
+        _IC_LEGACY_COMMUNICATION_ERR,
+        _IC_LEGACY_DEVICE_NOT_FOUND_ERR,
+        _IC_LEGACY_DEVICE_NOT_OPEN_ERR,
+    }
+)
+
+# Scan was cancelled (by the user at the device, or programmatically).
+_CANCEL_ERROR_CODES = frozenset({_IC_SCAN_OPERATION_CANCELED})
 
 
 def _normalize_error_code(code: int | None) -> int | None:
@@ -74,6 +101,14 @@ def _normalize_error_code(code: int | None) -> int | None:
     return code
 
 
+def _error_code(error) -> int | None:
+    """Return the normalized signed status code of an NSError, or None."""
+    try:
+        return _normalize_error_code(int(error.code()))
+    except Exception:
+        return None
+
+
 def pump_run_loop(duration: float) -> None:
     """Run the current thread's run loop for up to *duration* seconds.
 
@@ -197,10 +232,7 @@ class _ScanDelegate(NSObject):
     def device_didOpenSessionWithError_(self, device, error):
         if error:
             self.error = str(error)
-            try:
-                self.error_code = _normalize_error_code(int(error.code()))
-            except Exception:
-                self.error_code = None
+            self.error_code = _error_code(error)
         else:
             self.session_open = True
         self._open_event.set()
@@ -238,6 +270,7 @@ class _ScanDelegate(NSObject):
     def scannerDevice_didCompleteScanWithError_(self, device, error):
         if error:
             self.error = str(error)
+            self.error_code = _error_code(error)
         self._scan_done.set()
 
     def device_didCloseSessionWithError_(self, device, error):
@@ -439,6 +472,34 @@ def _safe_str(dev, attr: str) -> str | None:
         return None
 
 
+def _name_and_location(dev) -> tuple[str | None, str | None]:
+    """Compute the (display name, location) pair for an ICDevice.
+
+    ImageCaptureCore's ``locationDescription`` is *not* a physical location
+    for network scanners: over TCP/IP it returns the device's Bonjour name —
+    the label macOS itself shows (e.g. ``"PLC"``, ``"Piano 1°"``) — while
+    ``name`` is only the generic model series (e.g. ``"EPSON … Series"``).
+    So for network devices the location string is really the display name;
+    surface it as such and leave ``location`` unset rather than echoing the
+    same value in both fields.
+
+    For USB/FireWire/etc. devices ``locationDescription`` is the standard bus
+    descriptor (``"USB"``, …) — a genuine location — so keep it as the
+    location and use the device name as the display name.
+    """
+    name = _safe_str(dev, "name")
+    loc = _safe_str(dev, "locationDescription")
+    try:
+        transport = dev.transportType()
+    except Exception:
+        transport = None
+    if transport is not None and transport == ImageCaptureCore.ICTransportTypeTCPIP:
+        # Bonjour name: the OS-displayed name, not a location.
+        return (loc or name), None
+    # Bus-attached device: locationDescription is the bus type.
+    return name, (loc if loc and loc != name else None)
+
+
 class MacOSBackend:
     backend_name = "imagecapture"
     """macOS scanning backend using ImageCaptureCore.
@@ -627,27 +688,24 @@ class MacOSBackend:
                 if uid not in self._devices:
                     self._devices[uid] = dev
 
-            def _location(dev):
-                # ImageCaptureCore echoes the device name as the location
-                # description when no real location is set — treat that as
-                # "no location" rather than surfacing a redundant string.
-                loc = _safe_str(dev, "locationDescription")
-                return loc if loc and loc != dev.name() else None
-
-            return [
-                Scanner(
-                    name=dev.name(),
-                    vendor=_safe_str(dev, "manufacturer"),
-                    model=None,
-                    backend=self.backend_name,
-                    scanner_id=_safe_str(dev, "UUIDString") or dev.name(),
-                    uuid=_safe_str(dev, "UUIDString") or None,
-                    location=_location(dev),
-                    # Image Capture shows the device name verbatim.
-                    display_name=dev.name(),
+            scanners = []
+            for dev in delegate.scanners:
+                display_name, location = _name_and_location(dev)
+                scanners.append(
+                    Scanner(
+                        name=dev.name(),
+                        vendor=_safe_str(dev, "manufacturer"),
+                        model=None,
+                        backend=self.backend_name,
+                        scanner_id=_safe_str(dev, "UUIDString") or dev.name(),
+                        uuid=_safe_str(dev, "UUIDString") or None,
+                        location=location,
+                        # The label Image Capture shows (Bonjour name for
+                        # network scanners, device name otherwise).
+                        display_name=display_name,
+                    )
                 )
-                for dev in delegate.scanners
-            ]
+            return scanners
 
         return self._on_main(_build_list)
 
@@ -691,6 +749,12 @@ class MacOSBackend:
                     "or host (e.g. Image Capture, Preview, or a vendor tool). "
                     "Close it and try again."
                 )
+            if last_error_code in _UNAVAILABLE_ERROR_CODES:
+                raise ScannerUnavailableError(
+                    f"Scanner {scanner.name!r} is unavailable — it may be "
+                    "offline, asleep, or disconnected. Check that it is powered "
+                    "on and reachable, then try again."
+                )
             raise ScanError(f"Failed to open device session: {last_error}")
 
         if scan_delegate is None or not scan_delegate.session_open:
@@ -885,65 +949,9 @@ class MacOSBackend:
             time.sleep(0.5)
 
             is_feeder = options.source == ScanSource.FEEDER
-            all_pages: list[ScannedPage] = []
-
-            while True:
-                scan_delegate._scan_done.clear()
-                scan_delegate.error = None
-                scan_delegate.completed_pages = []
-                scan_delegate._current_bands = []
-                scan_delegate._rows_received = 0
-                scan_delegate._last_pct = 0
-                scan_delegate._aborted = False
-                scan_delegate._expected_height = expected_height
-                scan_delegate._progress = options.progress
-
-                check_progress(options.progress, -1)
-
-                self._on_main(device.requestScan)
-
-                # Poll with short timeouts so scanner.abort() is responsive.
-                while not scan_delegate._scan_done.wait(timeout=0.25):
-                    if scanner._abort_event.is_set():
-                        self._on_main(device.cancelScan)
-                        raise ScanAborted("Scan aborted")
-
-                if scan_delegate._aborted:
-                    self._on_main(device.cancelScan)
-                    raise ScanAborted("Scan aborted by user")
-
-                if scan_delegate.error:
-                    err_lower = scan_delegate.error.lower()
-                    if "cancel" in err_lower or "abort" in err_lower:
-                        raise ScanAborted(
-                            f"Scan cancelled by device: {scan_delegate.error}"
-                        )
-                    raise ScanError(f"Scan failed: {scan_delegate.error}")
-
-                # Flush the last (or only) page
-                if scan_delegate._current_bands:
-                    scan_delegate._finish_page()
-
-                if not scan_delegate.completed_pages:
-                    if is_feeder:
-                        raise FeederEmptyError("No documents in feeder")
-                    raise ScanError("Scan completed but no image data was received")
-
-                for bands, w, h, bpc, nc, pdt in scan_delegate.completed_pages:
-                    raw, width, height, mode = _assemble_image(
-                        bands, w, h, bpc, nc, pdt
-                    )
-                    all_pages.append(
-                        ScannedPage(
-                            data=raw,
-                            width=width,
-                            height=height,
-                            color_mode=mode,
-                        )
-                    )
-
-                if not is_feeder:
-                    break
+            all_pages = self._collect_scan_rounds(
+                scanner, device, scan_delegate, options, is_feeder, expected_height
+            )
 
             check_progress(options.progress, 100)
             return all_pages
@@ -951,3 +959,96 @@ class MacOSBackend:
             raise
         except Exception as exc:
             raise ScanError(f"Scan failed: {exc}") from exc
+
+    def _collect_scan_rounds(
+        self,
+        scanner: Scanner,
+        device,
+        scan_delegate,
+        options: ScanOptions,
+        is_feeder: bool,
+        expected_height: int,
+    ) -> list[ScannedPage]:
+        """Drive ``requestScan`` rounds and gather the resulting pages.
+
+        A flatbed scan runs exactly one round.  A feeder keeps scanning until
+        a round yields no page: ImageCaptureCore signals the end of the stack
+        with an empty pass — or, on some devices, a "no documents in feeder"
+        completion error.  Either way that is the normal terminator once at
+        least one page has been collected, so the run stops and returns the
+        pages instead of surfacing the condition as an error.  Only an empty
+        *first* round means the feeder was genuinely empty.
+        """
+        all_pages: list[ScannedPage] = []
+
+        while True:
+            scan_delegate._scan_done.clear()
+            scan_delegate.error = None
+            scan_delegate.error_code = None
+            scan_delegate.completed_pages = []
+            scan_delegate._current_bands = []
+            scan_delegate._rows_received = 0
+            scan_delegate._last_pct = 0
+            scan_delegate._aborted = False
+            scan_delegate._expected_height = expected_height
+            scan_delegate._progress = options.progress
+
+            check_progress(options.progress, -1)
+
+            self._on_main(device.requestScan)
+
+            # Poll with short timeouts so scanner.abort() is responsive.
+            while not scan_delegate._scan_done.wait(timeout=0.25):
+                if scanner._abort_event.is_set():
+                    self._on_main(device.cancelScan)
+                    raise ScanAborted("Scan aborted")
+
+            if scan_delegate._aborted:
+                self._on_main(device.cancelScan)
+                raise ScanAborted("Scan aborted by user")
+
+            # Flush the last (or only) page and collect this round's pages
+            # *before* interpreting any completion error: a feeder's final
+            # pass can deliver a sheet and then report "no documents".
+            if scan_delegate._current_bands:
+                scan_delegate._finish_page()
+
+            new_pages = list(scan_delegate.completed_pages)
+            for bands, w, h, bpc, nc, pdt in new_pages:
+                raw, width, height, mode = _assemble_image(bands, w, h, bpc, nc, pdt)
+                all_pages.append(
+                    ScannedPage(
+                        data=raw,
+                        width=width,
+                        height=height,
+                        color_mode=mode,
+                    )
+                )
+
+            if scan_delegate.error:
+                if scan_delegate.error_code in _CANCEL_ERROR_CODES:
+                    raise ScanAborted(
+                        f"Scan cancelled by device: {scan_delegate.error}"
+                    )
+                # ImageCaptureCore has no "feeder empty" code, so the pass
+                # after the last sheet surfaces as a generic, vendor-specific
+                # scanner error.  Once we've collected at least one page that
+                # is the normal end-of-feeder signal, not a failure — stop and
+                # return what we scanned instead of discarding it.
+                if is_feeder and all_pages:
+                    break
+                raise ScanError(f"Scan failed: {scan_delegate.error}")
+
+            if not new_pages:
+                # An empty pass ends a feeder run once pages exist; otherwise
+                # the feeder was empty to begin with.
+                if is_feeder:
+                    if all_pages:
+                        break
+                    raise FeederEmptyError("No documents in feeder")
+                raise ScanError("Scan completed but no image data was received")
+
+            if not is_feeder:
+                break
+
+        return all_pages

{scanlib-1.3.0 → scanlib-1.3.1}/src/scanlib/backends/_sane.py

@@ -20,7 +20,9 @@ from .._types import (
     ScanArea,
     ScanAborted,
     ScanError,
+    ScanLibError,
     ScannerBusyError,
+    ScannerUnavailableError,
     ScannedPage,
     Scanner,
     ScannerDefaults,
@@ -219,15 +221,38 @@ if _lib is not None:
 # ---------------------------------------------------------------------------
 
 
+def _status_message(status: int, context: str = "") -> str:
+    """Format a human-readable message for a ``SANE_Status`` code."""
+    name = _STATUS_NAMES.get(status, f"unknown ({status})")
+    msg = f"SANE error: {name}"
+    if context:
+        msg = f"{context}: {msg}"
+    return msg
+
+
+def _status_error(status: int, context: str = "") -> ScanError:
+    """Build a :class:`ScanError` for *status*, tagged with ``.sane_status``.
+
+    Callers classify the failure by the numeric ``SANE_Status`` code on the
+    exception rather than by parsing the message text.
+    """
+    err = ScanError(_status_message(status, context))
+    err.sane_status = status
+    return err
+
+
 def _check_status(status: int, context: str = "") -> None:
     if status != _STATUS_GOOD:
-        name = _STATUS_NAMES.get(status, f"unknown ({status})")
-        msg = f"SANE error: {name}"
-        if context:
-            msg = f"{context}: {msg}"
         if status == _STATUS_DEVICE_BUSY:
             raise ScannerBusyError()
-        raise ScanError(msg)
+        if status == _STATUS_IO_ERROR:
+            # I/O error means communication with the device failed — it is
+            # offline, asleep, or disconnected, not held by another session.
+            raise ScannerUnavailableError(
+                f"{_status_message(status, context)} — the scanner may be "
+                "offline, asleep, or disconnected."
+            )
+        raise _status_error(status, context)
 
 
 def _ensure_lib() -> None:
@@ -723,8 +748,7 @@ def _scan_one_page(dev: _SaneDevice, progress=None) -> ScannedPage:
     if status != _STATUS_GOOD:
         if status == _STATUS_DEVICE_BUSY:
             raise ScannerBusyError()
-        name = _STATUS_NAMES.get(status, f"unknown ({status})")
-        raise ScanError(f"sane_start: {name}")
+        raise _status_error(status, "sane_start")
 
     params = dev.get_parameters()
     width = params.pixels_per_line
@@ -752,8 +776,7 @@ def _scan_one_page(dev: _SaneDevice, progress=None) -> ScannedPage:
             # instead of EOF once all data has been delivered.
             break
         if st != _STATUS_GOOD:
-            name = _STATUS_NAMES.get(st, f"unknown ({st})")
-            raise ScanError(f"sane_read: {name}")
+            raise _status_error(st, "sane_read")
 
     raw = b"".join(chunks)
 
@@ -872,6 +895,9 @@ class SaneBackend:
     def open_scanner(self, scanner: Scanner) -> None:
         try:
             dev = _open_device(scanner.name)
+        except ScanLibError:
+            # Already a typed scanlib error (busy/unavailable/…) — preserve it.
+            raise
         except Exception as exc:
             raise ScanError(f"Failed to open scanner {scanner.name!r}: {exc}") from exc
         self._handles[scanner.name] = dev
@@ -983,10 +1009,11 @@ class SaneBackend:
                     scan_started = True
                     page = _scan_one_page(dev, progress=options.progress)
                 except ScanError as exc:
-                    msg = str(exc).lower()
-                    if is_feeder and ("no docs" in msg or "eof" in msg):
+                    status = getattr(exc, "sane_status", None)
+                    # End of an automatic feeder run: no more documents / EOF.
+                    if is_feeder and status in (_STATUS_NO_DOCS, _STATUS_EOF):
                         break
-                    if "cancel" in msg or "jammed" in msg:
+                    if status in (_STATUS_CANCELLED, _STATUS_JAMMED):
                         raise ScanAborted(f"Scan cancelled by device: {exc}") from exc
                     raise
 

{scanlib-1.3.0 → scanlib-1.3.1}/src/scanlib/backends/_wia.py

@@ -66,6 +66,7 @@ from .._types import (
     ScanAborted,
     ScanError,
     ScannerBusyError,
+    ScannerUnavailableError,
     ScannedPage,
     Scanner,
     ScannerDefaults,
@@ -115,11 +116,28 @@ _FEEDER = 2
 
 _WIA_FORMAT_BMP = GUID("{B96B3CAB-0728-11D3-9D7B-0000F81EF32E}")
 
+# WIA item categories (wiadef.h).  A WIA 2.0 scanner exposes one child
+# item per source; scanning the *wrong* item (e.g. the flatbed item with
+# the feeder selected) makes some drivers scan blank pages from an empty
+# feeder forever instead of reporting WIA_ERROR_PAPER_EMPTY.
+_WIA_CATEGORY_FLATBED = GUID("{FB607B1F-43F3-488B-855B-FB703EC342A6}")
+_WIA_CATEGORY_FEEDER = GUID("{FE131934-F84C-42AD-8DA4-6129CDDD7288}")
+
 _WIA_ERROR_PAPER_EMPTY = -2145320957  # 0x80210003
 # HRESULTs that mean the device is in use / unavailable to this session.
 _WIA_ERROR_BUSY = -2145320954  # 0x80210006
 _WIA_ERROR_DEVICE_LOCKED = -2145320947  # 0x8021000D
 _WIA_BUSY_ERRORS = frozenset({_WIA_ERROR_BUSY, _WIA_ERROR_DEVICE_LOCKED})
+# HRESULTs that mean the device couldn't be reached — offline, asleep, or
+# disconnected — rather than held by another session.
+_WIA_ERROR_OFFLINE = -2145320955  # 0x80210005
+_WIA_ERROR_DEVICE_COMM = -2145320950  # 0x8021000A (DEVICE_COMMUNICATION)
+_WIA_UNAVAILABLE_ERRORS = frozenset({_WIA_ERROR_OFFLINE, _WIA_ERROR_DEVICE_COMM})
+# Generic Windows cancellation HRESULTs (a device-initiated cancel; a
+# caller-initiated abort is detected separately via the callback).
+_E_ABORT = -2147467260  # 0x80004004
+_WIA_ERROR_CANCELLED = -2147023673  # 0x800704C7 HRESULT_FROM_WIN32(ERROR_CANCELLED)
+_WIA_CANCEL_ERRORS = frozenset({_E_ABORT, _WIA_ERROR_CANCELLED})
 
 # Property attribute flags (from WiaDef.h)
 _WIA_PROP_RANGE = 0x10
@@ -780,6 +798,42 @@ def _read_wia_color_modes(storage) -> list[ColorMode]:
     return []
 
 
+def _enum_scan_items(root_item):
+    """Map scan sources to their dedicated WIA child items.
+
+    Returns ``(child_map, default_child)`` where *child_map* maps
+    :class:`ScanSource` to the child item whose WIA category matches that
+    source, and *default_child* is the first child item (a fallback for
+    scanners that expose a single generic item).  Scanning a source through
+    its own child item is what makes the driver report
+    ``WIA_ERROR_PAPER_EMPTY`` for an empty feeder instead of scanning blanks.
+    """
+    child_map: dict[ScanSource, object] = {}
+    default_child = None
+    try:
+        enum_items = root_item.EnumChildItems(None)
+    except Exception:
+        return child_map, default_child
+    while True:
+        try:
+            child, fetched = enum_items.Next(1)
+        except Exception:
+            break
+        if not fetched:
+            break
+        if default_child is None:
+            default_child = child
+        try:
+            category = child.GetItemCategory()
+        except Exception:
+            continue
+        if category == _WIA_CATEGORY_FEEDER:
+            child_map[ScanSource.FEEDER] = child
+        elif category == _WIA_CATEGORY_FLATBED:
+            child_map[ScanSource.FLATBED] = child
+    return child_map, default_child
+
+
 def _read_wia_sources(storage) -> list[ScanSource]:
     """Determine available scan sources from device capabilities."""
     caps = _read_prop(storage, _WIA_DPS_DOCUMENT_HANDLING_CAPABILITIES, 0)
@@ -1149,8 +1203,15 @@ class WiaBackend:
             dm = self._create_device_manager()
             root_item = dm.CreateDevice(0, scanner.id)
         except Exception as exc:
-            if getattr(exc, "hresult", None) in _WIA_BUSY_ERRORS:
+            hr = getattr(exc, "hresult", None)
+            if hr in _WIA_BUSY_ERRORS:
                 raise ScannerBusyError() from exc
+            if hr in _WIA_UNAVAILABLE_ERRORS:
+                raise ScannerUnavailableError(
+                    f"Scanner {scanner.id!r} is unavailable — it may be "
+                    "offline, asleep, or disconnected. Check that it is powered "
+                    "on and reachable, then try again."
+                ) from exc
             raise ScanError(f"Failed to open scanner {scanner.id!r}: {exc}") from exc
 
         # Read device-level properties from root item
@@ -1165,46 +1226,31 @@ class WiaBackend:
         if not source_types:
             source_types = [ScanSource.FLATBED]
 
-        # Get first child item for item-level properties
-        child_item = None
-        try:
-            enum_items = root_item.EnumChildItems(None)
-            child, fetched = enum_items.Next(1)
-            if fetched:
-                child_item = child
-        except Exception:
-            pass
+        # Map each source to its dedicated child item (Flatbed/Feeder),
+        # falling back to the first item for single-item scanners.
+        child_map, default_child = _enum_scan_items(root_item)
 
         source_infos: list[SourceInfo] = []
-        if child_item is not None:
+        if default_child is not None:
             try:
-                item_storage = child_item.QueryInterface(IWiaPropertyStorage)
-                device_area = _read_wia_max_scan_area(root_storage, item_storage)
-
-                # Read per-source resolutions and color modes.
+                # Read each source's resolutions/color modes from its own
+                # child item (the feeder may differ from the flatbed).
                 for source in source_types:
-                    if root_storage is not None:
-                        try:
-                            select_val = (
-                                _FEEDER if source == ScanSource.FEEDER else _FLATBED
-                            )
-                            _write_prop(
-                                root_storage,
-                                _WIA_DPS_DOCUMENT_HANDLING_SELECT,
-                                select_val,
-                            )
-                        except Exception:
-                            pass
+                    src_item = child_map.get(source, default_child)
+                    item_storage = src_item.QueryInterface(IWiaPropertyStorage)
                     source_infos.append(
                         SourceInfo(
                             type=source,
                             resolutions=_read_wia_resolutions(item_storage),
                             color_modes=_read_wia_color_modes(item_storage),
-                            max_scan_area=device_area,
+                            max_scan_area=_read_wia_max_scan_area(
+                                root_storage, item_storage
+                            ),
                         )
                     )
 
-                scanner._defaults = _read_wia_defaults(item_storage, source_types)
+                default_storage = default_child.QueryInterface(IWiaPropertyStorage)
+                scanner._defaults = _read_wia_defaults(default_storage, source_types)
             except Exception:
                 scanner._defaults = None
         else:
@@ -1222,7 +1268,7 @@ class WiaBackend:
             scanner._defaults = None
 
         scanner._sources = source_infos
-        self._handles[scanner.id] = (root_item, child_item)
+        self._handles[scanner.id] = (root_item, child_map, default_child)
 
     def _close_scanner_impl(self, scanner: Scanner) -> None:
         self._handles.pop(scanner.id, None)
@@ -1234,7 +1280,11 @@ class WiaBackend:
         if items is None:
             raise ScanError("Scanner is not open")
 
-        root_item, child_item = items
+        root_item, child_map, default_child = items
+        source = options.source or ScanSource.FLATBED
+        # Scan from the source's own child item — using the flatbed item for
+        # a feeder scan makes some drivers scan blanks from an empty feeder.
+        child_item = child_map.get(source, default_child)
         if child_item is None:
             raise ScanError("Scanner has no scan items")
 
@@ -1296,34 +1346,47 @@ class WiaBackend:
 
             while True:
                 callback = _TransferCallback(options.progress, scanner._abort_event)
+                end_of_feeder = False
                 try:
                     transfer.Download(0, callback)
                 except Exception as exc:
+                    # Classify by HRESULT, never by message text.
                     hr = getattr(exc, "hresult", None)
-                    msg_text = str(exc).lower()
-                    if callback._aborted:
+                    if callback._aborted or hr in _WIA_CANCEL_ERRORS:
                         raise ScanAborted("Scan aborted") from exc
-                    if (
-                        hr == _WIA_ERROR_PAPER_EMPTY
-                        or "paper" in msg_text
-                        or "empty" in msg_text
-                    ):
+                    if hr in _WIA_BUSY_ERRORS:
+                        raise ScannerBusyError() from exc
+                    if hr in _WIA_UNAVAILABLE_ERRORS:
+                        raise ScannerUnavailableError() from exc
+                    if hr == _WIA_ERROR_PAPER_EMPTY:
+                        # Feeder ran dry: empty from the start if nothing was
+                        # scanned, otherwise the normal end of a feeder run.
                         if is_feeder and not all_pages and not callback.pages:
                             raise FeederEmptyError("No documents in feeder") from exc
-                        # Feeder empty after some pages — that's normal
-                    elif hr in _WIA_BUSY_ERRORS:
-                        raise ScannerBusyError() from exc
-                    elif "cancel" in msg_text or "abort" in msg_text:
-                        raise ScanAborted(f"Scan cancelled by device: {exc}") from exc
-                    elif not callback.pages and not all_pages:
+                        end_of_feeder = True
+                    elif not all_pages and not callback.pages:
+                        # Unrecognised failure with nothing scanned — a real error.
                         raise ScanError(f"Scan failed: {exc}") from exc
+                    else:
+                        # Unrecognised error after pages on a feeder — stop the
+                        # run rather than risk looping on a repeating failure.
+                        end_of_feeder = True
 
                 all_pages.extend(callback.pages)
 
-                if not is_feeder:
+                if not is_feeder or end_of_feeder:
+                    break
+                if not callback.pages:
+                    # Feeder Download returned successfully but produced no
+                    # page and didn't raise WIA_ERROR_PAPER_EMPTY — some
+                    # scanners (e.g. Epson WSD) signal an empty feeder this
+                    # way.  Stop instead of calling Download again, which
+                    # would re-run the scanner on an empty feeder forever.
                     break
 
             if not all_pages:
+                if is_feeder:
+                    raise FeederEmptyError("No documents in feeder")
                 raise ScanError("No pages were scanned")
 
             check_progress(options.progress, 100)

{scanlib-1.3.0 → scanlib-1.3.1/src/scanlib.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: scanlib
-Version: 1.3.0
+Version: 1.3.1
 Summary: A multiplatform document scanning library for Python
 Author-email: Angelo Mottola <a.mottola@gmail.com>
 License: MIT