openalex-local 0.3.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

@@ -1,209 +1,8 @@
 #!/usr/bin/env python3
-"""CLI for openalex_local."""
+"""Backward compatibility: re-export from _cli."""
 
-import json
-import sys
+from ._cli import cli, main
 
-import click
+__all__ = ["cli", "main"]
 
-from . import __version__
-
-
-def _print_recursive_help(ctx, param, value):
-    """Callback for --help-recursive flag."""
-    if not value or ctx.resilient_parsing:
-        return
-
-    def _print_command_help(cmd, prefix: str, parent_ctx):
-        """Recursively print help for a command and its subcommands."""
-        click.secho(f"\n━━━ {prefix} ━━━", fg="cyan", bold=True)
-        sub_ctx = click.Context(cmd, info_name=prefix.split()[-1], parent=parent_ctx)
-        click.echo(cmd.get_help(sub_ctx))
-
-        if isinstance(cmd, click.Group):
-            for sub_name, sub_cmd in sorted(cmd.commands.items()):
-                _print_command_help(sub_cmd, f"{prefix} {sub_name}", sub_ctx)
-
-    # Print main help
-    click.secho("━━━ openalex-local ━━━", fg="cyan", bold=True)
-    click.echo(ctx.get_help())
-
-    # Print all subcommands recursively
-    for name, cmd in sorted(cli.commands.items()):
-        _print_command_help(cmd, f"openalex-local {name}", ctx)
-
-    ctx.exit(0)
-
-
-@click.group(context_settings={"help_option_names": ["-h", "--help"]})
-@click.version_option(__version__, "--version")
-@click.option("--http", is_flag=True, help="Use HTTP API instead of direct database")
-@click.option("--api-url", help="API URL for http mode (default: auto-detect)")
-@click.option(
-    "--help-recursive",
-    is_flag=True,
-    is_eager=True,
-    expose_value=False,
-    callback=_print_recursive_help,
-    help="Show help for all commands recursively.",
-)
-@click.pass_context
-def cli(ctx, http, api_url):
-    """
-    Local OpenAlex database with 284M+ works and full-text search.
-
-    \b
-    Supports both direct database access (db mode) and HTTP API (http mode).
-
-    \b
-    DB mode (default if database found):
-      openalex-local search "machine learning"
-
-    \b
-    HTTP mode (connect to API server):
-      openalex-local --http search "machine learning"
-    """
-    ctx.ensure_object(dict)
-
-    if http or api_url:
-        from . import configure_http
-
-        configure_http(api_url or "http://localhost:31292")
-
-
-@cli.command("search")
-@click.argument("query")
-@click.option("-n", "--number", default=10, help="Number of results")
-@click.option("-o", "--offset", default=0, help="Skip first N results")
-@click.option("-a", "--abstracts", is_flag=True, help="Show abstracts")
-@click.option("-A", "--authors", is_flag=True, help="Show authors")
-@click.option("--concepts", is_flag=True, help="Show concepts/topics")
-@click.option("--json", "as_json", is_flag=True, help="Output as JSON")
-def search_cmd(query, number, offset, abstracts, authors, concepts, as_json):
-    """Search for works by title, abstract, or authors."""
-    from . import search
-
-    try:
-        results = search(query, limit=number, offset=offset)
-    except FileNotFoundError as e:
-        click.secho(f"Error: {e}", fg="red", err=True)
-        sys.exit(1)
-
-    if as_json:
-        output = {
-            "query": query,
-            "total": results.total,
-            "elapsed_ms": results.elapsed_ms,
-            "works": [w.to_dict() for w in results.works],
-        }
-        click.echo(json.dumps(output, indent=2))
-        return
-
-    click.secho(
-        f"Found {results.total:,} matches in {results.elapsed_ms:.1f}ms\n",
-        fg="green",
-    )
-
-    for i, work in enumerate(results.works, 1):
-        click.secho(f"{i}. {work.title} ({work.year})", fg="cyan", bold=True)
-        click.echo(f"   DOI: {work.doi or 'N/A'}")
-        click.echo(f"   Journal: {work.source or 'N/A'}")
-
-        if authors and work.authors:
-            author_str = ", ".join(work.authors[:5])
-            if len(work.authors) > 5:
-                author_str += f" (+{len(work.authors) - 5} more)"
-            click.echo(f"   Authors: {author_str}")
-
-        if abstracts and work.abstract:
-            abstract = work.abstract[:300]
-            if len(work.abstract) > 300:
-                abstract += "..."
-            click.echo(f"   Abstract: {abstract}")
-
-        if concepts and work.concepts:
-            concept_names = [c.get("name", "") for c in work.concepts[:5]]
-            click.echo(f"   Concepts: {', '.join(concept_names)}")
-
-        click.echo()
-
-
-@cli.command("search-by-doi")
-@click.argument("doi")
-@click.option("--json", "as_json", is_flag=True, help="Output as JSON")
-def search_by_doi_cmd(doi, as_json):
-    """Search for a work by DOI."""
-    from . import get
-
-    try:
-        work = get(doi)
-    except FileNotFoundError as e:
-        click.secho(f"Error: {e}", fg="red", err=True)
-        sys.exit(1)
-
-    if work is None:
-        click.secho(f"Not found: {doi}", fg="red", err=True)
-        sys.exit(1)
-
-    if as_json:
-        click.echo(json.dumps(work.to_dict(), indent=2))
-        return
-
-    click.secho(work.title, fg="cyan", bold=True)
-    click.echo(f"DOI: {work.doi}")
-    click.echo(f"OpenAlex ID: {work.openalex_id}")
-    click.echo(f"Year: {work.year or 'N/A'}")
-    click.echo(f"Journal: {work.source or 'N/A'}")
-    click.echo(f"Type: {work.type or 'N/A'}")
-    click.echo(f"Citations: {work.cited_by_count or 0}")
-
-    if work.authors:
-        click.echo(f"Authors: {', '.join(work.authors)}")
-
-    if work.abstract:
-        click.echo(f"\nAbstract:\n{work.abstract}")
-
-    if work.is_oa and work.oa_url:
-        click.echo(f"\nOpen Access: {work.oa_url}")
-
-
-@cli.command("status")
-@click.option("--json", "as_json", is_flag=True, help="Output as JSON")
-def status_cmd(as_json):
-    """Show status and configuration."""
-    from . import info
-
-    try:
-        status = info()
-    except FileNotFoundError as e:
-        if as_json:
-            click.echo(json.dumps({"status": "error", "error": str(e)}, indent=2))
-        else:
-            click.secho(f"Error: {e}", fg="red", err=True)
-        sys.exit(1)
-
-    if as_json:
-        click.echo(json.dumps(status, indent=2))
-        return
-
-    click.secho("OpenAlex Local Status", fg="cyan", bold=True)
-    click.echo(f"Mode: {status.get('mode', 'unknown')}")
-    click.echo(f"Status: {status.get('status', 'unknown')}")
-
-    if "db_path" in status:
-        click.echo(f"Database: {status['db_path']}")
-
-    if "work_count" in status:
-        click.echo(f"Works: {status['work_count']:,}")
-
-    if "fts_indexed" in status:
-        click.echo(f"FTS Indexed: {status['fts_indexed']:,}")
-
-
-def main():
-    """Entry point for CLI."""
-    cli()
-
-
-if __name__ == "__main__":
-    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