scanlib 1.2.0__tar.gz → 1.3.1__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: scanlib
-Version: 1.2.0
+Version: 1.3.1
 Summary: A multiplatform document scanning library for Python
 Author-email: Angelo Mottola <a.mottola@gmail.com>
 License: MIT
@@ -67,10 +67,10 @@ A multiplatform document scanning library for Python with platform-native scanni
 | Platform | Backend | Scanner types | eSCL | System packages |
 |---|---|---|---|---|
 | **macOS 10.7+** | ImageCaptureCore | USB + network | Opt-in (`SCANLIB_ESCL=1`) | None |
-| **Windows 10+** | WIA 2.0 | USB | Always enabled | None |
+| **Windows 10+** | WIA 2.0 | USB + network | Always enabled | None |
 | **Linux** | SANE | USB | Always enabled | `libsane-dev libjpeg-dev` |
 
-The eSCL (AirScan) backend discovers and drives network scanners directly over HTTP — no OS-level scanner drivers needed. On Linux and Windows it runs alongside the platform backend automatically. On macOS, ImageCaptureCore already handles network scanners natively; set `SCANLIB_ESCL=1` to use the eSCL backend instead.
+The eSCL (AirScan) backend discovers and drives network scanners directly over HTTP — no OS-level scanner drivers needed. On Linux and Windows it runs alongside the platform backend automatically, and a network scanner found by both is reported once (matched by device UUID or IP), preferring the platform driver. On macOS, ImageCaptureCore already handles network scanners natively, so eSCL is opt-in. Set `SCANLIB_ESCL=1` to enable eSCL on macOS, or — on any platform — to prefer the eSCL driver over the platform driver for scanners seen by both.
 
 ## Installation
 

{scanlib-1.2.0 → scanlib-1.3.1}/README.md

@@ -23,10 +23,10 @@ A multiplatform document scanning library for Python with platform-native scanni
 | Platform | Backend | Scanner types | eSCL | System packages |
 |---|---|---|---|---|
 | **macOS 10.7+** | ImageCaptureCore | USB + network | Opt-in (`SCANLIB_ESCL=1`) | None |
-| **Windows 10+** | WIA 2.0 | USB | Always enabled | None |
+| **Windows 10+** | WIA 2.0 | USB + network | Always enabled | None |
 | **Linux** | SANE | USB | Always enabled | `libsane-dev libjpeg-dev` |
 
-The eSCL (AirScan) backend discovers and drives network scanners directly over HTTP — no OS-level scanner drivers needed. On Linux and Windows it runs alongside the platform backend automatically. On macOS, ImageCaptureCore already handles network scanners natively; set `SCANLIB_ESCL=1` to use the eSCL backend instead.
+The eSCL (AirScan) backend discovers and drives network scanners directly over HTTP — no OS-level scanner drivers needed. On Linux and Windows it runs alongside the platform backend automatically, and a network scanner found by both is reported once (matched by device UUID or IP), preferring the platform driver. On macOS, ImageCaptureCore already handles network scanners natively, so eSCL is opt-in. Set `SCANLIB_ESCL=1` to enable eSCL on macOS, or — on any platform — to prefer the eSCL driver over the platform driver for scanners seen by both.
 
 ## Installation
 

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

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

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

