bookcli 0.1.0__py3-none-any.whl

bookcli/providers/openlibrary.py

@@ -0,0 +1,256 @@
+"""Open Library API provider implementation."""
+
+import logging
+from typing import List, Optional
+import httpx
+
+from bookcli.exceptions import ProviderError, DownloadError
+from bookcli.models import BookMetadata
+from bookcli.providers.base import BaseProvider
+
+logger = logging.getLogger(__name__)
+
+
+class OpenLibraryProvider(BaseProvider):
+    """Open Library API provider."""
+
+    def __init__(self, timeout_seconds: int = 15):
+        super().__init__(name="openlibrary", timeout_seconds=timeout_seconds)
+        self.search_url = "https://openlibrary.org/search.json"
+
+    def _map_doc_to_metadata(self, doc: dict) -> BookMetadata:
+        """Maps Open Library search document to BookMetadata."""
+        work_key = doc.get("key", "")
+        # Standardize ID: openlibrary:OL123W
+        book_id = f"openlibrary:{work_key.split('/')[-1]}"
+
+        title = doc.get("title", "Unknown Title")
+        subtitle = doc.get("subtitle")
+        authors = doc.get("author_name", [])
+        
+        # Publishers (Open Library returns a list)
+        publishers = doc.get("publisher", [])
+        publisher = publishers[0] if publishers else None
+
+        published_year = doc.get("first_publish_year")
+        pages = doc.get("number_of_pages_median")
+
+        # Languages (Open Library returns ISO codes in list, e.g. ['eng'])
+        languages = doc.get("language", [])
+        language = languages[0] if languages else None
+
+        # ISBN list
+        isbns = doc.get("isbn", [])
+        isbn = isbns[0] if isbns else None
+
+        # Cover Image URL
+        cover_i = doc.get("cover_i")
+        cover_url = f"https://covers.openlibrary.org/b/id/{cover_i}-M.jpg" if cover_i else None
+
+        # Internet Archive IDs (ia) for downloads
+        ia_list = doc.get("ia", [])
+        download_available = False
+        download_url = None
+        file_format = None
+
+        if ia_list:
+            # We filter out items that don't look like standard IA IDs (e.g. starting with markers like 'lending')
+            valid_ia = [ia for ia in ia_list if not ia.startswith("lending:")]
+            if valid_ia:
+                ia_id = valid_ia[0]
+                # Default to epub for IA download
+                download_url = f"https://archive.org/download/{ia_id}/{ia_id}.epub"
+                download_available = True
+                file_format = "epub"
+
+        return BookMetadata(
+            id=book_id,
+            title=title,
+            subtitle=subtitle,
+            authors=authors,
+            description=None,  # Search endpoint doesn't return full description; get_book will fetch it
+            language=language,
+            publisher=publisher,
+            published_year=published_year,
+            pages=pages,
+            isbn=isbn,
+            cover_url=cover_url,
+            download_url=download_url,
+            source=self.name,
+            download_availability=download_available,
+            file_format=file_format
+        )
+
+    async def search(
+        self,
+        query: str,
+        author: Optional[str] = None,
+        isbn: Optional[str] = None,
+        publisher: Optional[str] = None,
+        subject: Optional[str] = None
+    ) -> List[BookMetadata]:
+        """Searches Open Library."""
+        params = {}
+        if query.strip():
+            params["q"] = query.strip()
+        if author:
+            params["author"] = author
+        if isbn:
+            params["isbn"] = isbn
+        if publisher:
+            params["publisher"] = publisher
+        if subject:
+            params["subject"] = subject
+
+        if not params:
+            return []
+
+        params["limit"] = 20
+
+        try:
+            async with httpx.AsyncClient(timeout=self.timeout_seconds) as client:
+                response = await client.get(self.search_url, params=params)
+                if response.status_code != 200:
+                    raise ProviderError(f"Open Library API returned status {response.status_code}")
+
+                data = response.json()
+                docs = data.get("docs", [])
+                
+                results = []
+                for doc in docs:
+                    try:
+                        results.append(self._map_doc_to_metadata(doc))
+                    except Exception as e:
+                        logger.warning("Error parsing Open Library doc: %s", e)
+                return results
+
+        except httpx.RequestError as e:
+            logger.error("HTTP error searching Open Library: %s", e)
+            raise ProviderError(f"Network error querying Open Library API: {e}")
+        except Exception as e:
+            logger.error("Error searching Open Library: %s", e)
+            raise ProviderError(f"Open Library search failed: {e}")
+
+    async def get_book(self, book_id: str) -> Optional[BookMetadata]:
+        """Fetches details for a single work from Open Library."""
+        actual_id = book_id.split(":", 1)[-1]
+        
+        # Work URL (fetch the work JSON, e.g. /works/OL123W.json)
+        work_url = f"https://openlibrary.org/works/{actual_id}.json"
+        
+        try:
+            async with httpx.AsyncClient(timeout=self.timeout_seconds) as client:
+                # Fetch detailed Work JSON
+                work_response = await client.get(work_url)
+                if work_response.status_code == 404:
+                    return None
+                if work_response.status_code != 200:
+                    raise ProviderError(f"Open Library work endpoint returned {work_response.status_code}")
+                
+                work_data = work_response.json()
+
+                # Get description
+                description = None
+                desc_field = work_data.get("description")
+                if isinstance(desc_field, dict):
+                    description = desc_field.get("value")
+                elif isinstance(desc_field, str):
+                    description = desc_field
+
+                # Get authors (works only contain references to author keys, e.g. {"author": {"key": "/authors/OL123A"}})
+                authors = []
+                for auth_entry in work_data.get("authors", []):
+                    auth_key = auth_entry.get("author", {}).get("key")
+                    if auth_key:
+                        # Fetch author detail to get name
+                        auth_response = await client.get(f"https://openlibrary.org{auth_key}.json")
+                        if auth_response.status_code == 200:
+                            authors.append(auth_response.json().get("name", ""))
+
+                # Fetch editions to find pages, publisher, ISBN, cover, and downloads
+                # /works/OL123W/editions.json
+                editions_url = f"https://openlibrary.org/works/{actual_id}/editions.json"
+                editions_response = await client.get(editions_url)
+                
+                publisher = None
+                published_year = None
+                pages = None
+                isbn = None
+                cover_url = None
+                download_available = False
+                download_url = None
+                file_format = None
+
+                if editions_response.status_code == 200:
+                    editions_data = editions_response.json()
+                    entries = editions_data.get("entries", [])
+                    
+                    if entries:
+                        # Check the first edition with details
+                        first_ed = entries[0]
+                        
+                        publishers = first_ed.get("publishers", [])
+                        publisher = publishers[0] if publishers else None
+
+                        pub_date = first_ed.get("publish_date")
+                        if pub_date:
+                            # Try parsing year
+                            try:
+                                published_year = int(pub_date.split()[-1])
+                            except ValueError:
+                                pass
+
+                        pages = first_ed.get("number_of_pages")
+                        
+                        isbns = first_ed.get("isbn_13", []) or first_ed.get("isbn_10", [])
+                        isbn = isbns[0] if isbns else None
+
+                        # Cover URL if present
+                        covers = first_ed.get("covers", [])
+                        if covers:
+                            cover_url = f"https://covers.openlibrary.org/b/id/{covers[0]}-M.jpg"
+
+                        # Internet Archive IDs
+                        ia_list = first_ed.get("ocaid") or first_ed.get("ia", [])
+                        if isinstance(ia_list, str):
+                            ia_list = [ia_list]
+                        
+                        if ia_list:
+                            valid_ia = [ia for ia in ia_list if not ia.startswith("lending:")]
+                            if valid_ia:
+                                ia_id = valid_ia[0]
+                                download_url = f"https://archive.org/download/{ia_id}/{ia_id}.epub"
+                                download_available = True
+                                file_format = "epub"
+
+                return BookMetadata(
+                    id=book_id,
+                    title=work_data.get("title", "Unknown Title"),
+                    subtitle=work_data.get("subtitle"),
+                    authors=authors,
+                    description=description,
+                    language=None,
+                    publisher=publisher,
+                    published_year=published_year,
+                    pages=pages,
+                    isbn=isbn,
+                    cover_url=cover_url,
+                    download_url=download_url,
+                    source=self.name,
+                    download_availability=download_available,
+                    file_format=file_format
+                )
+
+        except httpx.RequestError as e:
+            raise ProviderError(f"Network error getting Open Library Work: {e}")
+        except Exception as e:
+            raise ProviderError(f"Open Library Work retrieval failed: {e}")
+
+    async def download(self, book: BookMetadata, dest_path: str) -> None:
+        """Downloads the Open Library Book. Delegates to central downloader."""
+        if not book.download_availability or not book.download_url:
+            raise DownloadError("No legal download URL available for this Open Library book.")
+        
+        # Import dynamically to avoid circular dependencies
+        from bookcli.downloader import download_file
+        await download_file(book.download_url, dest_path, self.timeout_seconds)

