sebsync 1.0.0__py3-none-any.whl

sebsync-1.0.0.dist-info/AUTHORS.md

@@ -0,0 +1,3 @@
+The following authors have contributed to sebsync:
+
+- Paul Bryan

sebsync-1.0.0.dist-info/LICENSE

@@ -0,0 +1,19 @@
+© 2024 sebsync authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sebsync-1.0.0.dist-info/METADATA

@@ -0,0 +1,83 @@
+Metadata-Version: 2.1
+Name: sebsync
+Version: 1.0.0
+Summary: Synchronize Standard Ebooks catalog with local EPUB collection.
+Home-page: https://github.com/pbryan/sebsync/
+License: MIT
+Keywords: standard,ebook,book,synchronization,sync,download
+Author: sebsync authors
+Requires-Python: >=3.10,<4.0
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: System :: Archiving :: Mirroring
+Requires-Dist: click (>=8.1,<9.0)
+Requires-Dist: requests (>=2.32,<3.0)
+Description-Content-Type: text/markdown
+
+# sebsync
+
+sebsync is a simple script to synchronize the [Standard Ebooks](https://standardebooks.org/)
+catalog with your local EPUB collection.
+
+## How it works
+
+The script reads the Standard Ebooks [OPDS feed](https://standardebooks.org/feeds) and
+reconciles the ebooks in their catalog against the EPUBs in your local filesystem,
+downloading new ones or updating existing ones as necessary.
+
+If a new ebook is detected in the catalog, then it will be downloaded into your downloads
+directory. If an updated version of a book is detected in the catalog that is already in your
+local filesystem, then the updated version will be downloaded and stored in the existing local
+file.
+
+The script also detects extraneous local ebooks (local ebooks not found in the Standard
+Ebooks catalog). This can can occur when Standard Ebooks changes the identifier of a previously
+published ebook. It's a rare occurrence, and it's generally safe to delete such files.
+
+## Requirements
+
+This script uses Standard Ebooks' OPDS feed to access metadata on all books their catalog. In
+order to do so, you need to be a member of the Standard Ebooks
+[Patrons Circle](https://standardebooks.org/donate#patrons-circle) (or have previously produced
+an ebook for Standard Ebooks). If you're not already a Standard Ebooks patron, please consider
+becoming one. It's a tremendously valuable project, deserving of your support.
+
+## Installation
+
+```
+pipx install sebsync
+```
+
+## Example usage
+
+```
+sebsync --email addr@example.com --books /home/user/MyBooks --downloads /home/user/MyBooks/Downloads
+```
+
+## Questions and answers
+
+Q1. *Why use a separate downloads directory for new ebooks?*
+
+A1. This is a feature for those who want to easily recognize new ebooks, and to manually
+rename and/or categorize them within their library. If this feature is not useful for you,
+simply set `--downloads` to be the same directory as `--books`.
+
+Q2. *What is pipx?*
+
+A2. [pipx](https://pipx.pypa.io/) is a utility that allows Python packages like sebsync to
+be installed in an isolated environment. This makes it really easy to install and run such
+scripts without interfering with other Python package installations.
+
+Q3. *Does this script support Kindle books?*
+
+A3. Not presently. A cursory analysis of the Standard Ebooks AZW3 structure suggests that there
+currently isn't a reliable method to reconcile Kindle ebooks with the OPDS feed catalog. If
+this feature is important to you, please let us know by voting for
+[this issue](https://github.com/pbryan/sebsync/issues/2) in GitHub.
+

sebsync-1.0.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+sebsync.py,sha256=u1IDAS_Z86orsx__hpSzjtO68X1cJZs-FLAZry8S-kQ,8426
+sebsync-1.0.0.dist-info/AUTHORS.md,sha256=Ynzo5ZrXeZI7TPmSWz7ZyKWaQKkWB96AHpw-_ihHhiI,65
+sebsync-1.0.0.dist-info/LICENSE,sha256=2nOKwUpN7p1uc32KrEnDt1EVY16pFgeIyV1iyQr0Kw8,1048
+sebsync-1.0.0.dist-info/METADATA,sha256=CtkSsLheBoKA6BQA6RUoE7fLBM0VMrc7l7S3GaNma1o,3406
+sebsync-1.0.0.dist-info/WHEEL,sha256=sP946D7jFCHeNz5Iq4fL4Lu-PrWrFsgfLXbbkciIZwg,88
+sebsync-1.0.0.dist-info/entry_points.txt,sha256=vLL74SO0m9xORcjSlCvDwkgJe3qSqSWB13VAitn2mxc,40
+sebsync-1.0.0.dist-info/RECORD,,

sebsync-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: poetry-core 1.9.0
+Root-Is-Purelib: true
+Tag: py3-none-any

sebsync-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+sebsync=sebsync:main
+

sebsync.py

@@ -0,0 +1,271 @@
+"""Synchronize Standard Ebooks catalog with local EPUB collection."""
+
+import click
+import requests
+import xml.etree.ElementTree as ElementTree
+import zipfile
+
+from contextlib import suppress
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from requests.auth import HTTPBasicAuth
+
+
+_dry_run: bool = False
+_quiet: bool = False
+_verbose: bool = False
+
+
+class Status:
+    NEW = click.style("N", fg="green")
+    UPDATE = click.style("U", fg="blue")
+    EXTRA = click.style("X", fg="yellow")
+
+
+_epilog = f"""
+    The following statuses are reported:
+
+    \b
+    {Status.NEW}: new (downloads the new ebook to downloads directory)
+    {Status.UPDATE}: update (overwrites the existing local ebook with new version)
+    {Status.EXTRA}: extraneous (local ebook was not found in Standard Ebooks catalog)
+"""
+
+
+@dataclass
+class StandardEbook:
+    """Metadata for ebook in Standard Ebooks OPDS catalog."""
+
+    id: str
+    title: str
+    author: str
+    href: str
+    updated: datetime
+
+
+@dataclass
+class LocalEbook:
+    """Metadata for ebook in local directory."""
+
+    id: str
+    title: str
+    path: Path
+    modified: datetime
+
+
+# map type selection to link title in OPDS catalog
+type_selector = {
+    "compatible": "Recommended compatible epub",
+    "kobo": "Kobo Kepub epub",
+    "advanced": "Advanced epub",
+}
+
+
+def echo_status(path: Path, status: str) -> None:
+    if not _quiet:
+        click.echo(f"{status} {path}")
+
+
+def if_exists(path: Path) -> Path | None:
+    return path if path.exists() else None
+
+
+def fromisoformat(text: str) -> datetime:
+    """Convert RFC 3339 string into datetime; compatible with Python 3.10."""
+    if not text.endswith("Z"):
+        raise ValueError("expecting RFC 3339 formatted string")
+    d = datetime.fromisoformat(text.rstrip("Z"))
+    return datetime(
+        d.year, d.month, d.day, d.hour, d.minute, d.second, d.microsecond, timezone.utc
+    )
+
+
+def get_remote_ebooks(opds_url: str, email: str, type: str) -> dict[str, StandardEbook]:
+    """Return Standard Ebooks metadata for EPUBs from the OPDS catalog."""
+    ns = {"atom": "http://www.w3.org/2005/Atom", "dc": "http://purl.org/dc/terms/"}
+    ebooks = {}
+    response = requests.get(opds_url, stream=True, auth=HTTPBasicAuth(email, ""))
+    response.raw.decode_content = True
+    root = ElementTree.parse(response.raw).getroot()
+    for entry in root.iterfind(".//atom:entry", ns):
+        ebook = StandardEbook(
+            id=entry.find("dc:identifier", ns).text,
+            title=entry.find("atom:title", ns).text,
+            author=entry.find("atom:author", ns).find("atom:name", ns).text,
+            href=entry.find(f".//atom:link[@title='{type_selector[type]}']", ns).attrib["href"],
+            updated=fromisoformat(entry.find("atom:updated", ns).text),
+        )
+        ebooks[ebook.id] = ebook
+    return ebooks
+
+
+def get_local_ebooks(dir: Path) -> dict[str, LocalEbook]:
+    """Return metadata of Standard EPUBs in the specified directory and subdirectories."""
+    ebooks = {}
+    for path in dir.glob("**/*.epub"):
+        with suppress():  # ignore invalid ebook
+            with zipfile.ZipFile(path) as zip:
+                with zip.open("META-INF/container.xml") as file:
+                    root = ElementTree.parse(file)
+                    ns = {"container": "urn:oasis:names:tc:opendocument:xmlns:container"}
+                    rootfile = root.find(".//container:rootfile", ns).attrib["full-path"]
+                with zip.open(rootfile) as file:
+                    root = ElementTree.parse(file)
+                    ns = {
+                        "opf": "http://www.idpf.org/2007/opf",
+                        "dc": "http://purl.org/dc/elements/1.1/",
+                    }
+                    metadata = root.find("opf:metadata", ns)
+                    id = metadata.find("dc:identifier", ns)
+                    if id is None or "standardebooks.org" not in id.text:
+                        continue
+                    modified = metadata.find(".//opf:meta[@property='dcterms:modified']", ns)
+                    ebook = LocalEbook(
+                        id=id.text,
+                        title=metadata.find(".//dc:title", ns).text,
+                        path=path,
+                        modified=fromisoformat(modified.text),
+                    )
+                    ebooks[ebook.id] = ebook
+    return ebooks
+
+
+def download_ebook(url: str, path: Path) -> None:
+    """Download the ebook at the specified URL into the specified path."""
+    if not _dry_run:
+        response = requests.get(url, stream=True)
+        with path.open("wb") as file:
+            for chunk in response.iter_content(chunk_size=1 * 1024 * 1024):
+                file.write(chunk)
+
+
+def sortable_author(author: str) -> str:
+    """Return the sortable name of the given author."""
+    suffixes = {"Jr.", "Sr.", "Esq.", "PhD"}
+    split = author.split()
+    if len(split) < 2:
+        return author
+    last = split.pop().rstrip(",")
+    suffix = None
+    if last in suffixes:
+        suffix = last
+        last = split.pop()
+    result = last
+    if split:
+        result += f", {' '.join(split)}"
+    if suffix:
+        result += f", {suffix}"
+    return result
+
+
+def ebook_filename(ebook: StandardEbook) -> str:
+    """Return an appropriate EPUB file name for the given Standard Ebooks author and title."""
+    replace = {"/": "-", "‘": "'", "’": "'", '"': "'", "“": "'", "”": "'"}
+    result = f"{sortable_author(ebook.author)} - {ebook.title}.epub"
+    for k, v in replace.items():
+        result = result.replace(k, v)
+    return result
+
+
+@click.command(help=__doc__, epilog=_epilog)
+@click.option(
+    "--books",
+    help="Directory where local books are stored.",
+    type=click.Path(exists=True, file_okay=False, dir_okay=True, writable=True, path_type=Path),
+    default=if_exists(Path.home() / "Books"),
+)
+@click.option(
+    "--downloads",
+    help="Directory where new ebooks are downloaded.",
+    type=click.Path(exists=True, file_okay=False, dir_okay=True, writable=True, path_type=Path),
+    default=if_exists(Path.home() / "Downloads"),
+)
+@click.option(
+    "--force-update",
+    help="Force update of all local ebooks.",
+    is_flag=True,
+)
+@click.option(
+    "--dry-run",
+    help="Perform a trial run with no changes made.",
+    is_flag=True,
+)
+@click.option(
+    "--email",
+    help="Email address to authenticate with Standard Ebooks.",
+    required=True,
+)
+@click.help_option()
+@click.option(
+    "--opds",
+    help="URL of Standard Ebooks OPDS catalog.",
+    default="https://standardebooks.org/feeds/opds/all",
+)
+@click.option(
+    "--quiet",
+    help="Suppress non-error messages.",
+    is_flag=True,
+)
+@click.option(
+    "--type",
+    type=click.Choice(list(type_selector.keys())),
+    help="EPUB type to download.",
+    default="compatible",
+)
+@click.option(
+    "--verbose",
+    help="Increase verbosity.",
+    is_flag=True,
+)
+@click.version_option(package_name="sebsync")
+def sebsync(
+    books: Path,
+    downloads: Path,
+    dry_run: bool,
+    email: str,
+    force_update: bool,
+    opds: str,
+    quiet: bool,
+    type: str,
+    verbose: bool,
+):
+    global _dry_run
+    global _verbose
+    global _quiet
+
+    _dry_run = dry_run
+    _verbose = verbose and not quiet  # quiet wins
+    _quiet = quiet
+
+    remote_ebooks = get_remote_ebooks(opds, email, type)
+    if not remote_ebooks:
+        raise click.ClickException("OPDS download failed. Is email address correct?")
+    if _verbose:
+        click.echo(f"Found {len(remote_ebooks)} remote ebooks.")
+
+    local_ebooks = get_local_ebooks(downloads) | get_local_ebooks(books)
+    if _verbose:
+        click.echo(f"Found {len(local_ebooks)} local ebooks.")
+
+    for remote_ebook in remote_ebooks.values():
+        if local_ebook := local_ebooks.get(remote_ebook.id):
+            if remote_ebook.updated != local_ebook.modified or force_update:
+                echo_status(local_ebook.path, Status.UPDATE)
+                download_ebook(remote_ebook.href, local_ebook.path)
+        else:
+            path = downloads / ebook_filename(remote_ebook)
+            echo_status(path, Status.NEW)
+            download_ebook(remote_ebook.href, path)
+
+    for local_ebook in local_ebooks.values():
+        if local_ebook.id not in remote_ebooks:
+            echo_status(local_ebook.path, Status.EXTRA)
+
+
+def main():
+    sebsync(show_default=True)
+
+
+if __name__ == "__main__":
+    main()