pathapi-httpx 0.1.0__py3-none-any.whl

pathapi_httpx/AGENTS.md

@@ -0,0 +1,149 @@
+# `pathapi_httpx` — public API header
+
+Header-file-style reference for the `pathapi_httpx` package: every public
+export with its signature, arguments, contract and gotchas, so the package can
+be used without reading its source. It ships inside the package and is
+self-contained. Development documentation lives with the source at
+<https://github.com/jose-pr/pathapi-httpx>.
+
+Names are imported from `pathapi_httpx`, which exports two classes,
+`HttpxTransport` and `AsyncHttpxTransport`, and `__version__`. A module or name
+that starts with an underscore is private and nothing there is contract.
+
+`pip install pathapi-httpx`. Required dependencies: `pathapi>=0.1.2,<0.2` and
+`httpx>=0.28.0,<0.29`. `httpx` is imported when a transport is built, not when
+this package is. HTTP/2 needs `h2`: `pip install "httpx[http2]"`.
+
+`pathapi_httpx.__version__` is the version of the installed
+distribution, read from its metadata. The rendered documentation is at
+<https://jose-pr.github.io/pathapi-httpx/> and the project overview is the
+`README.md` shipped next to this file (`pathapi_httpx/README.md`).
+
+## The `httpx` transports (`pathapi_httpx`)
+
+```python
+class HttpxTransport:
+    client: httpx.Client
+    def __init__(self, client=None, **client_args): ...
+    def send(
+        self, method, url, *, headers, body=None, timeout, stream=False,
+    ) -> HTTPResponse: ...
+    def close(self) -> None: ...
+
+class AsyncHttpxTransport:
+    client: httpx.AsyncClient
+    def __init__(self, client=None, **client_args): ...
+    async def send(
+        self, method, url, *, headers, body=None, timeout, stream=False,
+    ) -> AsyncHTTPResponse: ...
+    async def aclose(self) -> None: ...
+```
+
+`HttpxTransport` is an HTTP transport for `pathapi.http` and
+`AsyncHttpxTransport` an async one (the contracts are "The transport contract"
+and "The async transport contract" in the `pathapi` header): `send()` makes one
+request with an `httpx` client and returns a `pathapi.http.HTTPResponse`, or
+for the async one an `AsyncHTTPResponse` read with coroutines. `pathapi.http`
+finds them through the `httpx` entries of its `pathapi.http_transports` and
+`pathapi.http_async_transports` entry-point groups, which this distribution
+declares, so installing the distribution is all that is needed:
+
+- `HTTPClient(HttpxTransport(client))` and
+  `AsyncHTTPClient(AsyncHttpxTransport(client))` send every request of the
+  client through the `httpx` client. `HTTPClient` and `AsyncHTTPClient` follow
+  the redirects and never close a transport they were given.
+- `PATHAPI_HTTP_TRANSPORT=httpx` makes every `HTTPClient` that was given no
+  transport build `HttpxTransport()`, and `PATHAPI_HTTP_ASYNC_TRANSPORT=httpx`
+  every `AsyncHTTPClient` build `AsyncHttpxTransport()`; so do
+  `pathapi.http.default_transport()`, `default_async_transport()` and
+  `get_transport("httpx")()`, `get_async_transport("httpx")()`.
+
+Use `HttpxTransport` for what the built-in transport does not do: HTTP/2, a
+client of your own with its `mounts`, `limits`, proxies and `auth`,
+`SSL_CERT_FILE` and the certifi bundle. Use `AsyncHttpxTransport` to send from
+an event loop on its own sockets: `ThreadedTransport` (the default async
+transport) needs a worker thread for every request that is waiting.
+
+- **`client`** — the `httpx.Client` (`httpx.AsyncClient` for the async
+  transport) to send with, an object with a `send()` method (an async one for
+  the async transport; `TypeError` otherwise). `None` makes a new one from
+  `client_args`. The attribute `client` is the one in use. `close()` (`await
+  aclose()`) closes a client this transport made and leaves a caller's open, so
+  a client passed in is still usable afterwards; both transports are context
+  managers that close (`async with` for the async one). A client the
+  synchronous transport made is also closed when the transport is collected;
+  the async one must be closed with `aclose()`. A response that is still open
+  keeps its transport alive.
+- **`client_args`** — keyword arguments of `httpx.Client(...)` /
+  `httpx.AsyncClient(...)` for the client the transport makes: `verify` (a
+  `bool` or an `ssl.SSLContext`), `cert`, `http2`, `proxy`, `mounts`,
+  `transport`, `limits`, `trust_env`, `auth`, ... `client_args` together with a
+  `client` is `TypeError`. `follow_redirects` is always `False`, whatever is
+  given.
+- **`send(method, url, *, headers, body=None, timeout, stream=False)`** is
+  `HTTPTransport.send()` (`await send()` of `ThreadedTransport.send()`):
+  `ValueError` before anything is sent for what `pathapi.http.prepare_request()`
+  refuses, one request and no redirect followed (a client told to
+  `follow_redirects` still returns the redirect), the response body read whole
+  with `stream=False`. A `timeout` of `(connect, read)` is `httpx.Timeout`'s
+  `connect` and `pool`, and `read` and `write`. A body that is a binary file or
+  an iterable of `bytes` is read by the async transport on a worker thread.
+- **Exactly the headers it is given.** `httpx` adds no `User-Agent`, `Accept`
+  or `Connection` and no cookie of the client's jar, and the default headers of
+  the client are not sent: `HTTPClient` and `AsyncHTTPClient` decide the headers
+  of a request.
+- **Credentials belong to one server.** The `auth` of the client is used for
+  the server of the first request: its scheme, host and port. A request to any
+  other server carries the `Authorization` it was given and nothing the client
+  holds. An `auth` of the client wins over an `Authorization` header on that
+  first server. Redirects are followed by `HTTPClient`, which drops
+  `Authorization` when one leaves the server.
+- **Failures** are `TimeoutError`, `ConnectionError`, `ssl.SSLError`,
+  `ValueError` (the request was not valid) or `OSError(EIO)` (a reply that is
+  not valid HTTP, is cut short or has more than 100 header fields, or a
+  `Location` that a client given to the transport cannot read). The text of an
+  `httpx` exception, which can quote a URL, is never passed on, and the
+  exception is not chained. An exception raised by the request body passes
+  through. `repr()` shows nothing of the client or the arguments.
+
+`pathapi_httpx.__version__` is a `str`.
+
+## Checking the transports
+
+`pathapi` ships the tests that hold a transport to the promises of the
+built-in ones. With this distribution and `pytest` installed:
+
+```
+python -m pathapi.http.testing --http-transports httpx --http-async-transports httpx -q
+```
+
+## Environment variables
+
+### `PATHAPI_HTTP_TRANSPORT` and `PATHAPI_HTTP_ASYNC_TRANSPORT`
+
+Read by `pathapi.http`. `httpx` makes an `HTTPClient` (an `AsyncHTTPClient`)
+that was given no transport build `HttpxTransport()` (`AsyncHttpxTransport()`).
+The name is case-sensitive, and one that no installed distribution declares is
+`ValueError` naming the choices.
+
+### `httpx` variables
+
+A client the transport makes has `trust_env=True`, so `httpx` reads
+`HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY` and `NO_PROXY`, and `SSL_CERT_FILE`
+and `SSL_CERT_DIR` (unless `verify=` is given). Pass `trust_env=False` to
+ignore them.
+
+## Gotchas
+
+`HttpxTransport()` builds an `httpx.Client` the moment it is constructed; a
+client it made is closed by `close()`, by leaving a `with` block, and when the
+transport is collected, so a transport you build is yours to close. An
+`HTTPClient` closes only a transport it built itself, which is why
+`HTTPClient(HttpxTransport(client))` does not close one.
+
+An `httpx.AsyncClient` keeps its connections on the event loop that first sent
+with it: an `AsyncHttpxTransport` is used from one loop, and a transport for
+another `asyncio.run()` is a new one.
+
+A client given to the transport that is mounted on `httpx.MockTransport` works:
+its replies are read whole already, and `send()` returns them as they are.

