oalex 0.2.0__py3-none-any.whl

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/_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/_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"

oalex/_rate_limit.py

@@ -0,0 +1,39 @@
+"""Async rate limiter: at most one call per ``min_interval`` seconds, in order.
+
+OpenAlex rejects bursts above 100 requests/second with a 429. The
+client's default of one request per 0.1s stays an order of magnitude
+under that, which leaves room for several processes sharing one IP.
+Process-local; clients in separate processes keep their own limiters
+and can collectively exceed the rate. That's acceptable for a
+single-process client library; distributed deployments should layer
+their own coordination.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import time
+
+
+class RateLimiter:
+    """Fixed-interval async rate limiter.
+
+    ``acquire()`` returns immediately if at least ``min_interval`` seconds
+    have passed since the last release; otherwise sleeps until that's
+    true. Safe to call from many coroutines on one loop via an internal lock.
+    """
+
+    def __init__(self, min_interval_seconds: float) -> None:
+        if min_interval_seconds <= 0:
+            raise ValueError("min_interval_seconds must be positive")
+        self._interval = min_interval_seconds
+        self._lock = asyncio.Lock()
+        self._last_call = 0.0
+
+    async def acquire(self) -> None:
+        async with self._lock:
+            now = time.monotonic()
+            wait = self._interval - (now - self._last_call)
+            if wait > 0:
+                await asyncio.sleep(wait)
+            self._last_call = time.monotonic()

oalex/client.py

@@ -0,0 +1,415 @@
+"""Async client for OpenAlex's ``/works`` endpoint.
+
+The rate limiter uses ``asyncio.Lock``, so one instance belongs to one
+event loop and isn't thread-safe. Both ``async with Client() as client:``
+and manual ``aclose()`` are supported.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import os
+from collections.abc import AsyncIterator, Sequence
+from pathlib import Path
+from typing import Any, Final, Literal, overload
+from urllib.parse import quote, urlencode
+
+import httpx
+
+from oalex._backoff import _parse_retry_after, with_backoff
+from oalex._cache import DiskCache
+from oalex._rate_limit import RateLimiter
+from oalex.errors import OalexRateLimited, OalexRequestError, OalexUnavailable
+from oalex.types import Work, _strip_doi_url, _strip_openalex_id_url, parse_work
+
+_log = logging.getLogger(__name__)
+
+_API_BASE: Final = "https://api.openalex.org"
+_API_KEY_ENV: Final = "OPENALEX_API_KEY"
+_DEFAULT_CACHE_TTL_SECONDS: Final = 24 * 60 * 60
+_DEFAULT_TIMEOUT: Final = 30.0
+_DEFAULT_MIN_INTERVAL: Final = 0.1
+# The API accepted per-page=200 when last checked (Sep 2026) even though the
+# current docs say 100. Clamp here so an oversized value never becomes a 400.
+_MAX_PER_PAGE: Final = 200
+
+
+def _default_cache_dir() -> Path:
+    return Path.home() / ".cache" / "oalex"
+
+
+class Client:
+    """Async client for the OpenAlex Works API.
+
+    OpenAlex meters usage against a daily credit budget (since February
+    2026). Requests without an API key share a small keyless budget,
+    enough for roughly a hundred searches a day. A free key from
+    https://openalex.org/settings/api raises it tenfold. Fetching a single
+    work by id is free either way; searches and filtered lists are not.
+
+    Args:
+        api_key: OpenAlex API key, sent as a Bearer token so it never lands
+            in URLs, cache keys, or error messages. Falls back to the
+            ``OPENALEX_API_KEY`` environment variable.
+        email: Sent as ``mailto=``. OpenAlex has ignored it since the
+            polite pool was retired; it stays accepted so older callers
+            keep working.
+        cache_dir: Disk cache location. Defaults to ``~/.cache/oalex/``.
+        ttl_seconds: Cache TTL in seconds. Defaults to 24 hours.
+        min_interval_seconds: Minimum time between requests. Defaults
+            to 0.1s (10 req/sec; OpenAlex's hard ceiling is 100).
+        timeout: Per-request HTTP timeout in seconds. Defaults to 30s.
+            Ignored when ``client`` is given; configure that client instead.
+        client: Optional pre-built :class:`httpx.AsyncClient` to reuse.
+            When provided, ``aclose()`` does NOT close it; that's the
+            caller's responsibility.
+    """
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        email: str | None = None,
+        cache_dir: str | os.PathLike[str] | None = None,
+        ttl_seconds: int = _DEFAULT_CACHE_TTL_SECONDS,
+        min_interval_seconds: float = _DEFAULT_MIN_INTERVAL,
+        timeout: float = _DEFAULT_TIMEOUT,
+        client: httpx.AsyncClient | None = None,
+    ) -> None:
+        key = api_key if api_key is not None else os.environ.get(_API_KEY_ENV)
+        self._headers = {"Authorization": f"Bearer {key.strip()}"} if key and key.strip() else {}
+        self._email = email.strip() if email and email.strip() else None
+        cache_path = Path(cache_dir) if cache_dir is not None else _default_cache_dir()
+        self._cache = DiskCache(cache_path, ttl_seconds=ttl_seconds)
+        self._rate = RateLimiter(min_interval_seconds)
+        self._owns_client = client is None
+        self._client = client if client is not None else httpx.AsyncClient(timeout=timeout)
+
+    async def __aenter__(self) -> Client:
+        return self
+
+    async def __aexit__(self, *exc_info: object) -> None:
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        """Close the underlying HTTP client if we own it."""
+        if self._owns_client:
+            await self._client.aclose()
+
+    async def search(
+        self,
+        query: str,
+        *,
+        per_page: int = 25,
+        year_min: int | None = None,
+        year_max: int | None = None,
+    ) -> Sequence[Work]:
+        """Search OpenAlex's full-text index and return the first page.
+
+        Args:
+            query: Freeform query string passed to OpenAlex's ``search=``.
+            per_page: Maximum number of results to return, clamped to
+                1..200. Use :meth:`iter_search` for more than one page.
+            year_min: Earliest publication year, inclusive.
+            year_max: Latest publication year, inclusive.
+
+        Returns:
+            Works in OpenAlex's relevance order. Records without a
+            parseable id are skipped.
+
+        Raises:
+            OalexRateLimited: Daily credit budget exhausted, or 429s outlasted retries.
+            OalexRequestError: OpenAlex rejected the query (bad filter, bad key).
+            OalexUnavailable: Transient upstream failure (5xx after
+                retries, network error, malformed JSON).
+        """
+        params = _search_params(query, per_page=per_page, year_min=year_min, year_max=year_max)
+        payload = await self._get_json("/works", params)
+        return _parse_results(payload)
+
+    async def iter_search(
+        self,
+        query: str,
+        *,
+        year_min: int | None = None,
+        year_max: int | None = None,
+        per_page: int = _MAX_PER_PAGE,
+        max_results: int | None = None,
+    ) -> AsyncIterator[Work]:
+        """Yield search results across pages using OpenAlex's cursor paging.
+
+        Each page is one metered list call, so on the keyless budget a
+        broad query can run the day's credits out long before the result
+        set ends. Set ``max_results`` unless you really want everything.
+        Offset paging stops at 10,000 results; cursor paging doesn't.
+        """
+        params = _search_params(query, per_page=per_page, year_min=year_min, year_max=year_max)
+        cursor: str | None = "*"
+        yielded = 0
+        while cursor is not None and (max_results is None or yielded < max_results):
+            payload = await self._get_json("/works", {**params, "cursor": cursor})
+            works = _parse_results(payload)
+            for work in works:
+                yield work
+                yielded += 1
+                # Return mid-page rather than at the top of the loop, which
+                # would first pay for a page we'd throw away.
+                if max_results is not None and yielded >= max_results:
+                    return
+            meta = payload.get("meta")
+            next_cursor = meta.get("next_cursor") if isinstance(meta, dict) else None
+            # Stop on an empty page even if a next_cursor came back; trusting
+            # it would let a misbehaving cursor bill us per empty page forever.
+            cursor = next_cursor if isinstance(next_cursor, str) and works else None
+
+    async def fetch_work(self, work_id: str) -> Work | None:
+        """Fetch a single Work by OpenAlex ID or DOI.
+
+        Args:
+            work_id: A bare OpenAlex ID (``W2626778328``), an OpenAlex URL
+                (``https://openalex.org/W2626778328``, the form ``Work.url``
+                and ``raw["referenced_works"]`` use), an ``openalex:``
+                prefixed ID, or a ``doi:`` prefixed DOI
+                (``doi:10.1038/nature12373``). Bare DOIs are not
+                recognized; use :meth:`fetch_doi` for those.
+
+        Returns:
+            A :class:`Work`, or ``None`` if OpenAlex returns 404 or the id
+            has a prefix this client doesn't know. Merged-away ids follow
+            OpenAlex's redirect to the surviving record.
+
+        Raises:
+            OalexRateLimited: Daily credit budget exhausted.
+            OalexRequestError: OpenAlex rejected the request.
+            OalexUnavailable: Transient upstream failure.
+        """
+        path = _work_path(work_id)
+        if path is None:
+            return None
+        return await self._fetch_work_at(path)
+
+    async def fetch_doi(self, doi: str) -> Work | None:
+        """Fetch a Work by DOI.
+
+        Accepts a bare DOI (``10.1038/nature12373``), a ``doi:`` prefixed
+        one, or a ``doi.org`` URL.
+        """
+        bare = _strip_doi_url(doi.removeprefix("doi:"))
+        if bare is None:
+            return None
+        return await self._fetch_work_at(_doi_path(bare))
+
+    async def fetch_referenced(
+        self,
+        work_id: str,
+        *,
+        limit: int = 10,
+    ) -> Sequence[Work]:
+        """Resolve a Work's ``referenced_works`` array into full :class:`Work` records.
+
+        OpenAlex stores each Work's outgoing citation list as an array of
+        work URLs. This fetches the parent, then fetches neighbors in array
+        order until ``limit`` of them resolve. Neighbor fetches are
+        singleton lookups, which OpenAlex doesn't charge credits for; a
+        batched ``ids.openalex`` filter would be one request but is billed
+        as a list call.
+
+        Args:
+            work_id: Parent paper ID (accepts the same forms as
+                :meth:`fetch_work`).
+            limit: Maximum number of referenced Works to return.
+
+        Returns:
+            Referenced Works in array order. A neighbor that 404s or keeps
+            failing after retries is skipped and the next one takes its
+            place. Returns ``()`` when the parent doesn't exist or has no
+            ``referenced_works``.
+
+        Raises:
+            OalexUnavailable: Persistent failure fetching the parent.
+                Neighbor failures never escalate.
+        """
+        return await self._fetch_graph_neighbors(work_id, field="referenced_works", limit=limit)
+
+    async def fetch_related(
+        self,
+        work_id: str,
+        *,
+        limit: int = 10,
+    ) -> Sequence[Work]:
+        """Resolve a Work's ``related_works`` array into full :class:`Work` records.
+
+        Same fan-out shape as :meth:`fetch_referenced`, but reads
+        ``related_works``, OpenAlex's similarity neighborhood computed from
+        topic overlap. It isn't a citation relationship: a "related" Work
+        need not cite the source Work or be cited by it.
+        """
+        return await self._fetch_graph_neighbors(work_id, field="related_works", limit=limit)
+
+    async def _fetch_work_at(self, path: str) -> Work | None:
+        payload = await self._get_json(path, allow_404=True)
+        return parse_work(payload) if payload is not None else None
+
+    async def _fetch_graph_neighbors(
+        self,
+        work_id: str,
+        *,
+        field: str,
+        limit: int,
+    ) -> Sequence[Work]:
+        path = _work_path(work_id)
+        if path is None:
+            return ()
+        parent = await self._get_json(path, allow_404=True)
+        if parent is None:
+            return ()
+        neighbor_urls = parent.get(field)
+        if not isinstance(neighbor_urls, list):
+            return ()
+        ids = [oa_id for url in neighbor_urls if (oa_id := _strip_openalex_id_url(url))]
+        return await self._resolve_works(ids, limit=limit)
+
+    async def _resolve_works(self, ids: Sequence[str], *, limit: int) -> Sequence[Work]:
+        results: list[Work] = []
+        pending = list(ids)
+        # Fetch in waves sized to the shortfall so a 404 or dead neighbor gets
+        # replaced by the next id in order, without fetching past the limit
+        # when everything resolves.
+        while pending and len(results) < limit:
+            wave, pending = pending[: limit - len(results)], pending[limit - len(results) :]
+            fetched = await asyncio.gather(*(self._fetch_neighbor(ref_id) for ref_id in wave))
+            results.extend(work for work in fetched if work is not None)
+        return tuple(results)
+
+    async def _fetch_neighbor(self, ref_id: str) -> Work | None:
+        try:
+            return await self._fetch_work_at(f"/works/{quote(ref_id, safe='')}")
+        except (OalexUnavailable, OalexRequestError) as exc:
+            _log.warning("oalex: neighbor fetch failed for %s: %s", ref_id, exc)
+            return None
+
+    @overload
+    async def _get_json(
+        self, path: str, params: dict[str, str] | None = ..., *, allow_404: Literal[False] = ...
+    ) -> dict[str, Any]: ...
+
+    @overload
+    async def _get_json(
+        self, path: str, params: dict[str, str] | None = ..., *, allow_404: Literal[True]
+    ) -> dict[str, Any] | None: ...
+
+    async def _get_json(
+        self,
+        path: str,
+        params: dict[str, str] | None = None,
+        *,
+        allow_404: bool = False,
+    ) -> dict[str, Any] | None:
+        merged: dict[str, str] = {"mailto": self._email} if self._email else {}
+        if params:
+            merged.update(params)
+        cache_key = path + "?" + urlencode(sorted(merged.items()))
+        cached = self._cache.get(cache_key)
+        if cached is not None:
+            return _decode(cached)
+
+        async def do_request() -> httpx.Response:
+            # Inside the retried callable so retries also wait their turn.
+            await self._rate.acquire()
+            # OpenAlex answers merged-away ids with a 301 to the survivor.
+            return await self._client.get(
+                _API_BASE + path,
+                params=merged,
+                headers=self._headers,
+                follow_redirects=True,
+            )
+
+        try:
+            response = await with_backoff(do_request)
+        except httpx.HTTPError as exc:
+            raise OalexUnavailable(f"request to {path} failed: {exc!r}") from exc
+        status = response.status_code
+        if allow_404 and status == 404:
+            return None
+        if status == 429:
+            retry_after = _parse_retry_after(response.headers.get("retry-after"))
+            raise OalexRateLimited(
+                f"OpenAlex rate limit hit on {path}: {_error_detail(response)}",
+                retry_after=retry_after,
+            )
+        if status >= 500:
+            raise OalexUnavailable(f"OpenAlex returned {status} for {path}")
+        if status >= 400:
+            raise OalexRequestError(
+                f"OpenAlex returned {status} for {path}: {_error_detail(response)}",
+                status_code=status,
+            )
+        payload = _decode(response.content)
+        # Cache after decoding so an HTML error page served with a 200 by some
+        # proxy doesn't get pinned for a whole TTL.
+        self._cache.set(cache_key, response.content)
+        return payload
+
+
+def _search_params(
+    query: str, *, per_page: int, year_min: int | None, year_max: int | None
+) -> dict[str, str]:
+    params = {
+        "search": query,
+        "per-page": str(min(max(per_page, 1), _MAX_PER_PAGE)),
+    }
+    if year_min is not None or year_max is not None:
+        # Open-ended ranges ("2018-") are valid OpenAlex filter syntax.
+        lo = str(year_min) if year_min is not None else ""
+        hi = str(year_max) if year_max is not None else ""
+        params["filter"] = f"publication_year:{lo}-{hi}"
+    return params
+
+
+def _work_path(work_id: str) -> str | None:
+    bare = _strip_openalex_id_url(work_id)
+    if bare is not None:
+        return f"/works/{quote(bare, safe='')}"
+    prefix, sep, raw = work_id.partition(":")
+    if not sep:
+        return f"/works/{quote(work_id, safe='')}"
+    if prefix == "openalex":
+        return f"/works/{quote(raw, safe='')}"
+    if prefix == "doi":
+        return _doi_path(raw)
+    return None
+
+
+def _doi_path(doi: str) -> str:
+    # DOIs may contain '#', '?' and ';' (old SICI-style Wiley DOIs do);
+    # unescaped, httpx would read those as a fragment or query string.
+    return f"/works/doi:{quote(doi, safe='/:')}"
+
+
+def _decode(body: bytes) -> dict[str, Any]:
+    try:
+        payload = json.loads(body)
+    except json.JSONDecodeError as exc:
+        raise OalexUnavailable("response was not JSON") from exc
+    if not isinstance(payload, dict):
+        raise OalexUnavailable(f"expected a JSON object, got {type(payload).__name__}")
+    return payload
+
+
+def _parse_results(payload: dict[str, Any]) -> list[Work]:
+    raw_results = payload.get("results")
+    if not isinstance(raw_results, list):
+        return []
+    return [work for raw in raw_results if isinstance(raw, dict) and (work := parse_work(raw))]
+
+
+def _error_detail(response: httpx.Response) -> str:
+    try:
+        body = response.json()
+    except ValueError:
+        return response.text[:200]
+    if isinstance(body, dict):
+        return str(body.get("message") or body.get("error") or body)[:200]
+    return str(body)[:200]

