Metadata-Version: 2.4
Name: opds
Version: 0.1.0
Summary: Create your OPDS catalog with Python
License-Expression: AGPL-3.0-or-later
License-File: LICENSE
Keywords: opds
Author: david
Author-email: no@email.it
Requires-Python: >=3.8
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Development Status :: 5 - Production/Stable
Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
Classifier: Natural Language :: English
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Classifier: Typing :: Typed
Provides-Extra: lxml
Project-URL: Changelog, https://gitlab.com/Dacid99/opds/-/blob/master/CHANGELOG.md
Project-URL: Documentation, https://gitlab.com/Dacid99/opds/-/blob/master/README.md
Project-URL: Homepage, https://pypi.org/project/opds/
Project-URL: Issues, https://gitlab.com/Dacid99/opds/-/issues
Project-URL: Repository, https://gitlab.com/Dacid99/opds.git
Description-Content-Type: text/markdown

# OPDS python library

![PyPI - Downloads](https://img.shields.io/pypi/dm/opds)
![PyPI - Version](https://img.shields.io/pypi/v/opds)
![PyPI - Python Version](https://img.shields.io/pypi/pyversions/opds)
![PyPI - License](https://img.shields.io/pypi/l/opds)
![Pipeline](https://gitlab.com/Dacid99/opds/badges/master/pipeline.svg)

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

```bash
pip install opds
```

If you prefer to use lxml over the stdlib xml for parsing, use the 'lxml' extra

```bash
pip install opds[lxml]
```

## Usage

First of all check out the [the official OPDS catalog spec documentation][opds-spec].

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

```python
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

```python
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.

```python
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][opds-spec].

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

```python
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

```python
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](https://gitlab.com/Dacid99/cata-log/)
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](LICENSE).

Any contributions will be subject to the same licensing.

[opds-spec]: https://specs.opds.io/opds-1.2#22-navigation-feeds

