sebsync 1.0a4__tar.gz → 1.0a6__tar.gz

{sebsync-1.0a4 → sebsync-1.0a6}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.1
 Name: sebsync
-Version: 1.0a4
-Summary: Synchronize Standard Ebooks catalog with local ebooks.
+Version: 1.0a6
+Summary: Synchronize Standard Ebooks catalog with a local EPUB collection.
 Home-page: https://github.com/pbryan/sebsync/
 License: MIT
 Keywords: ebook,downloader,standard,book
@@ -17,7 +17,6 @@ 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
@@ -38,7 +37,7 @@ 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.
+published ebook. It's a rare occurrence, and it's generally safe to delete such files.
 
 ## Requirements
 

{sebsync-1.0a4 → sebsync-1.0a6}/README.md

@@ -16,7 +16,7 @@ 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.
+published ebook. It's a rare occurrence, and it's generally safe to delete such files.
 
 ## Requirements
 

{sebsync-1.0a4 → sebsync-1.0a6}/pyproject.toml

@@ -8,12 +8,11 @@ target-version = ['py312']
 
 [tool.poetry]
 name = "sebsync"
-version = "1.0a4"
-description = "Synchronize Standard Ebooks catalog with local ebooks."
+version = "1.0a6"
+description = "Synchronize Standard Ebooks catalog with a local EPUB collection."
 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.0a4 → sebsync-1.0a6}/sebsync.py

@@ -23,15 +23,15 @@ class Status:
 
 
 _epilog = f"""
-    The following statuses are reported for ebooks:
+    The following statuses are reported:
 
     \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)
+    {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.
+    published ebook. It's a rare occurrence, and it's generally safe to delete such files.
 """
 
 
@@ -56,16 +56,24 @@ class LocalEbook:
     modified: datetime
 
 
-def _echo_status(path: Path, status: str) -> 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:
+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")
@@ -75,13 +83,6 @@ def _fromisoformat(text: str) -> datetime:
     )
 
 
-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/"}
@@ -95,7 +96,7 @@ def get_remote_ebooks(opds_url: str, email: str, type: str) -> dict[str, Standar
             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),
+            updated=fromisoformat(entry.find("atom:updated", ns).text),
         )
         ebooks[ebook.id] = ebook
     return ebooks
@@ -125,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
@@ -157,47 +158,49 @@ def ebook_filename(ebook: StandardEbook) -> str:
 @click.command(help=__doc__, epilog=_epilog)
 @click.option(
     "--books",
-    help="directory where local books are stored",
+    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"),
+    default=if_exists(Path.home() / "Books"),
 )
 @click.option(
     "--downloads",
-    help="directory where new 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 address 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(["compatible", "kobo", "advanced"]),
-    help="EPUB type to download",
+    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,
@@ -213,7 +216,7 @@ def sebsync(
     global _quiet
 
     _dry_run = dry_run
-    _verbose = verbose
+    _verbose = verbose and not quiet  # quiet wins
     _quiet = quiet
 
     remote_ebooks = get_remote_ebooks(opds, email, type)
@@ -229,16 +232,16 @@ def sebsync(
     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)
+                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)
+            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)
+            echo_status(local_ebook.path, Status.EXTRA)
 
 
 def main():