openalex-local 0.1.0__py3-none-any.whl → 0.3.1__py3-none-any.whl

openalex_local/aio.py

@@ -0,0 +1,259 @@
+"""Async API for openalex_local.
+
+Provides async versions of all core API functions using thread-local
+database connections and asyncio.to_thread() for non-blocking execution.
+
+Example:
+    >>> import asyncio
+    >>> from openalex_local import aio
+    >>>
+    >>> async def main():
+    ...     results = await aio.search("machine learning", limit=10)
+    ...     work = await aio.get("W2741809807")
+    ...     print(f"Found {results.total} matches")
+    >>>
+    >>> asyncio.run(main())
+"""
+
+import asyncio
+import threading
+from typing import Dict, List, Optional
+
+from ._core.config import Config
+from ._core.db import Database
+from ._core.fts import _search_with_db, _count_with_db
+from ._core.models import SearchResult, Work
+
+__all__ = [
+    "search",
+    "search_many",
+    "count",
+    "count_many",
+    "get",
+    "get_many",
+    "exists",
+    "info",
+]
+
+# Thread-local storage for database connections
+_thread_local = threading.local()
+
+
+def _get_thread_db() -> Database:
+    """Get or create 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:
+    """Synchronous search with thread-local database."""
+    db = _get_thread_db()
+    return _search_with_db(db, query, limit, offset)
+
+
+def _count_sync(query: str) -> int:
+    """Synchronous count with thread-local database."""
+    db = _get_thread_db()
+    return _count_with_db(db, query)
+
+
+def _get_sync(id_or_doi: str) -> Optional[Work]:
+    """Synchronous get with thread-local database."""
+    db = _get_thread_db()
+
+    # Try as OpenAlex ID first
+    if id_or_doi.startswith("W") or id_or_doi.startswith("w"):
+        data = db.get_work(id_or_doi.upper())
+        if data:
+            return Work.from_db_row(data)
+
+    # Try as DOI
+    data = db.get_work_by_doi(id_or_doi)
+    if data:
+        return Work.from_db_row(data)
+
+    return None
+
+
+def _get_many_sync(ids: List[str]) -> List[Work]:
+    """Synchronous get_many with thread-local database."""
+    works = []
+    for id_or_doi in ids:
+        work = _get_sync(id_or_doi)
+        if work:
+            works.append(work)
+    return works
+
+
+def _exists_sync(id_or_doi: str) -> bool:
+    """Synchronous exists check with thread-local database."""
+    db = _get_thread_db()
+
+    # Try as OpenAlex ID first
+    if id_or_doi.startswith("W") or id_or_doi.startswith("w"):
+        row = db.fetchone(
+            "SELECT 1 FROM works WHERE openalex_id = ?", (id_or_doi.upper(),)
+        )
+        if row:
+            return True
+
+    # Try as DOI
+    row = db.fetchone("SELECT 1 FROM works WHERE doi = ?", (id_or_doi,))
+    return row is not None
+
+
+def _info_sync() -> dict:
+    """Synchronous info with thread-local database."""
+    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
+
+    return {
+        "status": "ok",
+        "mode": "db",
+        "db_path": str(Config.get_db_path()),
+        "work_count": work_count,
+        "fts_indexed": fts_count,
+    }
+
+
+async def search(
+    query: str,
+    limit: int = 20,
+    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
+
+    Example:
+        >>> results = await aio.search("machine learning", limit=10)
+        >>> print(f"Found {results.total} matches")
+    """
+    return await asyncio.to_thread(_search_sync, query, limit, offset)
+
+
+async def count(query: str) -> int:
+    """
+    Async count of matching works.
+
+    Args:
+        query: FTS5 search query
+
+    Returns:
+        Number of matching works
+    """
+    return await asyncio.to_thread(_count_sync, query)
+
+
+async def get(id_or_doi: str) -> Optional[Work]:
+    """
+    Async get work by OpenAlex ID or DOI.
+
+    Args:
+        id_or_doi: OpenAlex ID (e.g., W2741809807) or DOI
+
+    Returns:
+        Work object or None if not found
+
+    Example:
+        >>> work = await aio.get("W2741809807")
+        >>> work = await aio.get("10.1038/nature12373")
+    """
+    return await asyncio.to_thread(_get_sync, id_or_doi)
+
+
+async def get_many(ids: List[str]) -> List[Work]:
+    """
+    Async get multiple works by OpenAlex ID or DOI.
+
+    Args:
+        ids: List of OpenAlex IDs or DOIs
+
+    Returns:
+        List of Work objects (missing IDs are skipped)
+    """
+    return await asyncio.to_thread(_get_many_sync, ids)
+
+
+async def exists(id_or_doi: str) -> bool:
+    """
+    Async check if a work exists in the database.
+
+    Args:
+        id_or_doi: OpenAlex ID or DOI
+
+    Returns:
+        True if work exists
+    """
+    return await asyncio.to_thread(_exists_sync, id_or_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]:
+    """
+    Execute multiple searches concurrently.
+
+    Args:
+        queries: List of search queries
+        limit: Maximum results per query
+
+    Returns:
+        List of SearchResult objects
+
+    Example:
+        >>> queries = ["machine learning", "neural networks", "deep learning"]
+        >>> results = await aio.search_many(queries, limit=5)
+        >>> for r in results:
+        ...     print(f"{r.query}: {r.total} matches")
+    """
+    tasks = [search(q, limit=limit) for q in queries]
+    return await asyncio.gather(*tasks)
+
+
+async def count_many(queries: List[str]) -> Dict[str, int]:
+    """
+    Count matches for multiple queries concurrently.
+
+    Args:
+        queries: List of search queries
+
+    Returns:
+        Dictionary mapping queries to counts
+
+    Example:
+        >>> queries = ["machine learning", "neural networks"]
+        >>> counts = await aio.count_many(queries)
+        >>> print(counts)
+        {'machine learning': 5000, 'neural networks': 3000}
+    """
+    tasks = [count(q) for q in queries]
+    counts = await asyncio.gather(*tasks)
+    return dict(zip(queries, counts))

