crossref-local 0.5.0__py3-none-any.whl → 0.5.1__py3-none-any.whl

crossref_local/__init__.py

@@ -64,7 +64,7 @@ Modules:
     aio - Async versions of all API functions
 """
 
-__version__ = "0.5.0"
+__version__ = "0.5.1"
 
 # Core API (from _core package)
 from ._core import (
@@ -89,6 +89,9 @@ from ._core import (
     get_cited,
     get_citation_count,
     CitationNetwork,
+    # Export
+    save,
+    SUPPORTED_FORMATS,
 )
 
 # Async API (public module)
@@ -134,6 +137,9 @@ __all__ = [
     "get_cited",
     "get_citation_count",
     "CitationNetwork",
+    # Export/Save
+    "save",
+    "SUPPORTED_FORMATS",
 ]
 
 

crossref_local/_cli/cli.py

@@ -1,29 +1,15 @@
 """Command-line interface for crossref_local."""
 
-import click
-import json
-import re
 import sys
-from typing import Optional
 
+import click
 from rich.console import Console
 
-from .. import search, get, info, __version__
+from .. import __version__, info
 
 console = Console()
 
 
-def _strip_xml_tags(text: str) -> str:
-    """Strip XML/JATS tags from abstract text."""
-    if not text:
-        return text
-    # Remove XML tags
-    text = re.sub(r"<[^>]+>", " ", text)
-    # Collapse multiple spaces
-    text = re.sub(r"\s+", " ", text)
-    return text.strip()
-
-
 class AliasedGroup(click.Group):
     """Click group that supports command aliases."""
 
@@ -140,126 +126,20 @@ def cli(ctx, http: bool, api_url: str):
         Config.set_mode("http")
 
 
-def _get_if_fast(db, issn: str, cache: dict) -> Optional[float]:
-    """Fast IF lookup from pre-computed OpenAlex data."""
-    if issn in cache:
-        return cache[issn]
-    row = db.fetchone(
-        "SELECT two_year_mean_citedness FROM journals_openalex WHERE issns LIKE ?",
-        (f"%{issn}%",),
-    )
-    cache[issn] = row["two_year_mean_citedness"] if row else None
-    return cache[issn]
-
-
-@cli.command("search", context_settings=CONTEXT_SETTINGS)
-@click.argument("query")
-@click.option(
-    "-n", "--number", "limit", default=10, show_default=True, 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(
-    "-if", "--impact-factor", "with_if", is_flag=True, help="Show journal impact factor"
-)
-@click.option("--json", "as_json", is_flag=True, help="Output as JSON")
-def search_cmd(
-    query: str,
-    limit: int,
-    offset: int,
-    abstracts: bool,
-    authors: bool,
-    with_if: bool,
-    as_json: bool,
-):
-    """Search for works by title, abstract, or authors."""
-    from .._core.db import get_db
-
-    try:
-        results = search(query, limit=limit, offset=offset)
-    except ConnectionError as e:
-        click.secho(f"Error: {e}", fg="red", err=True)
-        sys.exit(1)
-
-    if_cache, db = {}, None
-    try:
-        db = get_db() if with_if else None
-    except FileNotFoundError:
-        pass  # HTTP mode: IF lookup unavailable
-
-    if as_json:
-        output = {
-            "query": results.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))
-    else:
-        click.secho(
-            f"Found {results.total:,} matches in {results.elapsed_ms:.1f}ms\n",
-            fg="green",
-        )
-        for i, work in enumerate(results.works, start=offset + 1):
-            title = _strip_xml_tags(work.title) if work.title else "Untitled"
-            year = f"({work.year})" if work.year else ""
-            click.secho(f"{i}. {title} {year}", fg="cyan", bold=True)
-            click.echo(f"   DOI: {work.doi or 'N/A'}")
-            if authors and work.authors:
-                authors_str = ", ".join(work.authors[:5])
-                if len(work.authors) > 5:
-                    authors_str += f" et al. ({len(work.authors)} total)"
-                click.echo(f"   Authors: {authors_str}")
-            journal_line = f"   Journal: {work.journal or 'N/A'}"
-            if db and work.issn and (if_val := _get_if_fast(db, work.issn, if_cache)):
-                journal_line += f" (IF: {if_val:.2f}, OpenAlex)"
-            click.echo(journal_line)
-            if abstracts and work.abstract:
-                abstract = _strip_xml_tags(work.abstract)[:500]
-                click.echo(
-                    f"   Abstract: {abstract}{'...' if len(work.abstract) > 500 else ''}"
-                )
-            click.echo()
-
-
-@cli.command("search-by-doi", context_settings=CONTEXT_SETTINGS)
-@click.argument("doi")
-@click.option("--json", "as_json", is_flag=True, help="Output as JSON")
-@click.option("--citation", is_flag=True, help="Output as citation")
-def search_by_doi_cmd(doi: str, as_json: bool, citation: bool):
-    """Search for a work by DOI."""
-    try:
-        work = get(doi)
-    except ConnectionError as e:
-        click.echo(f"Error: {e}", err=True)
-        click.echo("\nRun 'crossref-local status' to check configuration.", err=True)
-        sys.exit(1)
-
-    if work is None:
-        click.echo(f"DOI not found: {doi}", err=True)
-        sys.exit(1)
+# Register search commands from search module
+from .search import search_by_doi_cmd, search_cmd
 
-    if as_json:
-        click.echo(json.dumps(work.to_dict(), indent=2))
-    elif citation:
-        click.echo(work.citation())
-    else:
-        click.echo(f"Title: {work.title}")
-        click.echo(f"Authors: {', '.join(work.authors)}")
-        click.echo(f"Year: {work.year}")
-        click.echo(f"Journal: {work.journal}")
-        click.echo(f"DOI: {work.doi}")
-        if work.citation_count:
-            click.echo(f"Citations: {work.citation_count}")
+cli.add_command(search_cmd)
+cli.add_command(search_by_doi_cmd)
 
 
 @cli.command(context_settings=CONTEXT_SETTINGS)
 def status():
     """Show status and configuration."""
-    from .._core.config import DEFAULT_DB_PATHS, DEFAULT_API_URLS
     import os
 
+    from .._core.config import DEFAULT_API_URLS, DEFAULT_DB_PATHS
+
     click.echo("CrossRef Local - Status")
     click.echo("=" * 50)
     click.echo()
@@ -299,10 +179,10 @@ def status():
     for var_name, description, value in env_vars:
         if value:
             if var_name == "CROSSREF_LOCAL_DB":
-                status = " (OK)" if os.path.exists(value) else " (NOT FOUND)"
+                stat = " (OK)" if os.path.exists(value) else " (NOT FOUND)"
             else:
-                status = ""
-            click.echo(f"  {var_name}={value}{status}")
+                stat = ""
+            click.echo(f"  {var_name}={value}{stat}")
             click.echo(f"      | {description}")
         else:
             click.echo(f"  {var_name} (not set)")
@@ -327,11 +207,10 @@ def status():
     # Check API servers
     click.echo("API Servers:")
     api_found = None
-    api_compatible = False
     for url in DEFAULT_API_URLS:
         try:
-            import urllib.request
             import json as json_module
+            import urllib.request
 
             # Check root endpoint for version
             req = urllib.request.Request(f"{url}/", method="GET")
@@ -344,13 +223,12 @@ def status():
                     # Check version compatibility
                     if server_version == __version__:
                         click.echo(f"  [OK] {url} (v{server_version})")
-                        api_compatible = True
                     else:
                         click.echo(
                             f"  [WARN] {url} (v{server_version} != v{__version__})"
                         )
                         click.echo(
-                            f"         Server version mismatch - may be incompatible"
+                            "         Server version mismatch - may be incompatible"
                         )
 
                     if api_found is None:
@@ -442,7 +320,7 @@ def relay(host: str, port: int):
       curl "http://localhost:8333/works?q=CRISPR&limit=10"
     """
     try:
