API reference

Public reader

class pyzxing.BarCodeReader(jar_path=None, cache_dir=None, timeout=None, max_workers=None, build_dir=None, java_command=None)

Bases: object

Decode barcodes through the versioned pyzxing Java Runner.

The reader resolves a Runner lazily on the first decode. An explicit JAR is used as-is, a local development build is preferred when present, and the configured release asset is otherwise downloaded and checksum-verified.

Parameters:

• jar_path – Optional path to a compatible executable Runner JAR.

• cache_dir – Directory used for downloaded Runner assets.

• timeout – Per-file Java process timeout in seconds.

• max_workers – Maximum number of parallel file decodes.

• build_dir – Optional local Maven output directory.

• java_command – Optional Java executable path or command name.

Raises:

JavaNotFoundError – If Java cannot be found during construction.

decode(filename_pattern, *, multi=True, try_harder=True, pure_barcode=False, character_set=None, possible_formats=None)

Decode every file matching a path or glob pattern.

Parameters:

• filename_pattern – Input path or glob pattern.

• multi – Search for multiple barcodes in each image.

• try_harder – Ask ZXing to spend more effort locating barcodes.

• pure_barcode – Treat each input as a clean monochrome barcode.

• character_set – Optional ZXing character-set hint.

• possible_formats – Optional iterable of ZXing format names.

Returns:

One flat list containing every decoded barcode dictionary.

Raises:

• TypeError – If a decode hint has an unsupported type.

• ValueError – If the path or a decode hint is invalid.

• FileNotFoundError – If the path or glob matches no files.

• FileTooLargeError – If an input exceeds the configured limit.

• DecodeTimeoutError – If a Runner process times out.

• DecodeError – If the Runner or protocol reports a failure.

decode_array(array, *, multi=True, try_harder=True, pure_barcode=False, character_set=None, possible_formats=None)

Decode a grayscale or RGB NumPy array through a temporary PNG.

OpenCV is imported only when this method is called. Decode hints and result semantics are identical to decode().

Parameters:

• array – NumPy-compatible two- or three-dimensional image array.

• multi – Search for multiple barcodes in the image.

• try_harder – Ask ZXing to spend more effort locating barcodes.

• pure_barcode – Treat the input as a clean monochrome barcode.

• character_set – Optional ZXing character-set hint.

• possible_formats – Optional iterable of ZXing format names.

Returns:

One flat list containing decoded barcode dictionaries.

Raises:

• ImportError – If OpenCV is not installed.

• TypeError – If a decode hint has an unsupported type.

• DecodeError – If image serialization or decoding fails.

Exceptions

exception pyzxing.PyZXingError

Bases: RuntimeError

Base exception for pyzxing runtime failures.

exception pyzxing.JavaNotFoundError

Bases: PyZXingError

Raised when no Java executable can be found.

exception pyzxing.DecodeError(message, code=None)

Bases: PyZXingError

Raised when the ZXing process cannot decode an input.

exception pyzxing.DecodeTimeoutError(message, code=None)

Bases: DecodeError

Raised when ZXing exceeds the configured timeout.

exception pyzxing.FileTooLargeError(message, code=None)

Bases: DecodeError

Raised when an input exceeds the configured size limit.