oxdef / lib2opds Goto Github PK

Static OPDS catalog generator powered by Python for local e-book library to be hosted on web server.

License: GNU General Public License v3.0

Python 99.66% Makefile 0.34%

opds opds-catalog opds-feed opds-generator ebook epub

lib2opds's Introduction

Lib2OPDS

lib2opds generates OPDS (version 1.2) catalog for local e-book library so it can be hosted utilizing web server. Currently meta data extraction is supported only for ePUB format.

Features

Directory hierarchy support
Virtual directories: new books, authors, etc.
ePUB format: metadata extraction, thumbnail generation
PDF format: metadata extraction, thumbnail generation
"Lazy" updating of feeds. lib2opds re-generates feeds only when new files are added into the library
Sidecar files for metadata extraction
Global and local configuration files as well as command line options
Caching for better processing of libraries with many books

How to install

lib2opds is distributed on PyPI. The best way to install it is with pipx.

pipx install lib2opds

How to use

$ tree ./test-library/
./test-library/
├── Linux
│   └── How Linux Works - Brian Ward.epub
└── Science Fiction
    ├── All Systems Red.epub
    └── I, Robot - Isaac Asimov.epub

$ lib2opds --opds-base-uri "/opds/" --library-base-uri "/library/" --library-dir "./test-library" --opds-dir "./output"

$ tree ./output/
./output/

├── covers
│   ├── 03e1b3fe-66b2-43eb-b9f1-da72813419e2
│   ├── 14cdd72c-680c-491c-a017-ddd0d2dbb1d2
│   └── e01dab66-3f78-402a-9ac8-83ebc6b24f11
├── feeds
│   ├── 101bcb13-37bf-4e13-a543-22c5ff3567d3.xml
│   ├── 127ae484-af53-4056-9cff-517984321e26.xml
│   └── db1d5760-72f5-4f23-af42-d9d6406207c9.xml
└── index.xml

/etc/lib2opds.ini is used by default and options can be overridden via command line arguments.

Example of configuration file for Nginx:

location /library {
        alias /library-dir;
}

location /opds {
        auth_basic  "Library Area";
        auth_basic_user_file /etc/nginx/htpasswd;
        alias /opds-dir;
        index index.xml;
}

location /opds/covers {
        alias /opds-dir/covers;
}

Library location here is not protected with basic auth because of the bug in some e-book reader software.

Tested devices and applications

PocketBook devices with "Network Libraries" feature
KyBook 3 eBook Reader
Foliate eBook Reader

lib2opds's People

Contributors

Stargazers

Watchers

Forkers

lake-of-fire

lib2opds's Issues

Debianise lib2opds

Currently all the main dependencies are available in Debian GNU/Linux distribution with sometimes a bit lower versions. It makes possible to distribute lib2opds as a regular deb package. See HowToPackageForDebian as well as Python/Packaging.

Provide distribution via Docker

Current approach of distribution lib2opds does not provide releases as well as does not have proper level of isolation in case of installation (only Python virtualenv) .

Distribution of releases via Docker images should solve these problems

Add SBOMs generation

clear_opds_dir option clears the cache

Provide manual pages

See Developing for pipx and pycowsay as example.

Add security considerations into SECURITY.md

XML parsing risks and defusedxml utilizing to minimize it
ePUB/ZIP extracting and forcing UUIDs for filenames
OPDS catalog access restriction
3rd party dependencies

Implement caching

To speed-up ebook files processing local caching could be helpful. There is already support for side-car files (for metadata and cover images as well) so it can be used for that purpose.

Support for alternative formats to download publication

From OPDS spec:

If the Publication was available in multiple formats as unique Resources, they would simply be listed:

<link rel="http://opds-spec.org/acquisition/borrow" 
      href="/content/borrow/4561.mobi"
      type="application/x-mobipocket-ebook" />
 
<link rel="http://opds-spec.org/acquisition/borrow" 
      href="/content/borrow/4561.epub"
      type="application/epub+zip" />

Migrate to pydantic and pydantic-settings

Add support for navigating to various feeds from a catalog entry

OPDS spec "5.2.3. Grouping Relations":

An OPDS Catalog Entry may include one or more atom:link elements to Navigation Feeds and Acquisition Feeds which contain it, either directly or indirectly. This specification uses the IANA standard link relation collection for this purpose.
An OPDS client may choose to group together all entries in an OPDS Feed whose collection link points to a given target.

For example, it could be a feed for specific author.

"Mixed type" exception while processing empty folders

Steps to reproduce:

Have an empty folder in library
Run lib2opds

Current result

                                                 ^^^^^^^^^
  File ".../site-packages/lib2opds/opds.py", line 81, in dir2odps
    raise Exception("Mixed dir {}".format(dirpath))
Exception: Mixed dir .../library/FOLDERNAME

Processing of PDF publications with inaccurate metadata

It is common case when PDF publication has inaccurate metadata (e.g. author and title). To solve it lib2opds provides sidecar metadata files support. The problem is cover extraction is also made inside metadata extraction and with using of sidecar files covers will be lost.

Possible workaround is to use metadata from sidecar file as default values for publication so lib2opds can extract cover as well. It is important to provide option to force using only data from sidecar files (because proper data can be overwritten with inaccurate information).