crossref-local 0.3.0__py3-none-any.whl → 0.4.0__py3-none-any.whl

crossref_local/__init__.py

@@ -4,6 +4,9 @@ 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")
@@ -14,65 +17,126 @@ Async usage:
     >>> results = await aio.search("machine learning")
     >>> counts = await aio.count_many(["CRISPR", "neural network"])
 
-Configuration:
+Configuration
+-------------
+
+DB mode (direct database access):
     >>> from crossref_local import configure
     >>> configure("/path/to/crossref.db")
-
     Or set CROSSREF_LOCAL_DB environment variable.
+
+HTTP mode (API access via HTTP):
+    >>> from crossref_local import configure_http
+    >>> configure_http("http://localhost:8333")
+    Or set CROSSREF_LOCAL_API_URL environment variable.
+
+    Typical setup with SSH tunnel:
+    $ ssh -L 8333:127.0.0.1:8333 your-server  # In terminal
+    >>> configure_http()  # Uses default localhost:8333
+
+Public API
+----------
+
+Functions:
+    search(query, limit, offset) -> SearchResult
+    count(query) -> int
+    get(doi) -> Work | None
+    get_many(dois) -> list[Work]
+    exists(doi) -> bool
+    enrich(results) -> SearchResult
+    enrich_dois(dois) -> list[Work]
+    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.0"
+__version__ = "0.3.1"
 
-# Core API
+# Core API (public functions)
 from .api import (
     search,
     count,
     get,
     get_many,
     exists,
+    enrich,
+    enrich_dois,
     configure,
+    configure_http,
+    configure_remote,  # Backward compatibility alias
+    get_mode,
     info,
 )
 
-# Models
+# Models (public classes)
 from .models import Work, SearchResult
 
-# Database utilities
-from .db import Database, connection
-
-# Configuration
-from .config import Config
-
-# Async API
+# Async API (public module)
 from . import aio
 
-# Citation network
+# Citation network (public functions and classes)
 from .citations import get_citing, get_cited, get_citation_count, CitationNetwork
 