oalex/errors.py

@@ -0,0 +1,49 @@
+"""Errors raised by the oalex client."""
+
+from __future__ import annotations
+
+
+class OalexError(Exception):
+    """Base for all oalex-defined exceptions."""
+
+
+class OalexUnavailable(OalexError):
+    """Raised when a transient failure prevents resolving a request.
+
+    Network errors, HTTP 5xx after exhausted retries, and malformed JSON
+    responses surface here. Distinct from "not found": ``fetch_work``
+    returns ``None`` for legitimate 404s rather than raising, so callers
+    can tell "this id doesn't exist in OpenAlex" apart from "OpenAlex is
+    having a bad day."
+    """
+
+    def __init__(self, reason: str) -> None:
+        super().__init__(reason)
+        self.reason = reason
+
+
+class OalexRateLimited(OalexUnavailable):
+    """OpenAlex answered 429 and retrying soon won't help.
+
+    Since February 2026 OpenAlex meters usage against a daily credit
+    budget that resets at midnight UTC. Keyless callers get a small one,
+    so a busy script can run it dry mid-day. ``retry_after`` is the
+    server's Retry-After hint in seconds when it sent one.
+    """
+
+    def __init__(self, reason: str, *, retry_after: float | None = None) -> None:
+        super().__init__(reason)
+        self.retry_after = retry_after
+
+
+class OalexRequestError(OalexError):
+    """OpenAlex rejected the request itself (a 4xx other than 404 and 429).
+
+    A bad filter, a malformed id, or an invalid API key lands here.
+    Retrying the same request will fail the same way.
+    """
+
+    def __init__(self, reason: str, *, status_code: int) -> None:
+        super().__init__(reason)
+        self.reason = reason
+        self.status_code = status_code

