crossref-local 0.3.1__py3-none-any.whl

crossref_local/__init__.py

@@ -0,0 +1,128 @@
+"""
+crossref_local - Local CrossRef database with full-text search.
+
+A Python package for querying a local mirror of the CrossRef database
+with 167M+ scholarly works, full-text search, and impact factor calculation.
+
+Quick Start
+-----------
+
+Sync usage:
+    >>> from crossref_local import search, get
+    >>> results = search("hippocampal sharp wave ripples")
+    >>> work = get("10.1126/science.aax0758")
+
+Async usage:
+    >>> from crossref_local import aio
+    >>> results = await aio.search("machine learning")
+    >>> counts = await aio.count_many(["CRISPR", "neural network"])
+
+Configuration
+-------------
+
+Local mode (direct database access):
+    >>> from crossref_local import configure
+    >>> configure("/path/to/crossref.db")
+    Or set CROSSREF_LOCAL_DB environment variable.
+
+Remote mode (API access via HTTP):
+    >>> from crossref_local import configure_remote
+    >>> configure_remote("http://localhost:3333")
+    Or set CROSSREF_LOCAL_API environment variable.
+
+    Typical setup with SSH tunnel:
+    $ ssh -L 3333:127.0.0.1:3333 nas  # In terminal
+    >>> configure_remote()  # Uses default localhost:3333
+
+Public API
+----------
+
+Functions:
+    search(query, limit, offset) -> SearchResult
+    count(query) -> int
+    get(doi) -> Work | None
+    get_many(dois) -> list[Work]
+    exists(doi) -> bool
+    configure(db_path) -> None
+    configure_remote(api_url) -> None
+    get_mode() -> str
+    info() -> dict
+
+Citation functions:
+    get_citing(doi) -> list[str]
+    get_cited(doi) -> list[str]
+    get_citation_count(doi) -> int
+
+Classes:
+    Work - Scholarly work with title, authors, DOI, etc.
+    SearchResult - Container for search results
+    CitationNetwork - Citation graph builder and visualizer
+
+Modules:
+    aio - Async versions of all API functions
+"""
+
+__version__ = "0.3.1"
+
+# Core API (public functions)
+from .api import (
+    search,
+    count,
+    get,
+    get_many,
+    exists,
+    configure,
+    configure_remote,
+    get_mode,
+    info,
+)
+
+# Models (public classes)
+from .models import Work, SearchResult
+
+# Async API (public module)
+from . import aio
+
+# Citation network (public functions and classes)
+from .citations import get_citing, get_cited, get_citation_count, CitationNetwork
+
+
+# Public API - what users should import
+__all__ = [
+    # Version
+    "__version__",
+    # Core search/retrieval
+    "search",
+    "count",
+    "get",
+    "get_many",
+    "exists",
+    # Configuration
+    "configure",
+    "configure_remote",
+    "get_mode",
+    "info",
+    # Data models
+    "Work",
+    "SearchResult",
+    # Async API
+    "aio",
+    # Citation network
+    "get_citing",
+    "get_cited",
+    "get_citation_count",
+    "CitationNetwork",
+]
+
+
+# ============================================================================
+# Advanced / Internal APIs (not in __all__, but importable if needed)
+# ============================================================================
+# These are exposed for advanced users but not part of the stable public API.
+# Use at your own risk - they may change without notice.
+#
+# from crossref_local.db import Database, connection
+# from crossref_local.config import Config
+# from crossref_local.remote import RemoteClient
+# from crossref_local.fts import search_dois
+# ============================================================================

crossref_local/__main__.py

@@ -0,0 +1,6 @@
+"""Entry point for python -m crossref_local."""
+
+from .cli import main
+
+if __name__ == "__main__":
+    main()

crossref_local/aio.py

