sebsync 1.0a2__tar.gz → 1.0a4__tar.gz

sebsync-1.0a4/PKG-INFO

@@ -0,0 +1,85 @@
+Metadata-Version: 2.1
+Name: sebsync
+Version: 1.0a4
+Summary: Synchronize Standard Ebooks catalog with local ebooks.
+Home-page: https://github.com/pbryan/sebsync/
+License: MIT
+Keywords: ebook,downloader,standard,book
+Author: sebsync authors
+Requires-Python: >=3.10,<4.0
+Classifier: Development Status :: 3 - Alpha
+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 :: Other/Nonlisted Topic
+Requires-Dist: click (>=8.1,<9.0)
+Requires-Dist: requests (>=2.32,<3.0)
+Project-URL: Documentation, https://github.com/pbryan/sebsync/tree/main/docs
+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 can also detect 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 occurance, 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.0a4/README.md

@@ -0,0 +1,62 @@
+# 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 can also detect 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 occurance, 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.0a2 → sebsync-1.0a4}/pyproject.toml

@@ -8,7 +8,7 @@ target-version = ['py312']
 
 [tool.poetry]
 name = "sebsync"
-version = "1.0alpha2"
+version = "1.0a4"
 description = "Synchronize Standard Ebooks catalog with local ebooks."
 readme = "README.md"
 authors = ["sebsync authors"]

{sebsync-1.0a2 → sebsync-1.0a4}/sebsync.py

@@ -1,4 +1,4 @@
-"""Synchronize Standard Ebooks catalog with local ebooks."""
+"""Synchronize Standard Ebooks catalog with a local EPUB collection."""
 
 import click
 import requests
@@ -6,7 +6,7 @@ import xml.etree.ElementTree as ElementTree
 import zipfile
 
 from dataclasses import dataclass
-from datetime import datetime
+from datetime import datetime, timezone
 from pathlib import Path
 from requests.auth import HTTPBasicAuth
 
@@ -16,8 +16,22 @@ _quiet: bool = False
 _verbose: bool = False
 
 
-_epilog = """
-    All options can be provided through environment variables in all-caps with SEBSYNC_ prefix.
+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 for ebooks:
+
+    \b
+     {Status.NEW}: new (ebook found in Standard Ebooks catalog but not found locally)
+     {Status.UPDATE}: update (new version of ebook found in Standard Ebooks catalog)
+     {Status.EXTRA}: extraneous (local ebook was not found in Standard Ebooks catalog)
+
+    An extraneous ebook can occur when Standard Ebooks changes the identifier of a previously
+    published ebook. It's a rare occurance, and it's generally safe to delete such files.
 """
 
 
@@ -42,15 +56,37 @@ class LocalEbook:
     modified: datetime
 
 
