Move the HTTP transport from httpx to httpx2 (#3)

httpx has seen no commit since February 2026. httpx2 is the fork its
original author now maintains under Pydantic's stewardship, published
from pydantic/httpx2 under the same BSD-3-Clause licence; it forked
httpx 0.28.1 and keeps the public API, so this is a rename rather than
a rewrite. The wider ecosystem has already moved: the Anthropic Python
SDK requires httpx2 as of its 1.0 release.

This is a breaking change for callers, because litfetch's HTTP types
are part of its surface. The two packages install side by side but
their classes are distinct, so an object cannot cross between them:
`Session.client` now returns an `httpx2.AsyncClient`, `client_factory`
must build one, `Session.get` returns an `httpx2.Response`, and the
errors litfetch raises are `httpx2` exceptions that an `except httpx`
clause no longer catches. Callers migrate by renaming their own
imports. Version bumped to 0.3.0 accordingly.

Two visible behaviour changes come with the fork: TLS is verified
against the operating system trust store via truststore rather than
certifi's bundle, and deprecation warnings are shown by default.

ADR 0001 is left untouched. It is a dated record of why a Session owns
one client and the per-host pacing state, and that decision is
unaffected by which package supplies the client.

Author: lgruen-cpg

docs/api.md

@@ -493,7 +493,7 @@ class Session:
     def __init__(
         self,
         *,
-        client_factory: Callable[[], httpx.AsyncClient] | None = None,
+        client_factory: Callable[[], httpx2.AsyncClient] | None = None,
         retry: RetryPolicy = <default>,
         timeout: float = 30.0,
         contact: str | None = None,
@@ -502,9 +502,9 @@ class Session:
     async def __aexit__(self, *exc) -> None  # closes it (a scope leaves it open)
     def scope(self) -> Session               # child with its own cache; see below
     @property
-    def client(self) -> httpx.AsyncClient    # escape hatch; valid only in-context
+    def client(self) -> httpx2.AsyncClient    # escape hatch; valid only in-context
     async def get(self, url, *, params=None, headers=None, rate=Rate.DEFAULT,
-                  follow_redirects=False) -> httpx.Response
+                  follow_redirects=False) -> httpx2.Response
     # operations: fetch_body, list_files, fetch_file, resolve_access, related_ids
 ```
 
@@ -514,7 +514,7 @@ or CA-cert configuration; the default builds a client with a litfetch
 `User-Agent` and `timeout`. `contact` (an email) is the caller's polite-pool
 identity — see [Contact](#contact) below. `get` paces per `rate` then issues a
 retrying GET (see [`RetryPolicy`](#retrypolicy)) — and, inside a `scope`, serves
-a repeat request from cache; `client` exposes the raw `httpx.AsyncClient` for
+a repeat request from cache; `client` exposes the raw `httpx2.AsyncClient` for
 what `get` doesn't cover (POST, streaming). `follow_redirects` is off by default
 (an API move should surface, not be chased silently); `fetch_file` downloads
 pass it through to follow publisher PDF redirects.
@@ -557,7 +557,7 @@ class Http(Protocol):
         headers: Mapping[str, str] | None = None,
         rate: Rate = Rate.DEFAULT,
         follow_redirects: bool = False,
-    ) -> httpx.Response
+    ) -> httpx2.Response
 ```
 
 The one-method surface a source or resolver depends on. `Session` implements it.

docs/institutional-access.md

@@ -50,7 +50,7 @@ async def _rewrite(request):
         request.headers['Host'] = new
 
 def factory():
-    return httpx.AsyncClient(headers={'Cookie': cookie}, event_hooks={'request': [_rewrite]})
+    return httpx2.AsyncClient(headers={'Cookie': cookie}, event_hooks={'request': [_rewrite]})
 
 async with litfetch.Session(client_factory=factory) as entitled:
     ...

docs/source-expansion-plan.md

@@ -98,12 +98,12 @@ without threading a shared record (resolving the open question below).
   (generalising `ElsevierFetcher` to any publisher) is deferred: it needs TDM
   token handling (see EZproxy/credentials below), and unentitled links 403.
 - **doi.org resolve** — **deferred.** Marginal coverage over Unpaywall's
-  `best_oa_location` for real friction: doi.org 30x-redirects (httpx doesn't
+  `best_oa_location` for real friction: doi.org 30x-redirects (httpx2 doesn't
   follow by default, and `Http.get` doesn't expose the option), and it is
   fetch-to-discover (a GET to classify by `content-type`, then a second GET to
   download — most redirects land on HTML anyway). If revisited: add
   `follow_redirects` to `Http.get` (opt-in) rather than enabling it globally
-  (httpx keeps custom auth headers across cross-origin redirects — a key-leak
+  (httpx2 keeps custom auth headers across cross-origin redirects — a key-leak
   footgun).
 
 ### 4. Opportunistic / later

litfetch/_http.py

@@ -22,7 +22,7 @@
 from collections.abc import Mapping
 from typing import Protocol
 
-import httpx
+import httpx2
 
 DEFAULT_TIMEOUT = 30.0
 # Base User-Agent, no contact. A caller who sets Session(contact=...) gets a
@@ -94,7 +94,7 @@ async def get(
         headers: Mapping[str, str] | None = None,
         rate: Rate = Rate.DEFAULT,
         follow_redirects: bool = False,
-    ) -> httpx.Response:
+    ) -> httpx2.Response:
         """GET ``url``, paced per ``rate`` and retried per the session policy."""
         ...
 
@@ -103,7 +103,7 @@ async def get(
 class RetryPolicy:
     """How :func:`get` retries a transient failure.
 
-    A transient failure is an ``httpx.TransportError`` (timeout, connection
+    A transient failure is an ``httpx2.TransportError`` (timeout, connection
     reset) or a retryable status (429, 500, 502, 503, 504).  Backoff is
     exponential with full jitter -- ``uniform(0, base_delay * 2**attempt)`` --
     capped at ``max_delay``; a 429/503 ``Retry-After`` in integer seconds
@@ -126,23 +126,23 @@ def __post_init__(self) -> None:
 
 
 async def get(
-    client: httpx.AsyncClient,
+    client: httpx2.AsyncClient,
     url: str,
     *,
     params: Mapping[str, str | int] | None = None,
     headers: Mapping[str, str] | None = None,
     retry: RetryPolicy = DEFAULT_RETRY,
     follow_redirects: bool = False,
-) -> httpx.Response:
+) -> httpx2.Response:
     """GET ``url``, retrying a transient failure per ``retry``.
 
-    Retries an ``httpx.TransportError`` or a retryable status (see
+    Retries an ``httpx2.TransportError`` or a retryable status (see
     :class:`RetryPolicy`) with backoff, then returns the final response --
     including a still-failing status, so the caller keeps its own status
     handling.  Re-raises the last transport error when every attempt fails.
 
     Args:
-        client: The httpx client to issue the request on.
+        client: The httpx2 client to issue the request on.
         url: The absolute URL to GET.
         params: Query parameters, if any.
         headers: Request headers, if any.
@@ -151,18 +151,18 @@ async def get(
             enable it to follow publisher PDF redirects).
 
     Returns:
-        The final :class:`httpx.Response` (a non-retryable status, or the last
+        The final :class:`httpx2.Response` (a non-retryable status, or the last
         response after exhausting retries).
 
     Raises:
-        httpx.TransportError: If every attempt fails at the transport layer.
+        httpx2.TransportError: If every attempt fails at the transport layer.
     """
     for attempt in range(retry.max_attempts):
         last_attempt = attempt == retry.max_attempts - 1
         retry_after: float | None = None
         try:
             response = await client.get(url, params=params, headers=headers, follow_redirects=follow_redirects)
-        except httpx.TransportError:
+        except httpx2.TransportError:
             if last_attempt:
                 raise
         else:
@@ -173,7 +173,7 @@ async def get(
     raise AssertionError('unreachable: the loop returns or raises on the last attempt')
 
 
-def _retry_after_seconds(response: httpx.Response) -> float | None:
+def _retry_after_seconds(response: httpx2.Response) -> float | None:
     """Parse a ``Retry-After`` header as integer seconds; ``None`` otherwise.
 
     The HTTP-date form is accepted by the spec but not used by the APIs

litfetch/crossref.py

@@ -12,7 +12,7 @@
 
 import logging
 
-import httpx
+import httpx2
 
 from litfetch import _doi, _http
 
@@ -39,7 +39,7 @@ async def fetch_work(doi: str, *, http: _http.Http, mailto: str | None = None) -
     params = {'mailto': mailto} if mailto else {}
     try:
         resp = await http.get(f'{_CROSSREF_BASE}/{_doi.encode_doi_path(doi)}', params=params)
-    except httpx.HTTPError:
+    except httpx2.HTTPError:
         logger.exception('Crossref lookup failed for %s', doi)
         return None
     if resp.status_code != 200:

litfetch/fetchers.py

@@ -43,7 +43,7 @@
 from typing import Protocol
 
 import defusedxml.ElementTree
-import httpx
+import httpx2
 
 from litfetch import _doi, _http, artifacts, crossref, ids, semantic_scholar, unpaywall
 
@@ -176,7 +176,7 @@ async def fetch_jats_xml(
         url = _pmc_versioned_xml_url(numeric, version)
         try:
             resp = await http.get(url)
-        except httpx.HTTPError:
+        except httpx2.HTTPError:
             logger.exception('PMC OA fetch failed for %s', url)
             continue
         if resp.status_code == 200:
@@ -251,7 +251,7 @@ async def _download(http: _http.Http, file: artifacts.File, *, what: str) -> art
     try:
         # Publisher PDF links commonly redirect (openURL -> content/pdf, ...); follow them.
         resp = await http.get(file.uri, follow_redirects=True)
-    except httpx.HTTPError:
+    except httpx2.HTTPError:
         logger.exception('%s fetch failed for %s', what, file.uri)
         return None
     if resp.status_code != 200:
@@ -350,7 +350,7 @@ async def _list_keys(self, http: _http.Http, prefix: str) -> list[tuple[str, int
                 params['continuation-token'] = token
             try:
                 resp = await http.get(f'{_PMC_S3_BASE}/', params=params)
-            except httpx.HTTPError:
+            except httpx2.HTTPError:
                 logger.exception('PMC OA list failed for prefix %s', prefix)
                 return keys
             if resp.status_code != 200:
@@ -396,7 +396,7 @@ async def fetch(
         url = f'{_EUROPE_PMC_BASE}/PMC{numeric}/fullTextXML'
         try:
             resp = await http.get(url)
-        except httpx.HTTPError:
+        except httpx2.HTTPError:
             logger.exception('Europe PMC fetch failed for %s', url)
             return None
         if resp.status_code != 200 or not resp.content:
@@ -446,7 +446,7 @@ async def fetch(
             return None
         try:
             resp = await http.get(link, headers={'X-ELS-APIKey': api_key, 'Accept': 'text/xml'})
-        except httpx.HTTPError:
+        except httpx2.HTTPError:
             logger.exception('Elsevier fetch failed for %s', link)
             return None
         if resp.status_code != 200 or not resp.content or not _elsevier_has_body(resp.content):
@@ -491,7 +491,7 @@ async def fetch(
         query = f'doi:{article_ids.doi}'
         try:
             resp = await http.get(_SPRINGER_BASE, params={'q': query, 'api_key': api_key})
-        except httpx.HTTPError:
+        except httpx2.HTTPError:
             logger.exception('Springer fetch failed for %s', article_ids.doi)
             return None
         if resp.status_code != 200 or not resp.content:
@@ -515,7 +515,7 @@ async def _fetch_impersonated(url: str, *, impersonate: str) -> bytes | None:
     """GET ``url`` with a browser TLS fingerprint via curl_cffi.
 
     bioRxiv's JATS host sits behind Cloudflare's fingerprint gate, which a plain
-    httpx client trips; curl_cffi impersonates a real browser's TLS/HTTP-2
+    httpx2 client trips; curl_cffi impersonates a real browser's TLS/HTTP-2
     fingerprint to pass it.  Raises a clear error when the optional extra is
     absent; returns ``None`` on a transport error or non-200.
     """
@@ -592,7 +592,7 @@ async def _jats_url(self, http: _http.Http, doi: str) -> str | None:
             url = f'{_BIORXIV_DETAILS_BASE}/{server}/{_doi.encode_doi_path(doi)}'
             try:
                 resp = await http.get(url)
-            except httpx.HTTPError:
+            except httpx2.HTTPError:
                 logger.exception('bioRxiv details lookup failed for %s', url)
                 continue
             if resp.status_code != 200:
@@ -780,7 +780,7 @@ async def _springer_meta_pdf(http: _http.Http, doi: str, api_key: str) -> tuple[
     """
     try:
         resp = await http.get(_SPRINGER_META_BASE, params={'q': f'doi:{doi}', 'api_key': api_key})
-    except httpx.HTTPError:
+    except httpx2.HTTPError:
         logger.exception('Springer Meta request failed for %s', doi)
         return None
     if resp.status_code != 200:

litfetch/relations.py

@@ -20,7 +20,7 @@
 import logging
 from typing import NamedTuple
 
-import httpx
+import httpx2
 
 from litfetch import _doi, _http, crossref, ids
 
@@ -83,7 +83,7 @@ async def _biorxiv_published(http: _http.Http, doi: str) -> str | None:
         url = f'{_BIORXIV_DETAILS_BASE}/{server}/{_doi.encode_doi_path(doi)}'
         try:
             resp = await http.get(url)
-        except httpx.HTTPError:
+        except httpx2.HTTPError:
             logger.exception('bioRxiv details lookup failed for %s', url)
             continue
         if resp.status_code != 200:

litfetch/resolvers.py

@@ -30,7 +30,7 @@
 import logging
 from collections.abc import Awaitable, Callable, Iterable, Mapping, Sequence
 
-import httpx
+import httpx2
 
 from litfetch import _http, ids, semantic_scholar
 
@@ -80,7 +80,7 @@ async def _get_json(
     """GET ``url`` and parse JSON, logging and swallowing transport errors."""
     try:
         resp = await http.get(url, params=params, rate=rate)
-    except httpx.HTTPError:
+    except httpx2.HTTPError:
         logger.exception('%s request failed', context)
         return None
     if resp.status_code != 200:
@@ -125,7 +125,7 @@ async def _get_json_or_abandon(
     """
     try:
         resp = await http.get(url, params=params, rate=rate)
-    except httpx.HTTPError as e:
+    except httpx2.HTTPError as e:
         raise _ChunkAbandonedError(f'{context}: transport failure') from e
     if resp.status_code in _http.RETRYABLE_STATUS:  # survived retries: never answered
         raise _ChunkAbandonedError(f'{context}: HTTP {resp.status_code} after retries')

litfetch/semantic_scholar.py

@@ -13,7 +13,7 @@
 
 import logging
 
-import httpx
+import httpx2
 
 from litfetch import _doi, _http, ids
 
@@ -59,7 +59,7 @@ async def fetch_paper(
     rate = _http.Rate.S2_KEYED if api_key else _http.Rate.S2_UNKEYED
     try:
         resp = await http.get(f'{_PAPER_BASE}/{pid}', params={'fields': fields}, headers=headers, rate=rate)
-    except httpx.HTTPError:
+    except httpx2.HTTPError:
         logger.exception('Semantic Scholar request failed')
         return None
     if resp.status_code != 200: