Response¶

The HTTP response object returned by all request methods.

Overview¶

The Response class provides access to all aspects of an HTTP response:

import httpr

response = httpr.get("https://httpbin.org/get")

# Status
print(response.status_code)  # 200

# Body
print(response.text)         # Decoded text
print(response.content)      # Raw bytes
data = response.json()       # Parsed JSON

# Headers (case-insensitive)
print(response.headers["content-type"])
print(response.headers["Content-Type"])  # Same result

# Cookies
print(response.cookies)      # {"session": "value"}

# Metadata
print(response.url)          # Final URL after redirects
print(response.encoding)     # Detected encoding

Properties¶

status_code¶

@property
def status_code(self) -> int

HTTP status code (e.g., 200, 404, 500).

Example:

response = httpr.get("https://httpbin.org/status/201")
print(response.status_code)  # 201

reason_phrase¶

@property
def reason_phrase(self) -> str

Canonical reason phrase for the status code (e.g., "OK", "Not Found").

Example:

response = httpr.get("https://httpbin.org/status/404")
print(response.reason_phrase)  # "Not Found"

Status classification¶

A set of boolean properties for checking the status code class without comparing integers manually:

Property	True when
`is_informational`	1xx status code
`is_success`	2xx status code
`is_redirect`	3xx status code
`is_client_error`	4xx status code
`is_server_error`	5xx status code
`is_error`	4xx or 5xx status code
`has_redirect_location`	3xx response with a `Location` header (301, 302, 303, 307, 308)

Example:

response = httpr.get("https://httpbin.org/status/200")

if response.is_success:
    print("Success!")
elif response.is_client_error:
    print("Client error")
elif response.is_server_error:
    print("Server error")

text¶

@property
def text(self) -> str

Response body decoded as text.

Encoding is automatically detected from:

Content-Type header charset
HTML meta charset tag
Falls back to UTF-8

Example:

response = httpr.get("https://httpbin.org/html")
print(response.text)  # HTML content

content¶

@property
def content(self) -> bytes

Response body as raw bytes.

Example:

response = httpr.get("https://httpbin.org/bytes/100")
print(len(response.content))  # 100

# Save binary file
response = httpr.get("https://httpbin.org/image/png")
with open("image.png", "wb") as f:
    f.write(response.content)

headers¶

@property
def headers(self) -> CaseInsensitiveHeaderMap

Response headers as a case-insensitive dict-like object.

Supports:

response.headers["Content-Type"] - get by key
response.headers.get("content-type", "default") - get with default
"content-type" in response.headers - check existence
response.headers.keys() - all header names
response.headers.values() - all header values
response.headers.items() - key-value pairs

Example:

response = httpr.get("https://httpbin.org/get")

# Case-insensitive access
print(response.headers["content-type"])
print(response.headers["Content-Type"])  # Same

# Iteration
for name, value in response.headers.items():
    print(f"{name}: {value}")

cookies¶

@property
def cookies(self) -> dict[str, str]

Cookies set by the server via Set-Cookie headers.

Example:

response = httpr.get("https://httpbin.org/cookies/set?name=value")
print(response.cookies)  # {"name": "value"}

url¶

@property
def url(self) -> str

Final URL after following any redirects.

Example:

response = httpr.get("https://httpbin.org/redirect/3")
print(response.url)  # https://httpbin.org/get

encoding¶

@property
def encoding(self) -> str

Character encoding detected from response headers or content.

Example:

response = httpr.get("https://httpbin.org/encoding/utf8")
print(response.encoding)  # "utf-8"

text_markdown¶

@property
def text_markdown(self) -> str

HTML response body converted to Markdown format.

Uses Rust's html2text crate for conversion.

Example:

response = httpr.get("https://example.com")
print(response.text_markdown)
# # Example Domain
#
# This domain is for use in illustrative examples...

text_plain¶

@property
def text_plain(self) -> str

HTML response body converted to plain text (no formatting).

Example:

response = httpr.get("https://example.com")
print(response.text_plain)

text_rich¶

@property
def text_rich(self) -> str

HTML response body converted to rich text format.

Methods¶

json¶

def json(self) -> Any

Parse response body as JSON.

Returns: Parsed JSON (dict, list, str, int, float, bool, or None)

Raises: Exception if body is not valid JSON

Example:

response = httpr.get("https://httpbin.org/json")
data = response.json()
print(data["slideshow"]["title"])

Note

json() is a method, not a property. Call it with parentheses.

raise_for_status¶

def raise_for_status(self) -> Response

Raise HTTPStatusError if the response has a non-2xx status code. Returns the response itself on success, so the call can be chained.

Returns: The same Response object (when the status is 2xx)

Raises: HTTPStatusError for any non-2xx status code

Example:

response = httpr.get("https://httpbin.org/status/404")

try:
    response.raise_for_status()
except httpr.HTTPStatusError as exc:
    print(exc)  # Client error '404 Not Found' for url '...'

# Chaining: raise on error, otherwise parse the body
data = httpr.get("https://httpbin.org/json").raise_for_status().json()

Note

Unlike requests, any non-2xx status raises — including 1xx and 3xx responses — matching httpx behavior. With redirects followed (the default), a 3xx is only seen when follow_redirects=False.

StreamingResponse¶

For streaming large responses without buffering the entire response in memory, use the Client.stream() method which returns a StreamingResponse.

import httpr

with httpr.Client() as client:
    with client.stream("GET", "https://httpbin.org/stream-bytes/1000") as response:
        for chunk in response.iter_bytes():
            process(chunk)

Properties¶

status_code¶

@property
def status_code(self) -> int

