OPDS python library

This package allows you to easily compose an OPDS version 1.2 catalog.

No reason to touch any xml yourself, everything is wrapped in semantic Python classes.

Installation

Install from PyPI

pip install opds

Note

This package will remain functional and safe without regular updates.

This package has NO dependencies. Also OPDS1.2 is a stable standardized format.

Therefore the only activity on this repo will be features and fixes. If there is low or no activity that does not indicate security or usability deficits.

Usage

First of all check out the the official OPDS catalog spec documentation.

It has a lot of useful and instructive examples that will help you understand what to add to your catalog.

A single OPDS catalog file is represented by the OPDSCatalog class

opds_catalog = opds.OPDSCatalog(title="Example")

The catalog comes with all required metadata configured by initialization. It is stored in the metadata member, you can use all methods of the list container to add more.

For example

summary = opds.Metadata(name="summary", value="An example OPDS catalog")
opds_catalog.metadata.append(summary)

Every catalog comes with 3 default namespaces: Atom (default), DublinCore (dc) and OPDS (opds). Add more by adding them to the attributes of the OPDSCatalog. You typically won't need to.

As special type of metadata one typically wants to add links for navigation to other catalogs of the same server. For quality of life there are Link subclasses for the most common link types.

other_catalog_link = opds.AcquisitionFeedLink(href="/other-catalog", rel=Link.Rel.SUBSECTION)
self_link = opds.NavigationFeedLink(href="/this-url", role=Link.Rel.SELF)
start_link = opds.NavigationFeedLink(href="/root-url", role=Link.Rel.START)
opds_catalog.links.extend([ other_catalog_link, self_link, start_link ])

The difference between navigation and acquisition feeds is explained in the OPDS spec.

After all metadata is defined, we add the entries to the catalog.

entry_1 = opds.Entry(title="Book 1", uid="book_1")
opds_catalog.entries.append(summary)

Entries hold metadata and links just like the catalog. Adding and manipulating them is completely analogous.

After everything is set up, write the catalog to xml bytes

opds_bytes = opds_catalog.write()

Done.

Disclaimer

There was no AI used in creating this package. Every single line was typed by human hand.

The source code was originally created for the Cata-Log project and later externalized for use across other projects.

License

This software is proudly released under the GNU Affero General Public License v3.0 or later (AGPLv3) open-source license.

Any contributions will be subject to the same licensing.