bookcli 0.1.0__tar.gz

bookcli-0.1.0/PKG-INFO

@@ -0,0 +1,198 @@
+Metadata-Version: 2.4
+Name: bookcli
+Version: 0.1.0
+Summary: A production-grade Python CLI book search and download application.
+License: MIT
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: typer>=0.9.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: httpx>=0.25.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: rapidfuzz>=3.0.0
+Requires-Dist: aiosqlite>=0.19.0
+
+# BookCLI
+
+BookCLI is a production-ready, clean-architecture command-line interface application built in Python 3.12+. It allows users to search multiple legal book sources concurrently, merge and rank results dynamically using fuzzy string matching, and safely download books when legally provided by the API source.
+
+---
+
+## Features
+
+- **Concurrent Multi-Provider Search**: Queries Google Books, Open Library, Project Gutenberg, and the Internet Archive concurrently.
+- **Advanced Deduplication & Ranking**: Automatically filters duplicate search entries using fuzzy title and author string comparison via `RapidFuzz` and sorts results based on metadata completeness and direct download availability.
+- **Safe & Legal Downloads**: Only attempts downloads when the source explicitly provides a free/public-domain download link.
+- **Custom Download Paths**: Allows downloading to custom directories or specific files via CLI arguments, search explorer prompts, or global configurations.
+- **Download Resumption**: Supports HTTP range requests to resume interrupted downloads.
+- **Rich Terminal UI**: Displays tabular results, dynamic progress bars, speed, ETA, and styled metadata panel screens utilizing `Rich`.
+- **Offline Mode & Metadata Caching**: Implements local caching in SQLite to preserve previously fetched results, allowing details to be checked offline.
+- **Short Session Indexing**: Supports referring to book search results by their simple short IDs (1, 2, 3...) in follow-up commands like `info`, `download`, `open`, and `favorite`.
+- **Search History & Favorites**: Saves queries and favorites locally.
+- **Configurable Options**: Change default download directory, cache TTL, client timeout, and disable/enable specific providers.
+
+---
+
+## Directory Architecture
+
+The project adheres to Clean Architecture principles:
+
+```text
+bookcli/
+│
+├── database/            # Database initialization and migrations
+│   └── migrations.py
+│
+├── providers/           # API clients for external book metadata providers
+│   ├── base.py
+│   ├── google_books.py
+│   ├── gutenberg.py
+│   ├── internet_archive.py
+│   └── openlibrary.py
+│
+├── services/            # Core business services
+│   ├── history.py
+│   ├── ranking.py
+│   └── search.py
+│
+├── cache.py             # SQLite metadata cache implementation
+├── cli.py               # Typer CLI application entry point and commands
+├── config.py            # Pydantic configuration loader and validator
+├── downloader.py        # Async downloader with range-resume and Rich progress
+├── exceptions.py        # Custom exceptions for uniform error handling
+├── opener.py            # OS-specific default application file opener
+├── settings.py          # Configuration defaults and directory paths
+└── utils.py             # Formatting and filename utilities
+```
+
+---
+
+## Installation
+
+Ensure you have Python 3.12+ installed. Install BookCLI locally in editable mode:
+
+```bash
+git clone https://github.com/your-username/bookcli.git
+cd bookcli
+pip install -e .
+```
+
+Once installed, the CLI tool is available globally as `book`. If the script directory is not on your PATH, you can use the provided script wrappers in the project root:
+- On Windows (CMD/PowerShell): `.\book.bat <command>`
+- On Unix/macOS/Git Bash: `./book <command>`
+- Or directly via Python module: `python -m bookcli.cli <command>`
+
+> [!NOTE]
+> On Windows, running `.\book.bat` without any command starts the **Interactive Search Explorer** loop, which also includes a menu option to update your default download directory.
+
+---
+
+## Usage
+
+### 1. Search for Books
+Query multiple providers concurrently. Results will display in a styled table containing short session IDs.
+
+```bash
+# General search
+book search "Atomic Habits"
+
+# Filtered search
+book search "Clean Code" --author "Robert C. Martin"
+book search "Relativity" --subject "Physics"
+```
+
+#### Interactive Explorer Mode
+When running search inside a terminal (TTY mode), you enter an interactive prompt:
+- Enter `i <ID>` to see details.
+- Enter `f <ID>` to favorite a book.
+- Enter `o <ID>` to open a downloaded book.
+- Enter `<ID>` to download a book to your default download directory.
+- Enter `<ID> -o <path>` or `<ID> --output <path>` to download a book to a **custom path** (e.g. `1 -o C:\downloads` or `1 -o mybook.epub`).
+- Enter `q` to quit.
+
+### 2. View Detailed Metadata
+Examine pages, publishers, description, ISBN, and download status of a book by using its short index ID (from your last search) or exact provider ID.
+
+```bash
+book info 1
+```
+
+### 3. Legal Download with Progress Bar
+Download the book with a progress bar. You can choose to download to your default configured directory or specify a custom path (either a directory or exact file path).
+
+```bash
+# Download to the default configured download directory
+book download 1
+
+# Download to a custom directory (automatically creates it if missing)
+book download 1 --output "/path/to/my_downloads/"
+book download 1 -o "C:\my_downloads\"
+
+# Download to a specific custom filename
+book download 1 --output "/path/to/my_books/clean_code.epub"
+```
+
+### 4. Open File in OS Default Viewer
+Open the downloaded book (EPUB, PDF, TXT) immediately in your operating system's default book reader.
+
+```bash
+book open 1
+```
+
+### 5. Managing Favorites
+Bookmark books to read later.
+
+```bash
+# Add to favorites
+book favorite add 1
+
+# List all favorites
+book favorite list
+
+# Remove from favorites
+book favorite remove gutenberg:1342
+```
+
+### 6. Configuration Settings
+List all configuration options or update parameters:
+
+```bash
+# View configuration
+book config
+
+# Set default download directory (can also use 'download-path' alias)
+book config set download-dir "/path/to/downloads"
+book config set download-path "/path/to/downloads"
+
+# Set client requests timeout
+book config set timeout 10
+
+# Disable a provider (e.g. internet_archive)
+book config set provider false internet-archive
+```
+
+### 7. Cache Management
+View statistics or clear cached metadata:
+
+```bash
+book cache stats
+book cache clear
+```
+
+### 8. Query History
+View your search history logs:
+
+```bash
+book history
+```
+
+---
+
+## Testing & Code Quality
+
+BookCLI includes a comprehensive test suite of unit and integration tests with **80%+ code coverage**.
+
+### Run Tests
+```bash
+python -m pytest --cov=bookcli
+```

