Zapros

Appearance

Configuration ​

Zapros is designed to be highly extensible and configurable. This page covers the main configuration options and how to use them.

Handlers ​

The primary configuration point for the client is the handler parameter. Handlers are responsible for making the actual HTTP requests and must implement the AsyncBaseHandler interface (BaseHandler for sync clients).

Built-in Handlers ​

Zapros ships three built-in transport handlers:

HandlerDescription
AsyncStdNetworkHandler / StdNetworkHandlerDefault handler. Uses the standard library. Supported in all environments.
AsyncPyodideHandler / PyodideHandlerFor Pyodide environments. Uses the browser's fetch API.
AsyncPyrequestsHandler / PyrequestsHandler (Experimental)Uses the Rust-based pyrequests library. Supports advanced features not available in the standard library handler.

To pass a handler explicitly:

python
from zapros import (
    AsyncClient,
    AsyncStdNetworkHandler,
)

async with AsyncClient(
    handler=AsyncStdNetworkHandler()
) as client:
    response = await client.request(
        "GET",
        "https://api.example.com/data",
    )
python
from zapros import (
    Client,
    StdNetworkHandler,
)

with Client(handler=StdNetworkHandler()) as client:
    response = client.request(
        "GET",
        "https://api.example.com/data",
    )

Middleware Handlers ​

In addition to transport handlers, Zapros includes middleware handlers — handlers that wrap another handler to add functionality. They implement the AsyncBaseMiddleware interface (BaseMiddleware for sync clients) and follow the chain of responsibility pattern.

python
from zapros import (
    AsyncClient,
    RetryHandler,
    AsyncStdNetworkHandler,
)

async with AsyncClient(
    handler=RetryHandler(
        AsyncStdNetworkHandler(),
        max_attempts=3,
    )
) as client:
    response = await client.request(
        "GET",
        "https://api.example.com/data",
    )
python
from zapros import (
    Client,
    RetryHandler,
    StdNetworkHandler,
)

with Client(
    handler=RetryHandler(
        StdNetworkHandler(),
        max_attempts=3,
    )
) as client:
    response = client.request(
        "GET",
        "https://api.example.com/data",
    )

Chaining Handlers ​

Multiple middleware handlers can be composed into a chain. For long chains, deeply nested constructors can become hard to read — use wrap_with_middleware for a more readable alternative:

python
from zapros import (
    CachingHandler,
    RetryHandler,
    RedirectHandler,
    CookieHandler,
    Client,
    StdNetworkHandler,
)

handler = (
    RetryHandler(
        StdNetworkHandler(),
        max_attempts=3,
        backoff_factor=0.1,
    )
    .wrap_with_middleware(
        lambda next: RedirectHandler(next)
    )
    .wrap_with_middleware(lambda next: CookieHandler(next))
    .wrap_with_middleware(lambda next: CachingHandler(next))
)

with Client(handler) as client:
    ...

You can also implement your own middleware handlers — just ensure they satisfy the AsyncBaseMiddleware (BaseMiddleware for sync) interface.

Default Headers ​

Pass default_headers to attach headers to every request made by the client. Headers passed directly to the request override any matching default headers:

python
from zapros import AsyncClient

async with AsyncClient(
    default_headers={"User-Agent": "MyCustomClient/1.0"}
) as client:
    response = await client.request(
        "GET",
        "https://api.example.com/data",
    )
python
from zapros import Client

with Client(
    default_headers={"User-Agent": "MyCustomClient/1.0"}
) as client:
    response = client.request(
        "GET",
        "https://api.example.com/data",
    )

Default Parameters ​

Pass default_params to append query parameters to every request made by the client. When the same key appears in multiple places, the following priority applies (highest to lowest):

  1. params passed directly to the request
  2. Query parameters embedded in the URL string
  3. default_params on the client
python
from zapros import AsyncClient

async with AsyncClient(
    default_params={"api_key": "my_api_key"}
) as client:
    response = await client.request(
        "GET",
        "https://api.example.com/data",
    )
python
from zapros import Client

with Client(
    default_params={"api_key": "my_api_key"}
) as client:
    response = client.request(
        "GET",
        "https://api.example.com/data",
    )

Authentication ​

Pass auth to the client to authenticate every request. Auth passed directly to the request takes priority over the client-level auth:

python
from zapros import AsyncClient

async with AsyncClient(
    auth=("username", "password")
) as client:
    response = await client.request(
        "GET",
        "https://api.example.com/data",
    )
python
from zapros import Client

with Client(auth=("username", "password")) as client:
    response = client.request(
        "GET",
        "https://api.example.com/data",
    )

For more advanced authentication schemes such as Digest or token-based auth, see Authentication.