all2md.utils.images

Image handling utilities for renderers.

This module provides utilities for working with images in various formats, including base64-encoded data URIs and temporary file management.

all2md.utils.images.decode_base64_image(data_uri: str) → tuple[bytes | None, str | None]

Decode a base64-encoded data URI to image bytes.

Extracts and decodes base64 image data from a data URI. Supports common image formats (png, jpeg, jpg, gif, webp, svg).

Parameters:: data_uri (str) – Data URI string in format: data:image/{format};base64,{data}
Returns:: Tuple of (image_data, image_format) or (None, None) if decoding fails. image_format is the file extension without dot (e.g., “png”, “jpeg”)
Return type:: tuple[bytes or None, str or None]

Examples

>>> data = "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUA..."
>>> image_bytes, fmt = decode_base64_image(data)
>>> print(fmt)
png
>>> print(len(image_bytes))
85

Notes

This function validates the data URI format and safely handles malformed or invalid base64 data.

all2md.utils.images.decode_base64_image_to_file(data_uri: str, output_dir: str | Path | None = None, delete_on_exit: bool = True) → str | None

Decode a base64 data URI and write to a temporary file.

Convenience function that decodes base64 image data and writes it to a temporary file. Useful for renderers that require file paths rather than in-memory bytes.

Parameters:

data_uri (str) – Data URI string in format: data:image/{format};base64,{data}
output_dir (str, Path, or None, default = None) – Directory for temporary file. If None, uses system temp directory.
delete_on_exit (bool, default = True) – If True, file will be automatically deleted when Python exits. If False, caller is responsible for cleanup.

Returns:

Path to temporary file, or None if decoding failed

Return type:

str or None

Examples

>>> data = "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUA..."
>>> temp_path = decode_base64_image_to_file(data)
>>> print(temp_path)
/tmp/tmpxyz123.png

Notes

If delete_on_exit is False, the caller MUST manually delete the temporary file to avoid disk space issues. Track the file path and use Path(temp_path).unlink() when done.

all2md.utils.images.parse_image_data_uri(data_uri: str) → dict[str, Any] | None

Parse a data URI and extract metadata.

Extracts format, encoding, and data from a data URI without decoding. Supports data URIs with parameters like charset, base64 encoding marker, etc.

Parameters:: data_uri (str) – Data URI string (any format, not just base64)
Returns:: Dictionary with keys: ‘mime_type’, ‘format’, ‘encoding’, ‘data’, ‘params’, ‘charset’ Returns None if URI is malformed
Return type:: dict or None

Examples

>>> uri = "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUA..."
>>> info = parse_image_data_uri(uri)
>>> print(info['format'])
png
>>> print(info['encoding'])
base64

>>> uri = "data:text/plain;charset=utf-8;base64,SGVsbG8="
>>> info = parse_image_data_uri(uri)
>>> print(info['charset'])
utf-8

all2md.utils.images.is_data_uri(uri: str) → bool

Check if a string is a data URI.

Parameters:: uri (str) – String to check
Returns:: True if string is a data URI
Return type:: bool

Examples

>>> is_data_uri("data:image/png;base64,...")
True
>>> is_data_uri("https://example.com/image.png")
False

all2md.utils.images.detect_image_format_from_bytes(data: bytes, max_bytes: int = 32) → str | None

Detect image format from file content using magic bytes.

This function examines the first few bytes of image data to determine the format, providing more reliable detection than file extensions.

Parameters:

data (bytes) – Image file content (at least first 32 bytes for reliable detection)
max_bytes (int, default 32) – Number of bytes to examine (default is sufficient for all formats)

Returns:

Image format (lowercase extension without dot) or None if unrecognized

Return type:

str or None

Examples

>>> with open("photo.jpg", "rb") as f:
...     data = f.read(32)
...     fmt = detect_image_format_from_bytes(data)
>>> print(fmt)
jpg

Notes

Supported formats and their magic byte signatures:

PNG: Starts with x89PNGrnx1an
JPEG: Starts with xffxd8xff
GIF: Starts with GIF87a or GIF89a
WebP: Contains WEBP at offset 8
BMP: Starts with BM
TIFF: Starts with II*x00 (little-endian) or MMx00* (big-endian)
ICO: Starts with x00x00x01x00
SVG: Starts with <svg or <?xml (after whitespace)

all2md.utils.images.get_image_format_from_path(path: str | Path) → str | None

Extract image format from file path.

Parameters:: path (str or Path) – File path
Returns:: Image format (lowercase extension without dot) or None if not an image
Return type:: str or None

Examples

>>> get_image_format_from_path("photo.jpg")
'jpg'
>>> get_image_format_from_path("document.pdf")
None