crossref-local 0.3.1__py3-none-any.whl

crossref_local/db.py

@@ -0,0 +1,138 @@
+"""Database connection handling for crossref_local."""
+
+import sqlite3
+import json
+import zlib
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Optional, Generator
+
+from .config import Config
+
+
+class Database:
+    """
+    Database connection manager.
+
+    Supports both direct usage and context manager pattern.
+    """
+
+    def __init__(self, db_path: Optional[str | Path] = None):
+        """
+        Initialize database connection.
+
+        Args:
+            db_path: Path to database. If None, auto-detects.
+        """
+        if db_path:
+            self.db_path = Path(db_path)
+        else:
+            self.db_path = Config.get_db_path()
+
+        self.conn: Optional[sqlite3.Connection] = None
+        self._connect()
+
+    def _connect(self) -> None:
+        """Establish database connection."""
+        # check_same_thread=False allows connection to be used across threads
+        # Safe for read-only operations (which is our use case)
+        self.conn = sqlite3.connect(self.db_path, check_same_thread=False)
+        self.conn.row_factory = sqlite3.Row
+
+    def close(self) -> None:
+        """Close database connection."""
+        if self.conn:
+            self.conn.close()
+            self.conn = None
+
+    def __enter__(self) -> "Database":
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
+        self.close()
+
+    def execute(self, query: str, params: tuple = ()) -> sqlite3.Cursor:
+        """Execute SQL query."""
+        return self.conn.execute(query, params)
+
+    def fetchone(self, query: str, params: tuple = ()) -> Optional[sqlite3.Row]:
+        """Execute query and fetch one result."""
+        cursor = self.execute(query, params)
+        return cursor.fetchone()
+
+    def fetchall(self, query: str, params: tuple = ()) -> list:
+        """Execute query and fetch all results."""
+        cursor = self.execute(query, params)
+        return cursor.fetchall()
+
+    def get_metadata(self, doi: str) -> Optional[dict]:
+        """
+        Get metadata for a DOI.
+
+        Args:
+            doi: DOI string
+
+        Returns:
+            Metadata dictionary or None
+        """
+        row = self.fetchone(
+            "SELECT metadata FROM works WHERE doi = ?",
+            (doi,)
+        )
+        if row and row["metadata"]:
+            return self._decompress_metadata(row["metadata"])
+        return None
+
+    def _decompress_metadata(self, data) -> dict:
+        """Decompress and parse metadata (handles both compressed and plain JSON)."""
+        # If it's already a string, parse directly
+        if isinstance(data, str):
+            return json.loads(data)
+
+        # If bytes, try decompression
+        if isinstance(data, bytes):
+            try:
+                decompressed = zlib.decompress(data)
+                return json.loads(decompressed)
+            except zlib.error:
+                return json.loads(data.decode("utf-8"))
+
+        return data
+
+
+# Singleton connection for convenience functions
+_db: Optional[Database] = None
+
+
+def get_db() -> Database:
+    """Get or create singleton database connection."""
+    global _db
+    if _db is None:
+        _db = Database()
+    return _db
+
+
+def close_db() -> None:
+    """Close singleton database connection."""
+    global _db
+    if _db:
+        _db.close()
+        _db = None
+
+
+@contextmanager
+def connection(db_path: Optional[str | Path] = None) -> Generator[Database, None, None]:
+    """
+    Context manager for database connection.
+
+    Args:
+        db_path: Path to database. If None, auto-detects.
+
+    Yields:
+        Database instance
+    """
+    db = Database(db_path)
+    try:
+        yield db
+    finally:
+        db.close()

crossref_local/fts.py

