oalex 0.2.0__tar.gz

oalex-0.2.0/.gitignore

@@ -0,0 +1,36 @@
+# Python bytecode
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+build/
+dist/
+*.egg-info/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Test / coverage artifacts
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+.tox/
+
+# Editor / OS
+.vscode/
+.idea/
+*.swp
+.DS_Store
+
+# Secrets — never commit these
+.env
+.env.*
+*.pem
+*.key
+credentials.json

oalex-0.2.0/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+## 0.2.0 (2026-09-22)
+
+OpenAlex retired the mailto polite pool in February 2026 and now meters a daily credit budget. This release catches the client up.
+
+### Breaking
+
+- A 4xx other than 404 and 429 now raises `OalexRequestError`, which is not a subclass of `OalexUnavailable`. Code that retried on `OalexUnavailable` was retrying bad filters and bad keys forever.
+- `email` is optional. A blank one no longer raises `ValueError`; OpenAlex ignores `mailto` now anyway.
+
+### Added
+
+- `api_key` argument, falling back to `OPENALEX_API_KEY`. Sent as a Bearer header.
+- `OalexRateLimited` for 429s, with the server's `retry_after`. Subclasses `OalexUnavailable`.
+- `iter_search` for cursor paging past the first page.
+- `fetch_work` accepts `https://openalex.org/W...` URLs; `fetch_doi` accepts a `doi:` prefix.
+
+### Fixed
+
+- A 429 with no credits left (or a `Retry-After` over 30s) is no longer retried.
+- Merged-away ids follow OpenAlex's 301 instead of raising.
+- DOIs containing `#`, `?` or `;` are percent-encoded instead of being truncated.
+- A 200 response that isn't a JSON object is no longer cached for the whole TTL.
+- Retries go through the rate limiter.
+- Concurrent cache writers no longer share a temp file, and a failed cache write logs instead of failing the request.
+
+### Build
+
+- hatchling instead of setuptools. CI now actually runs Python 3.10 through 3.14 (0.1.0 only ran 3.12).
+
+## 0.1.0 (2026-09-22)
+
+First release, extracted from research-mcp's OpenAlex adapter.

oalex-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 David Burton
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

oalex-0.2.0/PKG-INFO

