"""EPUB 3 generation, entirely in memory.
An EPUB is a ZIP with a strict shape, and a reader that rejects a book usually
does so because of a shape violation rather than because of its content. The
rules that matter here, and that the tests pin down:
* ``mimetype`` is the first entry, stored uncompressed, with no extra field. A
ZIP where it is deflated or not first is not an EPUB.
* ``META-INF/container.xml`` names the OPF, which is the package document.
* XML everywhere: the OPF, the navigation document, the NCX fallback and every
content document have to parse with a strict XML parser. Article bodies are
normalised by :mod:`app.xhtml` before they come anywhere near this module.
* A publication needs ``dc:identifier``, ``dc:title``, ``dc:language`` and a
``dcterms:modified`` timestamp; a navigation document marked ``properties="nav"``
is mandatory, and the NCX is kept as the EPUB 2 fallback because older readers
still look for it.
* Every manifest href resolves to a real entry, and every spine idref resolves to
a manifest item. Both are checked in the tests.
Nothing touches the filesystem: the ZIP is assembled in a ``BytesIO`` and handed
back as ``bytes``.
"""
from __future__ import annotations
import io
import logging
import zipfile
from dataclasses import dataclass, field
from datetime import UTC, datetime
from pathlib import Path
from app import images, urls, xhtml
LOGGER = logging.getLogger(__name__)
MIMETYPE = "application/epub+zip"
# Where each kind of part lives inside the package.
OPF_PATH = "OEBPS/content.opf"
NAV_PATH = "OEBPS/nav.xhtml"
NCX_PATH = "OEBPS/toc.ncx"
CSS_PATH = "OEBPS/styles/main.css"
COVER_PATH = "OEBPS/text/cover.xhtml"
ARTICLE_PATH = "OEBPS/text/article.xhtml"
IMAGE_DIR = "OEBPS/images"
XHTML_NAMESPACE = "http://www.w3.org/1999/xhtml"
OPF_NAMESPACE = "http://www.idpf.org/2007/opf"
DC_NAMESPACE = "http://purl.org/dc/elements/1.1/"
NCX_NAMESPACE = "http://www.daisy.org/z3986/2005/ncx/"
OPS_NAMESPACE = "http://www.idpf.org/2007/ops"
# A deliberately plain stylesheet. It sets a readable measure and gives code,
# quotes and images somewhere sane to sit, and it never fights the reader's own
# typography: no colours, no font families, no absolute sizes.
DEFAULT_STYLESHEET = """\
body { margin: 5%; line-height: 1.5; }
h1, h2, h3 { line-height: 1.25; page-break-after: avoid; }
.article-title { margin-bottom: 0.2em; }
.byline { margin-top: 0; font-size: 0.9em; opacity: 0.8; }
img { max-width: 100%; height: auto; }
figure { margin: 1em 0; }
figcaption { font-size: 0.9em; font-style: italic; }
blockquote { margin: 1em 1.5em; }
pre { white-space: pre-wrap; word-wrap: break-word; }
code, pre { font-family: monospace; }
table { border-collapse: collapse; max-width: 100%; }
td, th { border: 1px solid currentColor; padding: 0.3em 0.5em; }
hr { border: none; border-top: 1px solid currentColor; }
.source { margin-top: 2em; font-size: 0.85em; opacity: 0.8; }
.cover { text-align: center; }
.cover img { max-height: 90%; }
"""
# Content documents sit one directory below the images.
_TEXT_PREFIX = "../"
# A literal middle dot rather than the HTML entity ·: XML predefines only
# amp, lt, gt, quot and apos, and this package ships no DOCTYPE that could define
# any others, so an HTML entity here would make the document unparseable.
BYLINE_SEPARATOR = " \u00b7 "
class EpubTooLargeError(Exception):
"""The assembled book exceeded the configured size cap."""
@dataclass(frozen=True)
class BookImage:
"""An image embedded in the book."""
href: str # relative to the OPF, e.g. "images/img-1.png"
media_type: str
data: bytes
is_cover: bool = False
@property
def document_href(self) -> str:
"""The same image, as referenced from a document in ``text/``."""
return _TEXT_PREFIX + self.href
@dataclass
class Book:
"""Everything needed to write one EPUB."""
identifier: str
title: str
language: str
modified: datetime
content_xhtml: str
published: datetime | None = None
author: str | None = None
publisher: str | None = None
source_url: str | None = None
feed_title: str | None = None
images: list[BookImage] = field(default_factory=list)
stylesheet: str = DEFAULT_STYLESHEET
include_source_link: bool = True
@property
def cover_image(self) -> BookImage | None:
for image in self.images:
if image.is_cover:
return image
return None
def build_epub(book: Book) -> bytes:
"""Assemble a book into EPUB bytes."""
buffer = io.BytesIO()
# ZIP entry timestamps come from the book so that identical input produces
# identical bytes; a book that changes only because it was rebuilt would
# otherwise defeat every cache between here and the reader.
stamp = _zip_timestamp(book.modified)
with zipfile.ZipFile(buffer, "w", zipfile.ZIP_DEFLATED) as archive:
# The mimetype entry must come first and must not be compressed, which is
# why it is written through an explicit ZipInfo rather than writestr.
info = zipfile.ZipInfo("mimetype", date_time=stamp)
info.compress_type = zipfile.ZIP_STORED
info.external_attr = 0o644 << 16
archive.writestr(info, MIMETYPE)
_write(archive, "META-INF/container.xml", _container_xml(), stamp)
_write(archive, OPF_PATH, _opf_document(book), stamp)
_write(archive, NAV_PATH, _nav_document(book), stamp)
_write(archive, NCX_PATH, _ncx_document(book), stamp)
_write(archive, CSS_PATH, book.stylesheet, stamp)
_write(archive, COVER_PATH, _cover_document(book), stamp)
_write(archive, ARTICLE_PATH, _article_document(book), stamp)
for image in book.images:
package_dir = OPF_PATH.rsplit("/", 1)[0]
_write(archive, f"{package_dir}/{image.href}", image.data, stamp)
return buffer.getvalue()
def build_article_epub(
item,
*,
epub_config,
catalog_config,
fetcher=None,
max_content_bytes: int = 1_048_576,
) -> bytes:
"""Turn one FreshRSS item into an EPUB.
The article body comes from FreshRSS, normalised by :mod:`app.xhtml`. Images
are embedded when a fetcher is supplied, and any that cannot be fetched are
dropped from the body rather than left pointing at the network -- a book that
claims to work offline should.
"""
article = xhtml.parse_article(
item.content_html, base_url=item.url or "", max_input_bytes=max_content_bytes
)
book_images: list[BookImage] = []
image_map: dict[str, str | None] | None = None
if epub_config.include_images and fetcher is not None:
wanted = article.image_urls[: epub_config.max_images_per_article]
fetched = fetcher.fetch_all(wanted)
image_map = {}
for url in wanted:
image = fetched.get(url)
if image is None:
image_map[url] = None
continue
index = len(book_images) + 1
href = f"images/img-{index}{images.MEDIA_TYPES[image.media_type]}"
book_images.append(BookImage(href=href, media_type=image.media_type, data=image.data))
image_map[url] = _TEXT_PREFIX + href
elif article.image_urls:
# Keeping remote URLs means the OPF has to declare remote resources, which
# is handled by the caller not setting include_images.
image_map = None
book = Book(
identifier=urls.stable_urn("book", item.id),
title=item.title,
language=catalog_config.language,
modified=item.updated_at,
published=item.published_at,
content_xhtml=article.to_xhtml(image_map),
author=item.author or catalog_config.author,
publisher=catalog_config.publisher,
source_url=item.url,
feed_title=item.feed_title,
images=book_images,
include_source_link=epub_config.include_source_link,
stylesheet=_load_stylesheet(epub_config.stylesheet),
)
if epub_config.cover_image:
_choose_cover(book)
data = build_epub(book)
if len(data) > epub_config.max_epub_bytes:
raise EpubTooLargeError(
f"book is {len(data)} bytes, over the {epub_config.max_epub_bytes} byte cap"
)
return data
def _load_stylesheet(path: str | None) -> str:
"""Use the configured stylesheet, falling back to the built-in one."""
if not path:
return DEFAULT_STYLESHEET
try:
return Path(path).read_text(encoding="utf-8")
except OSError as exc:
LOGGER.warning("cannot read stylesheet %s (%s); using the built-in one", path, exc)
return DEFAULT_STYLESHEET
def _choose_cover(book: Book) -> None:
"""Promote the first suitably large image to be the book's cover.
A reader's library view shows a cover or a blank tile, and a feed's lead image
is almost always the right one. Images whose size cannot be read are skipped:
promoting an unknown image risks a cover that is a tracking pixel.
"""
for index, image in enumerate(book.images):
size = images.dimensions(image.data)
if size is None:
continue
width, height = size
if images.looks_like_a_cover(width, height):
book.images[index] = BookImage(
href=image.href,
media_type=image.media_type,
data=image.data,
is_cover=True,
)
return
def _write(
archive: zipfile.ZipFile,
path: str,
content: str | bytes,
stamp: tuple[int, int, int, int, int, int],
) -> None:
"""Write one entry, encoding text parts and passing binary parts through."""
info = zipfile.ZipInfo(path, date_time=stamp)
info.compress_type = zipfile.ZIP_DEFLATED
info.external_attr = 0o644 << 16
data = content if isinstance(content, bytes) else content.encode("utf-8")
archive.writestr(info, data)
def _zip_timestamp(moment: datetime) -> tuple[int, int, int, int, int, int]:
"""A ZIP timestamp, clamped to the range the format can express (from 1980)."""
year = max(1980, min(2107, moment.year))
return (year, moment.month, moment.day, moment.hour, moment.minute, moment.second)
# -- documents -----------------------------------------------------------
def _container_xml() -> str:
return (
'\n'
'
This article had no content to download.
") if book.include_source_link and book.source_url: lines.append( 'Originally published at ' f'{_escape(book.source_url)}.
' ) lines.extend([" ", "", ""]) return "\n".join(lines) # -- formatting ---------------------------------------------------------- def _escape(text: str) -> str: """XML-escape text for a document body or an attribute value.""" return xhtml.escape_text(text).replace('"', """) def _timestamp(moment: datetime) -> str: """An EPUB date: UTC, seconds precision, ``Z`` suffix.""" return moment.astimezone(UTC).strftime("%Y-%m-%dT%H:%M:%SZ") def _date_only(moment: datetime) -> str: return moment.astimezone(UTC).strftime("%Y-%m-%d")