bookcli/services/__init__.py

@@ -0,0 +1 @@
+"""Services for BookCLI."""

bookcli/services/history.py

@@ -0,0 +1,69 @@
+"""Service for managing search history in the SQLite database."""
+
+import logging
+from typing import List, Dict, Any
+from bookcli.database import DatabaseManager
+
+logger = logging.getLogger(__name__)
+
+
+async def add_search_history(
+    db_manager: DatabaseManager, query: str, results_count: int
+) -> None:
+    """Adds a search record to the search history table."""
+    insert_sql = """
+        INSERT INTO search_history (query, results_count)
+        VALUES (?, ?)
+    """
+    async with db_manager.connection() as conn:
+        try:
+            await conn.execute(insert_sql, (query, results_count))
+            await conn.commit()
+            logger.debug("Logged search query '%s' with %d results to history", query, results_count)
+        except Exception as e:
+            logger.error("Failed to write to search history: %s", e)
+
+
+async def get_search_history(
+    db_manager: DatabaseManager, limit: int = 50
+) -> List[Dict[str, Any]]:
+    """Retrieves list of search history entries, sorted by most recent first."""
+    select_sql = """
+        SELECT id, query, timestamp, results_count
+        FROM search_history
+        ORDER BY timestamp DESC, id DESC
+        LIMIT ?
+    """
+    async with db_manager.connection() as conn:
+        try:
+            async with conn.execute(select_sql, (limit,)) as cursor:
+                rows = await cursor.fetchall()
+                return [
+                    {
+                        "id": row["id"],
+                        "query": row["query"],
+                        "timestamp": row["timestamp"],
+                        "results_count": row["results_count"]
+                    }
+                    for row in rows
+                ]
+        except Exception as e:
+            logger.error("Failed to fetch search history: %s", e)
+            return []
+
+
+async def clear_search_history(db_manager: DatabaseManager) -> int:
+    """Clears all search history records. Returns the number of deleted records."""
+    async with db_manager.connection() as conn:
+        try:
+            async with conn.execute("SELECT COUNT(*) FROM search_history") as cursor:
+                row = await cursor.fetchone()
+                count = row[0] if row else 0
+
+            await conn.execute("DELETE FROM search_history")
+            await conn.commit()
+            logger.info("Cleared search history database (%d items).", count)
+            return count
+        except Exception as e:
+            logger.error("Failed to clear search history: %s", e)
+            return 0

