API Reference¶

`chumicro_requests` ¶

Non-blocking HTTP/1.1 client for CircuitPython, MicroPython, and CPython.

`CaseInsensitiveDict` ¶

Header dict whose lookups fold to lowercase.

`get(name, default=None)` ¶

Return the value for name or default if missing.

`items()` ¶

Yield (original_name, value) pairs in insertion order.

`add(name, value)` ¶

Append value to the existing header, joining with ,.

`HttpBusyError` ¶

Bases: HttpError

Caller issued a request while another was still in flight.

`HttpError` ¶

Bases: Exception

Base class for every chumicro-requests failure.

`HttpOversizedError` ¶

Bases: HttpError

Response body exceeded max_body_bytes.

`HttpProtocolError` ¶

Bases: HttpError

Server sent bytes the spec doesn't allow.

`HttpTimeoutError` ¶

Bases: HttpError

Per-request timeout_ms budget elapsed before the response completed.

`HttpURLError` ¶

Bases: HttpError

URL doesn't parse as a supported HTTP/HTTPS URL.

`ParseState` ¶

Streaming response parser states.

`ResponseParser` ¶

Streaming HTTP/1.1 response parser.

`body` `property` ¶

Body bytes received so far (final once :attr:state is DONE).

`init(*, max_body_bytes=DEFAULT_MAX_BODY_BYTES, max_header_bytes=DEFAULT_MAX_HEADER_BYTES, body_buffer=None, body_buffer_view=None, stream_body=False)` ¶

Construct the parser.

Parameters:

Name	Type	Description	Default
`max_body_bytes`	`int`	Cap on the buffered body size; ignored when stream_body is set.	`DEFAULT_MAX_BODY_BYTES`
`max_header_bytes`	`int`	Cap on status-line and header bytes staged before the body.	`DEFAULT_MAX_HEADER_BYTES`
`body_buffer`	`bytearray \| None`	Optional caller-owned `bytearray` reused as the body buffer.	`None`
`body_buffer_view`	`memoryview \| None`	Pre-cached `memoryview(body_buffer)`; required with body_buffer.	`None`
`stream_body`	`bool`	When `True`, stage the body in a fixed window instead of buffering whole.	`False`

`body_free()` ¶

Writable staging space in the streamed-body window, in bytes.

`read_body_into(buffer)` ¶

Copy staged body bytes into caller-owned buffer; return the count.

`discard_body()` ¶

Drop every staged body byte and reset both cursors.

`feed(chunk)` ¶

Append chunk to the parser's buffer and advance the state.

`feed_eof()` ¶

Signal that the peer closed the connection.

`encode_request(method, host, path, *, headers=None, body=None, user_agent=None)` ¶

Encode an HTTP/1.1 request into bytes ready for the wire.

Parameters:

Name	Type	Description	Default
`method`	`str`	HTTP verb, sent verbatim.	required
`host`	`str`	Value for the `Host:` header.	required
`path`	`str`	Request-target, typically the URL path + query.	required
`headers`	`CaseInsensitiveDict \| dict \| list \| tuple \| None`	Optional `(name, value)` pairs, dict, or CaseInsensitiveDict; override the defaults.	`None`
`body`	`bytes \| None`	Optional `bytes` body; adds `Content-Length` when set.	`None`
`user_agent`	`str \| None`	Override for the default `User-Agent` string.	`None`

Returns:

Type	Description
`bytes`	Encoded request as `bytes`.

Raises:

Type	Description
`HttpURLError`	A method, path, or header holds CR / LF / NUL or non-ASCII.

`parse_charset(content_type)` ¶

Extract the charset=... parameter from a Content-Type header.

Parameters:

Name	Type	Description	Default
`content_type`	`str \| None`	Raw `Content-Type` header value, or `None`.	required

Returns:

Type	Description
`str`	The detected charset name, or `"utf-8"` as the safe default.

`parse_url(url)` ¶

Split url into (scheme, host, port, path).

Parameters:

Name	Type	Description	Default
`url`	`str`	HTTP or HTTPS URL to split.	required

Returns:

Type	Description
`tuple[str, str, int, str]`	4-tuple `(scheme, host, port, path)`; path starts with `/`.

Raises:

Type	Description
`HttpURLError`	Bad scheme, missing host, or non-integer port.

`resolve_redirect_url(current_url, location)` ¶

Resolve a Location header value against the current request URL.

Parameters:

Name	Type	Description	Default
`current_url`	`str`	The URL of the request being redirected.	required
`location`	`str`	The raw `Location` header value from the response.	required

Returns:

Type	Description
`str`	Absolute URL the redirected request should target.

Raises:

Type	Description
`HttpURLError`	current_url doesn't parse, or location is empty.

API Reference¶

chumicro_requests ¶

CaseInsensitiveDict ¶

get(name, default=None) ¶

items() ¶

add(name, value) ¶

HttpBusyError ¶

HttpError ¶

HttpOversizedError ¶

HttpProtocolError ¶

HttpTimeoutError ¶

HttpURLError ¶

ParseState ¶

ResponseParser ¶

body property ¶

__init__(*, max_body_bytes=DEFAULT_MAX_BODY_BYTES, max_header_bytes=DEFAULT_MAX_HEADER_BYTES, body_buffer=None, body_buffer_view=None, stream_body=False) ¶

body_free() ¶

read_body_into(buffer) ¶

discard_body() ¶

feed(chunk) ¶

feed_eof() ¶

encode_request(method, host, path, *, headers=None, body=None, user_agent=None) ¶

parse_charset(content_type) ¶

parse_url(url) ¶

resolve_redirect_url(current_url, location) ¶

`chumicro_requests` ¶

`CaseInsensitiveDict` ¶

`get(name, default=None)` ¶

`items()` ¶

`add(name, value)` ¶

`HttpBusyError` ¶

`HttpError` ¶

`HttpOversizedError` ¶

`HttpProtocolError` ¶

`HttpTimeoutError` ¶

`HttpURLError` ¶

`ParseState` ¶

`ResponseParser` ¶

`body` `property` ¶

`init(*, max_body_bytes=DEFAULT_MAX_BODY_BYTES, max_header_bytes=DEFAULT_MAX_HEADER_BYTES, body_buffer=None, body_buffer_view=None, stream_body=False)` ¶

`body_free()` ¶

`read_body_into(buffer)` ¶

`discard_body()` ¶

`feed(chunk)` ¶

`feed_eof()` ¶

`encode_request(method, host, path, *, headers=None, body=None, user_agent=None)` ¶

`parse_charset(content_type)` ¶

`parse_url(url)` ¶

`resolve_redirect_url(current_url, location)` ¶