Zapros

Appearance

Response Object ​

The Response object represents an HTTP response returned from a request. It provides access to the status code, headers, and response body with both sync and async APIs.

Basic attributes ​

Every response has a status code and headers:

python
from zapros import AsyncClient

async with AsyncClient() as client:
    response = await client.request(
        "GET", "https://httpbin.org/get"
    )

    print(response.status)  # 200
    print(
        response.headers["content-type"]
    )  # "application/json"
python
from zapros import Client

with Client() as client:
    response = client.request(
        "GET", "https://httpbin.org/get"
    )

    print(response.status)  # 200
    print(
        response.headers["content-type"]
    )  # "application/json"
  • status — HTTP status code as an integer (200, 404, etc.)
  • headers — Case-insensitive Headers object containing response headers

Reading the response body ​

As text ​

Use text() or atext() to get the entire response body as a string:

python
async with AsyncClient() as client:
    response = await client.request(
        "GET",
        "https://httpbin.org/html",
    )
    html = await response.atext()
    print(html)
python
with Client() as client:
    response = client.request(
        "GET",
        "https://httpbin.org/html",
    )
    html = response.text()
    print(html)

The text is decoded using the charset specified in the Content-Type header, or UTF-8 if none is specified.

As bytes ​

Use read() or aread() to get the entire response body as bytes:

python
async with AsyncClient() as client:
    response = await client.request(
        "GET",
        "https://httpbin.org/bytes/100",
    )
    data = await response.aread()
    print(len(data))  # 100
python
with Client() as client:
    response = client.request(
        "GET",
        "https://httpbin.org/bytes/100",
    )
    data = response.read()
    print(len(data))  # 100

As JSON ​

Use json() or ajson() to parse the response body as JSON:

python
async with AsyncClient() as client:
    response = await client.request(
        "GET",
        "https://httpbin.org/json",
    )
    data = await response.ajson()
python
with Client() as client:
    response = client.request(
        "GET",
        "https://httpbin.org/json",
    )
    data = response.json()

Character encoding ​

The encoding property returns the charset from the Content-Type header:

python
response.headers[
    "content-type"
]  # "text/html; charset=iso-8859-1"
response.encoding  # "iso-8859-1"

If no charset is specified, it defaults to utf-8.

Streaming responses ​

For large responses, you can stream the body incrementally to avoid loading everything into memory at once.

Streaming decoded bytes ​

Use iter_bytes() or async_iter_bytes() to iterate over decoded chunks:

python
async with AsyncClient() as client:
    response = await client.request(
        "GET",
        "https://httpbin.org/stream-bytes/10000",
    )

    async for chunk in response.async_iter_bytes():
        process(chunk)
python
with Client() as client:
    response = client.request(
        "GET",
        "https://httpbin.org/stream-bytes/10000",
    )

    for chunk in response.iter_bytes():
        process(chunk)

The chunks are automatically decoded (gzip, deflate, brotli) based on the Content-Encoding header.

You can specify a custom chunk size (default is 8192 bytes):

python
for chunk in response.iter_bytes(chunk_size=4096):
    process(chunk)

NOTE

chunk_size re-chunks the stream coming from the handler — it does not control how many bytes are read from the socket. Socket read size is configured on the handler responsible for I/O.

Streaming text ​

Use iter_text() or async_iter_text() to iterate over text chunks:

python
async with AsyncClient() as client:
    response = await client.request(
        "GET",
        "https://httpbin.org/stream/10",
    )

    async for text_chunk in response.async_iter_text():
        print(text_chunk)
python
with Client() as client:
    response = client.request(
        "GET",
        "https://httpbin.org/stream/10",
    )

    for text_chunk in response.iter_text():
        print(text_chunk)

Text chunks are decoded using the response's encoding.

Streaming raw bytes ​

Use iter_raw() or async_iter_raw() to iterate over raw, unencoded bytes:

python
async with AsyncClient() as client:
    response = await client.request(
        "GET",
        "https://httpbin.org/gzip",
    )

    async for raw_chunk in response.async_iter_raw():
        save_compressed(raw_chunk)
python
with Client() as client:
    response = client.request(
        "GET",
        "https://httpbin.org/gzip",
    )

    for raw_chunk in response.iter_raw():
        save_compressed(raw_chunk)

Raw streaming skips content decoding — you get the bytes exactly as received from the server.

Resource management ​

When using client.request(), the response body is fully read and resources are freed before the method returns — no cleanup is required.

When using client.stream(), resources are held open so you can read the body incrementally. Always use it as a context manager to ensure resources are freed:

python
async with AsyncClient() as client:
    async with client.stream(
        "GET",
        "https://httpbin.org/stream/10",
    ) as response:
        async for chunk in response.async_iter_bytes():
            process(chunk)
python
with Client() as client:
    with client.stream(
        "GET",
        "https://httpbin.org/stream/10",
    ) as response:
        for chunk in response.iter_bytes():
            process(chunk)

The context manager calls aclose() or close() automatically when the block exits, even if you break early or an exception is raised. This is also useful when you want to inspect headers before deciding whether to download the full body.