bookcli/services/ranking.py

@@ -0,0 +1,169 @@
+"""Service for ranking and deduplicating book search results."""
+
+import re
+from typing import List, Optional
+from rapidfuzz import fuzz
+
+from bookcli.models import BookMetadata
+
+
+def normalize_isbn(isbn: Optional[str]) -> Optional[str]:
+    """Strips dashes, spaces, and lowercase 'x' to normalize ISBN."""
+    if not isbn:
+        return None
+    cleaned = re.sub(r"[- \s]", "", isbn).strip()
+    return cleaned.upper() if cleaned else None
+
+
+def is_duplicate(book1: BookMetadata, book2: BookMetadata) -> bool:
+    """Determines if two books are duplicates based on ISBN or Title+Author similarity."""
+    # Check ISBN match
+    isbn1 = normalize_isbn(book1.isbn)
+    isbn2 = normalize_isbn(book2.isbn)
+    if isbn1 and isbn2 and isbn1 == isbn2:
+        return True
+
+    # Check Title + Author similarity
+    # We use fuzz.token_set_ratio for comparison to support subtitle variations
+    title_sim = fuzz.token_set_ratio(book1.title.lower(), book2.title.lower())
+    
+    # Compare authors
+    authors1 = " ".join(book1.authors).lower()
+    authors2 = " ".join(book2.authors).lower()
+    
+    if authors1 and authors2:
+        author_sim = fuzz.token_sort_ratio(authors1, authors2)
+    elif not authors1 and not authors2:
+        author_sim = 100.0  # both have no authors
+    else:
+        author_sim = 0.0
+
+    # If title similarity is very high and author matches reasonably well
+    if title_sim >= 85 and author_sim >= 80:
+        return True
+
+    return False
+
+
+def merge_books(book1: BookMetadata, book2: BookMetadata) -> BookMetadata:
+    """Merges two duplicate books, prioritizing the one with download availability and richer metadata."""
+    # Determine primary book (prefer download availability, then longer description, then presence of cover)
+    if book1.download_availability and not book2.download_availability:
+        primary, secondary = book1, book2
+    elif book2.download_availability and not book1.download_availability:
+        primary, secondary = book2, book1
+    else:
+        desc1_len = len(book1.description or "")
+        desc2_len = len(book2.description or "")
+        if desc1_len >= desc2_len:
+            primary, secondary = book1, book2
+        else:
+            primary, secondary = book2, book1
+
+    # Merge fields
+    merged_authors = list(primary.authors)
+    for auth in secondary.authors:
+        if auth not in merged_authors:
+            merged_authors.append(auth)
+
+    return BookMetadata(
+        id=primary.id,
+        title=primary.title,
+        subtitle=primary.subtitle or secondary.subtitle,
+        authors=merged_authors,
+        description=primary.description or secondary.description,
+        language=primary.language or secondary.language,
+        publisher=primary.publisher or secondary.publisher,
+        published_year=primary.published_year or secondary.published_year,
+        pages=primary.pages or secondary.pages,
+        isbn=primary.isbn or secondary.isbn,
+        cover_url=primary.cover_url or secondary.cover_url,
+        download_url=primary.download_url or secondary.download_url,
+        source=f"{primary.source}, {secondary.source}" if primary.source != secondary.source else primary.source,
+        download_availability=primary.download_availability or secondary.download_availability,
+        file_format=primary.file_format or secondary.file_format
+    )
+
+
+def calculate_score(
+    book: BookMetadata,
+    query: str,
+    author: Optional[str] = None,
+    isbn: Optional[str] = None
+) -> float:
+    """Calculates a relevance score for a book based on search query and filters."""
+    score = 0.0
+
+    # 1. Exact ISBN Match (Max weight)
+    if isbn:
+        norm_query_isbn = normalize_isbn(isbn)
+        norm_book_isbn = normalize_isbn(book.isbn)
+        if norm_query_isbn and norm_book_isbn and norm_query_isbn == norm_book_isbn:
+            score += 200.0
+
+    # 2. Fuzzy Title Match
+    if query.strip():
+        # Title token sort ratio
+        title_ratio = fuzz.token_sort_ratio(query.lower(), book.title.lower())
+        # Title partial ratio (helps when query is a substring)
+        title_partial = fuzz.partial_ratio(query.lower(), book.title.lower())
+        score += (title_ratio * 0.6) + (title_partial * 0.4)
+
+    # 3. Fuzzy Author Match
+    book_authors_str = " ".join(book.authors).lower()
+    if author and book_authors_str:
+        author_ratio = fuzz.token_sort_ratio(author.lower(), book_authors_str)
+        score += author_ratio * 0.8
+    elif query.strip() and book_authors_str:
+        # Check if the query itself matches the author name
+        author_query_ratio = fuzz.token_sort_ratio(query.lower(), book_authors_str)
+        # If query matches author, add a moderate weight
+        if author_query_ratio > 70:
+            score += author_query_ratio * 0.4
+
+    # 4. Download Availability Bonus
+    if book.download_availability:
+        score += 15.0
+
+    # 5. Publisher Match (bonus if publisher was in query terms)
+    if query.strip() and book.publisher:
+        pub_ratio = fuzz.partial_ratio(query.lower(), book.publisher.lower())
+        if pub_ratio > 80:
+            score += 5.0
+
+    return score
+
+
+def rank_and_deduplicate(
+    books: List[BookMetadata],
+    query: str,
+    author: Optional[str] = None,
+    isbn: Optional[str] = None
+) -> List[BookMetadata]:
+    """Deduplicates and ranks a list of book metadata objects."""
+    # Deduplicate in-memory
+    unique_books: List[BookMetadata] = []
+    
+    for book in books:
+        found_dup_idx = -1
+        for idx, u_book in enumerate(unique_books):
+            if is_duplicate(book, u_book):
+                found_dup_idx = idx
+                break
+        
+        if found_dup_idx >= 0:
+            # Merge duplicate
+            unique_books[found_dup_idx] = merge_books(unique_books[found_dup_idx], book)
+        else:
+            unique_books.append(book)
+
+    # Calculate score and sort
+    # We sort descending by score
+    scored_books = [
+        (calculate_score(book, query, author, isbn), book)
+        for book in unique_books
+    ]
+    
+    scored_books.sort(key=lambda x: x[0], reverse=True)
+    
+    return [book for _, book in scored_books]

