ocracy.util

Image-input normalization and small shared helpers.

Different OCR backends want their input in different forms: a filesystem path (Tesseract, PaddleOCR), raw bytes (most cloud REST APIs), a PIL image, or a numpy array (deep-learning engines). Callers, meanwhile, want to pass whatever they have — a path, an http(s) URL, bytes, a PIL image, or an array. This module bridges the two with a handful of converters that lazily import Pillow / numpy / urllib only when actually exercised, so import ocracy stays dependency-free.

The key converters:

• load_image_bytes() — anything -> encoded image bytes (for REST APIs).

• ensure_file_path() — anything -> a path on disk (writing a temp file for in-memory inputs); pair with cleanup_temp() or use image_path().

• image_path() — a context manager yielding a path and cleaning up.

• to_pil() / to_numpy() — anything -> a PIL image / numpy array.

Functions

classify_input(image)	Classify an image input as url/path/bytes/pil/numpy.
is_url(x)	True if x is a string that looks like an http(s) URL.
load_image_bytes(image, *[, fmt])	Return encoded image bytes for any supported input.
ensure_file_path(image, *[, suffix])	Return (path, is_temp) for any supported input.
cleanup_temp(path, is_temp)	Delete path iff is_temp (the flag returned by ensure_file_path()).
image_path(image, *[, suffix])	Context manager yielding a filesystem path for image, cleaning up temps.
to_pil(image)	Convert any supported input into a PIL Image (lazy import).
to_numpy(image)	Convert any supported input into a numpy array (lazy import).
check_import(module_name, *, install_hint[, ...])	Import module_name or raise a friendly, actionable ImportError.

ocracy.util.check_import(module_name, *, install_hint, feature='this')

Import module_name or raise a friendly, actionable ImportError.

Centralizes the “you need to pip install X” guidance so adapters and converters don’t each hand-roll it.

ocracy.util.classify_input(image)

Classify an image input as url/path/bytes/pil/numpy.

Decided structurally (and via duck typing for PIL/numpy) so we never import Pillow or numpy just to look at the input.

Return type:

str

ocracy.util.cleanup_temp(path, is_temp)

Delete path iff is_temp (the flag returned by ensure_file_path()).

Return type:

None

ocracy.util.ensure_file_path(image, *, suffix='.png')

Return (path, is_temp) for any supported input.

Existing on-disk paths are returned untouched (is_temp=False). In-memory inputs (bytes/URL/PIL/numpy) are written to a temp file (is_temp=True); the caller is responsible for cleanup (use cleanup_temp(), or prefer the image_path() context manager).

Return type:

Tuple[str, bool]

ocracy.util.image_path(image, *, suffix='.png')

Context manager yielding a filesystem path for image, cleaning up temps.

Example:

with image_path(pil_image) as p:
    text = pytesseract.image_to_string(p)

Return type:

Iterator[str]

ocracy.util.is_url(x)

True if x is a string that looks like an http(s) URL.

Return type:

bool

ocracy.util.load_image_bytes(image, *, fmt='PNG')

Return encoded image bytes for any supported input.

Pass-through for bytes; reads files; fetches URLs; encodes PIL/numpy inputs as fmt (PNG by default — lossless and universally accepted).

Return type:

bytes

ocracy.util.to_numpy(image)

Convert any supported input into a numpy array (lazy import).

ocracy.util.to_pil(image)

Convert any supported input into a PIL Image (lazy import).