openalex_local/cache.py

@@ -0,0 +1,31 @@
+"""Cache module - re-exports from _cache package."""
+
+from ._cache import (
+    CacheInfo,
+    create,
+    append,
+    load,
+    query,
+    query_ids,
+    stats,
+    info,
+    exists,
+    list_caches,
+    delete,
+    export,
+)
+
+__all__ = [
+    "CacheInfo",
+    "create",
+    "append",
+    "load",
+    "query",
+    "query_ids",
+    "stats",
+    "info",
+    "exists",
+    "list_caches",
+    "delete",
+    "export",
+]

openalex_local/cli.py

@@ -0,0 +1,8 @@
+#!/usr/bin/env python3
+"""Backward compatibility: re-export from _cli."""
+
+from ._cli import cli, main
+
+__all__ = ["cli", "main"]
+
+# EOF

openalex_local/jobs.py

@@ -0,0 +1,169 @@
+#!/usr/bin/env python3
+# Timestamp: 2026-01-29
+"""Simple job/queue system for batch operations."""
+
+import json as _json
+import time as _time
+import uuid as _uuid
+from dataclasses import dataclass as _dataclass
+from dataclasses import field as _field
+from pathlib import Path as _Path
+from typing import Any as _Any
+from typing import Callable as _Callable
+from typing import Optional as _Optional
+
+__all__ = ["create", "get", "list_jobs", "run"]
+
+# Default jobs directory
+_JOBS_DIR = _Path.home() / ".openalex_local" / "jobs"
+
+
+@_dataclass
+class _Job:
+    """A batch job with progress tracking (internal)."""
+
+    id: str
+    items: list[str]  # e.g., DOIs or OpenAlex IDs to process
+    completed: list[str] = _field(default_factory=list)
+    failed: dict[str, str] = _field(default_factory=dict)  # item -> error
+    status: str = "pending"  # pending, running, completed, failed
+    created_at: float = _field(default_factory=_time.time)
+    updated_at: float = _field(default_factory=_time.time)
+    metadata: dict[str, _Any] = _field(default_factory=dict)
+
+    @property
+    def pending(self) -> list[str]:
+        """Items not yet processed."""
+        done = set(self.completed) | set(self.failed.keys())
+        return [i for i in self.items if i not in done]
+
+    @property
+    def progress(self) -> float:
+        """Progress as percentage (0-100)."""
+        if not self.items:
+            return 100.0
+        return len(self.completed) / len(self.items) * 100
+
+    def to_dict(self) -> dict:
+        return {
+            "id": self.id,
+            "items": self.items,
+            "completed": self.completed,
+            "failed": self.failed,
+            "status": self.status,
+            "created_at": self.created_at,
+            "updated_at": self.updated_at,
+            "metadata": self.metadata,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "_Job":
+        return cls(**data)
+
+
+class _JobQueue:
+    """Manages job persistence and execution (internal)."""
+
+    def __init__(self, jobs_dir: _Optional[_Path] = None):
+        self.jobs_dir = _Path(jobs_dir) if jobs_dir else _JOBS_DIR
+        self.jobs_dir.mkdir(parents=True, exist_ok=True)
+
+    def _job_path(self, job_id: str) -> _Path:
+        return self.jobs_dir / f"{job_id}.json"
+
+    def save(self, job: _Job) -> None:
+        """Save job to disk."""
+        job.updated_at = _time.time()
+        self._job_path(job.id).write_text(_json.dumps(job.to_dict(), indent=2))
+
+    def load(self, job_id: str) -> _Optional[_Job]:
+        """Load job from disk."""
+        path = self._job_path(job_id)
+        if not path.exists():
+            return None
+        return _Job.from_dict(_json.loads(path.read_text()))
+
+    def create(self, items: list[str], **metadata) -> _Job:
+        """Create a new job."""
+        job = _Job(id=str(_uuid.uuid4())[:8], items=items, metadata=metadata)
+        self.save(job)
+        return job
+
+    def list(self) -> list[_Job]:
+        """List all jobs."""
+        jobs = []
+        for path in self.jobs_dir.glob("*.json"):
+            try:
+                jobs.append(_Job.from_dict(_json.loads(path.read_text())))
+            except Exception:
+                continue
+        return sorted(jobs, key=lambda j: j.created_at, reverse=True)
+
+    def delete(self, job_id: str) -> bool:
+        """Delete a job."""
+        path = self._job_path(job_id)
+        if path.exists():
+            path.unlink()
+            return True
+        return False
+
+    def run(
+        self,
+        job: _Job,
+        processor: _Callable[[str], _Any],
+        on_progress: _Optional[_Callable[[_Job], None]] = None,
+    ) -> _Job:
+        """Run a job with a processor function."""
+        job.status = "running"
+        self.save(job)
+
+        for item in job.pending:
+            try:
+                processor(item)
+                job.completed.append(item)
+            except Exception as e:
+                job.failed[item] = str(e)
+            self.save(job)
+            if on_progress:
+                on_progress(job)
+
+        job.status = "completed" if not job.failed else "failed"
+        self.save(job)
+        return job
+
+
+# Module-level convenience functions
+_queue = None
+
+
+def _get_queue() -> _JobQueue:
+    global _queue
+    if _queue is None:
+        _queue = _JobQueue()
+    return _queue
+
+
+def create(items: list[str], **metadata) -> _Job:
+    """Create a new job."""
+    return _get_queue().create(items, **metadata)
+
+
+def get(job_id: str) -> _Optional[_Job]:
+    """Get a job by ID."""
+    return _get_queue().load(job_id)
+
+
+def list_jobs() -> list[_Job]:
+    """List all jobs."""
+    return _get_queue().list()
+
+
+def run(job_id: str, processor: _Callable[[str], _Any]) -> _Job:
+    """Run or resume a job."""
+    job = get(job_id)
+    if not job:
+        raise ValueError(f"Job not found: {job_id}")
+    return _get_queue().run(job, processor)
+
+
+# EOF

openalex_local/remote.py

@@ -0,0 +1,8 @@
+#!/usr/bin/env python3
+"""Backward compatibility: re-export from _remote."""
+
+from ._remote import RemoteClient, DEFAULT_API_URL, get_client, reset_client
+
+__all__ = ["RemoteClient", "DEFAULT_API_URL", "get_client", "reset_client"]
+
+# EOF

openalex_local/server.py

@@ -0,0 +1,8 @@
+#!/usr/bin/env python3
+"""Backward compatibility: re-export from _server."""
+
+from ._server import app, run_server, DEFAULT_PORT, DEFAULT_HOST
+
+__all__ = ["app", "run_server", "DEFAULT_PORT", "DEFAULT_HOST"]
+
+# EOF