crossref-local 0.3.1__py3-none-any.whl → 0.5.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
@@ -62,29 +64,41 @@ Modules:
     aio - Async versions of all API functions
 """
 
-__version__ = "0.3.1"
+__version__ = "0.5.0"
 
-# Core API (public functions)
-from .api import (
+# Core API (from _core package)
+from ._core import (
+    # Functions
     search,
     count,
     get,
     get_many,
     exists,
+    enrich,
+    enrich_dois,
     configure,
+    configure_http,
     configure_remote,
     get_mode,
     info,
+    # Models
+    Work,
+    SearchResult,
+    # Citations
+    get_citing,
+    get_cited,
+    get_citation_count,
+    CitationNetwork,
 )
 
-# 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
+# Cache module (public)
+from . import cache
+
+# Jobs module (public)
+from . import jobs
 
 
 # Public API - what users should import
@@ -97,9 +111,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 +125,10 @@ __all__ = [
     "SearchResult",
     # Async API
     "aio",
+    # Cache module
+    "cache",
+    # Jobs module
+    "jobs",
     # Citation network
     "get_citing",
     "get_cited",

crossref_local/_aio/__init__.py

@@ -0,0 +1,30 @@
+#!/usr/bin/env python3
+"""Async API module."""
+
+from ._impl import (
+    SearchResult,
+    Work,
+    count,
+    count_many,
+    exists,
+    get,
+    get_many,
+    info,
+    search,
+    search_many,
+)
+
+__all__ = [
+    "search",
+    "count",
+    "get",
+    "get_many",
+    "exists",
+    "info",
+    "search_many",
+    "count_many",
+    "SearchResult",
+    "Work",
+]
+
+# EOF

crossref_local/_aio/_impl.py

@@ -0,0 +1,238 @@
+"""
+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 as _asyncio
+import threading as _threading
+from typing import List, Optional
+
+from .._core.config import Config as _Config
+from .._core.db import Database as _Database
+from .._core.models import SearchResult, Work
+
+__all__ = [
+    "search",
+    "count",
+    "get",
+    "get_many",
+    "exists",
+    "info",
+    "search_many",
+    "count_many",
+    # Public types for type hints
+    "SearchResult",
+    "Work",
+]
+
+# 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 .._core import fts
+
+    db = _get_thread_db()
+    return fts._search_with_db(db, query, limit, offset)
+
+
+def _count_sync(query: str) -> int:
+    """Thread-safe sync count."""
+    from .._core 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))

crossref_local/_cache/__init__.py

@@ -0,0 +1,15 @@
+#!/usr/bin/env python3
+"""Internal cache helper modules."""
+
+from .export import export
+from .utils import cache_path, get_cache_dir, meta_path, sanitize_name
+
+__all__ = [
+    "export",
+    "cache_path",
+    "get_cache_dir",
+    "meta_path",
+    "sanitize_name",
+]
+
+# EOF

crossref_local/_cache/export.py

@@ -0,0 +1,100 @@
+"""Export functionality for cache module."""
+
+import csv as _csv
+import json as _json
+from pathlib import Path as _Path
+from typing import List, Optional
+
+from .utils import sanitize_name as _sanitize_name
+
+__all__ = [
+    "export",
+]
+
+
+def _load_cache(name: str, user_id: Optional[str] = None):
+    """Load cache data (lazy import to avoid circular dependency)."""
+    from ..cache import load
+
+    return load(name, user_id=user_id)
+
+
+def export(
+    name: str,
+    output_path: str,
+    format: str = "json",
+    fields: Optional[List[str]] = None,
+    user_id: Optional[str] = None,
+) -> str:
+    """Export cache to file.
+
+    Args:
+        name: Cache name
+        output_path: Output file path
+        format: Export format (json, csv, bibtex, dois)
+        fields: Fields to include (for json/csv)
+        user_id: Optional user ID for multi-tenant scoping
+
+    Returns:
+        Output file path
+
+    Raises:
+        ValueError: If cache name contains invalid characters
+    """
+    # Validate cache name
+    _sanitize_name(name)
+    papers = _load_cache(name, user_id=user_id)
+    output = _Path(output_path)
+
+    if format == "json":
+        if fields:
+            papers = [{k: p.get(k) for k in fields} for p in papers]
+        with open(output, "w") as f:
+            _json.dump(papers, f, indent=2)
+
+    elif format == "csv":
+        if fields is None:
+            fields = ["doi", "title", "authors", "year", "journal"]
+        with open(output, "w", newline="") as f:
+            writer = _csv.DictWriter(f, fieldnames=fields, extrasaction="ignore")
+            writer.writeheader()
+            for p in papers:
+                row = dict(p)
+                if "authors" in row and isinstance(row["authors"], list):
+                    row["authors"] = "; ".join(row["authors"])
+                writer.writerow(row)
+
+    elif format == "bibtex":
+        lines = []
+        for p in papers:
+            doi = p.get("doi", "").replace("/", "_").replace(".", "_")
+            entry = f"@article{{{doi},\n"
+            if p.get("title"):
+                entry += f"  title = {{{p['title']}}},\n"
+            if p.get("authors"):
+                authors = (
+                    " and ".join(p["authors"])
+                    if isinstance(p["authors"], list)
+                    else p["authors"]
+                )
+                entry += f"  author = {{{authors}}},\n"
+            if p.get("year"):
+                entry += f"  year = {{{p['year']}}},\n"
+            if p.get("journal"):
+                entry += f"  journal = {{{p['journal']}}},\n"
+            if p.get("doi"):
+                entry += f"  doi = {{{p['doi']}}},\n"
+            entry += "}\n"
+            lines.append(entry)
+        with open(output, "w") as f:
+            f.write("\n".join(lines))
+
+    elif format == "dois":
+        dois = [p["doi"] for p in papers if p.get("doi")]
+        with open(output, "w") as f:
+            f.write("\n".join(dois))
+
+    else:
+        raise ValueError(f"Unknown format: {format}")
+
+    return str(output)