oalex/types.py

@@ -0,0 +1,252 @@
+"""Typed wrappers for OpenAlex Work and Author payloads.
+
+OpenAlex's Work JSON is large (50+ fields) and changes shape over time;
+``Work`` exposes the commonly-used fields as typed attributes while
+preserving the raw payload at ``.raw`` for anything the typed surface
+doesn't cover. This keeps the package's surface small and lets callers
+reach into the full response without subclassing.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from datetime import date
+from types import MappingProxyType
+from typing import Any
+
+
+@dataclass(frozen=True, slots=True)
+class Author:
+    """An author on an OpenAlex Work.
+
+    ``orcid`` is the full ORCID URL when OpenAlex has one. Many records
+    don't, in which case it's ``None``.
+    """
+
+    name: str
+    orcid: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class Work:
+    """A scholarly work parsed from OpenAlex's ``/works`` endpoint.
+
+    ``id`` is the bare OpenAlex ID (``W2626778328``), not the full URL
+    that OpenAlex returns. Use ``.url`` for the canonical URL form.
+
+    ``raw`` holds the full deserialized JSON payload for fields not
+    surfaced as typed attributes (topics, keywords, locations,
+    counts_by_year, etc.).
+    """
+
+    id: str
+    title: str
+    abstract: str
+    authors: tuple[Author, ...]
+    published: date | None = None
+    url: str | None = None
+    doi: str | None = None
+    venue: str | None = None
+    pdf_url: str | None = None
+    citation_count: int | None = None
+    referenced_works: tuple[str, ...] = ()
+    """Bare OpenAlex IDs of works this work cites. Empty when OpenAlex
+    has no citation graph for this record (older items, non-citable
+    types) or when the field was stripped by a ``select=`` parameter."""
+    related_works: tuple[str, ...] = ()
+    """Bare OpenAlex IDs of works OpenAlex considers similar. Computed
+    from topic-vector overlap, not a citation relationship."""
+    field_name: str | None = None
+    """``primary_topic.field.display_name`` when present: a coarse
+    discipline label ("Computer Science", "Medicine", "Mathematics")."""
+    raw: Mapping[str, Any] = field(default_factory=lambda: MappingProxyType({}))
+
+
+def parse_work(raw: Mapping[str, Any] | None) -> Work | None:
+    """Parse an OpenAlex Work JSON payload into a :class:`Work`.
+
+    Returns ``None`` when the payload is empty or lacks a parseable
+    ``id``. OpenAlex sometimes returns placeholder records (merged
+    duplicates, withdrawn entries) that we don't want to surface to
+    callers.
+    """
+    if not raw:
+        return None
+    openalex_id = _strip_openalex_id_url(raw.get("id"))
+    if not openalex_id:
+        return None
+    title = (raw.get("title") or raw.get("display_name") or "").strip()
+    abstract = _reconstruct_abstract(raw.get("abstract_inverted_index"))
+    published = _parse_publication_date(
+        raw.get("publication_date"), raw.get("publication_year")
+    )
+    doi = _strip_doi_url(raw.get("doi"))
+    venue = _extract_venue(raw)
+    pdf_url = _extract_pdf_url(raw)
+    authors = _extract_authors(raw)
+    raw_count = raw.get("cited_by_count")
+    citation_count = raw_count if isinstance(raw_count, int) else None
+    referenced = _extract_id_list(raw.get("referenced_works"))
+    related = _extract_id_list(raw.get("related_works"))
+    field_name = _extract_field_name(raw)
+    return Work(
+        id=openalex_id,
+        title=title,
+        abstract=abstract,
+        authors=authors,
+        published=published,
+        url=raw.get("id") if isinstance(raw.get("id"), str) else None,
+        doi=doi,
+        venue=venue,
+        pdf_url=pdf_url,
+        citation_count=citation_count,
+        referenced_works=referenced,
+        related_works=related,
+        field_name=field_name,
+        raw=MappingProxyType(dict(raw)),
+    )
+
+
+def _strip_openalex_id_url(value: Any) -> str | None:
+    """``https://openalex.org/W123`` → ``W123``. Anything else → ``None``.
+
+    OpenAlex always returns its own ids as full URLs; this canonicalizes
+    on the bare form so callers don't have to slice URLs themselves.
+    """
+    if not isinstance(value, str) or not value:
+        return None
+    marker = "openalex.org/"
+    if marker not in value:
+        return None
+    bare = value.split(marker, 1)[1]
+    return bare or None
+
+
+def _strip_doi_url(value: Any) -> str | None:
+    """``https://doi.org/10.x/y`` → ``10.x/y``. Lower-cases per spec.
+
+    DOIs are case-insensitive per the spec; lower-casing here means
+    downstream dedup logic that hashes the DOI doesn't miss matches
+    when OpenAlex returns a mixed-case form.
+    """
+    if not isinstance(value, str) or not value:
+        return None
+    stripped = value
+    for prefix in ("https://doi.org/", "http://doi.org/"):
+        if stripped.startswith(prefix):
+            stripped = stripped.removeprefix(prefix)
+            break
+    return stripped.lower() or None
+
+
+def _reconstruct_abstract(inverted: Any) -> str:
+    """Flatten OpenAlex's ``{word: [positions]}`` index back to a string.
+
+    Each word can appear at multiple positions; we sort by position and
+    join with spaces. Quirky but preserves word order without storing
+    the abstract verbatim (OpenAlex's copyright workaround).
+    """
+    if not inverted or not isinstance(inverted, dict):
+        return ""
+    positions: list[tuple[int, str]] = []
+    for word, posns in inverted.items():
+        if not isinstance(posns, list):
+            continue
+        for pos in posns:
+            if isinstance(pos, int):
+                positions.append((pos, str(word)))
+    positions.sort()
+    return " ".join(word for _, word in positions)
+
+
+def _parse_publication_date(date_str: Any, year: Any) -> date | None:
+    if isinstance(date_str, str) and date_str:
+        try:
+            return date.fromisoformat(date_str)
+        except ValueError:
+            pass
+    if isinstance(year, int):
+        try:
+            return date(year, 1, 1)
+        except ValueError:
+            return None
+    return None
+
+
+def _extract_venue(raw: Mapping[str, Any]) -> str | None:
+    primary = raw.get("primary_location") or {}
+    source = primary.get("source") if isinstance(primary, dict) else None
+    if isinstance(source, dict):
+        name = (source.get("display_name") or "").strip()
+        if name:
+            return name
+    return None
+
+
+def _extract_pdf_url(raw: Mapping[str, Any]) -> str | None:
+    """Prefer ``best_oa_location.pdf_url``; fall back to ``open_access.oa_url``.
+
+    Both fields can be present; best_oa_location is a curated open-access
+    landing, oa_url is whatever URL OpenAlex has cached. Either is more
+    likely to actually serve a PDF than primary_location.pdf_url, which
+    is often null even when an OA copy exists elsewhere.
+    """
+    best = raw.get("best_oa_location") or {}
+    if isinstance(best, dict):
+        url = best.get("pdf_url")
+        if isinstance(url, str) and url:
+            return url
+    oa = raw.get("open_access") or {}
+    if isinstance(oa, dict):
+        url = oa.get("oa_url")
+        if isinstance(url, str) and url:
+            return url
+    return None
+
+
+def _extract_authors(raw: Mapping[str, Any]) -> tuple[Author, ...]:
+    authors: list[Author] = []
+    for entry in raw.get("authorships") or []:
+        if not isinstance(entry, dict):
+            continue
+        author = entry.get("author")
+        if not isinstance(author, dict):
+            continue
+        name = (author.get("display_name") or "").strip()
+        if not name:
+            continue
+        orcid = author.get("orcid")
+        authors.append(
+            Author(name=name, orcid=orcid if isinstance(orcid, str) else None)
+        )
+    return tuple(authors)
+
+
+def _extract_id_list(value: Any) -> tuple[str, ...]:
+    """Pull bare OpenAlex IDs out of a list of work URLs.
+
+    OpenAlex returns ``referenced_works`` / ``related_works`` as lists
+    of full work URLs (``https://openalex.org/W123``). This strips each
+    to its bare form and drops anything that doesn't parse.
+    """
+    if not isinstance(value, list):
+        return ()
+    return tuple(
+        oa_id
+        for item in value
+        if (oa_id := _strip_openalex_id_url(item)) is not None
+    )
+
+
+def _extract_field_name(raw: Mapping[str, Any]) -> str | None:
+    topic = raw.get("primary_topic")
+    if not isinstance(topic, dict):
+        return None
+    field_block = topic.get("field")
+    if not isinstance(field_block, dict):
+        return None
+    name = field_block.get("display_name")
+    if isinstance(name, str) and name.strip():
+        return name.strip()
+    return None

oalex-0.2.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,12 @@
+oalex/__init__.py,sha256=suOw72DWBPaSp7kdknWm152lLJHVOSHFe1zu-5pXPUk,812
+oalex/_backoff.py,sha256=KmyhuMZ4CcK_vIUdxXvk_Y3XjMG0sxp5Jz-RO1oKmG0,3916
+oalex/_cache.py,sha256=BDiIctptYSYx8zY3TptHcz2er2Qky4JlrrA2mCjcF0U,2173
+oalex/_rate_limit.py,sha256=Sw8-i1TPt6pwQRGFJqNXre5DCA1osL2Ra2Szd3s-mm8,1430
+oalex/client.py,sha256=MxRTeLVDnYEGzQs6EhxApwAHKjk4NM9EqzaKKCJ2q0c,16607
+oalex/errors.py,sha256=LjYwUZ4lHM5wmAJY7gJ4WbgwUKY1gewU-8XfBmLkZ1g,1643
+oalex/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+oalex/types.py,sha256=Ziqtp_zycpUILJubh48BJxle13dC_dU2wH0S_V3Uz18,8644
+oalex-0.2.0.dist-info/METADATA,sha256=-EJJ6YeisdPET1ywYfDC0187MhfCfTr0OZbYEH06L04,8953
+oalex-0.2.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+oalex-0.2.0.dist-info/licenses/LICENSE,sha256=a7XhdgxAUdy67A_UYSNRSXTA2i936Gwf0QrLm6_L8qk,1069
+oalex-0.2.0.dist-info/RECORD,,

oalex-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

oalex-0.2.0.dist-info/licenses/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.