"""Image metadata: media type sniffing and dimension parsing. Two small jobs, both in service of the EPUB writer. *Sniffing.* A feed image is as likely to arrive as ``application/octet-stream`` or ``text/plain`` as with a correct ``Content-Type``. An EPUB manifest entry whose media type does not match the bytes is invalid, so the type is decided from the actual magic bytes and the response header is only a fallback. *Dimensions.* Picking a cover means knowing which image is big enough to be one. Reading a PNG header or a JPEG start-of-frame costs nothing and avoids pulling in an imaging library (and its C dependencies) just to answer "is this wide?". """ from __future__ import annotations import struct # Types the EPUB writer will embed. SVG is deliberately absent: it can carry # script and external references, and an image in an article body has no reason # to need either. MEDIA_TYPES = { "image/jpeg": ".jpg", "image/png": ".png", "image/gif": ".gif", "image/webp": ".webp", } _MEDIA_TYPE_ALIASES = { "image/jpg": "image/jpeg", "image/pjpeg": "image/jpeg", "image/x-png": "image/png", "image/x-gif": "image/gif", } def normalise_media_type(raw: str | None) -> str | None: """Map a Content-Type header onto a media type this server will embed.""" if not raw: return None # Strip parameters: "image/jpeg; charset=binary" is still a JPEG. base = raw.split(";", 1)[0].strip().lower() base = _MEDIA_TYPE_ALIASES.get(base, base) return base if base in MEDIA_TYPES else None def sniff_media_type(data: bytes) -> str | None: """Identify an image from its leading bytes, or None if unrecognised.""" if len(data) < 12: return None if data.startswith(b"\xff\xd8\xff"): return "image/jpeg" if data.startswith(b"\x89PNG\r\n\x1a\n"): return "image/png" if data.startswith((b"GIF87a", b"GIF89a")): return "image/gif" if data.startswith(b"RIFF") and data[8:12] == b"WEBP": return "image/webp" return None def identify(data: bytes, declared: str | None) -> str | None: """Decide the media type for a fetched image. The bytes win. A declared type is used only when the bytes are recognisable as nothing else, and never to *override* a successful sniff -- otherwise a mislabelled payload would produce an invalid EPUB manifest. """ sniffed = sniff_media_type(data) if sniffed is not None: return sniffed return normalise_media_type(declared) def dimensions(data: bytes) -> tuple[int, int] | None: """Return ``(width, height)`` in pixels, or None when it cannot be read. Only the container headers are parsed: the value is used to decide whether an image is a plausible cover, so "unknown" is a perfectly good answer. """ sniffed = sniff_media_type(data) try: if sniffed == "image/png": return _png_dimensions(data) if sniffed == "image/gif": return _gif_dimensions(data) if sniffed == "image/jpeg": return _jpeg_dimensions(data) if sniffed == "image/webp": return _webp_dimensions(data) except (struct.error, IndexError, ValueError): return None return None def _png_dimensions(data: bytes) -> tuple[int, int] | None: # IHDR is required to be the first chunk: 8 signature bytes, then length and # type, so width and height sit at a fixed offset. if len(data) < 24: return None width, height = struct.unpack(">II", data[16:24]) return (width, height) if width and height else None def _gif_dimensions(data: bytes) -> tuple[int, int] | None: if len(data) < 10: return None width, height = struct.unpack(" tuple[int, int] | None: if len(data) < 30: return None chunk = data[12:16] if chunk == b"VP8X": width = int.from_bytes(data[24:27], "little") + 1 height = int.from_bytes(data[27:30], "little") + 1 return (width, height) if chunk == b"VP8 ": # Lossy: dimensions are 14 bytes into the frame header, after the # start code, with 14 bits of width and 14 of height. if len(data) < 30: return None start = 26 width = int.from_bytes(data[start : start + 2], "little") & 0x3FFF height = int.from_bytes(data[start + 2 : start + 4], "little") & 0x3FFF return (width, height) if width and height else None if chunk == b"VP8L": bits = int.from_bytes(data[21:25], "little") width = (bits & 0x3FFF) + 1 height = ((bits >> 14) & 0x3FFF) + 1 return (width, height) return None # JPEG start-of-frame markers, which carry the dimensions. _SOF_MARKERS = frozenset( { 0xC0, 0xC1, 0xC2, 0xC3, 0xC5, 0xC6, 0xC7, 0xC9, 0xCA, 0xCB, 0xCD, 0xCE, 0xCF, } ) def _jpeg_dimensions(data: bytes) -> tuple[int, int] | None: """Walk the JPEG segment chain to the start-of-frame marker. A JPEG has no fixed header offset, so the segments have to be stepped over until the frame header appears. This is bounded work: it stops at the first frame marker, which always precedes the image data. """ index = 2 # skip the SOI marker (FF D8) limit = len(data) while index + 9 < limit: if data[index] != 0xFF: index += 1 continue marker = data[index + 1] if marker in (0xD8, 0x01) or 0xD0 <= marker <= 0xD7: index += 2 continue if marker == 0xDA: # start of scan: no frame header found return None length = struct.unpack(">H", data[index + 2 : index + 4])[0] if length < 2: return None if marker in _SOF_MARKERS: height, width = struct.unpack(">HH", data[index + 5 : index + 9]) return (width, height) if width and height else None index += 2 + length return None def looks_like_a_cover(width: int, height: int) -> bool: """Whether an image is a plausible book cover. A lead image is usually landscape and wide; a thumbnail, icon or tracking pixel is not. The bar is deliberately low -- it only has to beat a blank tile in a reader's library view. """ return width >= 400 and height >= 200