Requests, Responses, and URLs

TODO

Requests

Request instances in httpcore2 are deliberately simple, and only include the essential information required to represent an HTTP request.

Properties on the request are plain byte-wise representations.

>>> request = httpcore2.Request("GET", "https://www.example.com/")
>>> request.method
b"GET"
>>> request.url
httpcore2.URL(scheme=b"https", host=b"www.example.com", port=None, target=b"/")
>>> request.headers
[(b'Host', b'www.example.com')]
>>> request.stream
<httpcore2.ByteStream [0 bytes]>

The interface is liberal in the types that it accepts, but specific in the properties that it uses to represent them. For example, headers may be specified as a dictionary of strings, but internally are represented as a list of (byte, byte) tuples.

```python

headers = {"User-Agent": "custom"} request = httpcore2.Request("GET", "https://www.example.com/", headers=headers) request.headers [(b'Host', b'www.example.com'), (b"User-Agent", b"custom")]

Responses

...

URLs

...

Reference

`httpcore2.Request`

httpcore2.Request

An HTTP request.

init

__init__(
    method: bytes | str,
    url: URL | bytes | str,
    *,
    headers: HeaderTypes = None,
    content: bytes
    | Iterable[bytes]
    | AsyncIterable[bytes]
    | None = None,
    extensions: Extensions | None = None,
) -> None

Parameters:

Name	Type	Description	Default
`method`	`bytes \| str`	The HTTP request method, either as a string or bytes. For example: `GET`.	required
`url`	`URL \| bytes \| str`	The request URL, either as a `URL` instance, or as a string or bytes. For example: `"https://www.example.com".`	required
`headers`	`HeaderTypes`	The HTTP request headers.	`None`
`content`	`bytes \| Iterable[bytes] \| AsyncIterable[bytes] \| None`	The content of the request body.	`None`
`extensions`	`Extensions \| None`	A dictionary of optional extra information included on the request. Possible keys include `"timeout"`, and `"trace"`.	`None`

`httpcore2.Response`

httpcore2.Response

An HTTP response.

init

__init__(
    status: int,
    *,
    headers: HeaderTypes = None,
    content: bytes
    | Iterable[bytes]
    | AsyncIterable[bytes]
    | None = None,
    extensions: Extensions | None = None,
) -> None

Parameters:

Name	Type	Description	Default
`status`	`int`	The HTTP status code of the response. For example `200`.	required
`headers`	`HeaderTypes`	The HTTP response headers.	`None`
`content`	`bytes \| Iterable[bytes] \| AsyncIterable[bytes] \| None`	The content of the response body.	`None`
`extensions`	`Extensions \| None`	A dictionary of optional extra information included on the responseself.Possible keys include `"http_version"`, `"reason_phrase"`, and `"network_stream"`.	`None`

`httpcore2.URL`

httpcore2.URL

Represents the URL against which an HTTP request may be made.

The URL may either be specified as a plain string, for convenience:

url = httpcore2.URL("https://www.example.com/")

Or be constructed with explicitly pre-parsed components:

url = httpcore2.URL(scheme=b'https', host=b'www.example.com', port=None, target=b'/')

Using this second more explicit style allows integrations that are using httpcore to pass through URLs that have already been parsed in order to use libraries such as rfc-3986 rather than relying on the stdlib. It also ensures that URL parsing is treated identically at both the networking level and at any higher layers of abstraction.

The four components are important here, as they allow the URL to be precisely specified in a pre-parsed format. They also allow certain types of request to be created that could not otherwise be expressed.

For example, an HTTP request to http://www.example.com/ forwarded via a proxy at http://localhost:8080...

# Constructs an HTTP request with a complete URL as the target:
# GET https://www.example.com/ HTTP/1.1
url = httpcore2.URL(
    scheme=b'http',
    host=b'localhost',
    port=8080,
    target=b'https://www.example.com/'
)
request = httpcore2.Request(
    method="GET",
    url=url
)

Another example is constructing an OPTIONS * request...

# Constructs an 'OPTIONS *' HTTP request:
# OPTIONS * HTTP/1.1
url = httpcore2.URL(scheme=b'https', host=b'www.example.com', target=b'*')
request = httpcore2.Request(method="OPTIONS", url=url)

This kind of request is not possible to formulate with a URL string, because the / delimiter is always used to demark the target from the host/port portion of the URL.

For convenience, string-like arguments may be specified either as strings or as bytes. However, once a request is being issue over-the-wire, the URL components are always ultimately required to be a bytewise representation.

In order to avoid any ambiguity over character encodings, when strings are used as arguments, they must be strictly limited to the ASCII range chr(0)-chr(127). If you require a bytewise representation that is outside this range you must handle the character encoding directly, and pass a bytes instance.

init

__init__(
    url: bytes | str = "",
    *,
    scheme: bytes | str = b"",
    host: bytes | str = b"",
    port: int | None = None,
    target: bytes | str = b"",
) -> None

Parameters:

Name	Type	Description	Default
`url`	`bytes \| str`	The complete URL as a string or bytes.	`''`
`scheme`	`bytes \| str`	The URL scheme as a string or bytes. Typically either `"http"` or `"https"`.	`b''`
`host`	`bytes \| str`	The URL host as a string or bytes. Such as `"www.example.com"`.	`b''`
`port`	`int \| None`	The port to connect to. Either an integer or `None`.	`None`
`target`	`bytes \| str`	The target of the HTTP request. Such as `"/items?search=red"`.	`b''`