sebsync 1.0a3__tar.gz → 1.0a5__tar.gz

sebsync-1.0a5/PKG-INFO

@@ -0,0 +1,84 @@
+Metadata-Version: 2.1
+Name: sebsync
+Version: 1.0a5
+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)
+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.0a5/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.0a3 → sebsync-1.0a5}/pyproject.toml

@@ -8,12 +8,11 @@ target-version = ['py312']
 
 [tool.poetry]
 name = "sebsync"
-version = "1.0a3"
+version = "1.0a5"
 description = "Synchronize Standard Ebooks catalog with local ebooks."
 readme = "README.md"
 authors = ["sebsync authors"]
 homepage = "https://github.com/pbryan/sebsync/"
-documentation = "https://github.com/pbryan/sebsync/tree/main/docs"
 license = "MIT"
 keywords = ["ebook", "downloader", "standard", "book"]
 classifiers = [

{sebsync-1.0a3 → sebsync-1.0a5}/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
@@ -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:
+
+    \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)
+
+    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,11 +56,24 @@ class LocalEbook:
     modified: datetime
 
 
-def _if_exists(path: Path) -> Path | None:
+# 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:
+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")
@@ -56,11 +83,11 @@ def _fromisoformat(text: str) -> datetime:
     )
 
 
-def get_standard_ebooks(opds: str, email: str) -> dict[str, StandardEbook]:
+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):
@@ -68,10 +95,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=_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
@@ -101,7 +126,7 @@ def get_local_ebooks(dir: Path) -> dict[str, LocalEbook]:
                     id=id.text,
                     title=metadata.find(".//dc:title", ns).text,
                     path=path,
-                    modified=_fromisoformat(modified.text),
+                    modified=fromisoformat(modified.text),
                 )
                 ebooks[ebook.id] = ebook
     return ebooks
@@ -109,8 +134,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:
@@ -135,74 +158,90 @@ def ebook_filename(ebook: StandardEbook) -> str:
 @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, path_type=Path),
-    default=_if_exists(Path.home() / "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 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"),
+    default=if_exists(Path.home() / "Downloads"),
 )
 @click.option(
     "--dry-run",
-    help="perform a trial run with no changes made",
+    help="Perform a trial run with no changes made.",
     is_flag=True,
 )
 @click.option(
     "--email",
-    help="email to authenticate with Standard Ebooks",
+    help="Email address to authenticate with Standard Ebooks.",
     required=True,
 )
+@click.help_option()
 @click.option(
     "--opds",
-    help="URL of Standard Ebooks OPDS catalog",
+    help="URL of Standard Ebooks OPDS catalog.",
     default="https://standardebooks.org/feeds/opds/all",
 )
 @click.option(
     "--quiet",
-    help="suppress non-error messages",
+    help="Suppress non-error messages.",
     is_flag=True,
 )
+@click.option(
+    "--type",
+    type=click.Choice(type_selector.keys()),
+    help="EPUB type to download.",
+    default="compatible",
+)
 @click.option(
     "--verbose",
-    help="increase verbosity",
+    help="Increase verbosity.",
     is_flag=True,
 )
+@click.version_option(package_name="sebsync")
 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
     global _quiet
 
     _dry_run = dry_run
-    _verbose = verbose
+    _verbose = verbose and not quiet  # quiet wins
     _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.0a3/PKG-INFO

@@ -1,54 +0,0 @@
-Metadata-Version: 2.1
-Name: sebsync
-Version: 1.0a3
-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.0a3/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
-```