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

crossref_local/_core/export.py

@@ -0,0 +1,344 @@
+"""Export functionality for Work and SearchResult objects.
+
+Supports multiple output formats:
+- text: Human-readable formatted text
+- json: JSON format with all fields
+- bibtex: BibTeX bibliography format
+"""
+
+import json as _json
+from pathlib import Path as _Path
+from typing import TYPE_CHECKING, List, Optional, Union
+
+if TYPE_CHECKING:
+    from .models import SearchResult, Work
+
+__all__ = [
+    "save",
+    "export_text",
+    "export_json",
+    "export_bibtex",
+    "SUPPORTED_FORMATS",
+]
+
+SUPPORTED_FORMATS = ["text", "json", "bibtex"]
+
+
+def _sanitize_bibtex_key(doi: str) -> str:
+    """Convert DOI to valid BibTeX key."""
+    return doi.replace("/", "_").replace(".", "_").replace("-", "_")
+
+
+def _escape_bibtex(text: str) -> str:
+    """Escape special characters for BibTeX."""
+    if not text:
+        return ""
+    # Escape special LaTeX characters
+    replacements = [
+        ("&", r"\&"),
+        ("%", r"\%"),
+        ("$", r"\$"),
+        ("#", r"\#"),
+        ("_", r"\_"),
+        ("{", r"\{"),
+        ("}", r"\}"),
+    ]
+    for old, new in replacements:
+        text = text.replace(old, new)
+    return text
+
+
+def work_to_text(work: "Work", include_abstract: bool = False) -> str:
+    """Convert a Work to human-readable text format.
+
+    Args:
+        work: Work object to convert
+        include_abstract: Whether to include abstract
+
+    Returns:
+        Formatted text string
+    """
+    lines = []
+
+    # Title
+    title = work.title or "Untitled"
+    year = f"({work.year})" if work.year else ""
+    lines.append(f"{title} {year}".strip())
+
+    # Authors
+    if work.authors:
+        authors_str = ", ".join(work.authors[:5])
+        if len(work.authors) > 5:
+            authors_str += f" et al. ({len(work.authors)} authors)"
+        lines.append(f"Authors: {authors_str}")
+
+    # Journal and DOI
+    if work.journal:
+        journal_line = f"Journal: {work.journal}"
+        if work.volume:
+            journal_line += f", {work.volume}"
+            if work.issue:
+                journal_line += f"({work.issue})"
+        if work.page:
+            journal_line += f", {work.page}"
+        lines.append(journal_line)
+
+    lines.append(f"DOI: {work.doi}")
+
+    # Impact factor
+    if work.impact_factor:
+        lines.append(
+            f"Impact Factor: {work.impact_factor:.2f} ({work.impact_factor_source or 'unknown'})"
+        )
+
+    # Citation count
+    if work.citation_count is not None:
+        lines.append(f"Citations: {work.citation_count}")
+
+    # Abstract
+    if include_abstract and work.abstract:
+        # Strip XML tags
+        import re
+
+        abstract = re.sub(r"<[^>]+>", " ", work.abstract)
+        abstract = re.sub(r"\s+", " ", abstract).strip()
+        lines.append(f"Abstract: {abstract}")
+
+    return "\n".join(lines)
+
+
+def work_to_bibtex(work: "Work") -> str:
+    """Convert a Work to BibTeX format.
+
+    Args:
+        work: Work object to convert
+
+    Returns:
+        BibTeX entry string
+    """
+    key = _sanitize_bibtex_key(work.doi) if work.doi else "unknown"
+    work_type = work.type or "article"
+
+    # Map CrossRef types to BibTeX types
+    bibtex_type_map = {
+        "journal-article": "article",
+        "book-chapter": "incollection",
+        "book": "book",
+        "proceedings-article": "inproceedings",
+        "dissertation": "phdthesis",
+        "report": "techreport",
+    }
+    bibtex_type = bibtex_type_map.get(work_type, "misc")
+
+    lines = [f"@{bibtex_type}{{{key},"]
+
+    if work.title:
+        lines.append(f"  title = {{{_escape_bibtex(work.title)}}},")
+
+    if work.authors:
+        authors = " and ".join(work.authors)
+        lines.append(f"  author = {{{_escape_bibtex(authors)}}},")
+
+    if work.year:
+        lines.append(f"  year = {{{work.year}}},")
+
+    if work.journal:
+        lines.append(f"  journal = {{{_escape_bibtex(work.journal)}}},")
+
+    if work.volume:
+        lines.append(f"  volume = {{{work.volume}}},")
+
+    if work.issue:
+        lines.append(f"  number = {{{work.issue}}},")
+
+    if work.page:
+        lines.append(f"  pages = {{{work.page}}},")
+
+    if work.publisher:
+        lines.append(f"  publisher = {{{_escape_bibtex(work.publisher)}}},")
+
+    if work.doi:
+        lines.append(f"  doi = {{{work.doi}}},")
+
+    if work.url:
+        lines.append(f"  url = {{{work.url}}},")
+
+    if work.issn:
+        lines.append(f"  issn = {{{work.issn}}},")
+
+    lines.append("}")
+
+    return "\n".join(lines)
+
+
+def export_text(
+    works: List["Work"],
+    include_abstract: bool = False,
+    query: Optional[str] = None,
+    total: Optional[int] = None,
+    elapsed_ms: Optional[float] = None,
+) -> str:
+    """Export works to text format.
+
+    Args:
+        works: List of Work objects
+        include_abstract: Whether to include abstracts
+        query: Original search query (for header)
+        total: Total number of matches
+        elapsed_ms: Search time in milliseconds
+
+    Returns:
+        Formatted text string
+    """
+    lines = []
+
+    # Header
+    if query is not None:
+        lines.append(f"Search: {query}")
+        if total is not None:
+            lines.append(f"Found: {total:,} matches")
+        if elapsed_ms is not None:
+            lines.append(f"Time: {elapsed_ms:.1f}ms")
+        lines.append("")
+        lines.append("=" * 60)
+        lines.append("")
+
+    # Works
+    for i, work in enumerate(works, 1):
+        lines.append(f"[{i}]")
+        lines.append(work_to_text(work, include_abstract=include_abstract))
+        lines.append("")
+        lines.append("-" * 40)
+        lines.append("")
+
+    return "\n".join(lines)
+
+
+def export_json(
+    works: List["Work"],
+    query: Optional[str] = None,
+    total: Optional[int] = None,
+    elapsed_ms: Optional[float] = None,
+    indent: int = 2,
+) -> str:
+    """Export works to JSON format.
+
+    Args:
+        works: List of Work objects
+        query: Original search query
+        total: Total number of matches
+        elapsed_ms: Search time in milliseconds
+        indent: JSON indentation
+
+    Returns:
+        JSON string
+    """
+    data = {
+        "works": [w.to_dict() for w in works],
+    }
+
+    if query is not None:
+        data["query"] = query
+    if total is not None:
+        data["total"] = total
+    if elapsed_ms is not None:
+        data["elapsed_ms"] = elapsed_ms
+
+    return _json.dumps(data, indent=indent, ensure_ascii=False)
+
+
+def export_bibtex(works: List["Work"]) -> str:
+    """Export works to BibTeX format.
+
+    Args:
+        works: List of Work objects
+
+    Returns:
+        BibTeX string with all entries
+    """
+    entries = [work_to_bibtex(w) for w in works]
+    return "\n\n".join(entries)
+
+
+def save(
+    data: Union["Work", "SearchResult", List["Work"]],
+    path: Union[str, _Path],
+    format: str = "json",
+    include_abstract: bool = True,
+) -> str:
+    """Save Work(s) or SearchResult to a file.
+
+    Args:
+        data: Work, SearchResult, or list of Works to save
+        path: Output file path
+        format: Output format ("text", "json", "bibtex")
+        include_abstract: Include abstracts in text format
+
+    Returns:
+        Path to saved file
+
+    Raises:
+        ValueError: If format is not supported
+
+    Examples:
+        >>> from crossref_local import search, save
+        >>> results = search("machine learning", limit=10)
+        >>> save(results, "results.json")
+        >>> save(results, "results.bib", format="bibtex")
+        >>> save(results, "results.txt", format="text")
+    """
+    from .models import SearchResult, Work
+
+    if format not in SUPPORTED_FORMATS:
+        raise ValueError(
+            f"Unsupported format: {format}. "
+            f"Supported formats: {', '.join(SUPPORTED_FORMATS)}"
+        )
+
+    path = _Path(path)
+
+    # Extract works and metadata
+    if isinstance(data, Work):
+        works = [data]
+        query = None
+        total = None
+        elapsed_ms = None
+    elif isinstance(data, SearchResult):
+        works = data.works
+        query = data.query
+        total = data.total
+        elapsed_ms = data.elapsed_ms
+    elif isinstance(data, list):
+        works = data
+        query = None
+        total = len(data)
+        elapsed_ms = None
+    else:
+        raise TypeError(f"Unsupported data type: {type(data)}")
+
+    # Generate content
+    if format == "text":
+        content = export_text(
+            works,
+            include_abstract=include_abstract,
+            query=query,
+            total=total,
+            elapsed_ms=elapsed_ms,
+        )
+    elif format == "json":
+        content = export_json(
+            works,
+            query=query,
+            total=total,
+            elapsed_ms=elapsed_ms,
+        )
+    elif format == "bibtex":
+        content = export_bibtex(works)
+    else:
+        raise ValueError(f"Unsupported format: {format}")
+
+    # Write to file
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(content, encoding="utf-8")
+
+    return str(path)

crossref_local/_core/fts.py

@@ -5,7 +5,7 @@ import time as _time
 from typing import List, Optional
 
 from .db import Database, get_db
-from .models import SearchResult, Work
+from .models import LimitInfo, SearchResult, Work
 
 __all__ = [
     "search",
@@ -102,11 +102,30 @@ def search(
         metadata = db._decompress_metadata(row["metadata"])
         works.append(Work.from_metadata(row["doi"], metadata))
 
+    # Build limit info
+    returned = len(works)
+    capped = returned < total and returned == limit
+    capped_reason = None
+    if capped:
+        capped_reason = (
+            f"crossref-local: Limited to {limit} results (total available: {total})"
+        )
+
+    limit_info = LimitInfo(
+        requested=limit,
+        returned=returned,
+        total_available=total,
+        capped=capped,
+        capped_reason=capped_reason,
+        stage="crossref-local",
+    )
+
     return SearchResult(
         works=works,
         total=total,
         query=query,
         elapsed_ms=elapsed_ms,
+        limit_info=limit_info,
     )
 
 

crossref_local/_core/models.py

@@ -7,6 +7,7 @@ from typing import List, Optional
 __all__ = [
     "Work",
     "SearchResult",
+    "LimitInfo",
 ]
 
 
@@ -48,6 +49,8 @@ class Work:
     url: Optional[str] = None
     citation_count: Optional[int] = None
     references: List[str] = _field(default_factory=list)
+    impact_factor: Optional[float] = None
+    impact_factor_source: Optional[str] = None
 
     @classmethod
     def from_metadata(cls, doi: str, metadata: dict) -> "Work":
@@ -130,6 +133,8 @@ class Work:
             "url": self.url,
             "citation_count": self.citation_count,
             "references": self.references,
+            "impact_factor": self.impact_factor,
+            "impact_factor_source": self.impact_factor_source,
         }
 
     def citation(self, style: str = "apa") -> str:
@@ -163,6 +168,84 @@ class Work:
 
         return ". ".join(filter(None, parts))
 
+    def to_text(self, include_abstract: bool = False) -> str:
+        """
+        Format as human-readable text.
+
+        Args:
+            include_abstract: Include abstract in output
+
+        Returns:
+            Formatted text string
+        """
+        from .export import work_to_text
+
+        return work_to_text(self, include_abstract=include_abstract)
+
+    def to_bibtex(self) -> str:
+        """
+        Format as BibTeX entry.
+
+        Returns:
+            BibTeX string
+        """
+        from .export import work_to_bibtex
+
+        return work_to_bibtex(self)
+
+    def save(self, path: str, format: str = "json") -> str:
+        """
+        Save work to file.
+
+        Args:
+            path: Output file path
+            format: Output format ("text", "json", "bibtex")
+
+        Returns:
+            Path to saved file
+
+        Examples:
+            >>> work = get("10.1038/nature12373")
+            >>> work.save("paper.json")
+            >>> work.save("paper.bib", format="bibtex")
+        """
+        from .export import save
+
+        return save(self, path, format=format)
+
+
+@_dataclass
+class LimitInfo:
+    """
+    Information about result limiting at each stage.
+
+    Attributes:
+        requested: Number of results requested
+        returned: Number of results actually returned
+        total_available: Total matches in database
+        capped: Whether results were capped
+        capped_reason: Why results were capped (if applicable)
+        stage: Which stage applied this limit (e.g., "crossref-local", "scitex", "django")
+    """
+
+    requested: int
+    returned: int
+    total_available: int
+    capped: bool = False
+    capped_reason: Optional[str] = None
+    stage: str = "crossref-local"
+
+    def to_dict(self) -> dict:
+        """Convert to dictionary."""
+        return {
+            "requested": self.requested,
+            "returned": self.returned,
+            "total_available": self.total_available,
+            "capped": self.capped,
+            "capped_reason": self.capped_reason,
+            "stage": self.stage,
+        }
+
 
 @_dataclass
 class SearchResult:
@@ -174,12 +257,14 @@ class SearchResult:
         total: Total number of matches
         query: Original search query
         elapsed_ms: Search time in milliseconds
+        limit_info: Information about result limiting
     """
 
     works: List[Work]
     total: int
     query: str
     elapsed_ms: float
+    limit_info: Optional[LimitInfo] = None
 
     def __len__(self) -> int:
         return len(self.works)
@@ -189,3 +274,27 @@ class SearchResult:
 
     def __getitem__(self, idx):
         return self.works[idx]
+
+    def save(
+        self, path: str, format: str = "json", include_abstract: bool = True
+    ) -> str:
+        """
+        Save search results to file.
+
+        Args:
+            path: Output file path
+            format: Output format ("text", "json", "bibtex")
+            include_abstract: Include abstracts in text format
+
+        Returns:
+            Path to saved file
+
+        Examples:
+            >>> results = search("machine learning", limit=10)
+            >>> results.save("results.json")
+            >>> results.save("results.bib", format="bibtex")
+            >>> results.save("results.txt", format="text")
+        """
+        from .export import save
+
+        return save(self, path, format=format, include_abstract=include_abstract)

crossref_local/_remote/base.py

@@ -10,7 +10,7 @@ import urllib.parse
 import urllib.error
 from typing import List, Optional, Dict, Any
 
-from .._core.models import Work, SearchResult
+from .._core.models import SearchResult, Work
 from .._core.config import DEFAULT_PORT
 
 # Default URL uses SCITEX port convention
@@ -104,6 +104,7 @@ class RemoteClient:
         year: Optional[int] = None,
         limit: int = 10,
         offset: int = 0,
+        with_if: bool = False,
     ) -> SearchResult:
         """
         Search for papers.
@@ -114,8 +115,9 @@ class RemoteClient:
             title: Search by title (explicit)
             authors: Search by author name
             year: Filter by publication year
-            limit: Maximum results (default: 10, max: 100)
+            limit: Maximum results (default: 10)
             offset: Skip first N results for pagination
+            with_if: Include impact factor data (OpenAlex)
 
         Returns:
             SearchResult with matching works
@@ -125,8 +127,9 @@ class RemoteClient:
 
         params = {
             "q": search_query,
-            "limit": min(limit, 100),
+            "limit": limit,
             "offset": offset,
+            "with_if": with_if,
         }
 
         data = self._request("/works", params)
@@ -142,19 +145,38 @@ class RemoteClient:
                 authors=item.get("authors", []),
                 year=item.get("year"),
                 journal=item.get("journal"),
+                issn=item.get("issn"),
                 volume=item.get("volume"),
                 issue=item.get("issue"),
                 page=item.get("page") or item.get("pages"),
                 abstract=item.get("abstract"),
                 citation_count=item.get("citation_count"),
+                impact_factor=item.get("impact_factor"),
+                impact_factor_source=item.get("impact_factor_source"),
             )
             works.append(work)
 
+        # Parse limit_info from response
+        limit_info = None
+        if data.get("limit_info"):
+            from .._core.models import LimitInfo
+
+            li = data["limit_info"]
+            limit_info = LimitInfo(
+                requested=li.get("requested", limit),
+                returned=li.get("returned", len(works)),
+                total_available=li.get("total_available", data.get("total", 0)),
+                capped=li.get("capped", False),
+                capped_reason=li.get("capped_reason"),
+                stage=li.get("stage", "crossref-local-remote"),
+            )
+
         return SearchResult(
             works=works,
             total=data.get("total", len(works)),
             query=query or title or doi or "",
             elapsed_ms=data.get("elapsed_ms", 0.0),
+            limit_info=limit_info,
         )
 
     def get(self, doi: str) -> Optional[Work]:

crossref_local/_server/models.py

@@ -20,6 +20,19 @@ class WorkResponse(BaseModel):
     page: Optional[str] = None
     abstract: Optional[str] = None
     citation_count: Optional[int] = None
+    impact_factor: Optional[float] = None
+    impact_factor_source: Optional[str] = None
+
+
+class LimitInfoResponse(BaseModel):
+    """Information about result limiting."""
+
+    requested: int
+    returned: int
+    total_available: int
+    capped: bool = False
+    capped_reason: Optional[str] = None
+    stage: str = "crossref-local"
 
 
 class SearchResponse(BaseModel):
@@ -30,6 +43,7 @@ class SearchResponse(BaseModel):
     returned: int
     elapsed_ms: float
     results: List[WorkResponse]
+    limit_info: Optional[LimitInfoResponse] = None
 
 
 class InfoResponse(BaseModel):