+# Cache module (public)
+from . import cache
+
+
+# Public API - what users should import
 __all__ = [
     # Version
     "__version__",
-    # Core API
+    # Core search/retrieval
     "search",
     "count",
     "get",
     "get_many",
     "exists",
+    # Enrichment (add citations/references to search results)
+    "enrich",
+    "enrich_dois",
+    # Configuration
     "configure",
+    "configure_http",
+    "configure_remote",  # Backward compatibility alias
+    "get_mode",
     "info",
-    # Models
+    # Data models
     "Work",
     "SearchResult",
-    # Database
-    "Database",
-    "connection",
-    # Config
-    "Config",
-    # Async
+    # Async API
     "aio",
-    # Citations
+    # Cache module
+    "cache",
+    # 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/api.py

@@ -1,13 +1,30 @@
-"""Main API for crossref_local."""
+"""Main API for crossref_local.
+
+Supports two modes:
+- db: Direct database access (requires database file)
+- http: HTTP API access (requires API server)
+
+Mode is auto-detected or can be set explicitly via:
+- CROSSREF_LOCAL_MODE environment variable ("db" or "http")
+- CROSSREF_LOCAL_API_URL environment variable (API URL)
+- configure() or configure_http() functions
+"""
 
 from typing import List, Optional
 
 from .config import Config
-from .db import Database, get_db, close_db, connection
+from .db import get_db, close_db
 from .models import Work, SearchResult
 from . import fts
 
 
+def _get_http_client():
+    """Get HTTP client (lazy import to avoid circular dependency)."""
+    from .remote import RemoteClient
+
+    return RemoteClient(Config.get_api_url())
+
+
 def search(
     query: str,
     limit: int = 10,
@@ -31,6 +48,9 @@ def search(
         >>> results = search("machine learning")
         >>> print(f"Found {results.total} matches")
     """
+    if Config.get_mode() == "http":
+        client = _get_http_client()
+        return client.search(query=query, limit=limit)
     return fts.search(query, limit, offset)
 
 
@@ -44,6 +64,10 @@ def count(query: str) -> int:
     Returns:
         Number of matching works
     """
+    if Config.get_mode() == "http":
+        client = _get_http_client()
+        result = client.search(query=query, limit=1)
+        return result.total
     return fts.count(query)
 
 
@@ -62,6 +86,9 @@ def get(doi: str) -> Optional[Work]:
         >>> work = get("10.1038/nature12373")
         >>> print(work.title)
     """
+    if Config.get_mode() == "http":
+        client = _get_http_client()
+        return client.get(doi)
     db = get_db()
     metadata = db.get_metadata(doi)
     if metadata:
@@ -79,6 +106,9 @@ def get_many(dois: List[str]) -> List[Work]:
     Returns:
         List of Work objects (missing DOIs are skipped)
     """
+    if Config.get_mode() == "http":
+        client = _get_http_client()
+        return client.get_many(dois)
     db = get_db()
     works = []
     for doi in dois:
@@ -98,6 +128,9 @@ def exists(doi: str) -> bool:
     Returns:
         True if DOI exists
     """
+    if Config.get_mode() == "http":
+        client = _get_http_client()
+        return client.exists(doi)
     db = get_db()
     row = db.fetchone("SELECT 1 FROM works WHERE doi = ?", (doi,))
     return row is not None
@@ -105,7 +138,7 @@ def exists(doi: str) -> bool:
 
 def configure(db_path: str) -> None:
     """
-    Configure database path.
+    Configure for local database access.
 
     Args:
         db_path: Path to CrossRef SQLite database
@@ -118,13 +151,122 @@ def configure(db_path: str) -> None:
     close_db()  # Reset singleton to use new path
 
 
+def configure_http(api_url: str = "http://localhost:8333") -> None:
+    """
+    Configure for HTTP API access.
+
+    Args:
+        api_url: URL of CrossRef Local API server
+
+    Example:
+        >>> from crossref_local import configure_http
+        >>> configure_http("http://localhost:8333")
+        >>> # Or via SSH tunnel:
+        >>> # ssh -L 8333:127.0.0.1:8333 your-server
+        >>> configure_http()  # Uses default localhost:8333
+    """
+    Config.set_api_url(api_url)
+
+
+# Backward compatibility alias
+configure_remote = configure_http
+
+
+def enrich(
+    results: SearchResult,
+    include_citations: bool = True,
+    include_references: bool = True,
+) -> SearchResult:
+    """
+    Enrich search results with full metadata (citations, references).
+
+    The search() function returns basic metadata for speed. This function
+    fetches full metadata for each work, adding citation counts and references.
+
+    Args:
+        results: SearchResult from search()
+        include_citations: Include citation counts
+        include_references: Include reference DOIs
+
+    Returns:
+        SearchResult with enriched works
+
+    Example:
+        >>> from crossref_local import search, enrich
+        >>> results = search("machine learning", limit=10)
+        >>> enriched = enrich(results)
+        >>> for work in enriched:
+        ...     print(f"{work.title}: {work.citation_count} citations")
+    """
+    enriched_works = []
+    for work in results.works:
+        full_work = get(work.doi)
+        if full_work:
+            enriched_works.append(full_work)
+        else:
+            # Keep original if full metadata not available
+            enriched_works.append(work)
+
+    return SearchResult(
+        works=enriched_works,
+        total=results.total,
+        query=results.query,
+        elapsed_ms=results.elapsed_ms,
+    )
+
+
+def enrich_dois(
+    dois: List[str],
+    include_citations: bool = True,
+    include_references: bool = True,
+) -> List[Work]:
+    """
+    Enrich a list of DOIs with full metadata.
+
+    Fetches complete metadata for each DOI including citation counts
+    and reference lists.
+
+    Args:
+        dois: List of DOIs to enrich
+        include_citations: Include citation counts
+        include_references: Include reference DOIs
+
+    Returns:
+        List of Work objects with full metadata
+
+    Example:
+        >>> from crossref_local import enrich_dois
+        >>> works = enrich_dois(["10.1038/nature12373", "10.1126/science.aax0758"])
+        >>> for w in works:
+        ...     print(f"{w.doi}: {w.citation_count} citations, {len(w.references)} refs")
+    """
+    return get_many(dois)
+
+
+def get_mode() -> str:
+    """
+    Get current mode.
+
+    Returns:
+        "db" or "http"
+    """
+    return Config.get_mode()
+
+
 def info() -> dict:
     """
-    Get database information.
+    Get database/API information.
 
     Returns:
-        Dictionary with database stats
+        Dictionary with database stats and mode info
     """
+    mode = Config.get_mode()
+
+    if mode == "http":
+        client = _get_http_client()
+        http_info = client.info()
+        return {"mode": "http", **http_info}
+
     db = get_db()
 
     # Get work count
@@ -146,6 +288,7 @@ def info() -> dict:
         citation_count = 0
 
     return {
+        "mode": "db",
         "db_path": str(Config.get_db_path()),
         "works": work_count,
         "fts_indexed": fts_count,