@@ -0,0 +1,236 @@
+"""
+Async API for crossref_local.
+
+Provides async versions of all API functions. Uses thread pool execution
+with per-thread database connections for thread safety.
+
+Usage:
+    from crossref_local import aio
+
+    async def main():
+        results = await aio.search("machine learning")
+        work = await aio.get("10.1038/nature12373")
+        n = await aio.count("CRISPR")
+
+    # Or import individual functions
+    from crossref_local.aio import search, get, count
+
+    # Concurrent operations
+    counts = await aio.count_many(["CRISPR", "machine learning"])
+"""
+
+import asyncio
+import threading
+from typing import List, Optional
+
+from .models import Work, SearchResult
+from .config import Config
+from .db import Database
+
+
+# Thread-local storage for database connections
+_thread_local = threading.local()
+
+
+def _get_thread_db() -> Database:
+    """Get thread-local database connection."""
+    if not hasattr(_thread_local, 'db'):
+        _thread_local.db = Database(Config.get_db_path())
+    return _thread_local.db
+
+
+def _search_sync(query: str, limit: int, offset: int) -> SearchResult:
+    """Thread-safe sync search."""
+    from . import fts
+    # Use thread-local DB
+    db = _get_thread_db()
+    return fts._search_with_db(db, query, limit, offset)
+
+
+def _count_sync(query: str) -> int:
+    """Thread-safe sync count."""
+    from . import fts
+    db = _get_thread_db()
+    return fts._count_with_db(db, query)
+
+
+def _get_sync(doi: str) -> Optional[Work]:
+    """Thread-safe sync get."""
+    db = _get_thread_db()
+    metadata = db.get_metadata(doi)
+    if metadata:
+        return Work.from_metadata(doi, metadata)
+    return None
+
+
+def _get_many_sync(dois: List[str]) -> List[Work]:
+    """Thread-safe sync get_many."""
+    db = _get_thread_db()
+    works = []
+    for doi in dois:
+        metadata = db.get_metadata(doi)
+        if metadata:
+            works.append(Work.from_metadata(doi, metadata))
+    return works
+
+
+def _exists_sync(doi: str) -> bool:
+    """Thread-safe sync exists."""
+    db = _get_thread_db()
+    row = db.fetchone("SELECT 1 FROM works WHERE doi = ?", (doi,))
+    return row is not None
+
+
+def _info_sync() -> dict:
+    """Thread-safe sync info."""
+    db = _get_thread_db()
+
+    row = db.fetchone("SELECT COUNT(*) as count FROM works")
+    work_count = row["count"] if row else 0
+
+    try:
+        row = db.fetchone("SELECT COUNT(*) as count FROM works_fts")
+        fts_count = row["count"] if row else 0
+    except Exception:
+        fts_count = 0
+
+    try:
+        row = db.fetchone("SELECT COUNT(*) as count FROM citations")
+        citation_count = row["count"] if row else 0
+    except Exception:
+        citation_count = 0
+
+    return {
+        "db_path": str(Config.get_db_path()),
+        "works": work_count,
+        "fts_indexed": fts_count,
+        "citations": citation_count,
+    }
+
+
+async def search(
+    query: str,
+    limit: int = 10,
+    offset: int = 0,
+) -> SearchResult:
+    """
+    Async full-text search across works.
+
+    Args:
+        query: Search query (supports FTS5 syntax)
+        limit: Maximum results to return
+        offset: Skip first N results (for pagination)
+
+    Returns:
+        SearchResult with matching works
+    """
+    return await asyncio.to_thread(_search_sync, query, limit, offset)
+
+
+async def count(query: str) -> int:
+    """
+    Async count matching works without fetching results.
+
+    Args:
+        query: FTS5 search query
+
+    Returns:
+        Number of matching works
+    """
+    return await asyncio.to_thread(_count_sync, query)
+
+
+async def get(doi: str) -> Optional[Work]:
+    """
+    Async get a work by DOI.
+
+    Args:
+        doi: Digital Object Identifier
+
+    Returns:
+        Work object or None if not found
+    """
+    return await asyncio.to_thread(_get_sync, doi)
+
+
+async def get_many(dois: List[str]) -> List[Work]:
+    """
+    Async get multiple works by DOI.
+
+    Args:
+        dois: List of DOIs
+
+    Returns:
+        List of Work objects (missing DOIs are skipped)
+    """
+    return await asyncio.to_thread(_get_many_sync, dois)
+
+
+async def exists(doi: str) -> bool:
+    """
+    Async check if a DOI exists in the database.
+
+    Args:
+        doi: Digital Object Identifier
+
+    Returns:
+        True if DOI exists
+    """
+    return await asyncio.to_thread(_exists_sync, doi)
+
+
+async def info() -> dict:
+    """
+    Async get database information.
+
+    Returns:
+        Dictionary with database stats
+    """
+    return await asyncio.to_thread(_info_sync)
+
+
+async def search_many(queries: List[str], limit: int = 10) -> List[SearchResult]:
+    """
+    Run multiple searches concurrently.
+
+    Args:
+        queries: List of search queries
+        limit: Maximum results per query
+
+    Returns:
+        List of SearchResult objects
+    """
+    tasks = [search(q, limit=limit) for q in queries]
+    return await asyncio.gather(*tasks)
+
+
+async def count_many(queries: List[str]) -> dict:
+    """
+    Count matches for multiple queries concurrently.
+
+    Args:
+        queries: List of search queries
+
+    Returns:
+        Dict mapping query -> count
+
+    Example:
+        >>> counts = await count_many(["CRISPR", "machine learning"])
+        >>> print(counts)
+        {'CRISPR': 45000, 'machine learning': 477922}
+    """
+    tasks = [count(q) for q in queries]
+    results = await asyncio.gather(*tasks)
+    return dict(zip(queries, results))
+
+
+__all__ = [
+    "search",
+    "count",
+    "get",
+    "get_many",
+    "exists",
+    "info",
+    "search_many",
+    "count_many",
+]

