QuickStart - HTTPX

First, start by importing HTTPX:
Now, let’s try to get a webpage.
Similarly, to make an HTTP POST request:
The PUT, DELETE, HEAD, and OPTIONS requests all follow the same style:
To include URL query parameters in the request, use the params keyword:
To see how the values get encoding into the URL string, we can inspect the resulting URL that was used to make the request:
You can also pass a list of items as a value:
HTTPX will automatically handle decoding the response content into Unicode text.
You can inspect what encoding will be used to decode the response.
In some cases the response may not contain an explicit encoding, in which case HTTPX will attempt to automatically determine an encoding to use.
If you need to override the standard behaviour and explicitly set the encoding to use, then you can do that too.
The response content can also be accessed as bytes, for non-text responses:
Any gzip and deflate HTTP response encodings will automatically be decoded for you. If brotlipy is installed, then the brotli response encoding will be supported. If zstandard is installed, then zstd response encodings will also be supported.
For example, to create an image from binary data returned by a request, you can use the following code:
Often Web API responses will be encoded as JSON.
To include additional headers in the outgoing request, use the headers keyword argument:
Some types of HTTP requests, such as POST and PUT requests, can include data in the request body. One common way of including that is as form-encoded data, which is used for HTML forms.
Form encoded data can also include multiple values from a given key.
You can also upload files, using HTTP multipart encoding:
You can also explicitly set the filename and content type, by using a tuple of items for the file value:
If you need to include non-file data fields in the multipart form, use the data=... parameter:
Form encoded data is okay if all you need is a simple key-value data structure. For more complicated data structures you'll often want to use JSON encoding instead.
For other encodings, you should use the content=... parameter, passing either a bytes type or a generator that yields bytes.
You may also want to set a custom Content-Type header when uploading binary data.
We can inspect the HTTP status code of the response:
HTTPX also includes an easy shortcut for accessing status codes by their text phrase.
We can raise an exception for any responses which are not a 2xx success code:
Any successful response codes will return the Response instance rather than raising an exception.
The method returns the response instance, allowing you to use it inline. For example:
The response headers are available as a dictionary-like interface.
The Headers data type is case-insensitive, so you can use any capitalization.
Multiple values for a single response header are represented as a single comma-separated value, as per RFC 7230:
A recipient MAY combine multiple header fields with the same field name into one “field-name: field-value” pair, without changing the semantics of the message, by appending each subsequent field-value to the combined field value in order, separated by a comma.
For large downloads you may want to use streaming responses that do not load the entire response body into memory at once.
You can stream the binary content of the response...
Or the text of the response...
Or stream the text, on a line-by-line basis...
HTTPX will use universal line endings, normalising all cases to \n.
In some cases you might want to access the raw bytes on the response without applying any HTTP content decoding. In this case any content encoding that the web server has applied such as gzip, deflate, brotli, or zstd will not be automatically decoded.
If you're using streaming responses in any of these ways then the response.content and response.text attributes will not be available, and will raise errors if accessed. However you can also use the response streaming functionality to conditionally load the response body: