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

crossref_local/{citations.py → _core/citations.py}

@@ -16,13 +16,22 @@ Usage:
     network.save_html("citation_network.html")
 """
 
-from dataclasses import dataclass, field
-from typing import List, Dict, Optional, Set, Tuple
-from pathlib import Path
+from dataclasses import dataclass as _dataclass
+from dataclasses import field as _field
+from typing import Dict, List, Optional, Set, Tuple
 
-from .db import get_db, Database
+from .db import Database, get_db
 from .models import Work
 
+__all__ = [
+    "get_citing",
+    "get_cited",
+    "get_citation_count",
+    "CitationNode",
+    "CitationEdge",
+    "CitationNetwork",
+]
+
 
 def get_citing(doi: str, limit: int = 100, db: Optional[Database] = None) -> List[str]:
     """
@@ -46,7 +55,7 @@ def get_citing(doi: str, limit: int = 100, db: Optional[Database] = None) -> Lis
         WHERE cited_doi = ?
         LIMIT ?
         """,
-        (doi, limit)
+        (doi, limit),
     )
     return [row["citing_doi"] for row in rows]
 
@@ -73,7 +82,7 @@ def get_cited(doi: str, limit: int = 100, db: Optional[Database] = None) -> List
         WHERE citing_doi = ?
         LIMIT ?
         """,
-        (doi, limit)
+        (doi, limit),
     )
     return [row["cited_doi"] for row in rows]
 
@@ -93,18 +102,18 @@ def get_citation_count(doi: str, db: Optional[Database] = None) -> int:
         db = get_db()
 
     row = db.fetchone(
-        "SELECT COUNT(*) as count FROM citations WHERE cited_doi = ?",
-        (doi,)
+        "SELECT COUNT(*) as count FROM citations WHERE cited_doi = ?", (doi,)
     )
     return row["count"] if row else 0
 
 
-@dataclass
+@_dataclass
 class CitationNode:
     """A node in the citation network."""
+
     doi: str
     title: str = ""
-    authors: List[str] = field(default_factory=list)
+    authors: List[str] = _field(default_factory=list)
     year: Optional[int] = None
     journal: str = ""
     citation_count: int = 0
@@ -122,9 +131,10 @@ class CitationNode:
         }
 
 
-@dataclass
+@_dataclass
 class CitationEdge:
     """An edge in the citation network (citing -> cited)."""
+
     citing_doi: str
     cited_doi: str
     year: Optional[int] = None
@@ -272,6 +282,8 @@ class CitationNetwork:
         Raises:
             ImportError: If pyvis is not installed
         """
+        import math as _math
+
         try:
             from pyvis.network import Network
         except ImportError:
@@ -284,7 +296,7 @@ class CitationNetwork:
             directed=True,
             bgcolor="#ffffff",
             font_color="#333333",
-            **kwargs
+            **kwargs,
         )
 
         # Configure physics
@@ -298,15 +310,16 @@ class CitationNetwork:
         # Add nodes with styling based on depth and citation count
         for doi, node in self.nodes.items():
             # Size based on citation count (log scale)
-            import math
-            size = 10 + min(30, math.log1p(node.citation_count) * 5)
+            size = 10 + min(30, _math.log1p(node.citation_count) * 5)
 
             # Color based on depth
             colors = ["#e74c3c", "#3498db", "#2ecc71", "#9b59b6", "#f39c12"]
             color = colors[min(node.depth, len(colors) - 1)]
 
             # Label
-            title_short = (node.title[:50] + "...") if len(node.title) > 50 else node.title
+            title_short = (
+                (node.title[:50] + "...") if len(node.title) > 50 else node.title
+            )
             label = f"{title_short}\n({node.year or 'N/A'})"
 
             # Tooltip
@@ -316,7 +329,7 @@ class CitationNetwork:
             tooltip = f"""
             <b>{node.title}</b><br>
             {authors_str}<br>
-            {node.journal} ({node.year or 'N/A'})<br>
+            {node.journal} ({node.year or "N/A"})<br>
             Citations: {node.citation_count}<br>
             DOI: {doi}
             """
@@ -340,7 +353,9 @@ class CitationNetwork:
         net.save_graph(path)
         return path
 
-    def save_png(self, path: str = "citation_network.png", figsize: Tuple[int, int] = (12, 10)):
+    def save_png(
+        self, path: str = "citation_network.png", figsize: Tuple[int, int] = (12, 10)
+    ):
         """
         Save static PNG visualization using matplotlib.
 
