Requests Compatibility Guide
HTTPX aims to be compatible with the
requests API wherever possible.
This documentation outlines places where the API differs...
response.url will return a
URL instance, rather than a string.
str(response.url) if you need a string instance.
In our documentation we prefer the uppercased versions, such as
codes.NOT_FOUND, but also provide lower-cased versions for API compatibility with
Requests includes various synonyms for status codes that HTTPX does not support.
HTTPX provides a
.stream() interface rather than using
stream=True. This ensures that streaming responses are always properly closed outside of the stream block, and makes it visually clearer at which points streaming I/O APIs may be used with a response.
with request.stream("GET", "https://www.example.com") as response: ...
stream() block request data is made available with:
.iter_bytes()- Instead of
.iter_text()- Instead of
.iter_lines()- Corresponding to
.iter_raw()- Use this instead of
.read()- Read the entire response body, making
When using a
Client instance, the
cert arguments should always be passed on client instantiation, rather than passed to the request method.
If you need more than one different SSL configuration, you should use different client instances for each SSL configuration.
Request body on HTTP methods
OPTIONS methods are specified as not supporting a request body. To stay in line with this, the
.options functions do not support
If you really do need to send request data using these http methods you should use the generic
.request function instead.
Checking for 4xx/5xx responses
We don't support
response.is_ok since the naming is ambiguous there, and might incorrectly imply an equivalence to
response.status_code == codes.OK. Instead we provide the
response.is_error property. Use
if not response.is_error: instead of
The HTTPX equivalent of
session = requests.Session(**kwargs)
is generally equivalent to
client = httpx.Client(**kwargs)
If you need to mock HTTPX the same way that test utilities like
requests-mock does for
requests, see RESPX.