bookcli-0.1.0/README.md

@@ -0,0 +1,184 @@
+# BookCLI
+
+BookCLI is a production-ready, clean-architecture command-line interface application built in Python 3.12+. It allows users to search multiple legal book sources concurrently, merge and rank results dynamically using fuzzy string matching, and safely download books when legally provided by the API source.
+
+---
+
+## Features
+
+- **Concurrent Multi-Provider Search**: Queries Google Books, Open Library, Project Gutenberg, and the Internet Archive concurrently.
+- **Advanced Deduplication & Ranking**: Automatically filters duplicate search entries using fuzzy title and author string comparison via `RapidFuzz` and sorts results based on metadata completeness and direct download availability.
+- **Safe & Legal Downloads**: Only attempts downloads when the source explicitly provides a free/public-domain download link.
+- **Custom Download Paths**: Allows downloading to custom directories or specific files via CLI arguments, search explorer prompts, or global configurations.
+- **Download Resumption**: Supports HTTP range requests to resume interrupted downloads.
+- **Rich Terminal UI**: Displays tabular results, dynamic progress bars, speed, ETA, and styled metadata panel screens utilizing `Rich`.
+- **Offline Mode & Metadata Caching**: Implements local caching in SQLite to preserve previously fetched results, allowing details to be checked offline.
+- **Short Session Indexing**: Supports referring to book search results by their simple short IDs (1, 2, 3...) in follow-up commands like `info`, `download`, `open`, and `favorite`.
+- **Search History & Favorites**: Saves queries and favorites locally.
+- **Configurable Options**: Change default download directory, cache TTL, client timeout, and disable/enable specific providers.
+
+---
+
+## Directory Architecture
+
+The project adheres to Clean Architecture principles:
+
+```text
+bookcli/
+│
+├── database/            # Database initialization and migrations
+│   └── migrations.py
+│
+├── providers/           # API clients for external book metadata providers
+│   ├── base.py
+│   ├── google_books.py
+│   ├── gutenberg.py
+│   ├── internet_archive.py
+│   └── openlibrary.py
+│
+├── services/            # Core business services
+│   ├── history.py
+│   ├── ranking.py
+│   └── search.py
+│
+├── cache.py             # SQLite metadata cache implementation
+├── cli.py               # Typer CLI application entry point and commands
+├── config.py            # Pydantic configuration loader and validator
+├── downloader.py        # Async downloader with range-resume and Rich progress
+├── exceptions.py        # Custom exceptions for uniform error handling
+├── opener.py            # OS-specific default application file opener
+├── settings.py          # Configuration defaults and directory paths
+└── utils.py             # Formatting and filename utilities
+```
+
+---
+
+## Installation
+
+Ensure you have Python 3.12+ installed. Install BookCLI locally in editable mode:
+
+```bash
+git clone https://github.com/your-username/bookcli.git
+cd bookcli
+pip install -e .
+```
+
+Once installed, the CLI tool is available globally as `book`. If the script directory is not on your PATH, you can use the provided script wrappers in the project root:
+- On Windows (CMD/PowerShell): `.\book.bat <command>`
+- On Unix/macOS/Git Bash: `./book <command>`
+- Or directly via Python module: `python -m bookcli.cli <command>`
+
+> [!NOTE]
+> On Windows, running `.\book.bat` without any command starts the **Interactive Search Explorer** loop, which also includes a menu option to update your default download directory.
+
+---
+
+## Usage
+
+### 1. Search for Books
+Query multiple providers concurrently. Results will display in a styled table containing short session IDs.
+
+```bash
+# General search
+book search "Atomic Habits"
+
+# Filtered search
+book search "Clean Code" --author "Robert C. Martin"
+book search "Relativity" --subject "Physics"
+```
+
+#### Interactive Explorer Mode
+When running search inside a terminal (TTY mode), you enter an interactive prompt:
+- Enter `i <ID>` to see details.
+- Enter `f <ID>` to favorite a book.
+- Enter `o <ID>` to open a downloaded book.
+- Enter `<ID>` to download a book to your default download directory.
+- Enter `<ID> -o <path>` or `<ID> --output <path>` to download a book to a **custom path** (e.g. `1 -o C:\downloads` or `1 -o mybook.epub`).
+- Enter `q` to quit.
+
+### 2. View Detailed Metadata
+Examine pages, publishers, description, ISBN, and download status of a book by using its short index ID (from your last search) or exact provider ID.
+
+```bash
+book info 1
+```
+
+### 3. Legal Download with Progress Bar
+Download the book with a progress bar. You can choose to download to your default configured directory or specify a custom path (either a directory or exact file path).
+
+```bash
+# Download to the default configured download directory
+book download 1
+
+# Download to a custom directory (automatically creates it if missing)
+book download 1 --output "/path/to/my_downloads/"
+book download 1 -o "C:\my_downloads\"
+
+# Download to a specific custom filename
+book download 1 --output "/path/to/my_books/clean_code.epub"
+```
+
+### 4. Open File in OS Default Viewer
+Open the downloaded book (EPUB, PDF, TXT) immediately in your operating system's default book reader.
+
+```bash
+book open 1
+```
+
+### 5. Managing Favorites
+Bookmark books to read later.
+
+```bash
+# Add to favorites
+book favorite add 1
+
+# List all favorites
+book favorite list
+
+# Remove from favorites
+book favorite remove gutenberg:1342
+```
+
+### 6. Configuration Settings
+List all configuration options or update parameters:
+
+```bash
+# View configuration
+book config
+
+# Set default download directory (can also use 'download-path' alias)
+book config set download-dir "/path/to/downloads"
+book config set download-path "/path/to/downloads"
+
+# Set client requests timeout
+book config set timeout 10
+
+# Disable a provider (e.g. internet_archive)
+book config set provider false internet-archive
+```
+
+### 7. Cache Management
+View statistics or clear cached metadata:
+
+```bash
+book cache stats
+book cache clear
+```
+
+### 8. Query History
+View your search history logs:
+
+```bash
+book history
+```
+
+---
+
+## Testing & Code Quality
+
+BookCLI includes a comprehensive test suite of unit and integration tests with **80%+ code coverage**.
+
+### Run Tests
+```bash
+python -m pytest --cov=bookcli
+```