+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 get_standard_ebooks(opds: str, email: str) -> dict[str, StandardEbook]:
+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
+    )
+
+
+type_selector = {
+    "compatible": "Recommended compatible epub",
+    "kobo": "Kobo Kepub epub",
+    "advanced": "Advanced epub",
+}
+
+
+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, stream=True, auth=HTTPBasicAuth(email, ""))
+    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):
@@ -58,10 +94,8 @@ def get_standard_ebooks(opds: str, email: str) -> dict[str, 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(".//atom:link[@title='Recommended compatible epub']", ns).attrib[
-                "href"
-            ],
-            updated=datetime.fromisoformat(entry.find("atom:updated", 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
@@ -91,7 +125,7 @@ def get_local_ebooks(dir: Path) -> dict[str, LocalEbook]:
                     id=id.text,
                     title=metadata.find(".//dc:title", ns).text,
                     path=path,
-                    modified=datetime.fromisoformat(modified.text),
+                    modified=_fromisoformat(modified.text),
                 )
                 ebooks[ebook.id] = ebook
     return ebooks
@@ -99,8 +133,6 @@ def get_local_ebooks(dir: Path) -> dict[str, LocalEbook]:
 
 def download_ebook(url: str, path: Path) -> None:
     """Download the ebook at the specified URL into the specified path."""
-    if not _quiet:
-        click.echo(f"Download: {path}")
     if not _dry_run:
         response = requests.get(url, stream=True)
         with path.open("wb") as file:
@@ -126,12 +158,12 @@ def ebook_filename(ebook: StandardEbook) -> str:
 @click.option(
     "--books",
     help="directory where local books are stored",
-    type=click.Path(exists=True, file_okay=False, dir_okay=True, path_type=Path),
+    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 ebooks are downloaded",
+    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"),
 )
@@ -142,7 +174,7 @@ def ebook_filename(ebook: StandardEbook) -> str:
 )
 @click.option(
     "--email",
-    help="email to authenticate with Standard Ebooks",
+    help="email address to authenticate with Standard Ebooks",
     required=True,
 )
 @click.option(
@@ -155,13 +187,26 @@ def ebook_filename(ebook: StandardEbook) -> str:
     help="suppress non-error messages",
     is_flag=True,
 )
+@click.option(
+    "--type",
+    type=click.Choice(["compatible", "kobo", "advanced"]),
+    help="EPUB type to download",
+    default="compatible",
+)
 @click.option(
     "--verbose",
     help="increase verbosity",
     is_flag=True,
 )
 def sebsync(
-    books: str, downloads: str, dry_run: bool, email: str, opds: str, quiet: bool, verbose: bool
+    books: str,
+    downloads: str,
+    dry_run: bool,
+    email: str,
+    opds: str,
+    quiet: bool,
+    type: str,
+    verbose: bool,
 ):
     global _dry_run
     global _verbose
@@ -171,28 +216,29 @@ def sebsync(
     _verbose = verbose
     _quiet = quiet
 
-    remote_ebooks = get_standard_ebooks(opds, email)
+    remote_ebooks = get_remote_ebooks(opds, email, type)
     if not remote_ebooks:
-        raise click.ClickException("Email address rejected by Standard Ebooks.")
+        raise click.ClickException("OPDS download failed. Is email address correct?")
     if _verbose:
-        click.echo(f"Found {len(remote_ebooks)} remote Standard Ebooks titles.")
+        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 Standard Ebooks titles.")
+        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:
+                _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)
 
-    if not _quiet:
-        for local_ebook in local_ebooks.values():
-            if local_ebook.id not in remote_ebooks:
-                click.secho(f"Extra: {local_ebook.path}", fg="yellow")
+    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-1.0a2/PKG-INFO

@@ -1,54 +0,0 @@
-Metadata-Version: 2.1
-Name: sebsync
-Version: 1.0a2
-Summary: Synchronize Standard Ebooks catalog with local ebooks.
-Home-page: https://github.com/pbryan/sebsync/
-License: MIT
-Keywords: ebook,downloader,standard,book
-Author: sebsync authors
-Requires-Python: >=3.10,<4.0
-Classifier: Development Status :: 3 - Alpha
-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 :: Other/Nonlisted Topic
-Requires-Dist: click (>=8.1,<9.0)
-Requires-Dist: requests (>=2.32,<3.0)
-Project-URL: Documentation, https://github.com/pbryan/sebsync/tree/main/docs
-Description-Content-Type: text/markdown
-
-# sebsync
-
-sebsync is a simple script to synchronize all EPUBs from Standard Ebooks to your local
-filesystem. It detects any new and updated titles and downloads them automatically.
-
-## How it works
-
-The `sebsync` script reads the Standard Ebooks OPDS catalog and reconciles their titles against
-EPUBs in your local filesystem, downloading new ones or updating existing ones as necessary.
-
-If you're member of the Standard Ebooks
-[Patrons Circle](https://standardebooks.org/donate#patrons-circle), or have produced an ebook
-for them in the past, you may access their [OPDS feed](https://standardebooks.org/feeds),
-a catalog of all published titles. This allows new and updated titles to be easily recognized.
-
-If a title is detected in the catalog that is not present in your local books or downloads
-directory, then it will be downloaded into your downloads directory. If a new version of a book
-is detected in the catalog that is already in your local books or download directory, then the
-new version will be downloaded and stored in the same place it was found.
-
-## Installation
-
-```
-pipx install sebsync
-```
-
-### Example usage
-
-```
-sebsync --email address@example.com --books /home/user/MyBooks --downloads /home/user/MyBooks/Downloads
-```
-

sebsync-1.0a2/README.md

@@ -1,31 +0,0 @@
-# sebsync
-
-sebsync is a simple script to synchronize all EPUBs from Standard Ebooks to your local
-filesystem. It detects any new and updated titles and downloads them automatically.
-
-## How it works
-
-The `sebsync` script reads the Standard Ebooks OPDS catalog and reconciles their titles against
-EPUBs in your local filesystem, downloading new ones or updating existing ones as necessary.
-
-If you're member of the Standard Ebooks
-[Patrons Circle](https://standardebooks.org/donate#patrons-circle), or have produced an ebook
-for them in the past, you may access their [OPDS feed](https://standardebooks.org/feeds),
-a catalog of all published titles. This allows new and updated titles to be easily recognized.
-
-If a title is detected in the catalog that is not present in your local books or downloads
-directory, then it will be downloaded into your downloads directory. If a new version of a book
-is detected in the catalog that is already in your local books or download directory, then the
-new version will be downloaded and stored in the same place it was found.
-
-## Installation
-
-```
-pipx install sebsync
-```
-
-### Example usage
-
-```
-sebsync --email address@example.com --books /home/user/MyBooks --downloads /home/user/MyBooks/Downloads
-```