A Python library for generating OPDS (Open Publication Distribution System) 2.0 compliant feeds using Pydantic and type hints.

Based on the OPDS 2.0 specification.

This package is not yet on PyPI. Install directly from GitHub:

pip install git+https://github.com/ArchiveLabs/opds2.0.git

pytest tests/ -v

To use this library, you must implement two key classes:

• DataProvider: Defines how to search and retrieve records. You must subclass and implement the search method.
• DataProviderRecord: Defines the structure of a single record in your catalog. You must subclass and implement the metadata, links, and images methods.

from opds2 import DataProvider, DataProviderRecord, Metadata, Link

class MyRecord(DataProviderRecord):
		def metadata(self):
				return Metadata(title="Example Book")
		def links(self):
				return [Link(href="/books/1", rel="self", type="application/epub+zip")]
		def images(self):
				return None

class MyProvider(DataProvider):
		@staticmethod
		def search(query, limit=50, offset=0):
				# Return a list of MyRecord instances and total count
				records = [MyRecord()]
				return records, len(records)

# Create a catalog
from opds2.catalog import create_catalog
catalog = MyProvider.create_catalog([r.to_publication() for r in records])
print(catalog.model_dump_json(indent=2))

See examples/openlibrary.py for a real-world integration with OpenLibrary.

• Catalog: Represents an OPDS 2.0 catalog/feed
• Publication: Represents a publication (book, audiobook, etc.)
• Metadata: Metadata for catalogs and publications
• Link: Links to resources
• Contributor: Authors, illustrators, publishers, etc.
• Navigation: Navigation links for browsing

• create_catalog(): Create a basic catalog with optional search
• create_search_catalog(): Create a catalog from search results

This library was inspired by The Palace Project's OPDS implementation.

AGPLv3 License. See LICENSE for details.