create new package

Author: jdkent

.env.example

@@ -0,0 +1,3 @@
+ELSEVIER_API_KEY=YOUR_API_KEY
+ELSEVIER_HTTP_PROXY=socks5://127.0.0.1:1080
+ELSEVIER_HTTPS_PROXY=socks5://127.0.0.1:1080

.gitignore

@@ -0,0 +1,70 @@
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Virtual environments
+.venv/
+venv/
+env/
+.env.local
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+.tox/
+.pytest_cache/
+.nox/
+coverage.xml
+.coverage
+.coverage.*
+htmlcov/
+cache/
+
+# Type checker caches
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Ruff / lint caches
+.ruff_cache/
+
+# IDE / editor
+.idea/
+.vscode/
+*.code-workspace
+
+# OS files
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log
+
+# Local notebooks
+.ipynb_checkpoints/
+
+# pyenv
+.python-version
+
+.elsevier_cache

README.md

@@ -0,0 +1,32 @@
+# Elsvier Coordinate Extraction
+
+This package provides tools to search, download, and
+extract coordinates from Elseivier articles.
+
+## Installation
+
+pip install elsvier-coordinate-extraction
+
+or a local install:
+```bash
+git clone https://github.com/yourusername/elsevier-coordinate-extraction.git
+cd elsevier-coordinate-extraction
+pip install -e .
+```
+
+## Usage
+
+```python
+from elsvier_coordinate_extraction import search_articles, download_articles, extract_coordinates
+
+# Search for articles
+articles = search_articles(query="fmri", max_results=5)
+
+# Download full-text XML for the first article using its DOI/PMID
+records = [{"doi": articles[0]["doi"], "pmid": articles[0].get("pmid")}]  # type: ignore[index]
+downloaded = download_articles(records)
+
+# Extract coordinates
+coordinates = extract_coordinates(downloaded)
+print(coordinates)
+```

elsevier_coordinate_extraction/__init__.py

@@ -0,0 +1,12 @@
+"""
+elsevier Coordinate Extraction package.
+
+Module initialization sets up the exported API surface incrementally as
+components are implemented.
+"""
+
+from __future__ import annotations
+
+# Public re-exports will be populated during implementation.
+
+__all__: tuple[str, ...] = ()

elsevier_coordinate_extraction/cache.py

@@ -0,0 +1,40 @@
+"""Disk-backed cache helpers."""
+
+from __future__ import annotations
+
+import asyncio
+import hashlib
+from pathlib import Path
+
+
+class FileCache:
+    """Simple asynchronous cache that stores payloads on disk."""
+
+    def __init__(self, root: Path | str) -> None:
+        self._root = Path(root)
+        self._root.mkdir(parents=True, exist_ok=True)
+
+    async def get(self, namespace: str, key: str) -> bytes | None:
+        """Return cached bytes if present."""
+        path = self._path(namespace, key)
+        if not path.exists():
+            return None
+        return await asyncio.to_thread(path.read_bytes)
+
+    async def set(self, namespace: str, key: str, data: bytes) -> None:
+        """Persist payload bytes for future reuse."""
+        path = self._path(namespace, key)
+        await asyncio.to_thread(self._write_atomic, path, data)
+
+    def _path(self, namespace: str, key: str) -> Path:
+        digest = hashlib.sha256(key.encode("utf-8")).hexdigest()
+        directory = self._root / namespace
+        directory.mkdir(parents=True, exist_ok=True)
+        return directory / f"{digest}.bin"
+
+    @staticmethod
+    def _write_atomic(path: Path, data: bytes) -> None:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        tmp_path = path.with_suffix(".tmp")
+        tmp_path.write_bytes(data)
+        tmp_path.replace(path)

elsevier_coordinate_extraction/client.py

@@ -0,0 +1,138 @@
+"""Async ScienceDirect client built on httpx."""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Mapping
+from typing import Any
+
+import httpx
+
+from . import rate_limits
+from .settings import Settings
+
+__all__ = ["ScienceDirectClient"]
+
+
+class ScienceDirectClient:
+    """Thin wrapper around httpx.AsyncClient with Elsevier defaults."""
+
+    def __init__(
+        self,
+        settings: Settings,
+        *,
+        transport: httpx.AsyncBaseTransport | None = None,
+        max_retries: int = 3,
+    ) -> None:
+        self._settings = settings
+        self._transport = transport
+        self._max_retries = max(0, max_retries)
+        self._client: httpx.AsyncClient | None = None
+        concurrency = settings.concurrency or 1
+        self._semaphore = asyncio.Semaphore(concurrency)
+
+    async def __aenter__(self) -> ScienceDirectClient:
+        await self._ensure_client()
+        return self
+
+    async def __aexit__(self, exc_type, exc, tb) -> None:  # type: ignore[override]
+        if self._client is not None:
+            await self._client.aclose()
+            self._client = None
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Mapping[str, Any] | None = None,
+        accept: str | None = None,
+    ) -> httpx.Response:
+        """Perform an HTTP request and return the response."""
+        return await self._request(method, path, params=params, accept=accept)
+
+    async def get_json(
+        self,
+        path: str,
+        *,
+        params: Mapping[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        """Perform a GET request expecting JSON."""
+        response = await self.request(
+            "GET",
+            path,
+            params=params,
+            accept="application/json",
+        )
+        return response.json()
+
+    async def get_xml(
+        self,
+        path: str,
+        *,
+        params: Mapping[str, Any] | None = None,
+    ) -> str:
+        """Perform a GET request expecting XML."""
+        response = await self.request(
+            "GET",
+            path,
+            params=params,
+            accept="application/xml",
+        )
+        return response.text
+
+    async def _ensure_client(self) -> None:
+        if self._client is not None:
+            return
+        headers: dict[str, str] = {
+            "X-ELS-APIKey": self._settings.api_key,
+            "User-Agent": self._settings.user_agent,
+        }
+        if self._settings.insttoken:
+            headers["X-ELS-Insttoken"] = self._settings.insttoken
+        timeout = httpx.Timeout(self._settings.timeout)
+        proxy_value = self._settings.https_proxy or self._settings.http_proxy
+        self._client = httpx.AsyncClient(
+            base_url=self._settings.base_url,
+            timeout=timeout,
+            headers=headers,
+            transport=self._transport,
+            http2=True,
+            proxy=proxy_value,
+        )
+
+    async def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Mapping[str, Any] | None,
+        accept: str | None,
+    ) -> httpx.Response:
+        await self._ensure_client()
+        assert self._client is not None
+        attempt = 0
+        while True:
+            request_headers = {"Accept": accept} if accept else {}
+            async with self._semaphore:
+                response = await self._client.request(
+                    method,
+                    path,
+                    params=params,
+                    headers=request_headers,
+                )
+            delay = rate_limits.get_retry_delay(response)
+            if (
+                delay is not None
+                and response.status_code in {429, 500, 503}
+                and attempt < self._max_retries
+            ):
+                await asyncio.sleep(delay)
+                attempt += 1
+                continue
+
+            try:
+                response.raise_for_status()
+            except httpx.HTTPStatusError as exc:
+                raise exc
+            return response

elsevier_coordinate_extraction/download/__init__.py

@@ -0,0 +1,5 @@
+"""Download module public API."""
+
+from __future__ import annotations
+
+# Implementation forthcoming.