crossref_local/_cache/utils.py

@@ -0,0 +1,93 @@
+"""Cache utility functions for crossref-local.
+
+Provides path handling and validation utilities for the cache module.
+"""
+
+import os as _os
+import re as _re
+from pathlib import Path as _Path
+from typing import Optional
+
+__all__ = [
+    "sanitize_name",
+    "get_cache_dir",
+    "cache_path",
+    "meta_path",
+]
+
+
+# Valid cache name pattern: alphanumeric, underscores, hyphens only
+_CACHE_NAME_PATTERN = _re.compile(r"^[a-zA-Z0-9_-]+$")
+
+
+def sanitize_name(name: str) -> str:
+    """Sanitize cache name to prevent path traversal.
+
+    Args:
+        name: Cache name to sanitize
+
+    Returns:
+        Sanitized name
+
+    Raises:
+        ValueError: If name contains invalid characters
+    """
+    if not name:
+        raise ValueError("Cache name cannot be empty")
+    if not _CACHE_NAME_PATTERN.match(name):
+        raise ValueError(
+            f"Invalid cache name '{name}': only alphanumeric, underscores, and hyphens allowed"
+        )
+    if len(name) > 64:
+        raise ValueError(f"Cache name too long: {len(name)} chars (max 64)")
+    return name
+
+
+def get_cache_dir(user_id: Optional[str] = None) -> _Path:
+    """Get cache directory, creating if needed.
+
+    Args:
+        user_id: Optional user ID for multi-tenant scoping.
+                 If provided, creates a user-specific subdirectory.
+    """
+    cache_dir = _Path(
+        _os.environ.get(
+            "CROSSREF_LOCAL_CACHE_DIR", _Path.home() / ".cache" / "crossref-local"
+        )
+    )
+    # Add user subdirectory for multi-tenant support
+    if user_id:
+        # Sanitize user_id as well
+        safe_user_id = _re.sub(r"[^a-zA-Z0-9_-]", "", user_id[:16])
+        if safe_user_id:
+            cache_dir = cache_dir / safe_user_id
+    cache_dir.mkdir(parents=True, exist_ok=True)
+    return cache_dir
+
+
+def cache_path(name: str, user_id: Optional[str] = None) -> _Path:
+    """Get path for a named cache.
+
+    Args:
+        name: Cache name (will be sanitized)
+        user_id: Optional user ID for multi-tenant scoping
+
+    Returns:
+        Path to cache file
+    """
+    safe_name = sanitize_name(name)
+    return get_cache_dir(user_id) / f"{safe_name}.json"
+
+
+def meta_path(name: str, user_id: Optional[str] = None) -> _Path:
+    """Get path for cache metadata.
+
+    Args:
+        name: Cache name (will be sanitized)
+        user_id: Optional user ID for multi-tenant scoping
+
+    Returns:
+        Path to metadata file
+    """
+    safe_name = sanitize_name(name)
+    return get_cache_dir(user_id) / f"{safe_name}.meta.json"