@@ -351,6 +366,8 @@ class CitationNetwork:
         Raises:
             ImportError: If matplotlib is not installed
         """
+        import math as _math
+
         try:
             import matplotlib.pyplot as plt
             import networkx as nx
@@ -365,24 +382,34 @@ class CitationNetwork:
         pos = nx.spring_layout(G, k=2, iterations=50)
 
         # Node sizes based on citation count
-        import math
-        sizes = [100 + min(500, math.log1p(self.nodes[n].citation_count) * 50) for n in G.nodes()]
+        sizes = [
+            100 + min(500, _math.log1p(self.nodes[n].citation_count) * 50)
+            for n in G.nodes()
+        ]
 
         # Node colors based on depth
         colors = [self.nodes[n].depth for n in G.nodes()]
 
         # Draw
-        nx.draw_networkx_nodes(G, pos, node_size=sizes, node_color=colors,
-                               cmap=plt.cm.RdYlBu_r, alpha=0.8, ax=ax)
-        nx.draw_networkx_edges(G, pos, alpha=0.3, arrows=True,
-                               arrowsize=10, ax=ax)
+        nx.draw_networkx_nodes(
+            G,
+            pos,
+            node_size=sizes,
+            node_color=colors,
+            cmap=plt.cm.RdYlBu_r,
+            alpha=0.8,
+            ax=ax,
+        )
+        nx.draw_networkx_edges(G, pos, alpha=0.3, arrows=True, arrowsize=10, ax=ax)
 
         # Labels for important nodes (high citation count)
         labels = {}
         for doi in G.nodes():
             node = self.nodes[doi]
             if node.citation_count > 10 or doi == self.center_doi:
-                short_title = (node.title[:30] + "...") if len(node.title) > 30 else node.title
+                short_title = (
+                    (node.title[:30] + "...") if len(node.title) > 30 else node.title
+                )
                 labels[doi] = f"{short_title}\n({node.year or 'N/A'})"
 
         nx.draw_networkx_labels(G, pos, labels, font_size=8, ax=ax)
@@ -402,11 +429,13 @@ class CitationNetwork:
             "center_doi": self.center_doi,
             "depth": self.depth,
             "nodes": [n.to_dict() for n in self.nodes.values()],
-            "edges": [{"citing": e.citing_doi, "cited": e.cited_doi} for e in self.edges],
+            "edges": [
+                {"citing": e.citing_doi, "cited": e.cited_doi} for e in self.edges
+            ],
             "stats": {
                 "total_nodes": len(self.nodes),
                 "total_edges": len(self.edges),
-            }
+            },
         }
 
     def __repr__(self):

crossref_local/{config.py → _core/config.py}

@@ -1,29 +1,42 @@
 """Configuration for crossref_local."""
 
-import os
-from pathlib import Path
+import os as _os
+from pathlib import Path as _Path
 from typing import Optional
 
+__all__ = [
+    "Config",
+    "get_db_path",
+    "DEFAULT_PORT",
+    "DEFAULT_API_URL",
+]
+
 # Default database locations (checked in order)
 DEFAULT_DB_PATHS = [
-    Path.cwd() / "data" / "crossref.db",
-    Path.home() / ".crossref_local" / "crossref.db",
+    _Path.cwd() / "data" / "crossref.db",
+    _Path.home() / ".crossref_local" / "crossref.db",
 ]
 
-# Default remote API URL (via SSH tunnel)
+# Default port: SCITEX convention (3129X scheme)
+# 31290: scitex-cloud, 31291: crossref-local, 31292: openalex-local, 31293: audio relay
+DEFAULT_PORT = 31291
+
+# Default remote API URLs (checked in order)
 DEFAULT_API_URLS = [
-    "http://localhost:8333",  # SSH tunnel to NAS
+    f"http://localhost:{DEFAULT_PORT}",  # SCITEX default
+    "http://localhost:8333",  # Legacy port (backwards compatibility)
 ]
 DEFAULT_API_URL = DEFAULT_API_URLS[0]
 
 
-def get_db_path() -> Path:
+def get_db_path() -> _Path:
     """
     Get database path from environment or auto-detect.
 
     Priority:
