coolscanpy 0.1.0__py3-none-any.whl

coolscanpy/__init__.py

@@ -0,0 +1,102 @@
+"""coolscanpy -- direct-USB acquisition library for Nikon Coolscan film scanners.
+
+A python-sane-style API (module-level ``get_devices()``/``open()``, a
+``Device`` with typed option attributes, ``dev.scan() -> ndarray``) plus a
+roll-feeder extension (``Device.roll() -> Roll``: whole-roll preview,
+spacing-offset registration, fingerprint-refusal safety, one-shot batch fine
+scanning, receipts). See the package README for the hardware this has
+actually been validated against and what remains untested.
+"""
+
+from __future__ import annotations
+
+try:
+    from importlib.metadata import version as _pkg_version
+
+    __version__ = _pkg_version("coolscanpy")
+except Exception:  # pragma: no cover - only when the package isn't installed
+    __version__ = "0.1.0"
+
+from coolscanpy._device import Device, get_devices, open
+from coolscanpy._roll import Roll
+from coolscanpy.exceptions import (
+    BatchIntegrityError,
+    DeviceBusy,
+    DeviceNotFound,
+    EjectFailed,
+    FeederParked,
+    FingerprintRefused,
+    GeometryValidationError,
+    ManualReviewRequired,
+    PyCoolscanError,
+    RollMismatch,
+    SafeStopRequested,
+    SplitAlignmentError,
+    TransportSmearDetected,
+)
+from coolscanpy.types import (
+    ApprovalReceipt,
+    ArtifactEvidence,
+    Capabilities,
+    ClippingTelemetry,
+    DeviceInfo,
+    ExposureVector,
+    FingerprintComparison,
+    FocusDetailTelemetry,
+    Frame,
+    Material,
+    Option,
+    OptionType,
+    OptionUnit,
+    Progress,
+    Receipt,
+    RollFingerprint,
+    SplitAlignment,
+    Thumbnail,
+    TransportSmearAssessment,
+)
+
+__all__ = [
+    "__version__",
+    # module-level (python-sane-shaped)
+    "get_devices",
+    "open",
+    # core objects
+    "Device",
+    "Option",
+    "OptionType",
+    "OptionUnit",
+    "Capabilities",
+    "DeviceInfo",
+    # roll extension
+    "Roll",
+    "Material",
+    "Thumbnail",
+    "Frame",
+    "RollFingerprint",
+    "FingerprintComparison",
+    "Progress",
+    # receipts
+    "Receipt",
+    "ExposureVector",
+    "SplitAlignment",
+    "ClippingTelemetry",
+    "FocusDetailTelemetry",
+    "TransportSmearAssessment",
+    "ArtifactEvidence",
+    "ApprovalReceipt",
+    # exceptions
+    "PyCoolscanError",
+    "DeviceNotFound",
+    "DeviceBusy",
+    "EjectFailed",
+    "SafeStopRequested",
+    "FeederParked",
+    "RollMismatch",
+    "FingerprintRefused",
+    "ManualReviewRequired",
+    "GeometryValidationError",
+    "TransportSmearDetected",
+    "SplitAlignmentError",
+    "BatchIntegrityError",
+]

coolscanpy/_device.py