pathapi_httpx/README.md

@@ -0,0 +1,135 @@
+# pathapi-httpx
+
+[![Version](https://img.shields.io/pypi/v/pathapi-httpx.svg)](https://pypi.org/project/pathapi-httpx/)
+[![Python versions](https://img.shields.io/pypi/pyversions/pathapi-httpx.svg)](https://pypi.org/project/pathapi-httpx/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/jose-pr/pathapi-httpx/blob/main/LICENSE)
+[![Docs](https://img.shields.io/badge/docs-latest-blue.svg)](https://jose-pr.github.io/pathapi-httpx/)
+[![CI](https://img.shields.io/github/actions/workflow/status/jose-pr/pathapi-httpx/test.yml)](https://github.com/jose-pr/pathapi-httpx/actions/workflows/test.yml)
+
+**The `httpx` HTTP transports for [`pathapi`](https://github.com/jose-pr/pathapi).**
+`pathapi.http` sends requests with a transport built on the standard library,
+and from an event loop with that transport on worker threads. Install this
+distribution and `HTTPClient` sends through an `httpx.Client`, and
+`AsyncHTTPClient` through an `httpx.AsyncClient` on the caller's loop, with
+nothing to configure. It is documented at
+<https://jose-pr.github.io/pathapi-httpx/>.
+
+## Features
+
+| You want | Built-in transports | These transports |
+| --- | --- | --- |
+| Requests from an event loop without a worker thread per request | No: `ThreadedTransport` runs the standard-library transport on threads | Yes: `AsyncHttpxTransport` |
+| HTTP/2 | No | Yes: `HttpxTransport(http2=True)` with `httpx[http2]` |
+| Your own `httpx.Client` or `httpx.AsyncClient`: mounted transports, limits, proxies, `auth` | No | Yes: `HttpxTransport(client)` |
+| `SSL_CERT_FILE`, `SSL_CERT_DIR` and the certifi bundle | The system trust store, or an `ssl_context=` | Yes |
+| Proxies from the environment, `proxy=` and `mounts=` | `http://` proxies through a provider | Yes, as `httpx` does them |
+
+- **Credentials belong to one server.** The `auth` of a client is sent to the
+  server of the first request and to no other, and the clients of `pathapi.http`
+  never take an `Authorization` header to another server on a redirect.
+- **Exactly the headers it is given.** A client's default headers and cookies
+  are not added: `HTTPClient` and `AsyncHTTPClient` own the headers of a request.
+- **No third-party text in an error.** A failure of `httpx` is a
+  `TimeoutError`, `ConnectionError`, `ssl.SSLError`, `ValueError` or
+  `OSError(EIO)`; what the library says, which can quote a URL, is never passed on.
+- **The same promises as the built-in transports.** The tests `pathapi` runs
+  over its own transports run over these
+  (`python -m pathapi.http.testing --http-transports httpx --http-async-transports httpx`).
+
+## Installation
+
+```bash
+pip install pathapi-httpx
+```
+
+Requires `pathapi` and `httpx`, which pip installs with it. HTTP/2 needs
+`pip install "httpx[http2]"`.
+
+## Quick start
+
+**Send through an `httpx.Client` from threads or a script:**
+
+```python
+import httpx
+from pathapi.http import HTTPClient
+from pathapi_httpx import HttpxTransport
+
+with httpx.Client() as session:
+    with HTTPClient(HttpxTransport(session), timeout=(3, 30)) as client:
+        reply = client.request("GET", "http://files.example.org/reports/today.txt")
+        print(reply.read().decode())
+```
+
+The `httpx.Client` stays yours: neither the client nor the transport closes it.
+
+**Send from an event loop** with `httpx.AsyncClient` on that loop:
+
+```python
+import asyncio
+
+from pathapi.http import AsyncHTTPClient
+from pathapi_httpx import AsyncHttpxTransport
+
+
+async def main():
+    async with AsyncHttpxTransport() as transport:
+        async with AsyncHTTPClient(transport) as client:
+            replies = await asyncio.gather(
+                *(
+                    client.request("GET", f"http://files.example.org/reports/{day}.txt")
+                    for day in ("mon", "tue", "wed")
+                )
+            )
+            print([len(await reply.read()) for reply in replies])
+
+
+asyncio.run(main())
+```
+
+**Choose them for the whole process.** `PATHAPI_HTTP_TRANSPORT=httpx` and
+`PATHAPI_HTTP_ASYNC_TRANSPORT=httpx` make every `HTTPClient` and
+`AsyncHTTPClient` that was given no transport send through a new `httpx` client:
+
+```bash
+PATHAPI_HTTP_ASYNC_TRANSPORT=httpx python -c "from pathapi.http import AsyncHTTPClient; print(type(AsyncHTTPClient().transport))"
+```
+
+## API overview
+
+| Name | Purpose |
+| --- | --- |
+| `pathapi_httpx.HttpxTransport` | The transport: `send()` and `close()` over an `httpx.Client` |
+| `pathapi_httpx.AsyncHttpxTransport` | The async transport: `await send()` and `await aclose()` over an `httpx.AsyncClient` |
+| `pathapi_httpx.__version__` | The installed version |
+
+`pathapi.http` finds the classes through the `httpx` entries of its
+`pathapi.http_transports` and `pathapi.http_async_transports` entry-point
+groups, which this distribution declares. The reference is in the
+[API header](https://github.com/jose-pr/pathapi-httpx/blob/main/src/pathapi_httpx/AGENTS.md)
+that ships with the package.
+
+## Development
+
+```bash
+python -m venv .venv/3.14-posix-x86_64
+.venv/3.14-posix-x86_64/bin/python -m pip install -e ".[dev]"
+.venv/3.14-posix-x86_64/bin/python -m pytest -q -rs
+```
+
+`pathapi` 0.1.2 is a dependency; while it is not on PyPI, install it
+editable from its checkout first (`pip install -e ../pathapi`). The test run
+includes `python -m pathapi.http.testing --http-transports httpx
+--http-async-transports httpx`, the tests `pathapi` runs over its own transports.
+
+### Releasing
+
+This project follows [Semantic Versioning](https://semver.org/) and keeps a
+[`CHANGELOG.md`](CHANGELOG.md). Pushing a tag matching `v*` triggers the release
+workflow: test gate → build (checking the tag names the version built) → a strict
+docs build as a gate → GitHub release → publish. The release workflow never deploys
+the docs site itself: for a final release its last job dispatches the docs workflow
+at the tag, which owns every Pages deploy.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

pathapi_httpx/__init__.py

@@ -0,0 +1,18 @@
+"""The `httpx` HTTP transports for `pathapi.http`.
+
+Installing this distribution is enough: `pathapi.http` finds `HttpxTransport`
+through the `httpx` entry of its `pathapi.http_transports` group and
+`AsyncHttpxTransport` through the `httpx` entry of `pathapi.http_async_transports`,
+so `HTTPClient(HttpxTransport())`, `AsyncHTTPClient(AsyncHttpxTransport())`,
+`PATHAPI_HTTP_TRANSPORT=httpx` and `PATHAPI_HTTP_ASYNC_TRANSPORT=httpx` send
+through them. `httpx` is imported when a transport is built, not when this
+package is.
+"""
+
+from __future__ import annotations
+
+from ._async import AsyncHttpxTransport
+from ._sync import HttpxTransport
+from ._version import __version__
+
+__all__ = ["AsyncHttpxTransport", "HttpxTransport", "__version__"]

pathapi_httpx/_async.py

@@ -0,0 +1,156 @@
+"""`httpx.AsyncClient` as an async HTTP transport for `pathapi.http`."""
+
+from __future__ import annotations
+
+import asyncio as _asyncio
+import inspect as _inspect
+import typing as _ty
+
+from pathapi.http import AsyncHTTPResponse, prepare_request
+
+from ._common import (
+    CHUNK,
+    Pin,
+    build_request,
+    failure,
+    header_pairs,
+    import_httpx,
+    owned_client,
+    read_already,
+    requested_url,
+)
+
+_END = object()
+
+
+async def _pieces(body) -> "_ty.AsyncIterator[bytes]":
+    """A file or an iterable of bytes as an async iterator, each read made on a
+    worker thread so that it cannot block the loop."""
+    if hasattr(body, "read"):
+        while True:
+            chunk = await _asyncio.to_thread(body.read, CHUNK)
+            if not chunk:
+                return
+            yield chunk
+    else:
+        pieces = iter(body)
+        while True:
+            chunk = await _asyncio.to_thread(next, pieces, _END)
+            if chunk is _END:
+                return
+            yield chunk
+
+
+class _Body:
+    """The raw (still encoded) body of an `httpx` response."""
+
+    def __init__(self, owner, response):
+        self._owner = owner
+        self._response = response
+        self._chunks = response.aiter_raw()
+
+    async def read(self, amount: int) -> bytes:
+        try:
+            return await self._chunks.__anext__()
+        except StopAsyncIteration:
+            return b""
+        except Exception as error:
+            raise failure(error) from None
+
+    async def aclose(self) -> None:
+        await self._chunks.aclose()
+        await self._response.aclose()
+
+
+class AsyncHttpxTransport:
+    """Sends requests with an `httpx.AsyncClient`, on the event loop that
+    awaits them.
+
+    `client` is the client to use (the caller's: `aclose()` leaves it open), or
+    `None` for a new one built from `client_args` (`verify`, `cert`, `http2`,
+    `proxy`, `mounts`, `limits`, `trust_env`, `auth`, ...) that `aclose()`
+    closes. `client_args` with a `client` is `TypeError`. Like any
+    `httpx.AsyncClient`, it keeps connections of the loop it first sent on.
+
+    The transport sends one request and follows no redirect, whatever the
+    client says. It sends exactly the headers it is given: the default headers
+    and the cookies of a client are not added. The client's `auth` is used for
+    the server of the first request only; a request to any other server
+    carries just the `Authorization` it was given. A request body that is a
+    file or an iterable is read on a worker thread.
+
+    Failures are `TimeoutError`, `ConnectionError`, `ssl.SSLError`,
+    `ValueError` or `OSError(EIO)`; what `httpx` says is never passed on."""
+
+    def __init__(self, client: "_ty.Any" = None, **client_args):
+        httpx = self._httpx = import_httpx()
+        if client is not None:
+            if client_args:
+                raise TypeError(
+                    "client arguments apply to a client the transport makes"
+                )
+            if not _inspect.iscoroutinefunction(getattr(client, "send", None)):
+                raise TypeError("a client is an object with an async send() method")
+        self._owns_client = client is None
+        if client is None:
+            client = owned_client(httpx.AsyncClient)(
+                **{**client_args, "follow_redirects": False}
+            )
+        self.client = client
+        self._pin = Pin()
+
+    def __repr__(self) -> str:
+        return "AsyncHttpxTransport()"
+
+    async def __aenter__(self) -> "AsyncHttpxTransport":
+        return self
+
+    async def __aexit__(self, *exc_info) -> None:
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        """Closes the client if this transport made it. Harmless when called
+        again."""
+        if self._owns_client:
+            await self.client.aclose()
+
+    async def send(
+        self,
+        method: str,
+        url: str,
+        *,
+        headers: "_ty.Mapping[str, str]",
+        body: "bytes | _ty.BinaryIO | _ty.Iterable[bytes] | None" = None,
+        timeout: "float | tuple | None",
+        stream: bool = False,
+    ) -> AsyncHTTPResponse:
+        """One request, one response, as `ThreadedTransport.send()`."""
+        prepared = prepare_request(
+            method, url, headers=headers, body=body, timeout=timeout
+        )
+        content = prepared.body
+        if content is not None and not isinstance(content, (bytes, bytearray)):
+            content = _pieces(content)
+        request = build_request(self._httpx, prepared, content)
+        auth = self._pin.auth(prepared, self._httpx.USE_CLIENT_DEFAULT)
+        try:
+            response = await self.client.send(
+                request, stream=True, follow_redirects=False, auth=auth
+            )
+        except Exception as error:
+            raise failure(error) from None
+        try:
+            pairs = header_pairs(response)
+        except BaseException:
+            await response.aclose()
+            raise
+        body = read_already(response)
+        result = AsyncHTTPResponse(
+            response.status_code,
+            response.reason_phrase,
+            pairs,
+            requested_url(request),
+            body if body is not None else _Body(self, response),
+            decode=prepared.decode and body is None,
+        )
+        return result if stream else await result.buffered()

pathapi_httpx/_common.py

@@ -0,0 +1,185 @@
+"""What the synchronous and the asynchronous transport share: the request as
+`httpx` is given it, the reply as `pathapi.http` is given it, and the errors."""
+
+from __future__ import annotations
+
+import errno as _errno
+import ssl as _ssl
+import urllib.parse as _urlparse
+
+from pathapi.http import PreparedRequest
+
+CHUNK = 64 * 1024
+"""Most bytes of a request body read in one call."""
+
+MAX_HEADERS = 100
+"""Most header fields of a reply a transport accepts, as the built-in one."""
+
+_DEFAULT_PORTS = {"http": 80, "https": 443}
+
+
+def import_httpx():
+    try:
+        import httpx
+    except ImportError as error:
+        raise ImportError(
+            "httpx could not be imported; reinstall pathapi-httpx", name="httpx"
+        ) from error
+    return httpx
+
+
+def origin(url: str) -> "tuple[str, str, int | None]":
+    """The scheme, host and port a URL names."""
+    parts = _urlparse.urlsplit(url)
+    scheme = parts.scheme.lower()
+    try:
+        port = parts.port
+    except ValueError:
+        port = -1
+    return scheme, (parts.hostname or "").lower(), port or _DEFAULT_PORTS.get(scheme)
+
+
+class OnlyThis:
+    """Authentication that adds nothing of its own. A client's `auth` belongs to
+    the server of the first request; a request to any other carries the
+    `Authorization` it was given or none."""
+
+    def __init__(self, authorization: "str | None"):
+        self._authorization = authorization
+
+    def __call__(self, request):
+        request.headers.pop("Authorization", None)
+        if self._authorization is not None:
+            request.headers["Authorization"] = self._authorization
+        return request
+
+
+class Pin:
+    """The origin of the first request a transport sends."""
+
+    def __init__(self) -> None:
+        self._origin: "tuple | None" = None
+
+    def auth(self, prepared: PreparedRequest, default):
+        """`default` (the client's own `auth`) for the first server; for any
+        other, an object that sends only the `Authorization` of the request."""
+        here = origin(prepared.url)
+        if self._origin is None:
+            self._origin = here
+        if self._origin == here:
+            return default
+        given = next(
+            (v for k, v in prepared.headers.items() if k.lower() == "authorization"),
+            None,
+        )
+        return OnlyThis(given)
+
+
+def build_request(httpx, prepared: PreparedRequest, content):
+    """The `httpx.Request` for `prepared`: exactly its headers, none of a
+    client's defaults, with its `(connect, read)` timeout."""
+    connect, read = prepared.timeout
+    timeout = httpx.Timeout(connect=connect, read=read, write=read, pool=connect)
+    try:
+        return httpx.Request(
+            prepared.method,
+            prepared.url,
+            headers=prepared.headers,
+            content=content,
+            extensions={"timeout": timeout.as_dict()},
+        )
+    except httpx.InvalidURL:
+        raise ValueError("the request URL is not valid") from None
+
+
+_OWNED: "dict[type, type]" = {}
+
+
+def owned_client(base: type) -> type:
+    """`base` (`httpx.Client` or `httpx.AsyncClient`) as a client that does not
+    read the `Location` of a redirect it will not follow: `httpx` otherwise
+    fails a reply whose `Location` it cannot parse, where the caller of a
+    transport is to be given that reply."""
+    made = _OWNED.get(base)
+    if made is None:
+
+        class Client(base):  # type: ignore[valid-type, misc]
+            def _build_redirect_request(self, request, response):
+                return request
+
+        made = _OWNED[base] = Client
+    return made
+
+
+def requested_url(request) -> str:
+    """The URL a request went to, as `HTTPResponse.url` states it: no fragment,
+    `/` for an empty path."""
+    url = request.url
+    return f"{url.scheme}://{url.netloc.decode('ascii')}{url.raw_path.decode('ascii')}"
+
+
+def read_already(response) -> "bytes | None":
+    """The body of a response that `httpx` has read whole and decoded (one a
+    mounted `httpx.MockTransport` made), else `None`."""
+    return response.content if response.is_stream_consumed else None
+
+
+def header_pairs(response) -> "list[tuple[str, str]]":
+    """The headers of `response` as received, a name sent twice as two pairs;
+    more than `MAX_HEADERS` of them are `OSError(EIO)`."""
+    if len(response.headers.raw) > MAX_HEADERS:
+        raise OSError(_errno.EIO, f"the response has more than {MAX_HEADERS} headers")
+    return [
+        (name.decode("latin-1"), value.decode("latin-1"))
+        for name, value in response.headers.raw
+    ]
+
+
+def _find(error: BaseException, kind: type) -> "BaseException | None":
+    """An exception of `kind` among the causes of `error`."""
+    pending, seen = [error], set()
+    while pending:
+        current = pending.pop()
+        if id(current) in seen:
+            continue
+        seen.add(id(current))
+        if isinstance(current, kind):
+            return current
+        pending.extend(
+            nxt
+            for nxt in (current.__cause__, current.__context__, *current.args)
+            if isinstance(nxt, BaseException)
+        )
+    return None
+
+
+def failure(error: BaseException) -> BaseException:
+    """`error`, raised by `httpx` or by what it reads, as the exception a
+    transport raises: `TimeoutError`, `ConnectionError`, `ssl.SSLError`,
+    `ValueError` or `OSError(EIO)`. What `httpx` says, which can quote a URL,
+    is not passed on."""
+    httpx = import_httpx()
+    if isinstance(error, httpx.TimeoutException):
+        return TimeoutError(_errno.ETIMEDOUT, "the request timed out")
+    sslerror = _find(error, _ssl.SSLError)
+    if sslerror is not None:
+        return sslerror
+    if isinstance(error, httpx.RemoteProtocolError) and str(error).startswith(
+        "Server disconnected"
+    ):
+        return ConnectionError("the server closed the connection without a reply")
+    if isinstance(error, httpx.ProtocolError):
+        return OSError(_errno.EIO, "the response is not valid HTTP")
+    if isinstance(error, (httpx.NetworkError, httpx.ProxyError)):
+        return ConnectionError(f"connection failed ({type(error).__name__})")
+    if isinstance(error, httpx.InvalidURL):
+        # The URLs of a request were checked, so this is the `Location` of a
+        # reply, read by a client that was given to the transport.
+        return OSError(_errno.EIO, "the redirect of the reply names no usable URL")
+    if isinstance(error, httpx.UnsupportedProtocol):
+        return ValueError(f"the request is not valid ({type(error).__name__})")
+    if isinstance(error, (OSError, ValueError, TypeError)) and (
+        type(error).__module__ == "builtins"
+    ):
+        return error
+    return OSError(_errno.EIO, f"request failed ({type(error).__name__})")

pathapi_httpx/_sync.py

@@ -0,0 +1,134 @@
+"""`httpx.Client` as an HTTP transport for `pathapi.http`."""
+
+from __future__ import annotations
+
+import typing as _ty
+import weakref as _weakref
+
+from pathapi.http import HTTPResponse, prepare_request
+
+from ._common import (
+    CHUNK,
+    Pin,
+    build_request,
+    failure,
+    header_pairs,
+    import_httpx,
+    owned_client,
+    read_already,
+    requested_url,
+)
+
+
+class _Body:
+    """The raw (still encoded) body of an `httpx` response."""
+
+    def __init__(self, owner, response):
+        # The transport stays alive while its reply is open: collecting it
+        # would close the client the reply is reading from.
+        self._owner = owner
+        self._response = response
+        self._chunks = response.iter_raw()
+
+    def read(self, amount: int) -> bytes:
+        try:
+            return next(self._chunks, b"")
+        except Exception as error:
+            raise failure(error) from None
+
+    def close(self) -> None:
+        self._chunks.close()
+        self._response.close()
+
+
+class HttpxTransport:
+    """Sends requests with an `httpx.Client`.
+
+    `client` is the client to use (the caller's: `close()` leaves it open), or
+    `None` for a new one built from `client_args` (`verify`, `cert`, `http2`,
+    `proxy`, `mounts`, `limits`, `trust_env`, `auth`, ...) that `close()`
+    closes. `client_args` with a `client` is `TypeError`.
+
+    The transport sends one request and follows no redirect, whatever the
+    client says. It sends exactly the headers it is given: the default headers
+    and the cookies of a client are not added. The client's `auth` is used for
+    the server of the first request only; a request to any other server
+    carries just the `Authorization` it was given.
+
+    Failures are `TimeoutError`, `ConnectionError`, `ssl.SSLError`,
+    `ValueError` or `OSError(EIO)`; what `httpx` says is never passed on."""
+
+    def __init__(self, client: "_ty.Any" = None, **client_args):
+        httpx = self._httpx = import_httpx()
+        if client is not None:
+            if client_args:
+                raise TypeError(
+                    "client arguments apply to a client the transport makes"
+                )
+            if not callable(getattr(client, "send", None)):
+                raise TypeError("a client is an object with a send() method")
+        self._owns_client = client is None
+        if client is None:
+            client = owned_client(httpx.Client)(
+                **{**client_args, "follow_redirects": False}
+            )
+            # Without a finalizer a client that is dropped leaves its sockets
+            # to the garbage collector.
+            self._finalizer = _weakref.finalize(self, client.close)
+        self.client = client
+        self._pin = Pin()
+
+    def __repr__(self) -> str:
+        return "HttpxTransport()"
+
+    def __enter__(self) -> "HttpxTransport":
+        return self
+
+    def __exit__(self, *exc_info) -> None:
+        self.close()
+
+    def close(self) -> None:
+        """Closes the client if this transport made it, and does so when the
+        transport is collected without having been closed. Harmless when
+        called again."""
+        if self._owns_client:
+            self._finalizer.detach()
+            self.client.close()
+
+    def send(
+        self,
+        method: str,
+        url: str,
+        *,
+        headers: "_ty.Mapping[str, str]",
+        body: "bytes | _ty.BinaryIO | _ty.Iterable[bytes] | None" = None,
+        timeout: "float | tuple | None",
+        stream: bool = False,
+    ) -> HTTPResponse:
+        """One request, one response, as `HTTPTransport.send()`."""
+        prepared = prepare_request(
+            method, url, headers=headers, body=body, timeout=timeout
+        )
+        request = build_request(self._httpx, prepared, prepared.body)
+        auth = self._pin.auth(prepared, self._httpx.USE_CLIENT_DEFAULT)
+        try:
+            response = self.client.send(
+                request, stream=True, follow_redirects=False, auth=auth
+            )
+        except Exception as error:
+            raise failure(error) from None
+        try:
+            pairs = header_pairs(response)
+        except BaseException:
+            response.close()
+            raise
+        body = read_already(response)
+        result = HTTPResponse(
+            response.status_code,
+            response.reason_phrase,
+            pairs,
+            requested_url(request),
+            body if body is not None else _Body(self, response),
+            decode=prepared.decode and body is None,
+        )
+        return result if stream else result.buffered()

pathapi_httpx/_version.py

@@ -0,0 +1,11 @@
+"""The version of the installed distribution."""
+
+from __future__ import annotations
+
+from importlib import metadata as _metadata
+
+try:
+    __version__ = _metadata.version("pathapi-httpx")
+except _metadata.PackageNotFoundError:
+    # Run from a source tree that was never installed.
+    __version__ = "0+unknown"

pathapi_httpx-0.1.0.dist-info/METADATA

@@ -0,0 +1,172 @@
+Metadata-Version: 2.5
+Name: pathapi-httpx
+Version: 0.1.0
+Summary: The httpx HTTP transports for pathapi: a synchronous one and a native async one, with HTTP/2, your own httpx client and its mounts
+Project-URL: Homepage, https://github.com/jose-pr/pathapi-httpx/
+Project-URL: Documentation, https://jose-pr.github.io/pathapi-httpx/
+Project-URL: Issues, https://github.com/jose-pr/pathapi-httpx/issues
+Author: Jose A
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+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: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx<0.29,>=0.28.0
+Requires-Dist: pathapi<0.2,>=0.1.2
+Provides-Extra: dev
+Requires-Dist: black; extra == 'dev'
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: cryptography; extra == 'dev'
+Requires-Dist: hatchling; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs; extra == 'docs'
+Requires-Dist: mkdocs-material; extra == 'docs'
+Requires-Dist: mkdocstrings[python]; extra == 'docs'
+Description-Content-Type: text/markdown
+
+# pathapi-httpx
+
+[![Version](https://img.shields.io/pypi/v/pathapi-httpx.svg)](https://pypi.org/project/pathapi-httpx/)
+[![Python versions](https://img.shields.io/pypi/pyversions/pathapi-httpx.svg)](https://pypi.org/project/pathapi-httpx/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/jose-pr/pathapi-httpx/blob/main/LICENSE)
+[![Docs](https://img.shields.io/badge/docs-latest-blue.svg)](https://jose-pr.github.io/pathapi-httpx/)
+[![CI](https://img.shields.io/github/actions/workflow/status/jose-pr/pathapi-httpx/test.yml)](https://github.com/jose-pr/pathapi-httpx/actions/workflows/test.yml)
+
+**The `httpx` HTTP transports for [`pathapi`](https://github.com/jose-pr/pathapi).**
+`pathapi.http` sends requests with a transport built on the standard library,
+and from an event loop with that transport on worker threads. Install this
+distribution and `HTTPClient` sends through an `httpx.Client`, and
+`AsyncHTTPClient` through an `httpx.AsyncClient` on the caller's loop, with
+nothing to configure. It is documented at
+<https://jose-pr.github.io/pathapi-httpx/>.
+
+## Features
+
+| You want | Built-in transports | These transports |
+| --- | --- | --- |
+| Requests from an event loop without a worker thread per request | No: `ThreadedTransport` runs the standard-library transport on threads | Yes: `AsyncHttpxTransport` |
+| HTTP/2 | No | Yes: `HttpxTransport(http2=True)` with `httpx[http2]` |
+| Your own `httpx.Client` or `httpx.AsyncClient`: mounted transports, limits, proxies, `auth` | No | Yes: `HttpxTransport(client)` |
+| `SSL_CERT_FILE`, `SSL_CERT_DIR` and the certifi bundle | The system trust store, or an `ssl_context=` | Yes |
+| Proxies from the environment, `proxy=` and `mounts=` | `http://` proxies through a provider | Yes, as `httpx` does them |
+
+- **Credentials belong to one server.** The `auth` of a client is sent to the
+  server of the first request and to no other, and the clients of `pathapi.http`
+  never take an `Authorization` header to another server on a redirect.
+- **Exactly the headers it is given.** A client's default headers and cookies
+  are not added: `HTTPClient` and `AsyncHTTPClient` own the headers of a request.
+- **No third-party text in an error.** A failure of `httpx` is a
+  `TimeoutError`, `ConnectionError`, `ssl.SSLError`, `ValueError` or
+  `OSError(EIO)`; what the library says, which can quote a URL, is never passed on.
+- **The same promises as the built-in transports.** The tests `pathapi` runs
+  over its own transports run over these
+  (`python -m pathapi.http.testing --http-transports httpx --http-async-transports httpx`).
+
+## Installation
+
+```bash
+pip install pathapi-httpx
+```
+
+Requires `pathapi` and `httpx`, which pip installs with it. HTTP/2 needs
+`pip install "httpx[http2]"`.
+
+## Quick start
+
+**Send through an `httpx.Client` from threads or a script:**
+
+```python
+import httpx
+from pathapi.http import HTTPClient
+from pathapi_httpx import HttpxTransport
+
+with httpx.Client() as session:
+    with HTTPClient(HttpxTransport(session), timeout=(3, 30)) as client:
+        reply = client.request("GET", "http://files.example.org/reports/today.txt")
+        print(reply.read().decode())
+```
+
+The `httpx.Client` stays yours: neither the client nor the transport closes it.
+
+**Send from an event loop** with `httpx.AsyncClient` on that loop:
+
+```python
+import asyncio
+
+from pathapi.http import AsyncHTTPClient
+from pathapi_httpx import AsyncHttpxTransport
+
+
+async def main():
+    async with AsyncHttpxTransport() as transport:
+        async with AsyncHTTPClient(transport) as client:
+            replies = await asyncio.gather(
+                *(
+                    client.request("GET", f"http://files.example.org/reports/{day}.txt")
+                    for day in ("mon", "tue", "wed")
+                )
+            )
+            print([len(await reply.read()) for reply in replies])
+
+
+asyncio.run(main())
+```
+
+**Choose them for the whole process.** `PATHAPI_HTTP_TRANSPORT=httpx` and
+`PATHAPI_HTTP_ASYNC_TRANSPORT=httpx` make every `HTTPClient` and
+`AsyncHTTPClient` that was given no transport send through a new `httpx` client:
+
+```bash
+PATHAPI_HTTP_ASYNC_TRANSPORT=httpx python -c "from pathapi.http import AsyncHTTPClient; print(type(AsyncHTTPClient().transport))"
+```
+
+## API overview
+
+| Name | Purpose |
+| --- | --- |
+| `pathapi_httpx.HttpxTransport` | The transport: `send()` and `close()` over an `httpx.Client` |
+| `pathapi_httpx.AsyncHttpxTransport` | The async transport: `await send()` and `await aclose()` over an `httpx.AsyncClient` |
+| `pathapi_httpx.__version__` | The installed version |
+
+`pathapi.http` finds the classes through the `httpx` entries of its
+`pathapi.http_transports` and `pathapi.http_async_transports` entry-point
+groups, which this distribution declares. The reference is in the
+[API header](https://github.com/jose-pr/pathapi-httpx/blob/main/src/pathapi_httpx/AGENTS.md)
+that ships with the package.
+
+## Development
+
+```bash
+python -m venv .venv/3.14-posix-x86_64
+.venv/3.14-posix-x86_64/bin/python -m pip install -e ".[dev]"
+.venv/3.14-posix-x86_64/bin/python -m pytest -q -rs
+```
+
+`pathapi` 0.1.2 is a dependency; while it is not on PyPI, install it
+editable from its checkout first (`pip install -e ../pathapi`). The test run
+includes `python -m pathapi.http.testing --http-transports httpx
+--http-async-transports httpx`, the tests `pathapi` runs over its own transports.
+
+### Releasing
+
+This project follows [Semantic Versioning](https://semver.org/) and keeps a
+[`CHANGELOG.md`](CHANGELOG.md). Pushing a tag matching `v*` triggers the release
+workflow: test gate → build (checking the tag names the version built) → a strict
+docs build as a gate → GitHub release → publish. The release workflow never deploys
+the docs site itself: for a final release its last job dispatches the docs workflow
+at the tag, which owns every Pages deploy.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

pathapi_httpx-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+pathapi_httpx/AGENTS.md,sha256=HmST-TIoLPJUOPYzyzC9h9XnTwHzDjkIy-KNw1P_HNg,7776
+pathapi_httpx/__init__.py,sha256=GF0RZ2y2elC7KH0nvTUHZ5mfrIMjABr46Fc1jjNyHxI,741
+pathapi_httpx/_async.py,sha256=qYi2XEX4WTd9qR05qt6fZM8es_9vQ8A5qdh3Xw8X3Xc,5343
+pathapi_httpx/_common.py,sha256=vv8d4ODpJxPF1DcNwM-vfdneJTHdwnJnjEdCTg6ZtkQ,6720
+pathapi_httpx/_sync.py,sha256=U2M00gKZ-JfifhEHalEjApyG5aiMy17DMg81zsLSnzY,4575
+pathapi_httpx/_version.py,sha256=aWKSxVVOyk2ibF6fkEoqxrlXknS5XsPECa6LfsKQqDs,313
+pathapi_httpx/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pathapi_httpx/README.md,sha256=3BtWXywk7tfjHBcJ_n1h6gta4NrMtwCme4kSGVoR0ok,5934
+pathapi_httpx-0.1.0.dist-info/METADATA,sha256=QZSQK6R7KK3GW4fVHpyR9_7shyj-osihgbbiB4pE4mc,7457
+pathapi_httpx-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+pathapi_httpx-0.1.0.dist-info/entry_points.txt,sha256=cNbQg2CRSj4UxSazq5nrISnut9ji4qfWCE3Ys_B0C9Y,138
+pathapi_httpx-0.1.0.dist-info/licenses/LICENSE,sha256=bBY0SeXglEP0yGEOZbyqRTbNfXD0DVpkr-3mBq7-BPQ,1063
+pathapi_httpx-0.1.0.dist-info/RECORD,,

pathapi_httpx-0.1.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

pathapi_httpx-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,5 @@
+[pathapi.http_async_transports]
+httpx = pathapi_httpx:AsyncHttpxTransport
+
+[pathapi.http_transports]
+httpx = pathapi_httpx:HttpxTransport

pathapi_httpx-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Jose A
+
+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.