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

crossref_local/__init__.py

@@ -20,19 +20,19 @@ Async usage:
 Configuration
 -------------
 
-Local mode (direct database access):
+DB 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.
+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 3333:127.0.0.1:3333 nas  # In terminal
-    >>> configure_remote()  # Uses default localhost:3333
+    $ ssh -L 8333:127.0.0.1:8333 your-server  # In terminal
+    >>> configure_http()  # Uses default localhost:8333
 
 Public API
 ----------
@@ -43,6 +43,8 @@ Functions:
     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
@@ -71,8 +73,11 @@ from .api import (
     get,
     get_many,
     exists,
+    enrich,
+    enrich_dois,
     configure,
-    configure_remote,
+    configure_http,
+    configure_remote,  # Backward compatibility alias
     get_mode,
     info,
 )
@@ -86,6 +91,9 @@ from . import aio
 # 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__ = [
@@ -97,9 +105,13 @@ __all__ = [
     "get",
     "get_many",
     "exists",
+    # Enrichment (add citations/references to search results)
+    "enrich",
+    "enrich_dois",
     # Configuration
     "configure",
-    "configure_remote",
+    "configure_http",
+    "configure_remote",  # Backward compatibility alias
     "get_mode",
     "info",
     # Data models
@@ -107,6 +119,8 @@ __all__ = [
     "SearchResult",
     # Async API
     "aio",
+    # Cache module
+    "cache",
     # Citation network
     "get_citing",
     "get_cited",

crossref_local/api.py

@@ -1,13 +1,13 @@
 """Main API for crossref_local.
 
 Supports two modes:
-- local: Direct database access (requires database file)
-- remote: HTTP API access (requires API server)
+- 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 ("local" or "remote")
-- CROSSREF_LOCAL_API environment variable (API URL)
-- configure() or configure_remote() functions
+- 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
@@ -18,8 +18,8 @@ from .models import Work, SearchResult
 from . import fts
 
 
-def _get_remote_client():
-    """Get remote client (lazy import to avoid circular dependency)."""
+def _get_http_client():
+    """Get HTTP client (lazy import to avoid circular dependency)."""
     from .remote import RemoteClient
 
     return RemoteClient(Config.get_api_url())
@@ -48,8 +48,8 @@ def search(
         >>> results = search("machine learning")
         >>> print(f"Found {results.total} matches")
     """
-    if Config.get_mode() == "remote":
-        client = _get_remote_client()
+    if Config.get_mode() == "http":
+        client = _get_http_client()
         return client.search(query=query, limit=limit)
     return fts.search(query, limit, offset)
 
@@ -64,8 +64,8 @@ def count(query: str) -> int:
     Returns:
         Number of matching works
     """
-    if Config.get_mode() == "remote":
-        client = _get_remote_client()
+    if Config.get_mode() == "http":
+        client = _get_http_client()
         result = client.search(query=query, limit=1)
         return result.total
     return fts.count(query)
@@ -86,8 +86,8 @@ def get(doi: str) -> Optional[Work]:
         >>> work = get("10.1038/nature12373")
         >>> print(work.title)
     """
-    if Config.get_mode() == "remote":
-        client = _get_remote_client()
+    if Config.get_mode() == "http":
+        client = _get_http_client()
         return client.get(doi)
     db = get_db()
     metadata = db.get_metadata(doi)
@@ -106,8 +106,8 @@ def get_many(dois: List[str]) -> List[Work]:
     Returns:
         List of Work objects (missing DOIs are skipped)
     """
-    if Config.get_mode() == "remote":
-        client = _get_remote_client()
+    if Config.get_mode() == "http":
+        client = _get_http_client()
         return client.get_many(dois)
     db = get_db()
     works = []
@@ -128,8 +128,8 @@ def exists(doi: str) -> bool:
     Returns:
         True if DOI exists
     """
-    if Config.get_mode() == "remote":
-        client = _get_remote_client()
+    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,))
@@ -151,29 +151,104 @@ def configure(db_path: str) -> None:
     close_db()  # Reset singleton to use new path
 
 
-def configure_remote(api_url: str = "http://localhost:3333") -> None:
+def configure_http(api_url: str = "http://localhost:8333") -> None:
     """
-    Configure for remote API access.
+    Configure for HTTP API access.
 
     Args:
         api_url: URL of CrossRef Local API server
 
     Example:
-        >>> from crossref_local import configure_remote
-        >>> configure_remote("http://localhost:3333")
+        >>> from crossref_local import configure_http
+        >>> configure_http("http://localhost:8333")
         >>> # Or via SSH tunnel:
-        >>> # ssh -L 3333:127.0.0.1:3333 nas
-        >>> configure_remote()  # Uses default localhost:3333
+        >>> # 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:
-        "local" or "remote"
+        "db" or "http"
     """
     return Config.get_mode()
 
@@ -187,10 +262,10 @@ def info() -> dict:
     """
     mode = Config.get_mode()
 
-    if mode == "remote":
-        client = _get_remote_client()
-        remote_info = client.info()
-        return {"mode": "remote", **remote_info}
+    if mode == "http":
+        client = _get_http_client()
+        http_info = client.info()
+        return {"mode": "http", **http_info}
 
     db = get_db()
 
@@ -213,7 +288,7 @@ def info() -> dict:
         citation_count = 0
 
     return {
-        "mode": "local",
+        "mode": "db",
         "db_path": str(Config.get_db_path()),
         "works": work_count,
         "fts_indexed": fts_count,