bookcli-0.1.0/bookcli/__init__.py

@@ -0,0 +1,3 @@
+"""BookCLI package."""
+
+__version__ = "0.1.0"

bookcli-0.1.0/bookcli/cache.py

@@ -0,0 +1,103 @@
+"""Metadata cache using SQLite for BookCLI."""
+
+import json
+import logging
+from datetime import datetime, timezone
+from typing import Optional
+from bookcli.database import DatabaseManager
+from bookcli.models import BookMetadata
+
+logger = logging.getLogger(__name__)
+
+
+async def get_book_from_cache(
+    db_manager: DatabaseManager, book_id: str, ttl_seconds: int
+) -> Optional[BookMetadata]:
+    """Retrieves a book from the cache if it exists and has not expired."""
+    query = "SELECT json_data, cached_at FROM cached_books WHERE id = ?"
+    async with db_manager.connection() as conn:
+        async with conn.execute(query, (book_id,)) as cursor:
+            row = await cursor.fetchone()
+            if not row:
+                return None
+
+            json_data, cached_at_str = row[0], row[1]
+            try:
+                # SQLite datetime strings are stored in ISO format
+                # Parse timestamp: 'YYYY-MM-DD HH:MM:SS' or 'YYYY-MM-DDTHH:MM:SS...'
+                # We can replace ' ' with 'T' if needed, or use fromisoformat.
+                # In standard SQLite datetime, it might not contain 'T', let's format it.
+                if "T" not in cached_at_str:
+                    # e.g., '2026-07-11 04:53:00'
+                    cached_at = datetime.strptime(cached_at_str.split(".")[0], "%Y-%m-%d %H:%M:%S")
+                else:
+                    # e.g., ISO format
+                    cached_at = datetime.fromisoformat(cached_at_str)
+
+                # Convert to naive or timezone-aware matching
+                # Since datetime.now(timezone.utc) is timezone aware, let's make cached_at UTC aware.
+                if cached_at.tzinfo is None:
+                    cached_at = cached_at.replace(tzinfo=timezone.utc)
+
+                age = (datetime.now(timezone.utc) - cached_at).total_seconds()
+                if age > ttl_seconds:
+                    logger.debug("Cache expired for book ID %s (age: %s seconds)", book_id, age)
+                    # We could delete it, but simple overwrite on set is fine, or we can delete it now
+                    await conn.execute("DELETE FROM cached_books WHERE id = ?", (book_id,))
+                    await conn.commit()
+                    return None
+
+                data = json.loads(json_data)
+                return BookMetadata(**data)
+            except Exception as e:
+                logger.error("Failed to parse cached book %s: %s", book_id, e)
+                return None
+
+
+async def save_book_to_cache(db_manager: DatabaseManager, book: BookMetadata) -> None:
+    """Saves a book to the SQLite cache, overwriting if it already exists."""
+    query = """
+        INSERT OR REPLACE INTO cached_books (id, provider, json_data, cached_at)
+        VALUES (?, ?, ?, ?)
+    """
+    async with db_manager.connection() as conn:
+        try:
+            # Save date in standard ISO format with timezone (UTC)
+            now_str = datetime.now(timezone.utc).isoformat()
+            await conn.execute(
+                query,
+                (book.id, book.source, book.model_dump_json(), now_str)
+            )
+            await conn.commit()
+            logger.debug("Saved book %s to cache", book.id)
+        except Exception as e:
+            logger.error("Failed to write book %s to cache: %s", book.id, e)
+
+
+async def clear_cache_db(db_manager: DatabaseManager) -> int:
+    """Clears all cached books. Returns the number of rows deleted."""
+    async with db_manager.connection() as conn:
+        async with conn.execute("SELECT COUNT(*) FROM cached_books") as cursor:
+            row = await cursor.fetchone()
+            count = row[0] if row else 0
+
+        await conn.execute("DELETE FROM cached_books")
+        await conn.commit()
+        logger.info("Cleared cached metadata database (%d items).", count)
+        return count
+
+
+async def get_cache_db_stats(db_manager: DatabaseManager) -> dict:
+    """Gets metadata cache statistics."""
+    async with db_manager.connection() as conn:
+        async with conn.execute("SELECT COUNT(*), MIN(cached_at), MAX(cached_at) FROM cached_books") as cursor:
+            row = await cursor.fetchone()
+            count = row[0] if row else 0
+            oldest = row[1] if row and row[1] else "N/A"
+            newest = row[2] if row and row[2] else "N/A"
+
+        return {
+            "total_items": count,
+            "oldest_item": oldest,
+            "newest_item": newest
+        }