Clients - HTTPX

If you are coming from Requests, httpx.Client() is what you can use instead of requests.Session().
If you do anything more than experimentation, one-off scripts, or prototypes, then you should use a Client instance.
More efficient usage of network resources
When you make requests using the top-level API as documented in the Quickstart guide, HTTPX has to establish a new connection for every single request (connections are not reused). As the number of requests to a host increases, this quickly becomes inefficient.
On the other hand, a Client instance uses HTTP connection pooling. This means that when you make several requests to the same host, the Client will reuse the underlying TCP connection, instead of recreating one for every single request.
This can bring significant performance improvements compared to using the top-level API, including:
Client instances also support features that aren't available at the top-level API, such as:
The other sections on this page go into further detail about what you can do with a Client instance.
The recommended way to use a Client is as a context manager. This will ensure that connections are properly cleaned up when leaving the with block:
Alternatively, you can explicitly close the connection pool without block-usage using .close():
Once you have a Client, you can send requests using .get(), .post(), etc. For example:
These methods accept the same arguments as httpx.get(), httpx.post(), etc. This means that all features documented in the Quickstart guide are also available at the client level.
For example, to send a request with custom headers:
Clients allow you to apply configuration to all outgoing requests by passing parameters to the Client constructor.
For example, to apply a set of custom headers on every request:
When a configuration option is provided at both the client-level and request-level, one of two things can happen:
If you need finer-grained control on the merging of client-level and request-level parameters, see Request instances.
Additionally, Client accepts some configuration options that aren't available at the request level.
For example, base_url allows you to prepend an URL to all outgoing requests:
For a list of all available client parameters, see the Client API reference.
For maximum control on what gets sent over the wire, HTTPX supports building explicit Request instances:
To dispatch a Request instance across to the network, create a Client instance and use .send():
If you need to mix client-level and request-level options in a way that is not supported by the default Merging of parameters, you can use .build_request() and then make arbitrary modifications to the Request instance. For example:
If you need to monitor download progress of large responses, you can use response streaming and inspect the response.num_bytes_downloaded property.
This interface is required for properly determining download progress, because the total number of bytes returned by response.content or response.iter_content() will not always correspond with the raw content length of the response if HTTP response compression is being used.
For example, showing a progress bar using the tqdm library while a response is being downloaded could be done like this…
Or an alternate example, this time using the rich library…
If you need to monitor upload progress of large responses, you can use request content generator streaming.
For example, showing a progress bar using the tqdm library.
As mentioned in the quickstart multipart file encoding is available by passing a dictionary with the name of the payloads as keys and either tuple of elements or a file-like object or a string as values.
More specifically, if a tuple is used as a value, it must have between 2 and 3 elements:
It is safe to upload large files this way. File uploads are streaming by default, meaning that only one chunk will be loaded into memory at a time.
Non-file data fields can be included in the multipart form using by passing them to data=....
You can also send multiple files in one go with a multiple file field form. To do that, pass a list of (field, <file>) items instead of a dictionary, allowing you to pass multiple items with the same field. For instance this request sends 2 files, foo.png and bar.png in one request on the images form field: