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

openalex_local/_core/config.py

@@ -0,0 +1,120 @@
+#!/usr/bin/env python3
+# Timestamp: 2026-01-29
+"""Configuration for openalex_local."""
+
+import os as _os
+from pathlib import Path as _Path
+from typing import Optional as _Optional
+
+# Default database locations (checked in order)
+DEFAULT_DB_PATHS = [
+    _Path("/home/ywatanabe/proj/openalex-local/data/openalex.db"),
+    _Path("/home/ywatanabe/proj/openalex_local/data/openalex.db"),
+    _Path("/mnt/nas_ug/openalex_local/data/openalex.db"),
+    _Path.home() / ".openalex_local" / "openalex.db",
+    _Path.cwd() / "data" / "openalex.db",
+]
+
+
+def get_db_path() -> _Path:
+    """Get database path from environment or auto-detect."""
+    env_path = _os.environ.get("OPENALEX_LOCAL_DB")
+    if env_path:
+        path = _Path(env_path)
+        if path.exists():
+            return path
+        raise FileNotFoundError(f"OPENALEX_LOCAL_DB path not found: {env_path}")
+
+    for path in DEFAULT_DB_PATHS:
+        if path.exists():
+            return path
+
+    raise FileNotFoundError(
+        "OpenAlex database not found. Set OPENALEX_LOCAL_DB environment variable."
+    )
+
+
+DEFAULT_PORT = 31292
+DEFAULT_HOST = "0.0.0.0"
+
+
+class Config:
+    """Configuration container."""
+
+    _db_path: _Optional[_Path] = None
+    _api_url: _Optional[str] = None
+    _mode: str = "auto"  # "auto", "db", or "http"
+
+    @classmethod
+    def get_db_path(cls) -> _Path:
+        if cls._db_path is None:
+            cls._db_path = get_db_path()
+        return cls._db_path
+
+    @classmethod
+    def set_db_path(cls, path: str) -> None:
+        p = _Path(path)
+        if not p.exists():
+            raise FileNotFoundError(f"Database not found: {path}")
+        cls._db_path = p
+        cls._mode = "db"
+
+    @classmethod
+    def get_api_url(cls) -> str:
+        if cls._api_url:
+            return cls._api_url
+        return _os.environ.get(
+            "OPENALEX_LOCAL_API_URL", f"http://localhost:{DEFAULT_PORT}"
+        )
+
+    @classmethod
+    def set_api_url(cls, url: str) -> None:
+        cls._api_url = url.rstrip("/")
+        cls._mode = "http"
+
+    @classmethod
+    def set_mode(cls, mode: str) -> None:
+        """Set mode explicitly: 'db', 'http', or 'auto'."""
+        if mode not in ("auto", "db", "http"):
+            raise ValueError(f"Invalid mode: {mode}. Use 'auto', 'db', or 'http'")
+        cls._mode = mode
+
+    @classmethod
+    def get_mode(cls) -> str:
+        """
+        Get current mode.
+
+        Returns:
+            "db" if using direct database access
+            "http" if using HTTP API
+        """
+        if cls._mode == "auto":
+            # Check environment variable for explicit mode
+            env_mode = _os.environ.get("OPENALEX_LOCAL_MODE", "").lower()
+            if env_mode in ("http", "remote", "api"):
+                return "http"
+            if env_mode in ("db", "local"):
+                return "db"
+
+            # Check if API URL is set explicitly
+            if cls._api_url or _os.environ.get("OPENALEX_LOCAL_API_URL"):
+                return "http"
+
+            # Check if local database exists
+            try:
+                get_db_path()
+                return "db"
+            except FileNotFoundError:
+                # No local DB, try http
+                return "http"
+
+        return cls._mode
+
+    @classmethod
+    def reset(cls) -> None:
+        cls._db_path = None
+        cls._api_url = None
+        cls._mode = "auto"
+
+
+# EOF

openalex_local/{db.py → _core/db.py}

@@ -120,6 +120,59 @@ class Database:
 
         return result
 
+    def get_source_metrics(self, issn: str) -> Optional[Dict[str, Any]]:
+        """
+        Get source/journal metrics by ISSN.
+
+        Args:
+            issn: Journal ISSN
+
+        Returns:
+            Dictionary with impact_factor, h_index, cited_by_count or None
+        """
+        if not issn:
+            return None
+
+        # Try lookup via issn_lookup table first (fast)
+        row = self.fetchone(
+            """
+            SELECT s.two_year_mean_citedness as impact_factor,
+                   s.h_index as source_h_index,
+                   s.cited_by_count as source_cited_by_count,
+                   s.display_name as source_name
+            FROM issn_lookup l
+            JOIN sources s ON l.source_id = s.id
+            WHERE l.issn = ?
+            """,
+            (issn,),
+        )
+        if row:
+            return dict(row)
+
+        # Fallback: search in sources.issns JSON field
+        row = self.fetchone(
+            """
+            SELECT two_year_mean_citedness as impact_factor,
+                   h_index as source_h_index,
+                   cited_by_count as source_cited_by_count,
+                   display_name as source_name
+            FROM sources
+            WHERE issn_l = ? OR issns LIKE ?
+            """,
+            (issn, f'%"{issn}"%'),
+        )
+        if row:
+            return dict(row)
+
+        return None
+
+    def has_sources_table(self) -> bool:
+        """Check if sources table exists."""
+        row = self.fetchone(
+            "SELECT 1 FROM sqlite_master WHERE type='table' AND name='sources'"
+        )
+        return row is not None
+
 
 # Singleton connection for convenience functions
 _db: Optional[Database] = None

openalex_local/_core/export.py

@@ -0,0 +1,252 @@
+"""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 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 identifiers
+    if work.source:
+        source_line = f"Journal: {work.source}"
+        if work.volume:
+            source_line += f", {work.volume}"
+            if work.issue:
+                source_line += f"({work.issue})"
+        if work.pages:
+            source_line += f", {work.pages}"
+        lines.append(source_line)
+
+    if work.doi:
+        lines.append(f"DOI: {work.doi}")
+
+    lines.append(f"OpenAlex ID: {work.openalex_id}")
+
+    # Citation count
+    if work.cited_by_count is not None:
+        lines.append(f"Citations: {work.cited_by_count}")
+
+    # Open access
+    if work.is_oa:
+        lines.append(f"Open Access: {work.oa_url or 'Yes'}")
+
+    # Abstract
+    if include_abstract and work.abstract:
+        lines.append(f"Abstract: {work.abstract}")
+
+    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 = [w.citation("bibtex") 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 openalex_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)

openalex_local/{models.py → _core/models.py}

@@ -50,6 +50,10 @@ class Work:
     referenced_works: List[str] = field(default_factory=list)
     is_oa: bool = False
     oa_url: Optional[str] = None
+    # Source/journal metrics (from sources table)
+    impact_factor: Optional[float] = None  # 2yr_mean_citedness
+    source_h_index: Optional[int] = None
+    source_cited_by_count: Optional[int] = None
 
     @classmethod
     def from_openalex(cls, data: dict) -> "Work":
@@ -177,6 +181,9 @@ class Work:
             referenced_works=data.get("referenced_works", []),
             is_oa=bool(data.get("is_oa", False)),
             oa_url=data.get("oa_url"),
+            impact_factor=data.get("impact_factor"),
+            source_h_index=data.get("source_h_index"),
+            source_cited_by_count=data.get("source_cited_by_count"),
         )
 
     def to_dict(self) -> dict:
@@ -201,8 +208,179 @@ class Work:
             "referenced_works": self.referenced_works,
             "is_oa": self.is_oa,
             "oa_url": self.oa_url,
+            "impact_factor": self.impact_factor,
+            "source_h_index": self.source_h_index,
+            "source_cited_by_count": self.source_cited_by_count,
         }
 
+    def citation(self, style: str = "apa") -> str:
+        """
+        Format work as a citation string.
+
+        Args:
+            style: Citation style - "apa" (default) or "bibtex"
+
+        Returns:
+            Formatted citation string
+
+        Example:
+            >>> work.citation()  # APA format
+            'Piwowar, H., & Priem, J. (2018). The state of OA. PeerJ.'
+            >>> work.citation("bibtex")  # BibTeX format
+            '@article{W2741809807, title={The state of OA}, ...}'
+        """
+        if style.lower() == "bibtex":
+            return self._citation_bibtex()
+        return self._citation_apa()
+
+    def _citation_apa(self) -> str:
+        """Format as APA citation."""
+        parts = []
+
+        # Authors
+        if self.authors:
+            if len(self.authors) == 1:
+                parts.append(self._format_author_apa(self.authors[0]))
+            elif len(self.authors) == 2:
+                parts.append(
+                    f"{self._format_author_apa(self.authors[0])} & "
+                    f"{self._format_author_apa(self.authors[1])}"
+                )
+            else:
+                formatted = [self._format_author_apa(a) for a in self.authors[:19]]
+                if len(self.authors) > 20:
+                    formatted = (
+                        formatted[:19]
+                        + ["..."]
+                        + [self._format_author_apa(self.authors[-1])]
+                    )
+                parts.append(", ".join(formatted[:-1]) + ", & " + formatted[-1])
+
+        # Year
+        if self.year:
+            parts.append(f"({self.year})")
+
+        # Title
+        if self.title:
+            parts.append(f"{self.title}.")
+
+        # Source (journal)
+        if self.source:
+            source_part = f"*{self.source}*"
+            if self.volume:
+                source_part += f", *{self.volume}*"
+                if self.issue:
+                    source_part += f"({self.issue})"
+            if self.pages:
+                source_part += f", {self.pages}"
+            source_part += "."
+            parts.append(source_part)
+
+        # DOI
+        if self.doi:
+            parts.append(f"https://doi.org/{self.doi}")
+
+        return " ".join(parts)
+
+    def _format_author_apa(self, name: str) -> str:
+        """Format author name for APA (Last, F. M.)."""
+        parts = name.split()
+        if len(parts) == 1:
+            return parts[0]
+        last = parts[-1]
+        initials = " ".join(f"{p[0]}." for p in parts[:-1] if p)
+        return f"{last}, {initials}"
+
+    def _citation_bibtex(self) -> str:
+        """Format as BibTeX entry."""
+        # Determine entry type
+        entry_type = "article"
+        if self.type:
+            type_map = {
+                "book": "book",
+                "book-chapter": "incollection",
+                "proceedings": "inproceedings",
+                "proceedings-article": "inproceedings",
+                "dissertation": "phdthesis",
+                "report": "techreport",
+            }
+            entry_type = type_map.get(self.type, "article")
+
+        # Use OpenAlex ID as citation key
+        key = self.openalex_id or "unknown"
+
+        lines = [f"@{entry_type}{{{key},"]
+
+        if self.title:
+            lines.append(f"  title = {{{self.title}}},")
+
+        if self.authors:
+            author_str = " and ".join(self.authors)
+            lines.append(f"  author = {{{author_str}}},")
+
+        if self.year:
+            lines.append(f"  year = {{{self.year}}},")
+
+        if self.source:
+            if entry_type == "article":
+                lines.append(f"  journal = {{{self.source}}},")
+            elif entry_type in ("incollection", "inproceedings"):
+                lines.append(f"  booktitle = {{{self.source}}},")
+
+        if self.volume:
+            lines.append(f"  volume = {{{self.volume}}},")
+
+        if self.issue:
+            lines.append(f"  number = {{{self.issue}}},")
+
+        if self.pages:
+            lines.append(f"  pages = {{{self.pages}}},")
+
+        if self.publisher:
+            lines.append(f"  publisher = {{{self.publisher}}},")
+
+        if self.doi:
+            lines.append(f"  doi = {{{self.doi}}},")
+
+        if self.oa_url:
+            lines.append(f"  url = {{{self.oa_url}}},")
+
+        lines.append("}")
+
+        return "\n".join(lines)
+
+    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 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("W2741809807")
+            >>> work.save("paper.json")
+            >>> work.save("paper.bib", format="bibtex")
+        """
+        from .export import save
+
+        return save(self, path, format=format)
+
 
 @dataclass
 class SearchResult:
@@ -229,3 +407,26 @@ 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)

openalex_local/_remote/__init__.py

@@ -0,0 +1,34 @@
+"""Remote API client for openalex_local.
+
+Connects to an OpenAlex Local API server instead of direct database access.
+Use this when the database is on a remote server accessible via HTTP.
+"""
+
+from typing import Optional
+
+from .base import RemoteClient, DEFAULT_API_URL
+
+# Module-level client singleton
+_client: Optional[RemoteClient] = None
+
+
+def get_client(base_url: str = DEFAULT_API_URL) -> RemoteClient:
+    """Get or create singleton remote client."""
+    global _client
+    if _client is None or _client.base_url != base_url:
+        _client = RemoteClient(base_url)
+    return _client
+
+
+def reset_client() -> None:
+    """Reset singleton client."""
+    global _client
+    _client = None
+
+
+__all__ = [
+    "RemoteClient",
+    "DEFAULT_API_URL",
+    "get_client",
+    "reset_client",
+]