tbr-deal-finder 0.1.5__tar.gz → 0.1.7__tar.gz

tbr_deal_finder-0.1.7/CHANGELOG.md

@@ -0,0 +1,39 @@
+
+# Change Log
+
+## 0.1.7 (July 31, 2025)
+
+Notes: 
+* tbr-deal-finder no longer shows deals on books you own in the same format.
+  * Example: You own Dune on Audible so it won't show on Audible, Libro, or Chirp. It will show on Kindle (you don't own the ebook)
+* Improvements when attempting to match authors
+  * Chirp
+  * Libro.FM
+* Users no longer need to provide an export and can instead just track deals on their wishlist
+
+BUG FIXES:
+* Fixed wishlist pagination in libro.fm
+* Fixed issue forcing user to go through setup twice when running the setup command 
+
+---
+
+## 0.1.6 (July 30, 2025)
+
+Notes: 
+* tbr-deal-finder now also tracks deals on the books in your wishlist. Works for all retailers.   
+
+BUG FIXES:
+* Fixed issue where no deals would display if libro is the only tracked audiobook retailer.
+* Fixed retailer cli setup forcing a user to select at least two audiobook retailers.
+
+---
+
+## 0.1.5 (July 30, 2025)
+
+Notes: 
+* Added formatting to select messages to make the messages purpose clearer.
+
+BUG FIXES:
+* Fixed issue getting books from libro and chirp too aggressively
+* User must now track deals for at least one retailer 
+

tbr_deal_finder-0.1.7/DESIGN.md

@@ -0,0 +1,113 @@
+# TBR Deal Finder Design
+
+## Overview
+TBR Deal Finder is a CLI application that helps users track price drops and find deals on books in their To-Be-Read (TBR) list across various digital book retailers. The application is built with a modular architecture that separates data ingestion, processing, and output concerns.
+
+## Terms
+### Digital Book
+A book in electronic format, accessible via digital devices. Includes:
+- Audiobooks
+- E-books
+
+### Digital Book Retailer
+Platforms that sell or distribute digital books, such as:
+- Libro.fm (audiobooks)
+- Audible (audiobooks)
+- Kindle (e-books)
+- Chirp (discounted audiobooks)
+
+### Library Export
+A data file containing a user's reading list and status. Sources include:
+- **Automated Exports**:
+  - The StoryGraph
+  - Goodreads
+- **Manual CSVs**: Custom spreadsheets following the required format
+
+### TBR (To Be Read)
+A user's personal reading list of books they plan to read in the future.
+
+## Core Components
+
+### 1. Data Ingestion Layer
+- **Library Exports**: Handles importing book data from multiple sources:
+  - The StoryGraph exports
+  - Goodreads exports
+  - Custom CSV files
+- **Retailer APIs**: Interfaces with various digital book retailers to fetch current pricing and availability
+
+### 2. Core Data Model
+
+#### `Book` Class
+The central data structure that represents a book across the application:
+- **Purpose**: Serves as a consistent contract between different components
+- **Key Attributes**:
+  - Title and author information
+  - Format (Audiobook, Ebook, etc.)
+  - Pricing information (list price, current price)
+  - Retailer-specific metadata
+  - Timestamp for deal tracking
+
+### 3. Retailer Interface
+
+#### `Retailer` Base Class
+Abstract base class that defines the interface for all retailer implementations:
+- **Core Methods**:
+  - `get_book()`: Fetches book details from the retailer
+  - `get_wishlist()`: Retrieves the user's wishlist
+  - `get_library()`: Gets the user's purchased/owned books
+- **Current Implementations**:
+  - Audible
+  - Libro.fm
+  - Chirp
+  - Kindle (planned)
+
+### 4. Processing Pipeline
+1. **Data Collection**:
+   - Load TBR lists from configured sources
+   - Fetch owned books from retailers
+   - Retrieve current deals and pricing
+
+2. **Matching Logic**:
+   - Matches TBR books with retailer inventory
+   - Filters out owned books
+   - Identifies price drops and deals
+
+3. **Output Generation**:
+   - Formats results for CLI display
+   - Highlights best deals
+   - Provides purchase links
+
+## Data Flow
+
+```mermaid
+graph TD
+    A[Library Exports] -->|CSV/JSON| B[Book Objects]
+    C[Retailer APIs] -->|API Calls| B
+    B --> D[Deal Processing]
+    D --> E[CLI Output]
+    F[User Configuration] -->|Settings| C
+    F -->|Preferences| D
+```
+
+## Key Design Decisions
+
+### 1. Extensibility
+- Retailer implementations are pluggable through the `Retailer` base class
+- Support for multiple export formats and retailer APIs
+
+### 2. Performance
+- Asynchronous I/O for API calls
+- Caching of retailer responses
+- Efficient data structures for book matching
+
+### 3. User Experience
+- Clear, concise command-line interface
+- Configurable output formats
+- Progress indicators for long-running operations
+
+## Future Considerations
+- Support for more retailer APIs
+- Email notifications for price drops
+- Web interface for easier configuration
+- Integration with library lending services
+- Price history tracking