@@ -0,0 +1,172 @@
+"""Full-text search using FTS5."""
+
+import re
+import time
+from typing import List, Optional
+
+from .db import Database, get_db
+from .models import Work, SearchResult
+
+
+def _sanitize_query(query: str) -> str:
+    """
+    Sanitize query for FTS5.
+
+    Handles special characters that FTS5 interprets as operators:
+    - Hyphens in words like "RS-1" or "CRISPR-Cas9"
+    - Other special characters
+
+    If query contains problematic characters, wrap each term in quotes.
+    """
+    # If already quoted, return as-is
+    if query.startswith('"') and query.endswith('"'):
+        return query
+
+    # Check for problematic patterns (hyphenated words, special chars)
+    # But allow explicit FTS5 operators: AND, OR, NOT, NEAR
+    has_hyphenated_word = re.search(r'\w+-\w+', query)
+    has_special = re.search(r'[/\\@#$%^&]', query)
+
+    if has_hyphenated_word or has_special:
+        # Quote each word to treat as literal
+        words = query.split()
+        quoted = ' '.join(f'"{w}"' for w in words)
+        return quoted
+
+    return query
+
+
+def search(
+    query: str,
+    limit: int = 10,
+    offset: int = 0,
+    db: Optional[Database] = None,
+) -> SearchResult:
+    """
+    Full-text search across works.
+
+    Uses FTS5 index for fast searching across titles, abstracts, and authors.
+
+    Args:
+        query: Search query (supports FTS5 syntax like AND, OR, NOT, "phrases")
+        limit: Maximum results to return
+        offset: Skip first N results (for pagination)
+        db: Database connection (uses singleton if not provided)
+
+    Returns:
+        SearchResult with matching works
+
+    Example:
+        >>> results = search("hippocampal sharp wave ripples")
+        >>> print(f"Found {results.total} matches in {results.elapsed_ms:.1f}ms")
+        >>> for work in results:
+        ...     print(f"{work.title} ({work.year})")
+    """
+    if db is None:
+        db = get_db()
+
+    start = time.perf_counter()
+
+    # Sanitize query for FTS5
+    safe_query = _sanitize_query(query)
+
+    # Get total count
+    count_row = db.fetchone(
+        "SELECT COUNT(*) as total FROM works_fts WHERE works_fts MATCH ?",
+        (safe_query,)
+    )
+    total = count_row["total"] if count_row else 0
+
+    # Get matching works with metadata
+    rows = db.fetchall(
+        """
+        SELECT w.doi, w.metadata
+        FROM works_fts f
+        JOIN works w ON f.rowid = w.rowid
+        WHERE works_fts MATCH ?
+        LIMIT ? OFFSET ?
+        """,
+        (safe_query, limit, offset)
+    )
+
+    elapsed_ms = (time.perf_counter() - start) * 1000
+
+    # Convert to Work objects
+    works = []
+    for row in rows:
+        metadata = db._decompress_metadata(row["metadata"])
+        works.append(Work.from_metadata(row["doi"], metadata))
+
+    return SearchResult(
+        works=works,
+        total=total,
+        query=query,
+        elapsed_ms=elapsed_ms,
+    )
+
+
+def count(query: str, db: Optional[Database] = None) -> int:
+    """
+    Count matching works without fetching results.
+
+    Args:
+        query: FTS5 search query
+        db: Database connection
+
+    Returns:
+        Number of matching works
+    """
+    if db is None:
+        db = get_db()
+
+    safe_query = _sanitize_query(query)
+    row = db.fetchone(
+        "SELECT COUNT(*) as total FROM works_fts WHERE works_fts MATCH ?",
+        (safe_query,)
+    )
+    return row["total"] if row else 0
+
+
+def search_dois(
+    query: str,
+    limit: int = 1000,
+    db: Optional[Database] = None,
+) -> List[str]:
+    """
+    Search and return only DOIs (faster than full search).
+
+    Args:
+        query: FTS5 search query
+        limit: Maximum DOIs to return
+        db: Database connection
+
+    Returns:
+        List of matching DOIs
+    """
+    if db is None:
+        db = get_db()
+
+    safe_query = _sanitize_query(query)
+    rows = db.fetchall(
+        """
+        SELECT w.doi
+        FROM works_fts f
+        JOIN works w ON f.rowid = w.rowid
+        WHERE works_fts MATCH ?
+        LIMIT ?
+        """,
+        (safe_query, limit)
+    )
+
+    return [row["doi"] for row in rows]
+
+
+# Thread-safe versions for async API
+def _search_with_db(db: Database, query: str, limit: int, offset: int) -> SearchResult:
+    """Search with explicit database connection (for thread-safe async)."""
+    return search(query, limit, offset, db=db)
+
+
+def _count_with_db(db: Database, query: str) -> int:
+    """Count with explicit database connection (for thread-safe async)."""
+    return count(query, db=db)

crossref_local/impact_factor/__init__.py

@@ -0,0 +1,20 @@
+"""
+Impact Factor calculation module.
+
+Calculates journal impact factors from the local CrossRef database
+by analyzing citation patterns.
+
+Usage:
+    >>> from crossref_local.impact_factor import ImpactFactorCalculator
+    >>> with ImpactFactorCalculator() as calc:
+    ...     result = calc.calculate_impact_factor("Nature", target_year=2023)
+    ...     print(f"IF: {result['impact_factor']:.3f}")
+"""
+
+from .calculator import ImpactFactorCalculator
+from .journal_lookup import JournalLookup
+
+__all__ = [
+    "ImpactFactorCalculator",
+    "JournalLookup",
+]