-    1. CROSSREF_LOCAL_DB environment variable
-    2. First existing path from DEFAULT_DB_PATHS
+    1. SCITEX_SCHOLAR_CROSSREF_DB environment variable
+    2. CROSSREF_LOCAL_DB environment variable
+    3. First existing path from DEFAULT_DB_PATHS
 
     Returns:
         Path to the database file
@@ -31,13 +44,15 @@ def get_db_path() -> Path:
     Raises:
         FileNotFoundError: If no database found
     """
-    # Check environment variable first
-    env_path = os.environ.get("CROSSREF_LOCAL_DB")
+    # Check SCITEX environment variable first (takes priority)
+    env_path = _os.environ.get("SCITEX_SCHOLAR_CROSSREF_DB")
+    if not env_path:
+        env_path = _os.environ.get("CROSSREF_LOCAL_DB")
     if env_path:
-        path = Path(env_path)
+        path = _Path(env_path)
         if path.exists():
             return path
-        raise FileNotFoundError(f"CROSSREF_LOCAL_DB path not found: {env_path}")
+        raise FileNotFoundError(f"Database path not found: {env_path}")
 
     # Auto-detect from default locations
     for path in DEFAULT_DB_PATHS:
@@ -53,7 +68,7 @@ def get_db_path() -> Path:
 class Config:
     """Configuration container."""
 
-    _db_path: Optional[Path] = None
+    _db_path: Optional[_Path] = None
     _api_url: Optional[str] = None
     _mode: str = "auto"  # "auto", "db", or "http"
 
@@ -67,15 +82,18 @@ class Config:
             "http" if using HTTP API
         """
         if cls._mode == "auto":
-            # Check environment variable
-            env_mode = os.environ.get("CROSSREF_LOCAL_MODE", "").lower()
+            # Check environment variables (SCITEX takes priority)
+            env_mode = _os.environ.get(
+                "SCITEX_SCHOLAR_CROSSREF_MODE",
+                _os.environ.get("CROSSREF_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
-            if cls._api_url or os.environ.get("CROSSREF_LOCAL_API_URL"):
+            if cls._api_url or _os.environ.get("CROSSREF_LOCAL_API_URL"):
                 return "http"
 
             # Check if local database exists
@@ -96,16 +114,16 @@ class Config:
         cls._mode = mode
 
     @classmethod
-    def get_db_path(cls) -> Path:
+    def get_db_path(cls) -> _Path:
         """Get or auto-detect database 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 | Path) -> None:
+    def set_db_path(cls, path: str | _Path) -> None:
         """Set database path explicitly."""
-        path = Path(path)
+        path = _Path(path)
         if not path.exists():
             raise FileNotFoundError(f"Database not found: {path}")
         cls._db_path = path
@@ -125,7 +143,7 @@ class Config:
         if cls._api_url:
             return cls._api_url
 
-        env_url = os.environ.get("CROSSREF_LOCAL_API_URL")
+        env_url = _os.environ.get("CROSSREF_LOCAL_API_URL")
         if env_url:
             return env_url
 
@@ -140,8 +158,8 @@ class Config:
     @classmethod
     def _find_working_api(cls) -> Optional[str]:
         """Try each default API URL and return first working one."""
-        import urllib.request
         import urllib.error
+        import urllib.request
 
         for url in DEFAULT_API_URLS:
             try:

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

@@ -1,13 +1,20 @@
 """Database connection handling for crossref_local."""
 
-import sqlite3
-import json
-import zlib
-from contextlib import contextmanager
-from pathlib import Path
-from typing import Optional, Generator
+import json as _json
+import sqlite3 as _sqlite3
+import zlib as _zlib
+from contextlib import contextmanager as _contextmanager
+from pathlib import Path as _Path
+from typing import Generator, Optional
 
-from .config import Config
+from .config import Config as _Config
+
+__all__ = [
+    "Database",
+    "get_db",
+    "close_db",
+    "connection",
+]
 
 
 class Database:
@@ -17,7 +24,7 @@ class Database:
     Supports both direct usage and context manager pattern.
     """
 
-    def __init__(self, db_path: Optional[str | Path] = None):
+    def __init__(self, db_path: Optional[str | _Path] = None):
         """
         Initialize database connection.
 
@@ -25,19 +32,19 @@ class Database:
             db_path: Path to database. If None, auto-detects.
         """
         if db_path:
-            self.db_path = Path(db_path)
+            self.db_path = _Path(db_path)
         else:
-            self.db_path = Config.get_db_path()
+            self.db_path = _Config.get_db_path()
 
-        self.conn: Optional[sqlite3.Connection] = None
+        self.conn: Optional[_sqlite3.Connection] = None
         self._connect()
 
     def _connect(self) -> None:
         """Establish database connection."""
         # check_same_thread=False allows connection to be used across threads
         # Safe for read-only operations (which is our use case)
-        self.conn = sqlite3.connect(self.db_path, check_same_thread=False)
-        self.conn.row_factory = sqlite3.Row
+        self.conn = _sqlite3.connect(self.db_path, check_same_thread=False)
+        self.conn.row_factory = _sqlite3.Row
 
     def close(self) -> None:
         """Close database connection."""
@@ -51,11 +58,11 @@ class Database:
     def __exit__(self, exc_type, exc_val, exc_tb) -> None:
         self.close()
 
-    def execute(self, query: str, params: tuple = ()) -> sqlite3.Cursor:
+    def execute(self, query: str, params: tuple = ()) -> _sqlite3.Cursor:
         """Execute SQL query."""
         return self.conn.execute(query, params)
 
-    def fetchone(self, query: str, params: tuple = ()) -> Optional[sqlite3.Row]:
+    def fetchone(self, query: str, params: tuple = ()) -> Optional[_sqlite3.Row]:
         """Execute query and fetch one result."""
         cursor = self.execute(query, params)
         return cursor.fetchone()
@@ -75,10 +82,7 @@ class Database:
         Returns:
             Metadata dictionary or None
         """
-        row = self.fetchone(
-            "SELECT metadata FROM works WHERE doi = ?",
-            (doi,)
-        )
+        row = self.fetchone("SELECT metadata FROM works WHERE doi = ?", (doi,))
         if row and row["metadata"]:
             return self._decompress_metadata(row["metadata"])
         return None
@@ -87,15 +91,15 @@ class Database:
         """Decompress and parse metadata (handles both compressed and plain JSON)."""
         # If it's already a string, parse directly
         if isinstance(data, str):
-            return json.loads(data)
+            return _json.loads(data)
 
         # If bytes, try decompression
         if isinstance(data, bytes):
             try:
-                decompressed = zlib.decompress(data)
-                return json.loads(decompressed)
-            except zlib.error:
-                return json.loads(data.decode("utf-8"))
+                decompressed = _zlib.decompress(data)
+                return _json.loads(decompressed)
+            except _zlib.error:
+                return _json.loads(data.decode("utf-8"))
 
         return data
 
@@ -120,8 +124,10 @@ def close_db() -> None:
         _db = None
 
 
-@contextmanager
-def connection(db_path: Optional[str | Path] = None) -> Generator[Database, None, None]:
+@_contextmanager
+def connection(
+    db_path: Optional[str | _Path] = None,
+) -> Generator[Database, None, None]:
     """
     Context manager for database connection.
 

crossref_local/{fts.py → _core/fts.py}

@@ -1,11 +1,17 @@
 """Full-text search using FTS5."""
 
-import re
-import time
+import re as _re
+import time as _time
 from typing import List, Optional
 
 from .db import Database, get_db
-from .models import Work, SearchResult
+from .models import SearchResult, Work
+
+__all__ = [
+    "search",
+    "count",
+    "search_dois",
+]
 
 
 def _sanitize_query(query: str) -> str:
@@ -24,13 +30,13 @@ def _sanitize_query(query: str) -> str:
 
     # Check for problematic patterns (hyphenated words, special chars)
     # But allow explicit FTS5 operators: AND, OR, NOT, NEAR
-    has_hyphenated_word = re.search(r'\w+-\w+', query)
-    has_special = re.search(r'[/\\@#$%^&]', query)
+    has_hyphenated_word = _re.search(r"\w+-\w+", query)
+    has_special = _re.search(r"[/\\@#$%^&]", query)
 
     if has_hyphenated_word or has_special:
         # Quote each word to treat as literal
         words = query.split()
-        quoted = ' '.join(f'"{w}"' for w in words)
+        quoted = " ".join(f'"{w}"' for w in words)
         return quoted
 
     return query
@@ -65,15 +71,14 @@ def search(
     if db is None:
         db = get_db()
 
-    start = time.perf_counter()
+    start = _time.perf_counter()
 
     # Sanitize query for FTS5
     safe_query = _sanitize_query(query)
 
     # Get total count
     count_row = db.fetchone(
-        "SELECT COUNT(*) as total FROM works_fts WHERE works_fts MATCH ?",
-        (safe_query,)
+        "SELECT COUNT(*) as total FROM works_fts WHERE works_fts MATCH ?", (safe_query,)
     )
     total = count_row["total"] if count_row else 0
 
@@ -86,10 +91,10 @@ def search(
         WHERE works_fts MATCH ?
         LIMIT ? OFFSET ?
         """,
-        (safe_query, limit, offset)
+        (safe_query, limit, offset),
     )
 
-    elapsed_ms = (time.perf_counter() - start) * 1000
+    elapsed_ms = (_time.perf_counter() - start) * 1000
 
     # Convert to Work objects
     works = []
@@ -121,8 +126,7 @@ def count(query: str, db: Optional[Database] = None) -> int:
 
     safe_query = _sanitize_query(query)
     row = db.fetchone(
-        "SELECT COUNT(*) as total FROM works_fts WHERE works_fts MATCH ?",
-        (safe_query,)
+        "SELECT COUNT(*) as total FROM works_fts WHERE works_fts MATCH ?", (safe_query,)
     )
     return row["total"] if row else 0
 
@@ -155,7 +159,7 @@ def search_dois(
         WHERE works_fts MATCH ?
         LIMIT ?
         """,
-        (safe_query, limit)
+        (safe_query, limit),
     )
 
     return [row["doi"] for row in rows]

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

@@ -1,11 +1,16 @@
 """Data models for crossref_local."""
 
-from dataclasses import dataclass, field
+from dataclasses import dataclass as _dataclass
+from dataclasses import field as _field
 from typing import List, Optional
-import json
 
+__all__ = [
+    "Work",
+    "SearchResult",
+]
 
-@dataclass
+
+@_dataclass
 class Work:
     """
     Represents a scholarly work from CrossRef.
@@ -30,7 +35,7 @@ class Work:
 
     doi: str
     title: Optional[str] = None
-    authors: List[str] = field(default_factory=list)
+    authors: List[str] = _field(default_factory=list)
     year: Optional[int] = None
     journal: Optional[str] = None
     issn: Optional[str] = None
@@ -42,7 +47,7 @@ class Work:
     abstract: Optional[str] = None
     url: Optional[str] = None
     citation_count: Optional[int] = None
-    references: List[str] = field(default_factory=list)
+    references: List[str] = _field(default_factory=list)
 
     @classmethod
     def from_metadata(cls, doi: str, metadata: dict) -> "Work":
@@ -159,7 +164,7 @@ class Work:
         return ". ".join(filter(None, parts))
 
 
-@dataclass
+@_dataclass
 class SearchResult:
     """
     Container for search results with metadata.

crossref_local/_remote/__init__.py

@@ -0,0 +1,56 @@
+"""Remote API client package with collection support.
+
+Provides RemoteClient for connecting to CrossRef Local API server.
+"""
+
+from typing import Optional
+
+from .base import (
+    RemoteClient as _BaseClient,
+    DEFAULT_API_URL,
+)
+from .collections import CollectionsMixin
+
+
+class RemoteClient(CollectionsMixin, _BaseClient):
+    """Remote client with collection support.
+
+    Extends base RemoteClient with collection management methods.
+
+    Example:
+        >>> client = RemoteClient("http://localhost:31291")
+        >>> # Create a collection
+        >>> client.create_collection("epilepsy", query="epilepsy seizure")
+        >>> # Query collection
+        >>> papers = client.get_collection("epilepsy", fields=["doi", "title"])
+        >>> # Download as file
+        >>> client.download_collection("epilepsy", "papers.bib", format="bibtex")
+    """
+
+    pass
+
+
+# Module-level client singleton
+_client: Optional[RemoteClient] = None
+
+
+def get_client(base_url: str = DEFAULT_API_URL) -> RemoteClient:
+    """Get or create singleton remote client with collection support."""
+    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",
+]