{tbr_deal_finder-0.1.5 → tbr_deal_finder-0.1.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tbr-deal-finder
-Version: 0.1.5
+Version: 0.1.7
 Summary: Track price drops and find deals on books in your TBR list across audiobook and ebook formats.
 License: MIT
 License-File: LICENSE
@@ -9,6 +9,7 @@ Requires-Dist: aiohttp>=3.12.14
 Requires-Dist: audible==0.8.2
 Requires-Dist: click>=8.2.1
 Requires-Dist: duckdb>=1.3.2
+Requires-Dist: levenshtein>=0.27.1
 Requires-Dist: pandas>=2.3.1
 Requires-Dist: questionary>=2.1.0
 Requires-Dist: tqdm>=4.67.1
@@ -17,15 +18,17 @@ Description-Content-Type: text/markdown
 
 # tbr-deal-finder
 
-Track price drops and find deals on books in your TBR (To Be Read) list across audiobook and ebook formats.
+Track price drops and find deals on books in your TBR (To Be Read) and wishlist across digital book retailers.
 
 ## Features
-- Uses your StoryGraph exports, Goodreads exports, and custom csvs (spreadsheet) to track book deals
-- Supports multiple of the library exports above 
+- Use your StoryGraph exports, Goodreads exports, and custom csvs (spreadsheet) to track book deals
+- Supports multiple of the library exports above
+- Tracks deals on the wishlist of all your configured retailers like audible 
 - Supports multiple locales and currencies
-- Finds the latest and active deals from supported sellers
+- Find the latest and active deals from supported sellers
 - Simple CLI interface for setup and usage
 - Only get notified for new deals or view all active deals 
+- Filters out books you already own to prevent purchasing the same book on multiple retailers
 
 ## Support
 
@@ -66,7 +69,7 @@ Track price drops and find deals on books in your TBR (To Be Read) list across a
    https://docs.astral.sh/uv/getting-started/installation/
 
 ## Configuration
-This tool relies on the csv generated by the app you use to track your TBRs.
+This tool can use the csv generated by the app you use to track your TBRs.
 Here are the steps to get your export.
 
 ### StoryGraph

{tbr_deal_finder-0.1.5 → tbr_deal_finder-0.1.7}/README.md

@@ -1,14 +1,16 @@
 # tbr-deal-finder
 
-Track price drops and find deals on books in your TBR (To Be Read) list across audiobook and ebook formats.
+Track price drops and find deals on books in your TBR (To Be Read) and wishlist across digital book retailers.
 
 ## Features
-- Uses your StoryGraph exports, Goodreads exports, and custom csvs (spreadsheet) to track book deals
-- Supports multiple of the library exports above 
+- Use your StoryGraph exports, Goodreads exports, and custom csvs (spreadsheet) to track book deals
+- Supports multiple of the library exports above
+- Tracks deals on the wishlist of all your configured retailers like audible 
 - Supports multiple locales and currencies
-- Finds the latest and active deals from supported sellers
+- Find the latest and active deals from supported sellers
 - Simple CLI interface for setup and usage
 - Only get notified for new deals or view all active deals 
+- Filters out books you already own to prevent purchasing the same book on multiple retailers
 
 ## Support
 
@@ -49,7 +51,7 @@ Track price drops and find deals on books in your TBR (To Be Read) list across a
    https://docs.astral.sh/uv/getting-started/installation/
 
 ## Configuration
-This tool relies on the csv generated by the app you use to track your TBRs.
+This tool can use the csv generated by the app you use to track your TBRs.
 Here are the steps to get your export.
 
 ### StoryGraph

{tbr_deal_finder-0.1.5 → tbr_deal_finder-0.1.7}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "tbr-deal-finder"
-version = "0.1.5"
+version = "0.1.7"
 description = "Track price drops and find deals on books in your TBR list across audiobook and ebook formats."
 readme = "README.md"
 requires-python = ">=3.13"
@@ -10,6 +10,7 @@ dependencies = [
     "audible==0.8.2",
     "click>=8.2.1",
     "duckdb>=1.3.2",
+    "levenshtein>=0.27.1",
     "pandas>=2.3.1",
     "questionary>=2.1.0",
     "tqdm>=4.67.1",

{tbr_deal_finder-0.1.5 → tbr_deal_finder-0.1.7}/tbr_deal_finder/book.py

@@ -5,6 +5,7 @@ from enum import Enum
 from typing import Optional, Union
 
 import click
+from Levenshtein import ratio
 from unidecode import unidecode
 
 from tbr_deal_finder.config import Config
@@ -26,7 +27,11 @@ class Book:
     current_price: float
     timepoint: datetime
     format: Union[BookFormat, str]
+
+    # Metadata really only used for tracked books.
+    # See get_tbr_books for more context
     audiobook_isbn: str = None
+    audiobook_list_price: float = 0
 
     deleted: bool = False
 
@@ -35,16 +40,20 @@ class Book:
     normalized_authors: list[str] = None
 
     def __post_init__(self):
+        self.current_price = round(self.current_price, 2)
+        self.list_price = round(self.list_price, 2)
+        self.normalized_authors = get_normalized_authors(self.authors)
+
+        # Strip the title down to its most basic repr
+        # Improves hit rate on retailers
+        self.title = self.title.split(":")[0].split("(")[0].strip()
+
         if not self.deal_id:
-            self.deal_id = f"{self.title}__{self.normalized_authors}__{self.retailer}__{self.format}"
+            self.deal_id = f"{self.title}__{self.normalized_authors}__{self.format}__{self.retailer}"
 
         if isinstance(self.format, str):
             self.format = BookFormat(self.format)
 
-        self.current_price = round(self.current_price, 2)
-        self.list_price = round(self.list_price, 2)
-        self.normalized_authors = get_normalized_authors(self.authors)
-
     def discount(self) -> int:
         return int((self.list_price/self.current_price - 1) * 100)
 
@@ -56,6 +65,10 @@ class Book:
     def title_id(self) -> str:
         return f"{self.title}__{self.normalized_authors}__{self.format}"
 
+    @property
+    def full_title_str(self) -> str:
+        return f"{self.title}__{self.normalized_authors}"
+
     def list_price_string(self):
         return self.price_to_string(self.list_price)
 
@@ -74,6 +87,7 @@ class Book:
         response = dataclasses.asdict(self)
         response["format"] = self.format.value
         del response["audiobook_isbn"]
+        del response["audiobook_list_price"]
         del response["exists"]
         del response["normalized_authors"]
 
@@ -109,8 +123,33 @@ def print_books(books: list[Book]):
         click.echo(str(book))
 
 
+def get_full_title_str(title: str, authors: Union[list, str]) -> str:
+    return f"{title}__{get_normalized_authors(authors)}"
+
+
+def get_title_id(title: str, authors: Union[list, str], book_format: BookFormat) -> str:
+    return f"{title}__{get_normalized_authors(authors)}__{book_format.value}"
+
+
 def get_normalized_authors(authors: Union[str, list[str]]) -> list[str]:
     if isinstance(authors, str):
         authors = [i for i in authors.split(",")]
 
     return sorted([_AUTHOR_RE.sub('', unidecode(author)).lower() for author in authors])
+
+
+def is_matching_authors(a1: list[str], a2: list[str]) -> bool:
+    """Checks if two normalized authors are matching.
+    Matching here means that they are at least 80% similar using levenshtein distance.
+
+    Score is calculated as follows:
+        1 - (distance / (len1 + len2))
+
+    :param a1:
+    :param a2:
+    :return:
+    """
+    return any(
+        any(ratio(author1, author2, score_cutoff=.8) for author2 in a2)
+        for author1 in a1
+    )

{tbr_deal_finder-0.1.5 → tbr_deal_finder-0.1.7}/tbr_deal_finder/cli.py

@@ -9,7 +9,7 @@ import click
 import questionary
 
 from tbr_deal_finder.config import Config
-from tbr_deal_finder.library_exports import maybe_set_library_export_audiobook_isbn
+from tbr_deal_finder.library_exports import maybe_enrich_library_exports
 from tbr_deal_finder.migrations import make_migrations
 from tbr_deal_finder.book import get_deals_found_at, print_books, get_active_deals
 from tbr_deal_finder.retailer import RETAILER_MAP
@@ -28,12 +28,6 @@ from tbr_deal_finder.utils import (
 def cli():
     make_migrations()
 
-    # Check that the config exists for all commands ran
-    try:
-        Config.load()
-    except FileNotFoundError:
-        _set_config()
-
 
 def _add_path(existing_paths: list[str]) -> Union[str, None]:
     try:
@@ -68,24 +62,26 @@ def _set_library_export_paths(config: Config):
     Ensures that only valid, unique paths are added. Updates the config in-place.
     """
     while True:
-        if config.library_export_paths:
-            if len(config.library_export_paths) > 1:
-                choices = ["Add new path", "Remove path", "Done"]
-            else:
-                choices = ["Add new path", "Done"]
-
-            try:
-                user_selection = questionary.select(
-                    "What change would you like to make to your library export paths",
-                    choices=choices,
-                ).ask()
-            except (KeyError, KeyboardInterrupt, TypeError):
-                return
+        if len(config.library_export_paths) > 0:
+            choices = ["Add new path", "Remove path", "Done"]
         else:
-            click.echo("Add your library export path.")
-            user_selection = "Add new path"
+            choices = ["Add new path", "Done"]
+
+        try:
+            user_selection = questionary.select(
+                "What change would you like to make to your library export paths",
+                choices=choices,
+            ).ask()
+        except (KeyError, KeyboardInterrupt, TypeError):
+            return
 
         if user_selection == "Done":
+            if not config.library_export_paths:
+                if not click.confirm(
+                    "Don't add a GoodReads or StoryGraph export and use wishlist entirely? "
+                    "Note: Wishlist checks will still work even if you add your StoryGraph/GoodReads export."
+                ):
+                    continue
             return
         elif user_selection == "Add new path":
             if new_path := _add_path(config.library_export_paths):
@@ -124,15 +120,20 @@ def _set_locale(config: Config):
 
 
 def _set_tracked_retailers(config: Config):
+    if not config.tracked_retailers:
+        echo_info(
+            "If you haven't heard of it, Chirp doesn't charge a subscription and has some great deals. \n"
+            "Note: I don't work for Chirp and this isn't a paid plug."
+        )
+
     while True:
         user_response = questionary.checkbox(
-            "Select the retailers you want to check deals for.\n"
-            "Tip: Chirp doesn't have a subscription and can have good deals. I'd recommend checking it.\n",
+            "Select the retailers you want to check deals for.\n",
             choices=[
                 questionary.Choice(retailer, checked=retailer in config.tracked_retailers)
                 for retailer in RETAILER_MAP.keys()
         ]).ask()
-        if len(user_response) > 1:
+        if len(user_response) > 0:
             break
         else:
             echo_err("You must track deals for at least one retailer.")
@@ -183,9 +184,12 @@ def setup():
 @cli.command()
 def latest_deals():
     """Find book deals from your Library export."""
-    config = Config.load()
+    try:
+        config = Config.load()
+    except FileNotFoundError:
+        config = _set_config()
 
-    asyncio.run(maybe_set_library_export_audiobook_isbn(config))
+    asyncio.run(maybe_enrich_library_exports(config))
 
     db_conn = get_duckdb_conn()
     results = execute_query(

{tbr_deal_finder-0.1.5 → tbr_deal_finder-0.1.7}/tbr_deal_finder/config.py

@@ -62,10 +62,16 @@ class Config:
         tracked_retailers_str = parser.get('DEFAULT', 'tracked_retailers')
         locale = parser.get('DEFAULT', 'locale', fallback="us")
         cls.set_locale(locale)
+
+        if export_paths_str:
+            library_export_paths = [i.strip() for i in export_paths_str.split(",")]
+        else:
+            library_export_paths = []
+
         return cls(
             max_price=parser.getfloat('DEFAULT', 'max_price', fallback=8.0),  
             min_discount=parser.getint('DEFAULT', 'min_discount', fallback=35),
-            library_export_paths=[i.strip() for i in export_paths_str.split(",")],
+            library_export_paths=library_export_paths,
             tracked_retailers=[i.strip() for i in tracked_retailers_str.split(",")]
         )
 
@@ -78,7 +84,9 @@ class Config:
         return ", ".join(self.tracked_retailers)
 
     def set_library_export_paths(self, library_export_paths: Union[str, list[str]]):
-        if isinstance(library_export_paths, str):
+        if not library_export_paths:
+            self.library_export_paths = []
+        elif isinstance(library_export_paths, str):
             self.library_export_paths = [i.strip() for i in library_export_paths.split(",")]
         else:
             self.library_export_paths = library_export_paths

tbr_deal_finder-0.1.7/tbr_deal_finder/library_exports.py

@@ -0,0 +1,208 @@
+import asyncio
+import csv
+import shutil
+import tempfile
+from datetime import datetime
+from typing import Callable, Awaitable, Optional
+
+from tqdm.asyncio import tqdm_asyncio
+
+from tbr_deal_finder.book import Book, BookFormat, get_full_title_str
+from tbr_deal_finder.config import Config
+from tbr_deal_finder.retailer import LibroFM, Chirp
+
+
+def get_book_authors(book: dict) -> str:
+    if authors := book.get('Authors'):
+        return authors
+
+    authors = book['Author']
+    if additional_authors := book.get("Additional Authors"):
+        authors = f"{authors}, {additional_authors}"
+
+    return authors
+
+
+def get_book_title(book: dict) -> str:
+    title = book['Title']
+    return title.split("(")[0].strip()
+
+
+def is_tbr_book(book: dict) -> bool:
+    if "Read Status" in book:
+        return book["Read Status"] == "to-read"
+    elif "Bookshelves" in book:
+        return "to-read" in book["Bookshelves"]
+    else:
+        return True
+
+
+def requires_audiobook_list_price_default(config: Config) -> bool:
+    return bool(
+        "Libro.FM" in config.tracked_retailers
+        and "Audible" not in config.tracked_retailers
+        and "Chirp" not in config.tracked_retailers
+    )
+
+
+async def _maybe_set_column_for_library_exports(
+    config: Config,
+    attr_name: str,
+    get_book_callable: Callable[[Book, datetime, asyncio.Semaphore], Awaitable[Book]],
+    column_name: Optional[str] = None,
+):
+    """Adds a new column to all library exports that are missing it.
+    Uses get_book_callable to set the column value if a matching record couldn't be found
+    on that column in any other library export file.
+
+    :param config:
+    :param attr_name:
+    :param get_book_callable:
+    :param column_name:
+    :return:
+    """
+    if not config.library_export_paths:
+        return
+
+    if not column_name:
+        column_name = attr_name
+
+    books_requiring_check_map = dict()
+    book_to_col_val_map = dict()
+
+    # Iterate all library export paths
+    for library_export_path in config.library_export_paths:
+        with open(library_export_path, 'r', newline='', encoding='utf-8') as file:
+            # Use csv.DictReader to get dictionaries with column headers
+            for book_dict in csv.DictReader(file):
+                if not is_tbr_book(book_dict):
+                    continue
+
+                title = get_book_title(book_dict)
+                authors = get_book_authors(book_dict)
+                key = get_full_title_str(title, authors)
+
+                if column_name in book_dict:
+                    # Keep state of value for this book/key
+                    # in the event another export has the same book but the value is not set
+                    book_to_col_val_map[key] = book_dict[column_name]
+                    # Value has been found so a check no longer needs to be performed
+                    books_requiring_check_map.pop(key, None)
+                elif key not in book_to_col_val_map:
+                    # Not found, add the book to those requiring the column val to be set
+                    books_requiring_check_map[key] = Book(
+                        retailer="N/A",
+                        title=title,
+                        authors=authors,
+                        list_price=0,
+                        current_price=0,
+                        timepoint=config.run_time,
+                        format=BookFormat.NA
+                    )
+
+    if not books_requiring_check_map:
+        # Everything was resolved, nothing else to do
+        return
+
+    semaphore = asyncio.Semaphore(5)
+    human_readable_name = attr_name.replace("_", " ").title()
+
+    # Get books with the appropriate transform applied
+    # Responsibility is on the callable here
+    enriched_books = await tqdm_asyncio.gather(
+        *[
+            get_book_callable(book, config.run_time, semaphore) for book in books_requiring_check_map.values()
+        ],
+        desc=f"Getting required {human_readable_name} info"
+    )
+    updated_book_map = {
+        b.full_title_str: b
+        for b in enriched_books
+    }
+
+
+    # Go back and now add the new column where it hasn't been set
+    for library_export_path in config.library_export_paths:
+        with open(library_export_path, 'r', newline='', encoding='utf-8') as file:
+            reader = csv.DictReader(file)
+            field_names = list(reader.fieldnames) + [column_name]
+            file_content = [book_dict for book_dict in reader]
+            if not file_content or column_name in file_content[0]:
+                continue
+
+            with tempfile.NamedTemporaryFile(mode='w', delete=False, newline='') as temp_file:
+                temp_filename = temp_file.name
+                writer = csv.DictWriter(temp_file, fieldnames=field_names)
+                writer.writeheader()
+
+                for book_dict in file_content:
+                    if is_tbr_book(book_dict):
+                        title = get_book_title(book_dict)
+                        authors = get_book_authors(book_dict)
+                        key = get_full_title_str(title, authors)
+
+                        if key in book_to_col_val_map:
+                            col_val = book_to_col_val_map[key]
+                        elif key in updated_book_map:
+                            book = updated_book_map[key]
+                            col_val = getattr(book, attr_name)
+                        else:
+                            col_val = ""
+
+                        book_dict[column_name] = col_val
+                    else:
+                        book_dict[column_name] = ""
+
+                    writer.writerow(book_dict)
+
+        shutil.move(temp_filename, library_export_path)
+
+
+async def _maybe_set_library_export_audiobook_isbn(config: Config):
+    """To get the price from Libro.fm for a book, you need its ISBN
+
+    As opposed to trying to get that every time latest-deals is run
+        we're just updating the export csv once to include the ISBN.
+
+    Unfortunately, we do have to get it at run time for wishlists.
+    """
+    if "Libro.FM" not in config.tracked_retailers:
+        return
+
+    libro_fm = LibroFM()
+    await libro_fm.set_auth()
+
+    await _maybe_set_column_for_library_exports(
+        config,
+        "audiobook_isbn",
+        libro_fm.get_book_isbn,
+    )
+
+
+async def _maybe_set_library_export_audiobook_list_price(config: Config):
+    """Set a default list price for audiobooks
+
+    Only set if not currently set and the only audiobook retailer is Libro.FM
+    Libro.FM doesn't include the actual default price in its response, so this grabs the price reported by Chirp.
+    Chirp doesn't require a login to get this price info making it ideal in this instance.
+
+    :param config:
+    :return:
+    """
+    if not requires_audiobook_list_price_default(config):
+        return
+
+    chirp = Chirp()
+    await chirp.set_auth()
+
+    await _maybe_set_column_for_library_exports(
+        config,
+        "list_price",
+        chirp.get_book,
+        "audiobook_list_price"
+    )
+
+
+async def maybe_enrich_library_exports(config: Config):
+    await _maybe_set_library_export_audiobook_isbn(config)
+    await _maybe_set_library_export_audiobook_list_price(config)