309 lines
9.9 KiB
Python
309 lines
9.9 KiB
Python
"""OPDS 1.2 catalog documents.
|
|
|
|
The dialect is Atom with the OPDS profile, because that is what ebook readers
|
|
actually implement: KOReader, Calibre, Moon+ Reader, Librera, FBReader and Aldiko
|
|
all browse OPDS 1.2, and its navigation/acquisition split maps exactly onto the
|
|
category/feed/article tree this server mirrors out of FreshRSS.
|
|
|
|
The two document kinds, and the rules that matter:
|
|
|
|
*Navigation feeds* (``kind=navigation``) are directories. Each entry is a
|
|
``rel="subsection"`` link to another feed, carrying a text description such as an
|
|
unread count.
|
|
|
|
*Acquisition feeds* (``kind=acquisition``) list articles. Each entry carries an
|
|
``rel="http://opds-spec.org/acquisition/open-access"`` link with an EPUB media
|
|
type, which is what a reader downloads. A plain ``http://opds-spec.org/acquisition``
|
|
link to the same URL is also emitted: readers disagree about which relation to
|
|
look for, and both are valid ways to say the same thing. An ``alternate`` link
|
|
points at the original article, which readers show as "open in browser".
|
|
|
|
Every feed carries ``rel="self"`` with the profile in its type, plus ``rel="start"``
|
|
back to the root, because readers navigate by these rather than by URL. Pagination
|
|
uses ``rel="next"``/``rel="previous"``/``rel="first"``.
|
|
|
|
Documents are built as strings rather than through a DOM library: the output is
|
|
small, fully determined, and easy to read in a test failure. Every interpolated
|
|
value goes through an escaper, and the tests parse the result with a strict XML
|
|
parser.
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
from dataclasses import dataclass, field
|
|
from datetime import UTC, datetime
|
|
|
|
from app import xhtml
|
|
|
|
ATOM_NAMESPACE = "http://www.w3.org/2005/Atom"
|
|
OPDS_NAMESPACE = "http://opds-spec.org/2010/catalog"
|
|
OPENSEARCH_NAMESPACE = "http://a9.com/-/spec/opensearch/1.1/"
|
|
DC_NAMESPACE = "http://purl.org/dc/elements/1.1/"
|
|
|
|
NAVIGATION_TYPE = "application/atom+xml;profile=opds-catalog;kind=navigation"
|
|
ACQUISITION_TYPE = "application/atom+xml;profile=opds-catalog;kind=acquisition"
|
|
OPENSEARCH_TYPE = "application/opensearchdescription+xml"
|
|
|
|
EPUB_TYPE = "application/epub+zip"
|
|
HTML_TYPE = "text/html"
|
|
|
|
ACQUISITION_REL = "http://opds-spec.org/acquisition"
|
|
OPEN_ACCESS_REL = "http://opds-spec.org/acquisition/open-access"
|
|
SUBSECTION_REL = "subsection"
|
|
ALTERNATE_REL = "alternate"
|
|
|
|
|
|
@dataclass(frozen=True)
|
|
class NavEntry:
|
|
"""One row of a navigation feed: a link deeper into the catalog."""
|
|
|
|
title: str
|
|
entry_id: str
|
|
href: str
|
|
updated: datetime
|
|
description: str | None = None
|
|
|
|
|
|
@dataclass(frozen=True)
|
|
class AcquisitionEntry:
|
|
"""One row of an acquisition feed: an article, as a downloadable book."""
|
|
|
|
title: str
|
|
entry_id: str
|
|
updated: datetime
|
|
download_href: str
|
|
author: str | None = None
|
|
summary: str | None = None
|
|
language: str | None = None
|
|
alternate_href: str | None = None
|
|
categories: tuple[tuple[str, str], ...] = ()
|
|
|
|
|
|
@dataclass(frozen=True)
|
|
class PageLinks:
|
|
"""Pagination targets, already absolute. Omitting one omits its link."""
|
|
|
|
first: str | None = None
|
|
previous: str | None = None
|
|
next: str | None = None
|
|
|
|
|
|
@dataclass(frozen=True)
|
|
class FeedLinks:
|
|
"""Everything a reader needs to place a feed in the catalog.
|
|
|
|
Pagination lives only in :attr:`pages`: an earlier version also carried
|
|
``next_url``/``previous_url``, and the renderer read those while callers set
|
|
``pages``, so the links silently never appeared.
|
|
"""
|
|
|
|
self_url: str
|
|
start_url: str | None = None
|
|
search_url: str | None = None
|
|
pages: PageLinks = field(default_factory=PageLinks)
|
|
|
|
|
|
def navigation_feed(
|
|
*,
|
|
feed_id: str,
|
|
title: str,
|
|
updated: datetime,
|
|
links: FeedLinks,
|
|
entries: list[NavEntry],
|
|
author: str = "OPDS",
|
|
subtitle: str | None = None,
|
|
) -> str:
|
|
"""Render a navigation feed."""
|
|
return _feed(
|
|
feed_id=feed_id,
|
|
title=title,
|
|
updated=updated,
|
|
links=links,
|
|
entries=[_nav_entry_xml(entry) for entry in entries],
|
|
kind_type=NAVIGATION_TYPE,
|
|
author=author,
|
|
subtitle=subtitle,
|
|
)
|
|
|
|
|
|
def acquisition_feed(
|
|
*,
|
|
feed_id: str,
|
|
title: str,
|
|
updated: datetime,
|
|
links: FeedLinks,
|
|
entries: list[AcquisitionEntry],
|
|
author: str = "OPDS",
|
|
subtitle: str | None = None,
|
|
) -> str:
|
|
"""Render an acquisition feed."""
|
|
return _feed(
|
|
feed_id=feed_id,
|
|
title=title,
|
|
updated=updated,
|
|
links=links,
|
|
entries=[_acquisition_entry_xml(entry) for entry in entries],
|
|
kind_type=ACQUISITION_TYPE,
|
|
author=author,
|
|
subtitle=subtitle,
|
|
)
|
|
|
|
|
|
def opensearch_description(
|
|
*,
|
|
search_url: str,
|
|
short_name: str,
|
|
description: str,
|
|
output_type: str = ACQUISITION_TYPE,
|
|
) -> str:
|
|
"""Render an OpenSearch description document.
|
|
|
|
Readers that support search advertise it by fetching this document, which is
|
|
why the root navigation feed links to it with ``rel="search"``.
|
|
"""
|
|
return "\n".join(
|
|
[
|
|
'<?xml version="1.0" encoding="utf-8"?>',
|
|
f'<OpenSearchDescription xmlns="{OPENSEARCH_NAMESPACE}">',
|
|
f" <ShortName>{_escape(short_name)}</ShortName>",
|
|
f" <Description>{_escape(description)}</Description>",
|
|
" <InputEncoding>UTF-8</InputEncoding>",
|
|
" <OutputEncoding>UTF-8</OutputEncoding>",
|
|
f' <Url type="{_attribute(output_type)}" '
|
|
f'template="{_attribute(search_url)}?q={{searchTerms}}&page={{startPage?}}"/>',
|
|
"</OpenSearchDescription>",
|
|
"",
|
|
]
|
|
)
|
|
|
|
|
|
# -- feed assembly -------------------------------------------------------
|
|
|
|
|
|
def _feed(
|
|
*,
|
|
feed_id: str,
|
|
title: str,
|
|
updated: datetime,
|
|
links: FeedLinks,
|
|
entries: list[str],
|
|
kind_type: str,
|
|
author: str,
|
|
subtitle: str | None,
|
|
) -> str:
|
|
lines = [
|
|
'<?xml version="1.0" encoding="utf-8"?>',
|
|
f'<feed xmlns="{ATOM_NAMESPACE}" xmlns:opds="{OPDS_NAMESPACE}" xmlns:dc="{DC_NAMESPACE}">',
|
|
f" <id>{_escape(feed_id)}</id>",
|
|
f" <title>{_escape(title)}</title>",
|
|
f" <updated>{_timestamp(updated)}</updated>",
|
|
]
|
|
if subtitle:
|
|
lines.append(f" <subtitle>{_escape(subtitle)}</subtitle>")
|
|
lines.append(f" <author><name>{_escape(author)}</name></author>")
|
|
lines.extend(_feed_links_xml(links, kind_type))
|
|
lines.extend(entries)
|
|
lines.extend(["</feed>", ""])
|
|
return "\n".join(lines)
|
|
|
|
|
|
def _feed_links_xml(links: FeedLinks, kind_type: str) -> list[str]:
|
|
"""Self, start, search and pagination links, in that order."""
|
|
rendered = [
|
|
f' <link rel="self" href="{_attribute(links.self_url)}" type="{_attribute(kind_type)}"/>'
|
|
]
|
|
if links.start_url:
|
|
rendered.append(
|
|
f' <link rel="start" href="{_attribute(links.start_url)}" '
|
|
f'type="{_attribute(NAVIGATION_TYPE)}"/>'
|
|
)
|
|
if links.search_url:
|
|
rendered.append(
|
|
f' <link rel="search" href="{_attribute(links.search_url)}" '
|
|
f'type="{_attribute(OPENSEARCH_TYPE)}"/>'
|
|
)
|
|
first = links.pages.first
|
|
if first:
|
|
rendered.append(
|
|
f' <link rel="first" href="{_attribute(first)}" type="{_attribute(kind_type)}"/>'
|
|
)
|
|
if links.pages.previous:
|
|
rendered.append(
|
|
f' <link rel="previous" href="{_attribute(links.pages.previous)}" '
|
|
f'type="{_attribute(kind_type)}"/>'
|
|
)
|
|
if links.pages.next:
|
|
rendered.append(
|
|
f' <link rel="next" href="{_attribute(links.pages.next)}" '
|
|
f'type="{_attribute(kind_type)}"/>'
|
|
)
|
|
return rendered
|
|
|
|
|
|
def _nav_entry_xml(entry: NavEntry) -> str:
|
|
lines = [
|
|
" <entry>",
|
|
f" <title>{_escape(entry.title)}</title>",
|
|
f" <id>{_escape(entry.entry_id)}</id>",
|
|
f" <updated>{_timestamp(entry.updated)}</updated>",
|
|
]
|
|
if entry.description:
|
|
lines.append(f' <content type="text">{_escape(entry.description)}</content>')
|
|
lines.extend(
|
|
[
|
|
f' <link rel="{SUBSECTION_REL}" href="{_attribute(entry.href)}" '
|
|
f'type="{_attribute(NAVIGATION_TYPE)}"/>',
|
|
" </entry>",
|
|
]
|
|
)
|
|
return "\n".join(lines)
|
|
|
|
|
|
def _acquisition_entry_xml(entry: AcquisitionEntry) -> str:
|
|
lines = [
|
|
" <entry>",
|
|
f" <title>{_escape(entry.title)}</title>",
|
|
f" <id>{_escape(entry.entry_id)}</id>",
|
|
f" <updated>{_timestamp(entry.updated)}</updated>",
|
|
]
|
|
if entry.author:
|
|
lines.append(f" <author><name>{_escape(entry.author)}</name></author>")
|
|
if entry.summary:
|
|
lines.append(f' <summary type="text">{_escape(entry.summary)}</summary>')
|
|
if entry.language:
|
|
lines.append(f" <dc:language>{_escape(entry.language)}</dc:language>")
|
|
for term, label in entry.categories:
|
|
lines.append(f' <category term="{_attribute(term)}" label="{_attribute(label)}"/>')
|
|
# Two acquisition relations to the same resource, because readers disagree
|
|
# about which one to look for; both are valid.
|
|
for rel in (OPEN_ACCESS_REL, ACQUISITION_REL):
|
|
lines.append(
|
|
f' <link rel="{rel}" href="{_attribute(entry.download_href)}" '
|
|
f'type="{_attribute(EPUB_TYPE)}"/>'
|
|
)
|
|
if entry.alternate_href:
|
|
lines.append(
|
|
f' <link rel="{ALTERNATE_REL}" href="{_attribute(entry.alternate_href)}" '
|
|
f'type="{_attribute(HTML_TYPE)}"/>'
|
|
)
|
|
lines.append(" </entry>")
|
|
return "\n".join(lines)
|
|
|
|
|
|
# -- formatting ----------------------------------------------------------
|
|
|
|
|
|
def _escape(text: str) -> str:
|
|
"""Escape text for a document body."""
|
|
return xhtml.escape_text(text)
|
|
|
|
|
|
def _attribute(value: str) -> str:
|
|
"""Escape a value for a double-quoted attribute."""
|
|
return xhtml.escape_attribute(value)
|
|
|
|
|
|
def _timestamp(moment: datetime) -> str:
|
|
"""Atom dates are RFC 3339 in UTC."""
|
|
return moment.astimezone(UTC).strftime("%Y-%m-%dT%H:%M:%SZ")
|