Zapros

Cassette interactions are matched based on the method and the normalized URL.

• Query Parameters: These are sorted before matching, so ?a=1&b=2 matches ?b=2&a=1.
• Exclusions: Headers and request bodies are not part of the match key by default.

Matchers are objects used to inspect HTTP requests (checking methods, paths, headers, etc.) and return True if the request meets specific criteria. They are primarily used by the mocking system and cassette modifiers.

All matchers implement the Matcher protocol, which requires a match(request: Request) -> bool method. You can also implement your own custom matchers by following this protocol.

from zapros.matchers import Matcher

class MyCustomMatcher(Matcher):
    def match(self, request: Request) -> bool:
        # logic to return True or False
        return True

Middleware handlers wrap a transport handler to add functionality (like retries, caching, or cookie management). They follow the chain of responsibility pattern and must implement the AsyncBaseMiddleware (for async clients) or BaseMiddleware (for sync clients) interface.

To use middleware, wrap your transport handler with the desired middleware class and pass the resulting object to the handler parameter of the client.

from zapros import (
    AsyncClient,
    RetryMiddleware,
    AsyncStdNetworkHandler,
)

async with AsyncClient(
    handler=RetryMiddleware(
        AsyncStdNetworkHandler(),
        max_attempts=3,
    )
) as client:
    response = await client.get(
        "https://api.example.com/data",
    )

Zapros uses a chain of middleware handlers that wrap each other, ending in a single transport handler that performs the actual I/O (e.g., network calls, ASGI app calls, or browser fetch()).

Every request flows through this chain: Client ──► Middleware A ──► Middleware B ──► Transport handler ──► network / ASGI app / fetch()

Extending Zapros typically involves writing a middleware to intercept requests or responses. The client manages the lifecycle of the chain; calling client.aclose() or exiting a context manager will automatically walk the chain and call aclose() (or close()) on every handler and middleware in the sequence.

# Conceptual flow
Client ──► Middleware A ──► Middleware B ──► Transport handler ──► network

If you use AsyncStdNetworkHandler within a Trio event loop, it will automatically default to using TrioTransport instead of AsyncIOTransport. You can also explicitly specify TrioTransport in the handler configuration.

from zapros import AsyncClient, AsyncStdNetworkHandler, TrioTransport

async with AsyncClient(
    handler=AsyncStdNetworkHandler(transport=TrioTransport())
) as client:
    ...

Zapros uses a Sans-IO architecture that separates HTTP semantics from Transport.

• HTTP Semantics: Handled by AsyncClient and Client. This includes constructing requests, managing headers, decoding Content-Encoding, and encoding body formats (JSON, form, multipart).
• Transport: Handled by a separate handler. The handler is responsible for DNS, TCP, TLS, connection pooling, and wire protocols (HTTP/1.1, HTTP/2, HTTP/3).

This separation allows you to use powerful plugins (caching, retries, mocking, cassettes) regardless of the low-level transport implementation, and enables you to swap handlers without changing your client code.

Zapros abstracts the transport layer and provides several specialized handlers to support different environments and performance requirements:

• ASGI Handler: Similar to HTTPX, for interacting with ASGI applications.
• AsyncPyodideHandler: For running the same code in the browser via WASM.
• AsyncPyreqwestHandler: Built on Rust's reqwest library for high-performance requirements.
• WebSocket Client: Built on the wsproto library. The WebSocket handshake uses your standard client, meaning authentication, cookies, retries, and custom handlers apply to WebSocket connections.