crossref_local/api.py

@@ -0,0 +1,221 @@
+"""Main API for crossref_local.
+
+Supports two modes:
+- local: Direct database access (requires database file)
+- remote: HTTP API access (requires API server)
+
+Mode is auto-detected or can be set explicitly via:
+- CROSSREF_LOCAL_MODE environment variable ("local" or "remote")
+- CROSSREF_LOCAL_API environment variable (API URL)
+- configure() or configure_remote() functions
+"""
+
+from typing import List, Optional
+
+from .config import Config
+from .db import get_db, close_db
+from .models import Work, SearchResult
+from . import fts
+
+
+def _get_remote_client():
+    """Get remote client (lazy import to avoid circular dependency)."""
+    from .remote import RemoteClient
+
+    return RemoteClient(Config.get_api_url())
+
+
+def search(
+    query: str,
+    limit: int = 10,
+    offset: int = 0,
+) -> SearchResult:
+    """
+    Full-text search across works.
+
+    Uses FTS5 index for fast searching across titles, abstracts, and authors.
+
+    Args:
+        query: Search query (supports FTS5 syntax)
+        limit: Maximum results to return
+        offset: Skip first N results (for pagination)
+
+    Returns:
+        SearchResult with matching works
+
+    Example:
+        >>> from crossref_local import search
+        >>> results = search("machine learning")
+        >>> print(f"Found {results.total} matches")
+    """
+    if Config.get_mode() == "remote":
+        client = _get_remote_client()
+        return client.search(query=query, limit=limit)
+    return fts.search(query, limit, offset)
+
+
+def count(query: str) -> int:
+    """
+    Count matching works without fetching results.
+
+    Args:
+        query: FTS5 search query
+
+    Returns:
+        Number of matching works
+    """
+    if Config.get_mode() == "remote":
+        client = _get_remote_client()
+        result = client.search(query=query, limit=1)
+        return result.total
+    return fts.count(query)
+
+
+def get(doi: str) -> Optional[Work]:
+    """
+    Get a work by DOI.
+
+    Args:
+        doi: Digital Object Identifier
+
+    Returns:
+        Work object or None if not found
+
+    Example:
+        >>> from crossref_local import get
+        >>> work = get("10.1038/nature12373")
+        >>> print(work.title)
+    """
+    if Config.get_mode() == "remote":
+        client = _get_remote_client()
+        return client.get(doi)
+    db = get_db()
+    metadata = db.get_metadata(doi)
+    if metadata:
+        return Work.from_metadata(doi, metadata)
+    return None
+
+
+def get_many(dois: List[str]) -> List[Work]:
+    """
+    Get multiple works by DOI.
+
+    Args:
+        dois: List of DOIs
+
+    Returns:
+        List of Work objects (missing DOIs are skipped)
+    """
+    if Config.get_mode() == "remote":
+        client = _get_remote_client()
+        return client.get_many(dois)
+    db = get_db()
+    works = []
+    for doi in dois:
+        metadata = db.get_metadata(doi)
+        if metadata:
+            works.append(Work.from_metadata(doi, metadata))
+    return works
+
+
+def exists(doi: str) -> bool:
+    """
+    Check if a DOI exists in the database.
+
+    Args:
+        doi: Digital Object Identifier
+
+    Returns:
+        True if DOI exists
+    """
+    if Config.get_mode() == "remote":
+        client = _get_remote_client()
+        return client.exists(doi)
+    db = get_db()
+    row = db.fetchone("SELECT 1 FROM works WHERE doi = ?", (doi,))
+    return row is not None
+
+
+def configure(db_path: str) -> None:
+    """
+    Configure for local database access.
+
+    Args:
+        db_path: Path to CrossRef SQLite database
+
+    Example:
+        >>> from crossref_local import configure
+        >>> configure("/path/to/crossref.db")
+    """
+    Config.set_db_path(db_path)
+    close_db()  # Reset singleton to use new path
+
+
+def configure_remote(api_url: str = "http://localhost:3333") -> None:
+    """
+    Configure for remote API access.
+
+    Args:
+        api_url: URL of CrossRef Local API server
+
+    Example:
+        >>> from crossref_local import configure_remote
+        >>> configure_remote("http://localhost:3333")
+        >>> # Or via SSH tunnel:
+        >>> # ssh -L 3333:127.0.0.1:3333 nas
+        >>> configure_remote()  # Uses default localhost:3333
+    """
+    Config.set_api_url(api_url)
+
+
+def get_mode() -> str:
+    """
+    Get current mode.
+
+    Returns:
+        "local" or "remote"
+    """
+    return Config.get_mode()
+
+
+def info() -> dict:
+    """
+    Get database/API information.
+
+    Returns:
+        Dictionary with database stats and mode info
+    """
+    mode = Config.get_mode()
+
+    if mode == "remote":
+        client = _get_remote_client()
+        remote_info = client.info()
+        return {"mode": "remote", **remote_info}
+
+    db = get_db()
+
+    # Get work count
+    row = db.fetchone("SELECT COUNT(*) as count FROM works")
+    work_count = row["count"] if row else 0
+
+    # Get FTS count
+    try:
+        row = db.fetchone("SELECT COUNT(*) as count FROM works_fts")
+        fts_count = row["count"] if row else 0
+    except Exception:
+        fts_count = 0
+
+    # Get citations count
+    try:
+        row = db.fetchone("SELECT COUNT(*) as count FROM citations")
+        citation_count = row["count"] if row else 0
+    except Exception:
+        citation_count = 0
+
+    return {
+        "mode": "local",
+        "db_path": str(Config.get_db_path()),
+        "works": work_count,
+        "fts_indexed": fts_count,
+        "citations": citation_count,
+    }