@@ -0,0 +1,209 @@
+Metadata-Version: 2.5
+Name: oalex
+Version: 0.2.0
+Summary: Async Python client for the OpenAlex scholarly works API.
+Project-URL: Homepage, https://github.com/Burton-David/oalex
+Project-URL: Bug Tracker, https://github.com/Burton-David/oalex/issues
+Project-URL: OpenAlex API, https://help.openalex.org/api/
+Author-email: David Burton <david@databurton.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: async,citations,openalex,research,scholarly
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=7.4; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# oalex
+
+[![CI](https://github.com/Burton-David/oalex/actions/workflows/ci.yml/badge.svg)](https://github.com/Burton-David/oalex/actions/workflows/ci.yml)
+[![Python 3.10–3.14](https://img.shields.io/badge/python-3.10%20to%203.14-blue)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+Async Python client for the [OpenAlex](https://openalex.org/) scholarly works API. Typed, rate-limited, disk-cached, and careful with your daily credit budget.
+
+```python
+import asyncio
+from oalex import Client
+
+async def main() -> None:
+    async with Client(api_key="your-openalex-key") as oa:
+        works = await oa.search("attention is all you need", per_page=5)
+        for w in works:
+            print(w.id, w.title, w.citation_count)
+
+        vaswani = await oa.fetch_work("W2626778328")
+        if vaswani is not None:
+            print(vaswani.title, "cites", len(vaswani.referenced_works), "works")
+
+asyncio.run(main())
+```
+
+## Why this exists
+
+The OpenAlex HTTP API is clean, but every new client ends up re-solving the same things: rebuilding abstracts from the inverted index, retrying 429s and 5xx without burning the daily budget, following redirects for merged records, and caching so repeat lookups cost nothing. `oalex` does those once.
+
+## Features
+
+- **Typed.** `Work` and `Author` are frozen dataclasses. `Work.raw` exposes the full payload for fields the typed surface doesn't cover.
+- **Async.** `httpx` under the hood; `async with Client(...)` for clean teardown.
+- **API-key aware.** Pass `api_key=` or set `OPENALEX_API_KEY`. The key travels as a Bearer header, so it never shows up in URLs, cache files, or exception messages.
+- **Rate-limited.** One request per 0.1s by default, well under OpenAlex's 100 requests/second ceiling. Retries wait their turn too.
+- **Disk-cached.** `~/.cache/oalex/` with a 24-hour TTL. Only valid JSON is cached.
+- **Retried.** 1s/2s/4s backoff on 429 and 5xx, honoring `Retry-After` up to 30s. When a 429 says the daily budget is spent (`X-RateLimit-Remaining: 0`, or a `Retry-After` longer than 30s), the client raises `OalexRateLimited` at once instead of sleeping.
+- **Cursor paging.** `iter_search` walks past the first page (and past the 10,000-result offset limit).
+- **Citation graph.** `fetch_referenced` and `fetch_related` resolve OpenAlex's `referenced_works` / `related_works` arrays into full `Work` records.
+
+## Install
+
+Not on PyPI yet. Install from GitHub:
+
+```bash
+pip install git+https://github.com/Burton-David/oalex
+```
+
+Python 3.10+. The only runtime dependency is [httpx](https://www.python-httpx.org/).
+
+## OpenAlex credits
+
+Since February 2026 OpenAlex meters usage against a daily budget that resets at midnight UTC. These are the numbers the live API reported in September 2026:
+
+| Call | oalex method | Credits |
+|------|--------------|---------|
+| Single work by id or DOI | `fetch_work`, `fetch_doi`, each neighbor in `fetch_referenced` / `fetch_related` | 0 |
+| Search page | `search`, each page of `iter_search` | 10 |
+
+A keyless client gets 1,000 credits per day, which is about 100 searches. A [free API key](https://openalex.org/settings/api) raises the budget tenfold. OpenAlex has changed these numbers before; its [pricing page](https://help.openalex.org/access/pricing/) is the source of truth. Cache hits cost nothing.
+
+## Usage
+
+### Search
+
+```python
+works = await client.search(
+    "graph neural networks",
+    per_page=25,
+    year_min=2020,
+    year_max=2024,
+)
+```
+
+`search` returns one page. `per_page` is clamped to 1..200. Either year bound can be left off for an open-ended range.
+
+For more than one page, iterate:
+
+```python
+async for work in client.iter_search("graph neural networks", max_results=1000):
+    print(work.id, work.title)
+```
+
+Each page is a metered call, so set `max_results` on broad queries.
+
+### Fetch a single work
+
+```python
+# By OpenAlex ID: three equivalent forms
+work = await client.fetch_work("W2626778328")
+work = await client.fetch_work("openalex:W2626778328")
+work = await client.fetch_work("https://openalex.org/W2626778328")
+
+# By DOI
+work = await client.fetch_doi("10.1038/nature12373")
+work = await client.fetch_doi("https://doi.org/10.1038/nature12373")
+work = await client.fetch_work("doi:10.1038/nature12373")
+```
+
+`fetch_work` returns `None` for a 404 and for an id prefix it doesn't recognize (`arxiv:`, `pmid:`). A merged-away id follows OpenAlex's redirect and returns the surviving record.
+
+### Citation graph
+
+```python
+# Papers this paper cites
+refs = await client.fetch_referenced("W2626778328", limit=10)
+
+# Papers OpenAlex considers similar (topic overlap, not citations)
+related = await client.fetch_related("W2626778328", limit=10)
+```
+
+Neighbors are fetched concurrently, in array order. A neighbor that 404s or keeps failing is skipped, and the next id in the array takes its place. Errors fetching the parent propagate.
+
+### Raw payload access
+
+`Work.raw` is a read-only mapping of the full OpenAlex response. Reach into it for fields the typed surface doesn't expose:
+
+```python
+topics = [t["display_name"] for t in work.raw.get("topics", [])]
+source = (work.raw.get("primary_location") or {}).get("source") or {}
+source_id = source.get("id")
+```
+
+## Configuration
+
+```python
+Client(
+    api_key="...",                    # default: $OPENALEX_API_KEY, else keyless
+    cache_dir="/var/cache/oalex",     # default: ~/.cache/oalex
+    ttl_seconds=24 * 60 * 60,         # default: 24h
+    min_interval_seconds=0.1,         # default: 0.1s between requests
+    timeout=30.0,                     # default: 30s per request
+    client=my_httpx_client,           # optional: bring your own AsyncClient
+)
+```
+
+When you pass your own `httpx.AsyncClient`, `oalex` won't close it on exit, and `timeout` is ignored in favor of that client's settings.
+
+`email=` is still accepted and sent as `mailto=`. OpenAlex has ignored it since retiring the polite pool, so new code can leave it off.
+
+## Errors
+
+- `OalexError` is the base class for everything below.
+- `OalexUnavailable` covers transient failures: network errors, 5xx after retries, and a body that isn't a JSON object. Retrying later is reasonable.
+- `OalexRateLimited` is a subclass of `OalexUnavailable` for 429s. `retry_after` holds the server's `Retry-After` hint in seconds when it sent one. A spent daily budget refills at midnight UTC.
+- `OalexRequestError` covers any other 4xx except 404: a bad filter or an invalid API key, for example. `status_code` holds the HTTP status. Retrying the same request won't help.
+
+A 404 is not an error: `fetch_work` and `fetch_doi` return `None`, so "OpenAlex doesn't know this id" stays distinct from "OpenAlex is having a bad day."
+
+## Limits
+
+- Only the `/works` endpoint is wrapped. Authors, sources, and institutions are reachable only through `Work.raw`.
+- The rate limiter is per process. Several processes sharing one API key also share one daily budget, and nothing here coordinates them.
+- The cache stores responses as individual files and never prunes them. Clear `~/.cache/oalex/` yourself if it grows.
+
+## Development
+
+```bash
+git clone https://github.com/Burton-David/oalex
+cd oalex
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+ruff check oalex tests
+mypy oalex
+pytest
+```
+
+Tests use `httpx.MockTransport` and never touch the live API.
+
+## Credits
+
+Extracted from [research-mcp](https://github.com/Burton-David/ResearchAssistantMCP)'s OpenAlex source adapter, where the retry policy and disk-cache design were settled first.
+
+## License
+
+MIT. See `LICENSE`.

oalex-0.2.0/README.md

@@ -0,0 +1,176 @@
+# oalex
+
+[![CI](https://github.com/Burton-David/oalex/actions/workflows/ci.yml/badge.svg)](https://github.com/Burton-David/oalex/actions/workflows/ci.yml)
+[![Python 3.10–3.14](https://img.shields.io/badge/python-3.10%20to%203.14-blue)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+Async Python client for the [OpenAlex](https://openalex.org/) scholarly works API. Typed, rate-limited, disk-cached, and careful with your daily credit budget.
+
+```python
+import asyncio
+from oalex import Client
+
+async def main() -> None:
+    async with Client(api_key="your-openalex-key") as oa:
+        works = await oa.search("attention is all you need", per_page=5)
+        for w in works:
+            print(w.id, w.title, w.citation_count)
+
+        vaswani = await oa.fetch_work("W2626778328")
+        if vaswani is not None:
+            print(vaswani.title, "cites", len(vaswani.referenced_works), "works")
+
+asyncio.run(main())
+```
+
+## Why this exists
+
+The OpenAlex HTTP API is clean, but every new client ends up re-solving the same things: rebuilding abstracts from the inverted index, retrying 429s and 5xx without burning the daily budget, following redirects for merged records, and caching so repeat lookups cost nothing. `oalex` does those once.
+
+## Features
+
+- **Typed.** `Work` and `Author` are frozen dataclasses. `Work.raw` exposes the full payload for fields the typed surface doesn't cover.
+- **Async.** `httpx` under the hood; `async with Client(...)` for clean teardown.
+- **API-key aware.** Pass `api_key=` or set `OPENALEX_API_KEY`. The key travels as a Bearer header, so it never shows up in URLs, cache files, or exception messages.
+- **Rate-limited.** One request per 0.1s by default, well under OpenAlex's 100 requests/second ceiling. Retries wait their turn too.
+- **Disk-cached.** `~/.cache/oalex/` with a 24-hour TTL. Only valid JSON is cached.
+- **Retried.** 1s/2s/4s backoff on 429 and 5xx, honoring `Retry-After` up to 30s. When a 429 says the daily budget is spent (`X-RateLimit-Remaining: 0`, or a `Retry-After` longer than 30s), the client raises `OalexRateLimited` at once instead of sleeping.
+- **Cursor paging.** `iter_search` walks past the first page (and past the 10,000-result offset limit).
+- **Citation graph.** `fetch_referenced` and `fetch_related` resolve OpenAlex's `referenced_works` / `related_works` arrays into full `Work` records.
+
+## Install
+
+Not on PyPI yet. Install from GitHub:
+
+```bash
+pip install git+https://github.com/Burton-David/oalex
+```
+
+Python 3.10+. The only runtime dependency is [httpx](https://www.python-httpx.org/).
+
+## OpenAlex credits
+
+Since February 2026 OpenAlex meters usage against a daily budget that resets at midnight UTC. These are the numbers the live API reported in September 2026:
+
+| Call | oalex method | Credits |
+|------|--------------|---------|
+| Single work by id or DOI | `fetch_work`, `fetch_doi`, each neighbor in `fetch_referenced` / `fetch_related` | 0 |
+| Search page | `search`, each page of `iter_search` | 10 |
+
+A keyless client gets 1,000 credits per day, which is about 100 searches. A [free API key](https://openalex.org/settings/api) raises the budget tenfold. OpenAlex has changed these numbers before; its [pricing page](https://help.openalex.org/access/pricing/) is the source of truth. Cache hits cost nothing.
+
+## Usage
+
+### Search
+
+```python
+works = await client.search(
+    "graph neural networks",
+    per_page=25,
+    year_min=2020,
+    year_max=2024,
+)
+```
+
+`search` returns one page. `per_page` is clamped to 1..200. Either year bound can be left off for an open-ended range.
+
+For more than one page, iterate:
+
+```python
+async for work in client.iter_search("graph neural networks", max_results=1000):
+    print(work.id, work.title)
+```
+
+Each page is a metered call, so set `max_results` on broad queries.
+
+### Fetch a single work
+
+```python
+# By OpenAlex ID: three equivalent forms
+work = await client.fetch_work("W2626778328")
+work = await client.fetch_work("openalex:W2626778328")
+work = await client.fetch_work("https://openalex.org/W2626778328")
+
+# By DOI
+work = await client.fetch_doi("10.1038/nature12373")
+work = await client.fetch_doi("https://doi.org/10.1038/nature12373")
+work = await client.fetch_work("doi:10.1038/nature12373")
+```
+
+`fetch_work` returns `None` for a 404 and for an id prefix it doesn't recognize (`arxiv:`, `pmid:`). A merged-away id follows OpenAlex's redirect and returns the surviving record.
+
+### Citation graph
+
+```python
+# Papers this paper cites
+refs = await client.fetch_referenced("W2626778328", limit=10)
+
+# Papers OpenAlex considers similar (topic overlap, not citations)
+related = await client.fetch_related("W2626778328", limit=10)
+```
+
+Neighbors are fetched concurrently, in array order. A neighbor that 404s or keeps failing is skipped, and the next id in the array takes its place. Errors fetching the parent propagate.
+
+### Raw payload access
+
+`Work.raw` is a read-only mapping of the full OpenAlex response. Reach into it for fields the typed surface doesn't expose:
+
+```python
+topics = [t["display_name"] for t in work.raw.get("topics", [])]
+source = (work.raw.get("primary_location") or {}).get("source") or {}
+source_id = source.get("id")
+```
+
+## Configuration
+
+```python
+Client(
+    api_key="...",                    # default: $OPENALEX_API_KEY, else keyless
+    cache_dir="/var/cache/oalex",     # default: ~/.cache/oalex
+    ttl_seconds=24 * 60 * 60,         # default: 24h
+    min_interval_seconds=0.1,         # default: 0.1s between requests
+    timeout=30.0,                     # default: 30s per request
+    client=my_httpx_client,           # optional: bring your own AsyncClient
+)
+```
+
+When you pass your own `httpx.AsyncClient`, `oalex` won't close it on exit, and `timeout` is ignored in favor of that client's settings.
+
+`email=` is still accepted and sent as `mailto=`. OpenAlex has ignored it since retiring the polite pool, so new code can leave it off.
+
+## Errors
+
+- `OalexError` is the base class for everything below.
+- `OalexUnavailable` covers transient failures: network errors, 5xx after retries, and a body that isn't a JSON object. Retrying later is reasonable.
+- `OalexRateLimited` is a subclass of `OalexUnavailable` for 429s. `retry_after` holds the server's `Retry-After` hint in seconds when it sent one. A spent daily budget refills at midnight UTC.
+- `OalexRequestError` covers any other 4xx except 404: a bad filter or an invalid API key, for example. `status_code` holds the HTTP status. Retrying the same request won't help.
+
+A 404 is not an error: `fetch_work` and `fetch_doi` return `None`, so "OpenAlex doesn't know this id" stays distinct from "OpenAlex is having a bad day."
+
+## Limits
+
+- Only the `/works` endpoint is wrapped. Authors, sources, and institutions are reachable only through `Work.raw`.
+- The rate limiter is per process. Several processes sharing one API key also share one daily budget, and nothing here coordinates them.
+- The cache stores responses as individual files and never prunes them. Clear `~/.cache/oalex/` yourself if it grows.
+
+## Development
+
+```bash
+git clone https://github.com/Burton-David/oalex
+cd oalex
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+ruff check oalex tests
+mypy oalex
+pytest
+```
+
+Tests use `httpx.MockTransport` and never touch the live API.
+
+## Credits
+
+Extracted from [research-mcp](https://github.com/Burton-David/ResearchAssistantMCP)'s OpenAlex source adapter, where the retry policy and disk-cache design were settled first.
+
+## License
+
+MIT. See `LICENSE`.

oalex-0.2.0/oalex/__init__.py

@@ -0,0 +1,34 @@
+"""oalex: async Python client for the OpenAlex scholarly works API.
+
+Quick start::
+
+    import asyncio
+    from oalex import Client
+
+    async def main() -> None:
+        async with Client(api_key="...") as oa:
+            works = await oa.search("attention is all you need", per_page=5)
+            for w in works:
+                print(w.id, w.title)
+
+    asyncio.run(main())
+
+See https://help.openalex.org/api/ for the underlying API reference.
+"""
+
+from oalex.client import Client
+from oalex.errors import OalexError, OalexRateLimited, OalexRequestError, OalexUnavailable
+from oalex.types import Author, Work, parse_work
+
+__all__ = [
+    "Author",
+    "Client",
+    "OalexError",
+    "OalexRateLimited",
+    "OalexRequestError",
+    "OalexUnavailable",
+    "Work",
+    "parse_work",
+]
+
+__version__ = "0.2.0"

oalex-0.2.0/oalex/_backoff.py

@@ -0,0 +1,103 @@
+"""HTTP retry with exponential backoff.
+
+OpenAlex returns 429 (rate-limited) and 5xx (server busy) under load.
+Most of these failures are transient; the upstream's Retry-After header
+tells us when the burst has cleared. ``with_backoff`` runs the request,
+retries on retryable statuses (429 + 5xx) and transport errors with a
+1s/2s/4s schedule (three retries, ~7s of waiting in the worst case), and
+honors Retry-After when the server suggests a longer wait.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from collections.abc import Awaitable, Callable
+
+import httpx
+
+_log = logging.getLogger(__name__)
+
+_RETRYABLE_STATUS: frozenset[int] = frozenset({429, 500, 502, 503, 504})
+
+# 1s, 2s, 4s: three retries plus the initial attempt gives four tries
+# and a worst-case ~7s wait. Higher caps don't help in practice: when an
+# upstream's 429 cooldown is on the order of minutes, retrying longer
+# just delays the user without succeeding.
+_DEFAULT_DELAYS: tuple[float, ...] = (1.0, 2.0, 4.0)
+
+# Retry-After above this means the wait isn't a burst cooldown. On a 429
+# it's almost always the daily credit budget, which resets at midnight UTC,
+# so we hand the response back instead of sleeping on it.
+_MAX_RETRY_AFTER_SECONDS = 30.0
+
+
+async def with_backoff(
+    do_request: Callable[[], Awaitable[httpx.Response]],
+    *,
+    delays: tuple[float, ...] = _DEFAULT_DELAYS,
+) -> httpx.Response:
+    """Run ``do_request()`` with exponential backoff on retryable failures.
+
+    Returns the final :class:`httpx.Response`, which may still be a 429 or
+    5xx once retries run out; the caller decides how to surface it. A
+    transport error (connection refused, timeout) is retried the same way
+    and re-raised after the last attempt.
+
+    ``delays`` is the sequence of inter-attempt sleeps; total attempts =
+    ``len(delays) + 1``.
+    """
+    last_attempt = len(delays)
+    for attempt in range(last_attempt + 1):
+        try:
+            response = await do_request()
+        except httpx.TransportError as exc:
+            if attempt == last_attempt:
+                raise
+            _log.warning(
+                "oalex: network error on attempt %d/%d (%s); retrying",
+                attempt + 1, last_attempt + 1, exc,
+            )
+            sleep_for = delays[attempt]
+        else:
+            if response.status_code not in _RETRYABLE_STATUS or attempt == last_attempt:
+                return response
+            if _budget_exhausted(response):
+                return response
+            sleep_for = delays[attempt]
+            hint = _parse_retry_after(response.headers.get("retry-after"))
+            if hint is not None:
+                if hint > _MAX_RETRY_AFTER_SECONDS:
+                    return response
+                sleep_for = max(sleep_for, hint)
+            _log.warning(
+                "oalex: HTTP %d on attempt %d/%d; retrying",
+                response.status_code, attempt + 1, last_attempt + 1,
+            )
+        _log.info("oalex: backing off %.1fs", sleep_for)
+        await asyncio.sleep(sleep_for)
+    raise AssertionError("unreachable: the final attempt returns or raises")
+
+
+def _budget_exhausted(response: httpx.Response) -> bool:
+    # A 429 also fires for bursts over 100 req/s while credits remain; only
+    # a zero balance means waiting seconds is pointless.
+    return (
+        response.status_code == 429
+        and response.headers.get("x-ratelimit-remaining", "").strip() == "0"
+    )
+
+
+def _parse_retry_after(value: str | None) -> float | None:
+    """Parse a Retry-After header. Spec allows seconds-as-int OR HTTP-date.
+
+    We honor seconds. HTTP-date is rare and computing the delta is
+    error-prone (timezone, clock skew); falling back to the scheduled
+    delay is preferable to parsing it wrong.
+    """
+    if value is None:
+        return None
+    try:
+        return float(value.strip())
+    except ValueError:
+        return None

oalex-0.2.0/oalex/_cache.py

@@ -0,0 +1,60 @@
+"""Filesystem-backed key/value cache for HTTP responses.
+
+Repeated CLI / REPL invocations on the same record waste network time
+and, since OpenAlex started metering list and search calls, daily
+credits too. A small disk cache keyed by the request URL sidesteps
+that. Entries older than ``ttl_seconds`` are treated as misses.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import logging
+import os
+import tempfile
+import time
+from pathlib import Path
+
+_log = logging.getLogger(__name__)
+
+
+class DiskCache:
+    """Filesystem-backed key/value cache. Values are bytes; keys are arbitrary strings."""
+
+    def __init__(self, directory: str | os.PathLike[str], ttl_seconds: int) -> None:
+        self._dir = Path(directory)
+        self._dir.mkdir(parents=True, exist_ok=True)
+        self._ttl = ttl_seconds
+
+    def get(self, key: str) -> bytes | None:
+        path = self._path_for(key)
+        # Another process can prune the directory between stat and read;
+        # either way that's a miss, not an error.
+        try:
+            if (time.time() - path.stat().st_mtime) > self._ttl:
+                return None
+            return path.read_bytes()
+        except FileNotFoundError:
+            return None
+
+    def set(self, key: str, value: bytes) -> None:
+        path = self._path_for(key)
+        # A per-writer temp file: two processes caching the same key must not
+        # interleave writes into one shared .tmp before the rename.
+        try:
+            fd, tmp = tempfile.mkstemp(dir=self._dir, suffix=".tmp")
+            try:
+                with os.fdopen(fd, "wb") as fh:
+                    fh.write(value)
+                os.replace(tmp, path)
+            except BaseException:
+                os.unlink(tmp)
+                raise
+        except OSError as exc:
+            # The response is already in hand; a full disk or read-only cache
+            # dir shouldn't turn a successful fetch into a failure.
+            _log.warning("oalex: could not write cache entry %s: %s", path.name, exc)
+
+    def _path_for(self, key: str) -> Path:
+        digest = hashlib.sha256(key.encode("utf-8")).hexdigest()
+        return self._dir / f"{digest}.bin"