Introduction
HTTPX is a fully featured HTTP client for Python 3, which provides sync and async APIs, and support for HTTP/1.1, HTTP/2, and features such as timeouts, proxies, and authentication. This tutorial demonstrates how to use HTTPX to make GET and POST requests with comprehensive examples.
Getting Started with httpx
To use HTTPX, you first need to install the package. If you haven’t done so, you can install it using pip:
pip install httpx
Once installed, you can start making requests. Here’s the most basic example of a GET request:
import httpx
response = httpx.get('https://example.com')
print(response.status_code)
print(response.text)
A POST request can be similarly made:
import httpx
data = {'key': 'value'}
response = httpx.post('https://example.com/post', data=data)
print(response.status_code)
print(response.json())
Handling Query Parameters
Sometimes, you need to send query parameters with your GET requests. With HTTPX, this is straightforward:
import httpx
params = {'key1': 'value1', 'key2': 'value2'}
response = httpx.get('https://example.com/get', params=params)
print(response.status_code)
print(response.json())
Sending JSON Data with POST
If you need to send JSON data in your POST request, HTTPX makes it easy:
import httpx
json_data = {'key': 'value'}
response = httpx.post('https://example.com/post', json=json_data)
print(response.status_code)
print(response.json())
Advanced Usage: Timeouts and Headers
For more control over your requests, you might need to set timeouts or custom headers:
import httpx
headers = {'User-Agent': 'my-app/0.0.1'}
timeout = 10.0 # seconds
response = httpx.get('https://example.com', headers=headers, timeout=timeout)
print(response.status_code)
print(response.text)
Working with Sessions
When making multiple requests to the same host, it’s more efficient to use a session, which allows connection pooling:
import httpx
with httpx.Client() as client:
client.headers.update({'User-Agent': 'my-app/0.0.1'})
response = client.get('https://example.com')
print(response.status_code)
response = client.post('https://example.com/post', json={'key': 'value'})
print(response.status_code)
Error Handling
Error handling is crucial when dealing with network operations. HTTPX provides built-in exceptions that you can catch:
import httpx
try:
response = httpx.get('https://example.com/not_found')
response.raise_for_status()
except httpx.RequestError as exc:
print(f'Request error: {exc}')
except httpx.HTTPStatusError as exc:
print(f'HTTP error: {exc}')
Asynchronous Requests
For asynchronous support, HTTPX offers an async variant of the Client. Here’s an example of making async GET and POST requests:
import httpx
import asyncio
async def main():
async with httpx.AsyncClient() as client:
response = await client.get('https://example.com')
print(response.status_code)
response = await client.post('https://example.com/post', json={'key': 'value'})
print(response.status_code)
asyncio.run(main())
Testing with httpx
HTTPX comes with a test client that can be used to simulate requests without actual network operation, which is useful in test cases:
from starlette.responses import PlainTextResponse
from starlette.testclient import TestClient
async def app(scope, receive, send):
response = PlainTextResponse('Hello, world!')
await response(scope, receive, send)
client = TestClient(app)
response = client.get('/')
print(response.status_code)
print(response.text)
Conclusion
In this tutorial, you’ve seen how to make GET and POST requests with the Python HTTPX library. You’ve also explored some advanced features like error handling, sending headers, and using sessions. Equipped with this knowledge, you are now prepared to harness the full potential of HTTPX in your Python projects.