HTTP status code (e.g., 200, 404, 500).

Example:

with client.stream("GET", "https://httpbin.org/get") as response:
    print(response.status_code)  # 200

Status helpers¶

StreamingResponse exposes the same status API as Response, available immediately after the headers arrive (before the body is read):

reason_phrase — canonical reason phrase for the status code
is_informational, is_success, is_redirect, is_client_error, is_server_error, is_error — status-class booleans
has_redirect_location — 3xx response with a Location header
raise_for_status() — raise HTTPStatusError for a non-2xx status, otherwise return the streaming response itself

Example:

with client.stream("GET", "https://httpbin.org/stream-bytes/1000") as response:
    response.raise_for_status()  # bail out early on a non-2xx status
    for chunk in response.iter_bytes():
        process(chunk)

headers¶

@property
def headers(self) -> CaseInsensitiveHeaderMap

Response headers as a case-insensitive dict-like object.

Example:

with client.stream("GET", "https://httpbin.org/get") as response:
    content_type = response.headers["content-type"]

cookies¶

@property
def cookies(self) -> dict[str, str]

Cookies set by the server via Set-Cookie headers.

url¶

@property
def url(self) -> str

Final URL after following any redirects.

is_closed¶

@property
def is_closed(self) -> bool

Whether the stream has been closed.

Example:

with client.stream("GET", "https://httpbin.org/get") as response:
    print(response.is_closed)  # False
print(response.is_closed)  # True (after context manager exits)

is_consumed¶

@property
def is_consumed(self) -> bool

Whether the stream has been fully consumed.

Example:

with client.stream("GET", "https://httpbin.org/get") as response:
    print(response.is_consumed)  # False
    _ = list(response)  # Consume the stream
    print(response.is_consumed)  # True

Methods¶

iter_bytes¶

def iter_bytes(self) -> Iterator[bytes]

Iterate over the response body as bytes chunks.

Returns: Iterator yielding bytes chunks

Example:

with client.stream("GET", "https://httpbin.org/stream-bytes/1000") as response:
    for chunk in response.iter_bytes():
        print(f"Received {len(chunk)} bytes")

iter_text¶

def iter_text(self) -> TextIterator

Iterate over the response body as text chunks, decoded using the response encoding.

Returns: TextIterator yielding string chunks

Example:

with client.stream("GET", "https://httpbin.org/html") as response:
    for text in response.iter_text():
        print(text, end="")

iter_lines¶

def iter_lines(self) -> LineIterator

Iterate over the response body line by line.

Returns: LineIterator yielding string lines

Useful for Server-Sent Events (SSE) and line-based protocols.

Example:

with client.stream("GET", "https://httpbin.org/stream/10") as response:
    for line in response.iter_lines():
        print(line.strip())

read¶

def read(self) -> bytes

Read the entire remaining response body into memory.

Returns: Response body as bytes

Example:

with client.stream("GET", "https://httpbin.org/get") as response:
    if response.status_code == 200:
        content = response.read()

close¶

def close(self) -> None

Close the stream and release resources.

Note: When using the context manager, close() is called automatically.

Example:

with client.stream("GET", "https://httpbin.org/get") as response:
    # Process headers
    if response.status_code != 200:
        response.close()  # Close early without reading body
        return
    # Otherwise read body
    content = response.read()

Direct Iteration¶

StreamingResponse supports direct iteration, which is equivalent to calling iter_bytes():

with client.stream("GET", "https://httpbin.org/stream-bytes/1000") as response:
    for chunk in response:  # Same as response.iter_bytes()
        process(chunk)

Async Streaming¶

AsyncClient.stream() yields an AsyncStreamingResponse. It exposes the same attributes and methods as StreamingResponse (status, headers, cookies, URL, raise_for_status(), is_closed, is_consumed, the synchronous iter_*(), read() and close()), plus async variants that read each chunk on the client's thread pool so the event loop is never blocked:

aiter_bytes¶

def aiter_bytes(self) -> AsyncIterator[bytes]

Iterate over the response body as bytes chunks. async for chunk in response is equivalent.

aiter_text¶

def aiter_text(self) -> AsyncIterator[str]

Iterate over the response body as text chunks, decoded with the response's encoding.

aiter_lines¶

def aiter_lines(self) -> AsyncIterator[str]

Iterate over the response body line by line (lines include their trailing newline).

aread¶

async def aread(self) -> bytes

Read the entire remaining body into memory.

aclose¶

async def aclose(self) -> None

Close the stream and release its connection. Called automatically when the async with block exits.

Example:

async with httpr.AsyncClient() as client:
    async with client.stream("GET", "https://example.com/events") as response:
        async for line in response.aiter_lines():
            handle(line)

The synchronous iter_bytes(), iter_text(), iter_lines() and read() remain available on the async response but block the event loop until the next chunk arrives; prefer the a-prefixed methods in async code. A stream that is open when client.aclose() is called keeps its connection and can still be read to the end.

Important Notes¶

Always use as context manager: Ensures proper cleanup of resources
Headers available immediately: Status code, headers, cookies, and URL are accessible before reading the body
Body only read on demand: The response body is only fetched when you iterate or call read()
Cannot re-read: Once consumed, the stream cannot be read again
Supported for all methods: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS

Exception Handling¶

The streaming response raises specific exceptions:

StreamClosed: Raised when attempting to read from a closed stream
StreamConsumed: Raised when attempting to re-read a consumed stream

Example:

import httpr

with client.stream("GET", "https://httpbin.org/get") as response:
    content = response.read()

    # This will raise StreamConsumed
    try:
        more = response.read()
    except httpr.StreamConsumed:
        print("Stream already consumed")