Initial commit
This commit is contained in:
308
app/opds.py
Normal file
308
app/opds.py
Normal file
@@ -0,0 +1,308 @@
|
||||
"""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")
|
||||
Reference in New Issue
Block a user