bookcli/services/search.py

@@ -0,0 +1,96 @@
+"""Service coordinating concurrent search across multiple providers."""
+
+import asyncio
+import logging
+from typing import List, Optional
+
+from bookcli.config import AppConfig
+from bookcli.database import DatabaseManager
+from bookcli.models import BookMetadata
+from bookcli.cache import save_book_to_cache
+from bookcli.services.ranking import rank_and_deduplicate
+from bookcli.services.history import add_search_history
+from bookcli.providers.google_books import GoogleBooksProvider
+from bookcli.providers.openlibrary import OpenLibraryProvider
+from bookcli.providers.gutenberg import GutenbergProvider
+from bookcli.providers.internet_archive import InternetArchiveProvider
+
+logger = logging.getLogger(__name__)
+
+
+async def search_books(
+    query: str,
+    config: AppConfig,
+    db_manager: DatabaseManager,
+    author: Optional[str] = None,
+    isbn: Optional[str] = None,
+    publisher: Optional[str] = None,
+    subject: Optional[str] = None
+) -> List[BookMetadata]:
+    """Searches concurrently across all enabled book search providers, merges and ranks results.
+
+    Saves results to cache and logs the search query to history.
+    """
+    providers = []
+
+    # Instantiate only enabled providers
+    if config.providers.google_books:
+        providers.append(GoogleBooksProvider(timeout_seconds=config.timeout_seconds))
+    if config.providers.openlibrary:
+        providers.append(OpenLibraryProvider(timeout_seconds=config.timeout_seconds))
+    if config.providers.gutenberg:
+        providers.append(GutenbergProvider(timeout_seconds=config.timeout_seconds))
+    if config.providers.internet_archive:
+        providers.append(InternetArchiveProvider(timeout_seconds=config.timeout_seconds))
+
+    if not providers:
+        logger.warning("No search providers are enabled.")
+        return []
+
+    # Run searches concurrently
+    tasks = [
+        provider.search(
+            query=query,
+            author=author,
+            isbn=isbn,
+            publisher=publisher,
+            subject=subject
+        )
+        for provider in providers
+    ]
+
+    # Gather with return_exceptions=True to avoid one provider crash blocking others
+    search_results = await asyncio.gather(*tasks, return_exceptions=True)
+
+    all_books: List[BookMetadata] = []
+    for provider, result in zip(providers, search_results):
+        if isinstance(result, Exception):
+            logger.error("Provider %s search failed: %s", provider.name, result)
+        elif result:
+            all_books.extend(result)
+
+    # Rank and deduplicate
+    ranked_books = rank_and_deduplicate(
+        books=all_books,
+        query=query,
+        author=author,
+        isbn=isbn
+    )
+
+    # Cache metadata for each book (so it can be retrieved via book info <id> or book download <id> instantly)
+    # This also allows offline metadata lookup.
+    cache_tasks = [save_book_to_cache(db_manager, book) for book in ranked_books]
+    if cache_tasks:
+        await asyncio.gather(*cache_tasks, return_exceptions=True)
+
+    # Log to history
+    try:
+        await add_search_history(
+            db_manager=db_manager,
+            query=query or f"[author:{author or ''} isbn:{isbn or ''} pub:{publisher or ''} subj:{subject or ''}]",
+            results_count=len(ranked_books)
+        )
+    except Exception as history_err:
+        logger.error("Failed to write search history: %s", history_err)
+
+    return ranked_books