@@ -23,8 +23,10 @@ from ._types import (
     ScanError,
     ScanLibError,
     Scanner,
+    ScannerBusyError,
     ScannerDefaults,
     ScannerNotOpenError,
+    ScannerUnavailableError,
     ScanOptions,
     ScanSource,
     ScannedDocument,
@@ -52,6 +54,8 @@ __all__ = [
     "ScanLibError",
     "ScanError",
     "ScanAborted",
+    "ScannerBusyError",
+    "ScannerUnavailableError",
     "FeederEmptyError",
     "NoScannerFoundError",
     "BackendNotAvailableError",
@@ -63,19 +67,46 @@ __all__ = [
 # ---------------------------------------------------------------------------
 
 
+def _await_thread(thread: threading.Thread, timeout: float) -> None:
+    """Wait up to *timeout* seconds for *thread* to finish.
+
+    On macOS this delegates to the backend's run-loop-aware wait so the
+    ImageCaptureCore platform backend — whose discovery callbacks arrive
+    on the main thread's run loop — isn't starved.  Everywhere else a
+    plain blocking join is correct.
+    """
+    if sys.platform == "darwin":
+        from .backends._macos import await_thread
+
+        await_thread(thread, timeout)
+    else:
+        thread.join(timeout)
+
+
 class _CompositeBackend:
     """Merges results from a platform backend and the eSCL backend.
 
     ``list_scanners`` runs both backends' discovery in parallel and
-    deduplicates by IP address.  Each scanner's ``_backend_impl`` points
-    to whichever backend discovered it.
+    deduplicates: a platform scanner and an eSCL scanner are the same
+    physical device when their UUIDs match or their IPs match.  Each
+    scanner's ``_backend_impl`` points to whichever backend discovered it.
+
+    *prefer_escl* decides which entry survives a duplicate.  On Linux and
+    Windows the platform driver is preferred (the platform backend is
+    always on), so the eSCL duplicate is dropped.  On macOS the eSCL
+    backend is opt-in (``SCANLIB_ESCL=1``); enabling it signals a
+    preference for the eSCL driver, so there the platform duplicate is
+    dropped instead.
     """
 
-    def __init__(self, platform_backend: ScanBackend) -> None:
+    def __init__(
+        self, platform_backend: ScanBackend, *, prefer_escl: bool = False
+    ) -> None:
         from .backends._escl import EsclBackend
 
         self._platform = platform_backend
         self._escl = EsclBackend()
+        self._prefer_escl = prefer_escl
 
     def list_scanners(
         self,
@@ -105,12 +136,14 @@ class _CompositeBackend:
         t_platform.start()
         t_escl.start()
 
-        # Wait for eSCL first (fast, ~4s max), then give the platform
+        # Wait for eSCL first (fast, ~6s max), then give the platform
         # backend a short grace period to finish.  Don't block on a
-        # slow platform backend when eSCL already has results.
-        t_escl.join(timeout=timeout + 2)
+        # slow platform backend when eSCL already has results.  _await_thread
+        # pumps the macOS run loop while waiting (see its docstring) so the
+        # ImageCaptureCore platform backend isn't starved.
+        _await_thread(t_escl, timeout + 2)
         if t_platform.is_alive():
-            t_platform.join(timeout=2.0)
+            _await_thread(t_platform, 2.0)
 
         if cancel is not None and cancel.is_set():
             return []
@@ -120,25 +153,46 @@ class _CompositeBackend:
 
         if not escl_scanners:
             return platform_scanners
+        if not platform_scanners:
+            return escl_scanners
 
-        # Collect IPs from platform scanners for deduplication
         from ._mdns import extract_ip_from_uri
 
-        platform_ips: set[str] = set()
-        for s in platform_scanners:
-            ip = extract_ip_from_uri(s.name)
-            if ip:
-                platform_ips.add(ip)
-
-        # Add eSCL scanners not already found by the platform backend
+        # A platform scanner and an eSCL scanner are the same physical
+        # device when their UUIDs match or their IPs match.  The eSCL IP
+        # comes from mDNS (keyed by scanner id); the platform IP, when it
+        # has one, is parsed out of its name (e.g. a SANE ``escl:`` URI).
+        # On macOS the platform scanner exposes only a UUID, on Windows a
+        # WSD scanner exposes a UUID, on Linux a network SANE device
+        # exposes an IP — so matching on either key covers them all.  The
+        # identity sets never contain None, so a missing UUID/IP simply
+        # never matches (no explicit guard needed).
         escl_ips = self._escl.get_scanner_ips()
-        for s in escl_scanners:
-            ip = escl_ips.get(s.id)
-            if ip and ip in platform_ips:
-                continue  # already discovered by platform backend
-            platform_scanners.append(s)
 
-        return platform_scanners
+        if self._prefer_escl:
+            # Keep every eSCL entry; drop the platform duplicates.
+            escl_uuids = {s.uuid for s in escl_scanners if s.uuid}
+            escl_ip_set = set(escl_ips.values())
+            kept = [
+                s
+                for s in platform_scanners
+                if s.uuid not in escl_uuids
+                and extract_ip_from_uri(s.name) not in escl_ip_set
+            ]
+            return kept + escl_scanners
+
+        # Keep every platform entry; drop the eSCL duplicates.
+        platform_uuids = {s.uuid for s in platform_scanners if s.uuid}
+        platform_ip_set = {
+            ip for s in platform_scanners if (ip := extract_ip_from_uri(s.name))
+        }
+        kept = [
+            s
+            for s in escl_scanners
+            if s.uuid not in platform_uuids
+            and escl_ips.get(s.id) not in platform_ip_set
+        ]
+        return platform_scanners + kept
 
     # Delegate remaining methods to the scanner's own _backend_impl
     def open_scanner(self, scanner: Scanner) -> None:
@@ -169,23 +223,30 @@ def _get_backend() -> ScanBackend:
     if _backend is not None:
         return _backend
 
+    # Setting SCANLIB_ESCL=1 signals a preference for the eSCL driver over
+    # the platform driver when both discover the same device.
+    prefer_escl = os.environ.get("SCANLIB_ESCL", "").strip() == "1"
+
     if sys.platform == "linux":
         from .backends._sane import SaneBackend
 
-        _backend = _CompositeBackend(SaneBackend())
+        _backend = _CompositeBackend(SaneBackend(), prefer_escl=prefer_escl)
 
     elif sys.platform == "darwin":
         from .backends._macos import MacOSBackend
 
-        if os.environ.get("SCANLIB_ESCL", "").strip() == "1":
-            _backend = _CompositeBackend(MacOSBackend())
+        # On macOS the eSCL backend is opt-in (ImageCaptureCore already
+        # handles eSCL natively), so the composite is only used when
+        # SCANLIB_ESCL=1 — and enabling it implies preferring eSCL.
+        if prefer_escl:
+            _backend = _CompositeBackend(MacOSBackend(), prefer_escl=True)
         else:
             _backend = MacOSBackend()
 
     elif sys.platform == "win32":
         from .backends._wia import WiaBackend
 
-        _backend = _CompositeBackend(WiaBackend())
+        _backend = _CompositeBackend(WiaBackend(), prefer_escl=prefer_escl)
 
     else:
         raise BackendNotAvailableError(f"Unsupported platform: {sys.platform}")

{scanlib-1.2.0 → scanlib-1.3.1}/src/scanlib/_mdns.py

@@ -33,6 +33,8 @@ _SERVICE_TYPES = (
     "_uscan._tcp.local.",
     "_uscans._tcp.local.",
 )
+# Normalized (no trailing dot, lower-case) set for matching PTR owner names.
+_SERVICE_TYPE_SET = frozenset(s.rstrip(".").lower() for s in _SERVICE_TYPES)
 
 
 @dataclasses.dataclass
@@ -189,8 +191,15 @@ def _parse_responses(
         offset += rdlength
 
         if rtype == _TYPE_PTR:
-            target, _ = _read_name(data, rdstart)
-            ptrs.append((name, target))
+            # Only accept PTRs for the scanner service types we queried.
+            # We bind the mDNS port and join the multicast group, so the
+            # socket also receives unrelated service announcements from
+            # other devices on the LAN (AirPlay, screen sharing on
+            # _rfb._tcp, _companion-link, …); without this filter those
+            # iPhones/Macs/VMs get misreported as scanners.
+            if name.rstrip(".").lower() in _SERVICE_TYPE_SET:
+                target, _ = _read_name(data, rdstart)
+                ptrs.append((name, target))
         elif rtype == _TYPE_TXT:
             txts[name] = _parse_txt(data, rdstart, rdlength)
         elif rtype == _TYPE_A and rdlength == 4:
@@ -251,6 +260,57 @@ def _local_ipv4_addresses() -> list[str]:
     return unique
 
 
+def _resolve_srv_addresses(result: _BrowseResult) -> None:
+    """Copy SRV-target addresses onto their service instance names.
+
+    mDNS often carries the A/AAAA records under the target hostname
+    rather than the service instance name, and the two may arrive in
+    separate packets.  This links them on the accumulated result so a
+    service instance resolves to an IP even across packets.
+    """
+    for sname, srv in result.srvs.items():
+        if not result.addrs.get(sname) and result.addrs.get(srv.target):
+            result.addrs[sname] = list(result.addrs[srv.target])
+
+
+def _is_routable_address(addr: str) -> bool:
+    """False for addresses that cannot be used as a connection target.
+
+    Skips IPv6 link-local (``fe80::/10``), which require a ``%zone`` scope
+    id we do not track and so are not connectable, and IPv4 link-local
+    (``169.254.0.0/16``).  Some scanners advertise an extra service that
+    only resolves to a link-local address; surfacing it produces an
+    unusable, duplicate scanner entry.
+    """
+    a = addr.lower()
+    if a.startswith("169.254."):
+        return False
+    # IPv6 link-local fe80::/10 spans the fe80–febf prefixes.
+    if ":" in a and a[:3] in ("fe8", "fe9", "fea", "feb"):
+        return False
+    return True
+
+
+def _best_address(addrs: list[str]) -> str | None:
+    """Pick the best connectable address, or ``None`` if there is none.
+
+    Prefers IPv4 (simpler and unambiguous in an ``escl:IP:PORT`` id) and
+    skips link-local addresses.
+    """
+    routable = [a for a in addrs if _is_routable_address(a)]
+    ipv4 = [a for a in routable if ":" not in a]
+    if ipv4:
+        return ipv4[0]
+    return routable[0] if routable else None
+
+
+def _resolvable_instances(result: _BrowseResult) -> list[str]:
+    """Return PTR instance names that resolve to a usable (routable) IP."""
+    return [
+        inst for _svc, inst in result.ptrs if _best_address(result.addrs.get(inst, []))
+    ]
+
+
 def _browse_mdns(timeout: float = 4.0) -> _BrowseResult:
     """Send mDNS queries and collect responses.
 
@@ -305,34 +365,59 @@ def _browse_mdns(timeout: float = 4.0) -> _BrowseResult:
 
         sock.setblocking(False)
 
-        # Send PTR query.  On Windows, send on each interface so
-        # scanners on any subnet see it.
         query = _build_query(*_SERVICE_TYPES)
-        if local_addrs:
-            for addr in local_addrs:
+
+        def _send_query() -> None:
+            # On Windows, send on each interface so scanners on any
+            # subnet see the query.
+            if local_addrs:
+                for addr in local_addrs:
+                    try:
+                        sock.setsockopt(
+                            socket.IPPROTO_IP,
+                            socket.IP_MULTICAST_IF,
+                            socket.inet_aton(addr),
+                        )
+                        sock.sendto(query, (_MDNS_ADDR, _MDNS_PORT))
+                    except OSError:
+                        pass
+            else:
                 try:
-                    sock.setsockopt(
-                        socket.IPPROTO_IP,
-                        socket.IP_MULTICAST_IF,
-                        socket.inet_aton(addr),
-                    )
                     sock.sendto(query, (_MDNS_ADDR, _MDNS_PORT))
                 except OSError:
                     pass
-        else:
-            sock.sendto(query, (_MDNS_ADDR, _MDNS_PORT))
 
-        # Collect responses with early exit: once we've received at
-        # least one response, stop after a short quiet period (no new
-        # packets) rather than waiting the full timeout.
+        # Retransmit the query with growing intervals until a response
+        # arrives or the deadline passes: multicast is unreliable
+        # (especially over Wi-Fi) and a single lost query/response — or a
+        # responder transiently suppressing a duplicate question — would
+        # otherwise yield nothing for the full timeout.  Standard mDNS
+        # one-shot queriers retransmit (RFC 6762 §5.2).  Continuing to
+        # probe across the whole window also gives a sleeping scanner time
+        # to wake and answer.  Once a response arrives, stop retransmitting
+        # and linger for a short quiet period to gather additional records.
         quiet_period = 0.5
         got_response = False
-        deadline = time.monotonic() + timeout
+        start = time.monotonic()
+        deadline = start + timeout
+        send_interval = 0.25
+        next_send_at = 0.0  # seconds since start
         while True:
-            remaining = deadline - time.monotonic()
+            now = time.monotonic()
+            remaining = deadline - now
             if remaining <= 0:
                 break
-            wait = min(remaining, quiet_period) if got_response else remaining
+            elapsed = now - start
+            # Fire the next (re)transmission when due, then schedule the
+            # following one a little further out (capped at 1s).
+            if not got_response and elapsed >= next_send_at:
+                _send_query()
+                next_send_at = elapsed + send_interval
+                send_interval = min(send_interval * 2, 1.0)
+            if got_response:
+                wait = min(remaining, quiet_period)
+            else:
+                wait = max(0.0, min(remaining, next_send_at - elapsed))
             readable, _, _ = select.select([sock], [], [], wait)
             if not readable:
                 if got_response:
@@ -348,7 +433,12 @@ def _browse_mdns(timeout: float = 4.0) -> _BrowseResult:
             for k, v in addrs.items():
                 result.addrs.setdefault(k, []).extend(v)
             result.srvs.update(srvs)
-            if ptrs:
+            # Only treat the browse as answered once we have a service
+            # instance that actually resolves to an IP — a bare PTR with
+            # the address records still in flight is not enough, and
+            # exiting on it would drop the scanner.
+            _resolve_srv_addresses(result)
+            if _resolvable_instances(result):
                 got_response = True
 
     except OSError:
@@ -356,6 +446,7 @@ def _browse_mdns(timeout: float = 4.0) -> _BrowseResult:
     finally:
         sock.close()
 
+    _resolve_srv_addresses(result)
     return result
 
 
@@ -408,8 +499,12 @@ def discover_escl_services(timeout: float = 4.0) -> list[EsclServiceInfo]:
     for svc_type, instance_name in browse.ptrs:
         txt = browse.txts.get(instance_name, {})
         srv = browse.srvs.get(instance_name)
-        ips = browse.addrs.get(instance_name, [])
-        if not ips:
+        # Pick a usable address: prefer IPv4 and skip link-local addresses.
+        # A service that resolves only to a link-local address is not
+        # connectable (no %zone scope) and would otherwise show up as a
+        # broken, duplicate scanner entry.
+        ip = _best_address(browse.addrs.get(instance_name, []))
+        if ip is None:
             continue
 
         tls = "_uscans._tcp" in svc_type
@@ -425,7 +520,6 @@ def discover_escl_services(timeout: float = 4.0) -> list[EsclServiceInfo]:
                 continue
             seen_uuids.add(uuid)
 
-        ip = ips[0]
         if not uuid and ip in seen_ips:
             continue
         seen_ips.add(ip)

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

@@ -35,6 +35,36 @@ class FeederEmptyError(ScanError):
     """The document feeder has no pages to scan."""
 
 
+class ScannerBusyError(ScanError):
+    """The scanner is in use by another session or application."""
+
+    _DEFAULT = (
+        "Scanner is in use by another session or application. "
+        "Close it and try again."
+    )
+
+    def __init__(self, message: str = _DEFAULT) -> None:
+        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."""
 
@@ -267,6 +297,8 @@ class Scanner:
         *,
         scanner_id: str | None = None,
         location: str | None = None,
+        uuid: str | None = None,
+        display_name: str | None = None,
         _backend_impl: ScanBackend | None = None,
     ) -> None:
         self._name = name
@@ -275,6 +307,11 @@ class Scanner:
         self._backend = backend
         self._id = scanner_id if scanner_id is not None else name
         self._location = location
+        self._uuid = uuid.lower() if uuid else None
+        # OS-matching display label computed by the discovering backend
+        # (e.g. "vendor model" on SANE, the native device name elsewhere).
+        # str(scanner) uses it; None falls back to the generic logic below.
+        self._display_name = display_name
         self._backend_impl = _backend_impl
         self._sources: list[SourceInfo] = []
         self._defaults: ScannerDefaults | None = None
@@ -303,13 +340,34 @@ class Scanner:
         """
         return self._id
 
+    @property
+    def uuid(self) -> str | None:
+        """Lower-cased device UUID, or ``None`` when not available.
+
+        Populated on macOS (where it equals :attr:`id`), on WIA for
+        network/WSD scanners (extracted from the WSD port name), and on
+        eSCL (from the mDNS ``UUID`` record).  ``None`` on SANE.  Used by
+        the composite backend to recognise that a platform scanner and an
+        eSCL scanner are the same physical device.
+        """
+        return self._uuid
+
     def __str__(self) -> str:
-        """Human-readable scanner label suitable for UI display."""
+        """Human-readable scanner label suitable for UI display.
+
+        Returns the device's ``location`` when one is set; otherwise the
+        backend-computed ``display_name``, which matches what the OS shows
+        as the scanner's name (``vendor model`` on SANE, the native device
+        name on macOS/WIA/eSCL).  Falls back to a generic best-effort label
+        when no ``display_name`` was supplied (e.g. a scanner opened by id).
+        """
         if self._location:
             return self._location
+        if self._display_name:
+            return self._display_name
         if self._vendor and self._model:
             return f"{self._vendor} {self._model}"
-        return self._vendor or self._model or self._name
+        return self._name or self._vendor or self._model
 
     @property
     def vendor(self) -> str | None:
@@ -511,7 +569,11 @@ class Scanner:
             for page in self._backend_impl.scan_pages(self, options):
                 if self._abort_event.is_set():
                     raise ScanAborted("Scan aborted")
-                yield page
+                # Normalise to the requested color mode: scanners may
+                # return a richer mode than asked for (e.g. RGB when
+                # grayscale was requested), so down-convert here once for
+                # every backend rather than relying on each one.
+                yield _coerce_color_mode(page, options.color_mode, options.bw_threshold)
                 page_count += 1
             # Feeder: backend loops internally until empty; one call is enough.
             # Flatbed: backend scans one round; ask next_page to continue.
@@ -678,6 +740,39 @@ def wait_or_cancel(
     return True
 
 
+# Color-mode "richness" ordering: COLOR carries the most information,
+# BW the least.  We can down-convert (drop information) but never
+# up-convert (fabricate channels we were not given).
+_COLOR_MODE_RANK = {ColorMode.BW: 0, ColorMode.GRAY: 1, ColorMode.COLOR: 2}
+
+
+def _coerce_color_mode(
+    page: ScannedPage, target: ColorMode, bw_threshold: int = 128
+) -> ScannedPage:
+    """Down-convert *page* to the *target* color mode if it is richer.
+
+    Scanners do not always honour the requested color mode — some eSCL
+    devices return RGB even when grayscale is requested, for example.
+    This normalises a page to the mode the caller asked for: COLOR→GRAY
+    via luminance, GRAY/COLOR→BW via threshold.  Pages already at (or
+    below) the target richness are returned unchanged.
+    """
+    if _COLOR_MODE_RANK[page.color_mode] <= _COLOR_MODE_RANK[target]:
+        return page
+
+    from _scanlib_accel import gray_to_bw, rgb_to_gray
+
+    data = page.data
+    mode = page.color_mode
+    if mode == ColorMode.COLOR:
+        data = rgb_to_gray(data, page.width, page.height)
+        mode = ColorMode.GRAY
+    if target == ColorMode.BW and mode == ColorMode.GRAY:
+        data = gray_to_bw(data, page.width, page.height, bw_threshold)
+        mode = ColorMode.BW
+    return ScannedPage(data=data, width=page.width, height=page.height, color_mode=mode)
+
+
 def build_pdf(
     pages: Iterable[ScannedPage],
     *,