API Reference

Scanner Discovery

scanlib.list_scanners(*, timeout=15.0, cancel=None)

Return all available scanners on the current platform.

timeout controls how long (in seconds) to wait for scanner discovery. The default is DISCOVERY_TIMEOUT (15 s).

cancel, if given, is a threading.Event that the caller can set from another thread to interrupt discovery early. When the event is set the function returns immediately with an empty list.

The returned Scanner objects are lightweight — no device sessions are opened. Use Scanner.open() (or the context-manager protocol) to start a session before scanning.

Return type:

list[Scanner]

Parameters:

Scanner

class scanlib.Scanner(name, vendor, model, backend, *, scanner_id=None, location=None, _backend_impl=None)

Represents a discovered scanner device.

Use open() / close() (or the context-manager protocol) to start a session before calling scan().

Parameters:

  • name (str)

  • vendor (str | None)

  • model (str | None)

  • backend (str)

  • scanner_id (str | None)

  • location (str | None)

  • _backend_impl (ScanBackend | None)

property name: str

Platform-specific device name.

On SANE this is the device URI (e.g. escl:http://192.168.1.5:443/eSCL), on macOS and WIA it is a human-readable display name. Always populated.

property id: str

Platform-opaque string that uniquely identifies this device.

Guaranteed unique across all scanners returned by a single list_scanners() call. On SANE this is the device URI, on WIA the device ID, on macOS the device UUID.

property vendor: str | None

Scanner manufacturer, or None when not available.

Populated on SANE and macOS; None on WIA where WSD reports the driver vendor rather than the hardware manufacturer.

property model: str | None

Scanner model string, or None when not available.

Populated on SANE only; None on macOS and WIA.

property location: str | None

Free-form location string associated with the device.

Populated from ICDevice.locationDescription on macOS, or from the mDNS note TXT record on Linux/Windows. Returns None when no location is available.

property backend: str

"sane", "imagecapture", "wia", or "escl".

Type:

Backend identifier

property is_open: bool

Whether a device session is currently open.

property sources: list[SourceInfo]

Available scan sources and their capabilities.

Each entry is a SourceInfo with type, resolutions, color_modes, and max_scan_area. Only populated after open().

The first entry is the scanner’s primary source (typically flatbed). When scan() or scan_pages() is called without an explicit source, the first entry is used for parameter validation.

property defaults: ScannerDefaults | None

Default settings and supported values detected from the device.

Returns None if the backend could not determine defaults. Only available after open().

open()

Open a session on the scanner device. Returns self.

Return type:

Scanner

close()

Close the scanner session.

Return type:

None

abort()

Abort an in-progress scan.

Safe to call from any thread, even when no scan is running. The running scan() or scan_pages() call will raise ScanAborted shortly after this is called. The event is cleared automatically at the start of the next scan.

Return type:

None

scan_pages(*, dpi=300, color_mode=ColorMode.COLOR, scan_area=None, source=None, progress=None, next_page=None, bw_threshold=128)

Scan and yield individual ScannedPage objects.

Each page carries raw pixel data that can be inspected, encoded (via ScannedPage.to_jpeg() / ScannedPage.to_png()), reordered, or later assembled into a PDF with build_pdf().

When next_page is provided and the source is not a feeder, each page is yielded before the callback is invoked, so the caller can preview or process the page before deciding whether to continue scanning.

bw_threshold (0–255) controls the grayscale-to-BW cutoff when color_mode is ColorMode.BW. Pixels with a value ≥ threshold become white; below become black. Default is 128.

Parameters are the same as scan() except that image_format and jpeg_quality are not applicable here.

Return type:

Iterator[ScannedPage]

Parameters:
scan(*, dpi=300, color_mode=ColorMode.COLOR, scan_area=None, source=None, progress=None, next_page=None, image_format=None, jpeg_quality=85, bw_threshold=128)

Scan a document and return PDF bytes.

When source is ScanSource.FEEDER, all pages in the document feeder are scanned. Otherwise a single page is scanned.

When next_page is provided and the source is not a feeder, the callback is called after each page with the number of pages scanned so far. Return True to scan another page or False to stop.

image_format selects the encoding for page images inside the PDF: ImageFormat.JPEG (smaller files) or ImageFormat.PNG (lossless). When not specified, PNG is used for BW mode (since 1-bit packs much smaller than JPEG) and JPEG for everything else.

jpeg_quality (1–100) controls JPEG compression quality; ignored when image_format is PNG.

bw_threshold (0–255) controls the grayscale-to-BW cutoff when color_mode is ColorMode.BW. Default is 128.

Return type:

ScannedDocument

Parameters:

Scanned Pages

class scanlib.ScannedPage(data, width, height, color_mode)

A single scanned page with raw pixel data.

data contains raw pixel bytes with no header or wrapper — 1 byte per pixel for grayscale (ColorMode.GRAY), 3 bytes per pixel (R, G, B) for color (ColorMode.COLOR), or 1-bit packed (MSB first) for black & white (ColorMode.BW).

Parameters:
rotate(degrees)

Rotate the page clockwise by 90, 180, or 270 degrees.

Returns a new ScannedPage with the rotated pixel data. For 90° and 270° rotations, width and height are swapped.

Return type:

ScannedPage

Parameters:

degrees (int)

to_jpeg(quality=85)

Encode the page as JPEG and return the bytes.

Uses a platform-native encoder (ImageIO on macOS, WIC on Windows, libjpeg on Linux). quality ranges from 1 (smallest) to 100 (best). 1-bit BW pages are unpacked to 8-bit grayscale before encoding.

Return type:

bytes

Parameters:

quality (int)

to_png()

Encode the page as lossless PNG and return the bytes.

Uses stdlib zlib for compression — no external dependency.

Return type:

bytes

scanlib.build_pdf(pages, *, dpi=300, color_mode=ColorMode.COLOR, image_format=None, jpeg_quality=85, bw_threshold=128)

Build a PDF from scanned pages.

pages is any iterable of ScannedPage objects — they may come directly from Scanner.scan_pages() or from a list that has been reordered, filtered, etc.

image_format selects the encoding for page images inside the PDF: ImageFormat.JPEG (smaller files) or ImageFormat.PNG (lossless). When not specified, PNG is used for BW mode (since 1-bit packs much smaller than JPEG) and JPEG for everything else. jpeg_quality (1–100) controls JPEG compression; it is ignored when the format is PNG.

bw_threshold (0–255) controls the grayscale-to-BW cutoff when color_mode is ColorMode.BW. Default is 128.

Returns a ScannedDocument containing the PDF bytes.

Return type:

ScannedDocument

Parameters:

Scan Result

class scanlib.ScannedDocument(data, page_count, width, height, dpi, color_mode)

Result of a scan operation.

data contains PDF file bytes (one or more pages). width and height reflect the dimensions of the first page in pixels. Individual pages in the PDF may differ (e.g. after rotation).

Parameters:
width: int

Width of the first page in pixels.

height: int

Height of the first page in pixels.

Options & Configuration

class scanlib.ScanOptions(dpi=300, color_mode=ColorMode.COLOR, scan_area=None, source=None, progress=None, bw_threshold=128)

Options for a scan operation.

Parameters:
class scanlib.ColorMode(*values)

Color mode for scanning.

COLOR = 'color'
GRAY = 'gray'
BW = 'bw'
class scanlib.ScanSource(*values)

Scan source type.

FLATBED = 'flatbed'
FEEDER = 'feeder'
class scanlib.ImageFormat(*values)

Image encoding format used inside the PDF.

PNG = 'png'
JPEG = 'jpeg'
class scanlib.ScanArea(x, y, width, height)

Scan region in 1/10 millimeters.

x and y are offsets from the top-left corner of the scanner bed. width and height are the dimensions of the region to scan.

Parameters:
class scanlib.ScannerDefaults(dpi, color_mode, source)

Default settings detected from the device after opening.

Parameters:
class scanlib.SourceInfo(type, resolutions, color_modes, max_scan_area)

Capabilities of a single scan source.

Each SourceInfo bundles the supported resolutions, color modes, and maximum scan area for one scan source (flatbed or feeder). Access via Scanner.sources after opening the device.

Parameters:

Exceptions

class scanlib.ScanLibError

Base exception for scanlib.

class scanlib.ScanError

An error occurred during scanning.

class scanlib.ScanAborted

The scan was aborted before completion.

class scanlib.FeederEmptyError

The document feeder has no pages to scan.

class scanlib.ScannerNotOpenError

Operation requires an open scanner session.

class scanlib.NoScannerFoundError

No scanner device was found.

class scanlib.BackendNotAvailableError

The scanning backend for this platform is not installed.