API reference

APIClient class

The APIClient class extends requests’ requests.Session, requiring you to provide a base_url.

class ape_pie.APIClient(base_url: str, request_kwargs: dict[str, Any] | None = None, **kwargs: Any)

A client instance, pinning a requests.Session to a particular base URL.

You can use the usual requests API, e.g. client.post("some-url") after instantiating a client instance. Whenever you use a relative URL, it will be appended to the base_url.

The client prevents making requests to a different base/root than the configured base URL, so you don’t accidentally leak session-wide credentials to places they were not intended to go.

Parameters:

• base_url – The base URL of the API/service you intend to consume. Relative URLs in requests will be joined against this, while absolute/fully qualified URLs will be validated against the base URL.

• request_kwargs – a mapping of keyword arguments you would typically pass to requests.Session.request() or set on the session after instantiating it. They act as session-wide defaults which can be overridden on a per-request basis.

• kwargs – any additional keyword arguments are simply ignored, but you may want to consume them if you’re defining more specific client classes for your own needs.

request(method: str | bytes, url: str | bytes, *args, **kwargs) → Response

Pre-process a request before calling the parent method.

See the upstream requests.Session.request() documentation for the API reference.

Configuration adapters

Configuration adapters need to be implemented by your project, so that a client instance can be configured from your configuration source. It essentially acts as a translation from your domain-specific configuration to ape_pie.APIClient arguments.

Configuration adapters must implement our protocol:

class ape_pie.ConfigAdapter(*args, **kwargs)

get_client_base_url() → str

Return the API root/base URL to which relative URLs are made.

get_client_session_kwargs() → dict[str, Any]

Return kwargs to feed to requests.Session when using the client.

Provide a dict of possible requests.Session attributes which will (typically) be used as defaults for each request sent from the session, such as auth for authentication or cert and/or verify for mutual TLS purposes. Other examples would be a timeout that’s service-specific (and potentially different from the global default).

Note that many of these kwargs can still be overridden at call time, e.g.:

with APIClient.configure_from(some_service) as client:
    response = client.get("some/relative/path", timeout=10)