-        from .server import run_server
+        from .._server import run_server
     except ImportError:
         click.echo(
             "API server requires fastapi and uvicorn. Install with:\n"
@@ -451,7 +329,7 @@ def relay(host: str, port: int):
         )
         sys.exit(1)
 
-    from .server import DEFAULT_HOST, DEFAULT_PORT
+    from .._server import DEFAULT_HOST, DEFAULT_PORT
 
     host = host or DEFAULT_HOST
     port = port or DEFAULT_PORT
@@ -485,7 +363,6 @@ def list_apis(verbose, max_depth, as_json):
     """List Python APIs (alias for: scitex introspect api crossref_local)."""
     try:
         from scitex.cli.introspect import api
-        import click
 
         ctx = click.Context(api)
         ctx.invoke(

crossref_local/_cli/mcp_server.py

@@ -35,6 +35,8 @@ def search(
     limit: int = 10,
     offset: int = 0,
     with_abstracts: bool = False,
+    save_path: str | None = None,
+    save_format: str = "json",
 ) -> str:
     """Search for academic works by title, abstract, or authors.
 
@@ -43,9 +45,11 @@ def search(
 
     Args:
         query: Search query (e.g., "machine learning", "CRISPR", "neural network AND hippocampus")
-        limit: Maximum number of results to return (default: 10, max: 100)
+        limit: Maximum number of results to return (default: 10)
         offset: Skip first N results for pagination (default: 0)
         with_abstracts: Include abstracts in results (default: False)
+        save_path: Optional file path to save results (e.g., "results.json", "papers.bib")
+        save_format: Output format for save_path: "text", "json", or "bibtex" (default: "json")
 
     Returns:
         JSON string with search results including total count and matching works.
@@ -54,8 +58,21 @@ def search(
         search("machine learning")
         search("CRISPR", limit=20)
         search("neural network AND memory", with_abstracts=True)
+        search("epilepsy", save_path="epilepsy.bib", save_format="bibtex")
     """
-    results = _search(query, limit=min(limit, 100), offset=offset)
+    results = _search(query, limit=limit, offset=offset)
+
+    # Save to file if requested
+    saved_path = None
+    if save_path:
+        from .._core.export import save as _save
+
+        try:
+            saved_path = _save(
+                results, save_path, format=save_format, include_abstract=with_abstracts
+            )
+        except Exception as e:
+            return json.dumps({"error": f"Failed to save: {e}"})
 
     works_data = []
     for work in results.works:
@@ -70,25 +87,34 @@ def search(
             work_dict["abstract"] = work.abstract
         works_data.append(work_dict)
 
-    return json.dumps(
-        {
-            "query": results.query,
-            "total": results.total,
-            "returned": len(works_data),
-            "elapsed_ms": round(results.elapsed_ms, 2),
-            "works": works_data,
-        },
-        indent=2,
-    )
+    result = {
+        "query": results.query,
+        "total": results.total,
+        "returned": len(works_data),
+        "elapsed_ms": round(results.elapsed_ms, 2),
+        "works": works_data,
+    }
+
+    if saved_path:
+        result["saved_to"] = saved_path
+
+    return json.dumps(result, indent=2)
 
 
 @mcp.tool()
-def search_by_doi(doi: str, as_citation: bool = False) -> str:
+def search_by_doi(
+    doi: str,
+    as_citation: bool = False,
+    save_path: str | None = None,
+    save_format: str = "json",
+) -> str:
     """Get detailed information about a work by DOI.
 
     Args:
         doi: Digital Object Identifier (e.g., "10.1038/nature12373")
         as_citation: Return formatted citation instead of full metadata
+        save_path: Optional file path to save result (e.g., "paper.json", "paper.bib")
+        save_format: Output format for save_path: "text", "json", or "bibtex" (default: "json")
 
     Returns:
         JSON string with work metadata, or formatted citation string.
@@ -96,16 +122,34 @@ def search_by_doi(doi: str, as_citation: bool = False) -> str:
     Examples:
         search_by_doi("10.1038/nature12373")
         search_by_doi("10.1126/science.aax0758", as_citation=True)
+        search_by_doi("10.1038/nature12373", save_path="paper.bib", save_format="bibtex")
     """
     work = _get(doi)
 
     if work is None:
         return json.dumps({"error": f"DOI not found: {doi}"})
 
+    # Save to file if requested
+    saved_path = None
+    if save_path:
+        from .._core.export import save as _save
+
+        try:
+            saved_path = _save(work, save_path, format=save_format)
+        except Exception as e:
+            return json.dumps({"error": f"Failed to save: {e}"})
+
     if as_citation:
-        return work.citation()
+        result = work.citation()
+        if saved_path:
+            result += f"\n\n(Saved to: {saved_path})"
+        return result
 
-    return json.dumps(work.to_dict(), indent=2)
+    result = work.to_dict()
+    if saved_path:
+        result["saved_to"] = saved_path
+
+    return json.dumps(result, indent=2)
 
 
 @mcp.tool()

crossref_local/_cli/search.py

@@ -0,0 +1,199 @@
+"""Search commands for crossref-local CLI."""
+
+import json
+import re
+import sys
+from typing import Optional
+
+import click
+from rich.console import Console
+
+from .. import get, search
+from .._core.export import save as _save
+
+console = Console()
+
+CONTEXT_SETTINGS = {"help_option_names": ["-h", "--help"]}
+
+
+def _strip_xml_tags(text: str) -> str:
+    """Strip XML/JATS tags from abstract text."""
+    if not text:
+        return text
+    text = re.sub(r"<[^>]+>", " ", text)
+    text = re.sub(r"\s+", " ", text)
+    return text.strip()
+
+
+def _get_if_fast(db, issn: str, cache: dict) -> Optional[float]:
+    """Fast IF lookup from OpenAlex data."""
+    if issn in cache:
+        return cache[issn]
+    q = "SELECT two_year_mean_citedness FROM journals_openalex WHERE issns LIKE ?"
+    row = db.fetchone(q, (f"%{issn}%",))
+    cache[issn] = row["two_year_mean_citedness"] if row else None
+    return cache[issn]
+
+
+@click.command("search", context_settings=CONTEXT_SETTINGS)
+@click.argument("query")
+@click.option(
+    "-n", "--number", "limit", default=10, show_default=True, 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(
+    "-if", "--impact-factor", "with_if", is_flag=True, help="Show journal impact factor"
+)
+@click.option("--json", "as_json", is_flag=True, help="Output as JSON")
+@click.option(
+    "--save",
+    "save_path",
+    type=click.Path(),
+    help="Save results to file",
+)
+@click.option(
+    "--format",
+    "save_format",
+    type=click.Choice(["text", "json", "bibtex"]),
+    default="json",
+    help="Output format for --save (default: json)",
+)
+def search_cmd(
+    query: str,
+    limit: int,
+    offset: int,
+    abstracts: bool,
+    authors: bool,
+    with_if: bool,
+    as_json: bool,
+    save_path: Optional[str],
+    save_format: str,
+):
+    """Search for works by title, abstract, or authors."""
+    from .._core.config import Config
+    from .._core.db import get_db
+
+    try:
+        results = search(query, limit=limit, offset=offset, with_if=with_if)
+    except ConnectionError as e:
+        click.secho(f"Error: {e}", fg="red", err=True)
+        sys.exit(1)
+
+    # Local IF lookup only in DB mode (HTTP gets IF from API)
+    if_cache, db = {}, None
+    if with_if and Config.get_mode() != "http":
+        try:
+            db = get_db()
+        except FileNotFoundError:
+            pass
+
+    # Save to file if requested
+    if save_path:
+        try:
+            saved = _save(
+                results, save_path, format=save_format, include_abstract=abstracts
+            )
+            click.secho(
+                f"Saved {len(results)} results to {saved}", fg="green", err=True
+            )
+        except Exception as e:
+            click.secho(f"Error saving: {e}", fg="red", err=True)
+            sys.exit(1)
+
+    if as_json:
+        output = {
+            "query": results.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))
+    else:
+        click.secho(
+            f"Found {results.total:,} matches in {results.elapsed_ms:.1f}ms\n",
+            fg="green",
+        )
+        for i, work in enumerate(results.works, start=offset + 1):
+            title = _strip_xml_tags(work.title) if work.title else "Untitled"
+            year = f"({work.year})" if work.year else ""
+            click.secho(f"{i}. {title} {year}", fg="cyan", bold=True)
+            click.echo(f"   DOI: {work.doi or 'N/A'}")
+            if authors and work.authors:
+                authors_str = ", ".join(work.authors[:5])
+                if len(work.authors) > 5:
+                    authors_str += f" et al. ({len(work.authors)} total)"
+                click.echo(f"   Authors: {authors_str}")
+            journal_line = f"   Journal: {work.journal or 'N/A'}"
+            if_val = work.impact_factor or (
+                db and work.issn and _get_if_fast(db, work.issn, if_cache)
+            )
+            if if_val:
+                journal_line += f" (IF: {if_val:.2f}, OpenAlex)"
+            click.echo(journal_line)
+            if abstracts and work.abstract:
+                abstract = _strip_xml_tags(work.abstract)[:500]
+                click.echo(
+                    f"   Abstract: {abstract}{'...' if len(work.abstract) > 500 else ''}"
+                )
+            click.echo()
+
+
+@click.command("search-by-doi", context_settings=CONTEXT_SETTINGS)
+@click.argument("doi")
+@click.option("--json", "as_json", is_flag=True, help="Output as JSON")
+@click.option("--citation", is_flag=True, help="Output as citation")
+@click.option(
+    "--save",
+    "save_path",
+    type=click.Path(),
+    help="Save result to file",
+)
+@click.option(
+    "--format",
+    "save_format",
+    type=click.Choice(["text", "json", "bibtex"]),
+    default="json",
+    help="Output format for --save (default: json)",
+)
+def search_by_doi_cmd(
+    doi: str,
+    as_json: bool,
+    citation: bool,
+    save_path: Optional[str],
+    save_format: str,
+):
+    """Search for a work by DOI."""
+    try:
+        work = get(doi)
+    except ConnectionError as e:
+        click.echo(f"Error: {e}", err=True)
+        click.echo("\nRun 'crossref-local status' to check configuration.", err=True)
+        sys.exit(1)
+
+    if work is None:
+        click.echo(f"DOI not found: {doi}", err=True)
+        sys.exit(1)
+
+    # Save to file if requested
+    if save_path:
+        try:
+            saved = _save(work, save_path, format=save_format)
+            click.secho(f"Saved to {saved}", fg="green", err=True)
+        except Exception as e:
+            click.secho(f"Error saving: {e}", fg="red", err=True)
+            sys.exit(1)
+
+    if as_json:
+        click.echo(json.dumps(work.to_dict(), indent=2))
+    elif citation:
+        click.echo(work.citation())
+    else:
+        click.echo(f"Title: {work.title}")
+        click.echo(f"Authors: {', '.join(work.authors)}")
+        click.echo(f"Year: {work.year}")
+        click.echo(f"Journal: {work.journal}")
+        click.echo(f"DOI: {work.doi}")
+        if work.citation_count:
+            click.echo(f"Citations: {work.citation_count}")

crossref_local/_core/__init__.py

@@ -23,6 +23,7 @@ from .citations import (
 )
 from .config import Config
 from .db import Database, close_db, get_db
+from .export import SUPPORTED_FORMATS, save
 from .models import SearchResult, Work
 
 __all__ = [
@@ -53,6 +54,9 @@ __all__ = [
     "close_db",
     # Config
     "Config",
+    # Export
+    "save",
+    "SUPPORTED_FORMATS",
 ]
 
 # EOF

crossref_local/_core/api.py

@@ -48,6 +48,7 @@ def search(
     query: str,
     limit: int = 10,
     offset: int = 0,
+    with_if: bool = False,
 ) -> SearchResult:
     """
     Full-text search across works.
@@ -58,6 +59,7 @@ def search(
         query: Search query (supports FTS5 syntax)
         limit: Maximum results to return
         offset: Skip first N results (for pagination)
+        with_if: Include impact factor data (OpenAlex)
 
     Returns:
         SearchResult with matching works
@@ -69,7 +71,7 @@ def search(
     """
     if Config.get_mode() == "http":
         client = _get_http_client()
-        return client.search(query=query, limit=limit, offset=offset)
+        return client.search(query=query, limit=limit, offset=offset, with_if=with_if)
     return fts.search(query, limit, offset)