pathapi-requests

The requests HTTP transport for pathapi. pathapi.http sends requests with a transport built on the standard library; install this distribution and the same HTTPClient sends through a requests.Session instead, with nothing to configure. It is for what the built-in transport does not do, and it is documented at https://jose-pr.github.io/pathapi-requests/.

Features

• Credentials belong to one server. What the session holds for authentication is sent to the server of the first request and to no other, and HTTPClient never takes an Authorization header to another server on a redirect.
• No third-party text in an error. A failure of requests is a TimeoutError, ConnectionError, ssl.SSLError, ValueError or OSError(EIO); what the library says, which can quote a proxy URL with credentials, is never passed on.
• The same promises as the built-in transport. The tests pathapi runs over its own transport run over this one (python -m pathapi.http.testing --http-transports requests).

The URI paths of uripath use it too: with this distribution installed, with_session() and PATHAPI_HTTP_TRANSPORT=requests send through it.

Installation

pip install pathapi-requests

Requires pathapi and requests, which pip installs with it.

Quick start

Send through your own session. Hand the transport to an HTTPClient:

import requests
from pathapi.http import HTTPClient
from pathapi_requests import RequestsTransport

with requests.Session() as session:
    session.headers["X-Team"] = "storage"
    client = HTTPClient(RequestsTransport(session), timeout=(3, 30))
    reply = client.request("GET", "http://files.example.org/reports/today.txt")
    print(reply.read().decode())

The session stays yours: neither the client nor the transport closes it.

Choose it for the whole process. PATHAPI_HTTP_TRANSPORT=requests makes every HTTPClient that was given no transport send through a new session:

PATHAPI_HTTP_TRANSPORT=requests python -c "from pathapi.http import HTTPClient; print(type(HTTPClient().transport))"

Pick a proxy per URL. proxies is indexed with the request URL and answers a proxy, or None for no proxy; KeyError leaves it to requests:

from pathapi_requests import RequestsTransport


class ByHost:
    def __getitem__(self, url):
        if "internal.example.org" in url:
            return None  # direct
        if url.startswith("https://"):
            return "socks5h://gateway.example.org:1080"
        raise KeyError(url)  # what requests would have done


transport = RequestsTransport(proxies=ByHost())

API overview

pathapi.http finds the class through the requests entry of its pathapi.http_transports entry-point group, which this distribution declares. The reference is in the API header that ships with the package.

Development

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 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 requests, the tests pathapi runs over its own transport.

Releasing

This project follows Semantic Versioning and keeps a 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.