Initial commit

This commit is contained in:
2026-11-15 18:15:03 -05:00
commit b76aea2899
36 changed files with 9424 additions and 0 deletions

193
app/images.py Normal file
View File

@@ -0,0 +1,193 @@
"""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("<HH", data[6:10])
return (width, height) if width and height else None
def _webp_dimensions(data: bytes) -> 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