bookcli/settings.py

@@ -0,0 +1,28 @@
+"""Default settings and constants for BookCLI."""
+
+import os
+from pathlib import Path
+
+# Base Directory ~/.bookcli
+BASE_DIR = Path(os.environ.get("BOOKCLI_HOME", Path.home() / ".bookcli"))
+BASE_DIR.mkdir(parents=True, exist_ok=True)
+
+# File Paths
+DB_PATH = BASE_DIR / "bookcli.db"
+CONFIG_PATH = BASE_DIR / "config.json"
+DEFAULT_DOWNLOAD_DIR = BASE_DIR / "downloads"
+DEFAULT_DOWNLOAD_DIR.mkdir(parents=True, exist_ok=True)
+
+# Default configuration settings
+DEFAULT_CONFIG = {
+    "download_dir": str(DEFAULT_DOWNLOAD_DIR),
+    "cache_ttl_seconds": 86400,  # 1 day
+    "timeout_seconds": 15,
+    "theme": "dark",
+    "providers": {
+        "google_books": True,
+        "openlibrary": True,
+        "gutenberg": True,
+        "internet_archive": True
+    }
+}

bookcli/utils.py

@@ -0,0 +1,30 @@
+"""General utility helper functions for formatting and CLI presentation."""
+
+from typing import Union
+
+
+def format_size(size_in_bytes: Union[int, float]) -> str:
+    """Formats raw byte sizes into human-readable strings (KB, MB, GB)."""
+    if size_in_bytes < 1024:
+        return f"{size_in_bytes} B"
+    elif size_in_bytes < 1024 * 1024:
+        return f"{size_in_bytes / 1024:.2f} KB"
+    elif size_in_bytes < 1024 * 1024 * 1024:
+        return f"{size_in_bytes / (1024 * 1024):.2f} MB"
+    else:
+        return f"{size_in_bytes / (1024 * 1024 * 1024):.2f} GB"
+
+
+def format_speed(bytes_per_second: Union[int, float]) -> str:
+    """Formats transfer speed into human-readable strings (KB/s, MB/s)."""
+    return f"{format_size(bytes_per_second)}/s"
+
+
+def clean_filename(title: str) -> str:
+    """Cleans a string to make it safe for a filename."""
+    # Strip non-alphanumeric, spaces, underscores, dashes
+    cleaned = "".join(c for c in title if c.isalnum() or c in (" ", "_", "-")).strip()
+    # Replace spaces with underscores
+    cleaned = cleaned.replace(" ", "_")
+    # Limit length
+    return cleaned[:100]