@@ -0,0 +1,454 @@
+"""The python-sane-shaped plain surface: ``get_devices``/``open``/``Device``.
+
+This module is thin by design: it adapts ``session.service.ScannerService``
+(itself backed by ``transport.sane.SaneBackend``) to the fixed, typed option
+attributes and constraint-introspection shape the public API contract
+describes. It adds exactly two pieces of new behavior beyond adaptation and
+argument validation, both explicitly called for by the API contract:
+
+* an in-process registry so a second ``open()`` of an already-open device
+  raises :class:`~coolscanpy.exceptions.DeviceBusy` instead of silently
+  racing it (there is no cross-process reservation for the plain scan path);
+* a non-blocking per-device lock so a concurrent ``scan()``/``roll()`` call
+  raises :class:`~coolscanpy.exceptions.DeviceBusy` rather than blocking.
+
+``coolscanpy.session.service.ScannerService`` and ``coolscanpy.transport.sane``
+are imported lazily (inside functions, not at module level) so that plain
+``import coolscanpy`` stays cheap and does not pull in ``cv2``/``python-sane``
+-- matching this package's existing convention that only the code paths
+which actually need the SANE-backed transport pay for it (see the
+``[scanner]`` extra in ``pyproject.toml``).
+
+Enumeration itself never requires python-sane to be installed: ``get_devices()``
+tries the SANE route first, and only when python-sane is not importable falls
+back to direct USB enumeration (``pyusb``, already a runtime dependency,
+matching the LS-5000's fixed vendor/product id) -- see
+``_usb_fallback_device_infos``. That fallback device carries reduced,
+conservative capabilities, since there is no SANE session to negotiate the
+rest against. SANE-only operations (``Device.scan()``, ``Device.eject()``)
+still raise ``ImportError`` when actually called on such a device -- only
+enumeration and the roll-feeder extension, which never uses SANE, are
+unaffected by its absence.
+"""
+
+from __future__ import annotations
+
+import threading
+from typing import TYPE_CHECKING, Callable
+
+from coolscanpy.exceptions import DeviceBusy, DeviceNotFound, EjectFailed
+from coolscanpy.session.backend import ScannerCapabilities, ScannerDevice
+from coolscanpy.session.params import ScanParams
+from coolscanpy.types import Capabilities, DeviceInfo, Material, Option, OptionType, OptionUnit
+
+if TYPE_CHECKING:
+    from coolscanpy._roll import Roll
+    from coolscanpy.session.service import ScannerService
+
+_COOLSCAN3_PREFIX = "coolscan3:"
+
+_OPTION_NAMES: tuple[str, ...] = ("resolution", "depth", "samples", "autofocus", "auto_exposure")
+
+# The Nikon Coolscan LS-5000's fixed USB identity. The roll engine's capture
+# subprocess (protocol.ls5000_single_pass.worker) locates the physical unit
+# itself with this exact pair -- it never consumes a device id from this
+# module -- so these are duplicated constants, not a shared import, matching
+# that module's pinned/untouched status.
+_LS5000_USB_VENDOR_ID = 0x04B0
+_LS5000_USB_PRODUCT_ID = 0x4002
+_USB_FALLBACK_ID_PREFIX = "usb"
+
+
+def _default_service_factory() -> "ScannerService":
+    from coolscanpy.session.service import ScannerService
+
+    return ScannerService()
+
+
+# Rebindable so tests can substitute a service that wraps a fake backend
+# without touching hardware or python-sane. See tests/test_facade.py.
+_service_factory: Callable[[], "ScannerService"] = _default_service_factory
+
+_open_devices: set[str] = set()
+_open_devices_lock = threading.Lock()
+
+
+def _register_open_device(device_id: str) -> None:
+    with _open_devices_lock:
+        if device_id in _open_devices:
+            raise DeviceBusy(f"device {device_id!r} is already open in this process")
+        _open_devices.add(device_id)
+
+
+def _unregister_open_device(device_id: str) -> None:
+    with _open_devices_lock:
+        _open_devices.discard(device_id)
+
+
+def _is_coolscan_device_id(device_id: str) -> bool:
+    """True for a Coolscan LS-5000 SANE device id, direct or via saned.
+
+    ``get_devices()`` scope is one vendor: filter out every other SANE
+    backend's device (pieusb, generic flatbeds, etc.) so a caller never sees
+    a non-Coolscan unit, matching the module-level scope note. Imports
+    ``transport.sane`` lazily -- see the module docstring.
+    """
+
+    from coolscanpy.transport.sane import _strip_net_prefix
+
+    return _strip_net_prefix(device_id).startswith(_COOLSCAN3_PREFIX)
+
+
+def _capabilities_from(caps: ScannerCapabilities) -> Capabilities:
+    return Capabilities(
+        ir_channel=caps.ir_channel,
+        supported_dpi=caps.supported_dpi,
+        supported_depths=caps.supported_depths,
+        multi_sample=caps.multi_sample,
+        adapter_frame_capacity=caps.adapter_frame_capacity,
+        adapter_frame_control=caps.adapter_frame_control,
+        auto_exposure=caps.auto_exposure,
+        registered_geometry=caps.registered_geometry,
+        can_eject=caps.can_eject,
+    )
+
+
+def _device_info_from(device: ScannerDevice) -> DeviceInfo:
+    return DeviceInfo(
+        id=device.id,
+        vendor=device.vendor,
+        model=device.model,
+        capabilities=_capabilities_from(device.capabilities),
+    )
+
+
+def _usb_fallback_capabilities() -> Capabilities:
+    """Conservative capabilities for a device found only via direct USB.
+
+    No SANE session exists to negotiate a real capability set, so this
+    reports only what holds for every LS-5000 regardless of software stack:
+    a fixed 4000 dpi / 16-bit native fine-scan (what the roll engine's
+    single-pass capture always requests, independent of ``Device.resolution``/
+    ``.depth``) and frame-position addressing, so ``Device.roll()``'s
+    capability gate passes. Everything SANE would otherwise negotiate
+    per-unit (hardware multi-sample, auto-exposure, registered-geometry
+    positioning, medium eject) is conservatively false/absent rather than
+    guessed -- those remain genuinely SANE-only.
+    """
+
+    return Capabilities(
+        ir_channel=True,
+        supported_dpi=(4_000,),
+        supported_depths=(16,),
+        multi_sample=False,
+        adapter_frame_capacity=None,
+        adapter_frame_control=True,
+        auto_exposure=False,
+        registered_geometry=False,
+        can_eject=False,
+    )
+
+
+def _usb_fallback_device_infos() -> list[DeviceInfo]:
+    """Enumerate attached LS-5000 units directly over USB, no python-sane.
+
+    Used by :func:`get_devices` only when python-sane is not importable.
+    ``usb.core`` is imported lazily here, matching this package's convention
+    of scoping USB imports to the code that actually touches the bus.
+
+    The returned id is synthetic (``"usb:<bus>:<address>"``): honest about
+    the USB topology it was found on, but not a SANE device string, since
+    none was ever negotiated. Nothing downstream needs it to be one --
+    :meth:`Device.roll`'s capture subprocess locates the physical unit itself
+    by the same fixed vendor/product id (see
+    ``protocol.ls5000_single_pass.worker``), never through this id; the id
+    here only labels the in-process open-device registry and the ``Receipt``
+    metadata a roll capture carries.
+    """
+
+    import usb.core
+
+    capabilities = _usb_fallback_capabilities()
+    found = usb.core.find(
+        find_all=True,
+        idVendor=_LS5000_USB_VENDOR_ID,
+        idProduct=_LS5000_USB_PRODUCT_ID,
+    )
+    return [
+        DeviceInfo(
+            id=f"{_USB_FALLBACK_ID_PREFIX}:{device.bus}:{device.address}",
+            vendor="Nikon",
+            model="LS-5000 ED",
+            capabilities=capabilities,
+        )
+        for device in found
+    ]
+
+
+def get_devices(local_only: bool = False) -> list[DeviceInfo]:
+    """Enumerate attached Coolscan LS-5000 units.
+
+    Mirrors ``sane.get_devices()``; unlike SANE, this never returns a
+    non-Coolscan device -- there is no backend negotiation. ``local_only`` is
+    accepted for signature-compatibility with ``sane.get_devices()`` and is
+    currently always true (no network transport exists for this package).
+
+    Tries the SANE route first. When python-sane is not importable, falls
+    back to direct USB enumeration instead of raising -- see
+    :func:`_usb_fallback_device_infos`.
+    """
+
+    del local_only
+    try:
+        service = _service_factory()
+        devices = service.list_devices()
+    except ImportError:
+        return _usb_fallback_device_infos()
+    return [_device_info_from(device) for device in devices if _is_coolscan_device_id(device.id)]
+
+
+def open(devname: str) -> "Device":
+    """Open one Coolscan LS-5000. Mirrors ``sane.open(devname)``.
+
+    ``devname`` is either ``"ls5000"`` (friendly alias for "the one attached
+    unit") or an exact :class:`~coolscanpy.types.DeviceInfo.id` string
+    returned by :func:`get_devices`.
+    """
+
+    infos = get_devices()
+    if devname == "ls5000":
+        if not infos:
+            raise DeviceNotFound("no Coolscan LS-5000 unit is attached")
+        if len(infos) > 1:
+            raise DeviceNotFound(
+                "more than one Coolscan LS-5000 unit is attached; "
+                "disambiguate via get_devices()"
+            )
+        info = infos[0]
+    else:
+        matches = [candidate for candidate in infos if candidate.id == devname]
+        if not matches:
+            raise DeviceNotFound(f"no attached Coolscan LS-5000 unit matches {devname!r}")
+        info = matches[0]
+
+    _register_open_device(info.id)
+    try:
+        return Device(info, _service_factory())
+    except BaseException:
+        _unregister_open_device(info.id)
+        raise
+
+
+class Device:
+    """One opened Coolscan LS-5000 unit.
+
+    Construct via :func:`open`, not directly, except in tests that want to
+    drive a specific :class:`DeviceInfo`/service pair without going through
+    device enumeration.
+    """
+
+    def __init__(self, info: DeviceInfo, service: ScannerService) -> None:
+        self._info = info
+        self._service = service
+        self._lock = threading.Lock()
+        self._roll_lock = threading.Lock()
+        self._cancel_event: threading.Event | None = None
+        self._closed = False
+
+        caps = info.capabilities
+        self.resolution = max(caps.supported_dpi) if caps.supported_dpi else 4000
+        self.depth = 16 if 16 in caps.supported_depths else (
+            max(caps.supported_depths) if caps.supported_depths else 16
+        )
+        self.samples = 1
+        self.autofocus = True
+        self.auto_exposure = False
+
+    def __setattr__(self, name: str, value: object) -> None:
+        if name in _OPTION_NAMES:
+            self._validate_option(name, value)
+        object.__setattr__(self, name, value)
+
+    def _validate_option(self, name: str, value: object) -> None:
+        caps = self._info.capabilities
+        if name == "resolution":
+            if isinstance(value, bool) or not isinstance(value, int) or value not in caps.supported_dpi:
+                raise ValueError(f"resolution {value!r} is not in supported_dpi {caps.supported_dpi}")
+        elif name == "depth":
+            if isinstance(value, bool) or not isinstance(value, int) or value not in caps.supported_depths:
+                raise ValueError(f"depth {value!r} is not in supported_depths {caps.supported_depths}")
+        elif name == "samples":
+            allowed = (1, 4) if caps.multi_sample else (1,)
+            if isinstance(value, bool) or not isinstance(value, int) or value not in allowed:
+                raise ValueError(f"samples {value!r} is not in {allowed}")
+        elif name == "autofocus":
+            if not isinstance(value, bool):
+                raise TypeError("autofocus must be a bool")
+        elif name == "auto_exposure":
+            if not isinstance(value, bool):
+                raise TypeError("auto_exposure must be a bool")
+            if value and not caps.auto_exposure:
+                raise ValueError("device has no auto_exposure capability")
+
+    @property
+    def capabilities(self):
+        return self._info.capabilities
+
+    @property
+    def option_names(self) -> list[str]:
+        """Mirrors sane's ``optlist``."""
+
+        return list(_OPTION_NAMES)
+
+    def __getitem__(self, name: str) -> Option:
+        """Mirrors sane's ``dev['name']`` descriptor lookup."""
+
+        caps = self._info.capabilities
+        if name == "resolution":
+            return Option(
+                name="resolution",
+                title="Resolution",
+                desc="Scan resolution, in dots per inch.",
+                type=OptionType.INT,
+                unit=OptionUnit.DPI,
+                constraint=tuple(caps.supported_dpi),
+                active=True,
+                settable=len(caps.supported_dpi) > 1,
+            )
+        if name == "depth":
+            return Option(
+                name="depth",
+                title="Depth",
+                desc="Bits per sample.",
+                type=OptionType.INT,
+                unit=OptionUnit.NONE,
+                constraint=tuple(caps.supported_depths),
+                active=True,
+                settable=len(caps.supported_depths) > 1,
+            )
+        if name == "samples":
+            constraint = (1, 4) if caps.multi_sample else (1,)
+            return Option(
+                name="samples",
+                title="Samples",
+                desc="Hardware oversampling passes per line.",
+                type=OptionType.INT,
+                unit=OptionUnit.NONE,
+                constraint=constraint,
+                active=True,
+                settable=caps.multi_sample,
+            )
+        if name == "autofocus":
+            return Option(
+                name="autofocus",
+                title="Autofocus",
+                desc="Autofocus before each scan.",
+                type=OptionType.BOOL,
+                unit=OptionUnit.NONE,
+                constraint=None,
+                active=True,
+                settable=True,
+            )
+        if name == "auto_exposure":
+            return Option(
+                name="auto_exposure",
+                title="Auto exposure",
+                desc="Hardware auto-exposure metering.",
+                type=OptionType.BOOL,
+                unit=OptionUnit.NONE,
+                constraint=None,
+                active=caps.auto_exposure,
+                settable=caps.auto_exposure,
+            )
+        raise KeyError(name)
+
+    def scan(self, *, progress: Callable[[float], None] | None = None):
+        """Blocking. Returns a uint16 ``(H, W, 3)`` scanner-linear RGB array.
+
+        The plain, roll-independent scan path: a single ad-hoc capture at
+        whatever resolution/depth/samples are currently set. Never touches
+        roll bookkeeping, never produces a Receipt, never returns IR.
+        """
+
+        self._require_open()
+        if not self._lock.acquire(blocking=False):
+            raise DeviceBusy(f"device {self._info.id} is already scanning")
+        try:
+            cancel_event = threading.Event()
+            self._cancel_event = cancel_event
+            params = ScanParams(
+                dpi=self.resolution,
+                depth=self.depth,
+                capture_ir=False,
+                autofocus=self.autofocus,
+                samples_per_scan=self.samples,
+                auto_exposure=self.auto_exposure,
+            )
+            result = self._service.run_scan(
+                self._info.id,
+                params,
+                progress if progress is not None else (lambda _fraction: None),
+                cancel_event,
+            )
+            return result.rgb
+        finally:
+            self._cancel_event = None
+            self._lock.release()
+
+    def cancel(self) -> None:
+        """Mirrors ``sane.SaneDev.cancel()``. Call from a different thread
+        than the one blocked in :meth:`scan`."""
+
+        event = self._cancel_event
+        if event is not None:
+            event.set()
+
+    def roll(self, *, material: Material = Material.COLOR_NEGATIVE) -> "Roll":
+        """Open the 40-slot roll-feeder extension."""
+
+        self._require_open()
+        caps = self._info.capabilities
+        if caps.adapter_frame_capacity is None and not caps.adapter_frame_control:
+            raise ValueError("no roll adapter is attached/detected on this device")
+        if not self._roll_lock.acquire(blocking=False):
+            raise DeviceBusy(f"a Roll is already open on device {self._info.id}")
+        try:
+            from coolscanpy._roll import Roll
+
+            return Roll(self, material)
+        except BaseException:
+            self._roll_lock.release()
+            raise
+
+    def _release_roll_lock(self) -> None:
+        try:
+            self._roll_lock.release()
+        except RuntimeError:
+            pass
+
+    def eject(self) -> bool:
+        """Capability-gated vendor eject/unload."""
+
+        self._require_open()
+        try:
+            return bool(self._service.eject(self._info.id))
+        except RuntimeError as error:
+            raise EjectFailed(str(error)) from error
+
+    def close(self) -> None:
+        """Idempotent. Releases any transport claim this Device holds."""
+
+        if self._closed:
+            return
+        self._closed = True
+        _unregister_open_device(self._info.id)
+
+    def _require_open(self) -> None:
+        if self._closed:
+            raise RuntimeError("this Device has been closed")
+
+    def __enter__(self) -> "Device":
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()

coolscanpy/_logging.py

@@ -0,0 +1,27 @@
+"""Internal logging helper.
+
+A thin wrapper over the standard library's ``logging`` module so the rest of
+this package can call ``get_logger(__name__)`` without depending on any host
+application's logging configuration. A ``NullHandler`` is attached to the
+package's root logger so that an application which never configures logging
+gets no output and no "no handlers could be found" warning, per the standard
+library's guidance for library authors.
+"""
+
+import logging
+
+logging.getLogger("coolscanpy").addHandler(logging.NullHandler())
+
+
+def get_logger(name: str | None = None) -> logging.Logger:
+    """Return a logger namespaced under ``coolscanpy``.
+
+    ``name`` is typically a module's ``__name__`` (already fully qualified as
+    ``coolscanpy.<submodule>``), in which case it is used as-is. A bare,
+    unqualified name is nested under the package logger instead.
+    """
+    if not name:
+        return logging.getLogger("coolscanpy")
+    if name == "coolscanpy" or name.startswith("coolscanpy."):
+        return logging.getLogger(name)
+    return logging.getLogger(f"coolscanpy.{name}")