Developer Interface

Helper Functions

Note

Only use these functions if you're testing HTTPX in a console or making a small number of requests. Using a Client will enable HTTP/2 and connection pooling for more efficient and long-lived connections.

httpx.request(method, url, *, params=None, data=None, files=None, json=None, headers=None, cookies=None, auth=None, timeout=Timeout(timeout=5.0), allow_redirects=True, verify=True, cert=None, trust_env=True)

Sends an HTTP request.

Parameters:

  • method - HTTP method for the new Request object: GET, OPTIONS, HEAD, POST, PUT, PATCH, or DELETE.
  • url - URL for the new Request object.
  • params - (optional) Query parameters to include in the URL, as a string, dictionary, or list of two-tuples.
  • data - (optional) Data to include in the body of the request, as a dictionary
  • files - (optional) A dictionary of upload files to include in the body of the request.
  • json - (optional) A JSON serializable object to include in the body of the request.
  • headers - (optional) Dictionary of HTTP headers to include in the request.
  • cookies - (optional) Dictionary of Cookie items to include in the request.
  • auth - (optional) An authentication class to use when sending the request.
  • timeout - (optional) The timeout configuration to use when sending the request.
  • allow_redirects - (optional) Enables or disables HTTP redirects.
  • verify - (optional) SSL certificates (a.k.a CA bundle) used to verify the identity of requested hosts. Either True (default CA bundle), a path to an SSL certificate file, or False (disable verification).
  • cert - (optional) An SSL certificate used by the requested host to authenticate the client. Either a path to an SSL certificate file, or two-tuple of (certificate file, key file), or a three-tuple of (certificate file, key file, password).
  • trust_env - (optional) Enables or disables usage of environment variables for configuration.

Returns: Response

Usage:

>>> import httpx
>>> response = httpx.request('GET', 'https://httpbin.org/get')
>>> response
<Response [200 OK]>
httpx.get(url, *, params=None, headers=None, cookies=None, auth=None, allow_redirects=True, cert=None, verify=True, timeout=Timeout(timeout=5.0), trust_env=True)

Sends a GET request.

Parameters: See httpx.request.

Note that the data, files, and json parameters are not available on this function, as GET requests should not include a request body.

httpx.options(url, *, params=None, headers=None, cookies=None, auth=None, allow_redirects=True, cert=None, verify=True, timeout=Timeout(timeout=5.0), trust_env=True)

Sends an OPTIONS request.

Parameters: See httpx.request.

Note that the data, files, and json parameters are not available on this function, as OPTIONS requests should not include a request body.

httpx.head(url, *, params=None, headers=None, cookies=None, auth=None, allow_redirects=False, cert=None, verify=True, timeout=Timeout(timeout=5.0), trust_env=True)

Sends a HEAD request.

Parameters: See httpx.request.

Note that the data, files, and json parameters are not available on this function, as HEAD requests should not include a request body. The HEAD method also differs from the other cases in that allow_redirects defaults to False.

httpx.post(url, *, data=None, files=None, json=None, params=None, headers=None, cookies=None, auth=None, allow_redirects=True, cert=None, verify=True, timeout=Timeout(timeout=5.0), trust_env=True)

Sends a POST request.

Parameters: See httpx.request.

httpx.put(url, *, data=None, files=None, json=None, params=None, headers=None, cookies=None, auth=None, allow_redirects=True, cert=None, verify=True, timeout=Timeout(timeout=5.0), trust_env=True)

Sends a PUT request.

Parameters: See httpx.request.

httpx.patch(url, *, data=None, files=None, json=None, params=None, headers=None, cookies=None, auth=None, allow_redirects=True, cert=None, verify=True, timeout=Timeout(timeout=5.0), trust_env=True)

Sends a PATCH request.

Parameters: See httpx.request.

httpx.delete(url, *, params=None, headers=None, cookies=None, auth=None, allow_redirects=True, cert=None, verify=True, timeout=Timeout(timeout=5.0), trust_env=True)

Sends a DELETE request.

Parameters: See httpx.request.

Note that the data, files, and json parameters are not available on this function, as DELETE requests should not include a request body.

Client

class httpx.Client(*, auth=None, params=None, headers=None, cookies=None, verify=True, cert=None, proxies=None, timeout=Timeout(timeout=5.0), pool_limits=PoolLimits(soft_limit=10, hard_limit=100), max_redirects=20, base_url=None, dispatch=None, app=None, trust_env=True)

An HTTP client, with connection pooling, HTTP/2, redirects, cookie persistence, etc.

Usage:

>>> client = httpx.Client()
>>> response = client.get('https://example.org')

Parameters:

  • auth - (optional) An authentication class to use when sending requests.
  • params - (optional) Query parameters to include in request URLs, as a string, dictionary, or list of two-tuples.
  • headers - (optional) Dictionary of HTTP headers to include when sending requests.
  • cookies - (optional) Dictionary of Cookie items to include when sending requests.
  • verify - (optional) SSL certificates (a.k.a CA bundle) used to verify the identity of requested hosts. Either True (default CA bundle), a path to an SSL certificate file, or False (disable verification).
  • cert - (optional) An SSL certificate used by the requested host to authenticate the client. Either a path to an SSL certificate file, or two-tuple of (certificate file, key file), or a three-tuple of (certificate file, key file, password).
  • proxies - (optional) A dictionary mapping HTTP protocols to proxy URLs.
  • timeout - (optional) The timeout configuration to use when sending requests.
  • pool_limits - (optional) The connection pool configuration to use when determining the maximum number of concurrently open HTTP connections.
  • max_redirects - (optional) The maximum number of redirect responses that should be followed.
  • base_url - (optional) A URL to use as the base when building request URLs.
  • dispatch - (optional) A dispatch class to use for sending requests over the network.
  • app - (optional) An WSGI application to send requests to, rather than sending actual network requests.
  • trust_env - (optional) Enables or disables usage of environment variables for configuration.
headers

HTTP headers to include when sending requests.

cookies

Cookie values to include when sending requests.

params

Query parameters to include in the URL when sending requests.

request(self, method, url, *, data=None, files=None, json=None, params=None, headers=None, cookies=None, auth=None, allow_redirects=True, timeout=)
get(self, url, *, params=None, headers=None, cookies=None, auth=None, allow_redirects=True, timeout=)
head(self, url, *, params=None, headers=None, cookies=None, auth=None, allow_redirects=False, timeout=)
options(self, url, *, params=None, headers=None, cookies=None, auth=None, allow_redirects=True, timeout=)
post(self, url, *, data=None, files=None, json=None, params=None, headers=None, cookies=None, auth=None, allow_redirects=True, timeout=)
put(self, url, *, data=None, files=None, json=None, params=None, headers=None, cookies=None, auth=None, allow_redirects=True, timeout=)
patch(self, url, *, data=None, files=None, json=None, params=None, headers=None, cookies=None, auth=None, allow_redirects=True, timeout=)
delete(self, url, *, params=None, headers=None, cookies=None, auth=None, allow_redirects=True, timeout=)
build_request(self, method, url, *, data=None, files=None, json=None, params=None, headers=None, cookies=None)

Build and return a request instance.

send(self, request, *, stream=False, auth=None, allow_redirects=True, timeout=)
close(self)

AsyncClient

class httpx.AsyncClient(*, auth=None, params=None, headers=None, cookies=None, verify=True, cert=None, http2=False, proxies=None, timeout=Timeout(timeout=5.0), pool_limits=PoolLimits(soft_limit=10, hard_limit=100), max_redirects=20, base_url=None, dispatch=None, app=None, trust_env=True, uds=None)

An asynchronous HTTP client, with connection pooling, HTTP/2, redirects, cookie persistence, etc.

Usage:

>>> async with httpx.AsyncClient() as client:
>>>     response = await client.get('https://example.org')

Parameters:

  • auth - (optional) An authentication class to use when sending requests.
  • params - (optional) Query parameters to include in request URLs, as a string, dictionary, or list of two-tuples.
  • headers - (optional) Dictionary of HTTP headers to include when sending requests.
  • cookies - (optional) Dictionary of Cookie items to include when sending requests.
  • verify - (optional) SSL certificates (a.k.a CA bundle) used to verify the identity of requested hosts. Either True (default CA bundle), a path to an SSL certificate file, or False (disable verification).
  • cert - (optional) An SSL certificate used by the requested host to authenticate the client. Either a path to an SSL certificate file, or two-tuple of (certificate file, key file), or a three-tuple of (certificate file, key file, password).
  • http2 - (optional) A boolean indicating if HTTP/2 support should be enabled. Defaults to False.
  • proxies - (optional) A dictionary mapping HTTP protocols to proxy URLs.
  • timeout - (optional) The timeout configuration to use when sending requests.
  • pool_limits - (optional) The connection pool configuration to use when determining the maximum number of concurrently open HTTP connections.
  • max_redirects - (optional) The maximum number of redirect responses that should be followed.
  • base_url - (optional) A URL to use as the base when building request URLs.
  • dispatch - (optional) A dispatch class to use for sending requests over the network.
  • app - (optional) An ASGI application to send requests to, rather than sending actual network requests.
  • trust_env - (optional) Enables or disables usage of environment variables for configuration.
  • uds - (optional) A path to a Unix domain socket to connect through.
headers

HTTP headers to include when sending requests.

cookies

Cookie values to include when sending requests.

params

Query parameters to include in the URL when sending requests.

request(self, method, url, *, data=None, files=None, json=None, params=None, headers=None, cookies=None, auth=None, allow_redirects=True, timeout=)
get(self, url, *, params=None, headers=None, cookies=None, auth=None, allow_redirects=True, timeout=)
head(self, url, *, params=None, headers=None, cookies=None, auth=None, allow_redirects=False, timeout=)
options(self, url, *, params=None, headers=None, cookies=None, auth=None, allow_redirects=True, timeout=)
post(self, url, *, data=None, files=None, json=None, params=None, headers=None, cookies=None, auth=None, allow_redirects=True, timeout=)
put(self, url, *, data=None, files=None, json=None, params=None, headers=None, cookies=None, auth=None, allow_redirects=True, timeout=)
patch(self, url, *, data=None, files=None, json=None, params=None, headers=None, cookies=None, auth=None, allow_redirects=True, timeout=)
delete(self, url, *, params=None, headers=None, cookies=None, auth=None, allow_redirects=True, timeout=)
build_request(self, method, url, *, data=None, files=None, json=None, params=None, headers=None, cookies=None)

Build and return a request instance.

send(self, request, *, stream=False, auth=None, allow_redirects=True, timeout=)

Response

An HTTP response.

  • def __init__(...)
  • .status_code - int
  • .reason_phrase - str
  • .http_version - "HTTP/2" or "HTTP/1.1"
  • .url - URL
  • .headers - Headers
  • .content - bytes
  • .text - str
  • .encoding - str
  • .is_redirect - bool
  • .request - Request
  • .cookies - Cookies
  • .history - List[Response]
  • .elapsed - timedelta
  • The amount of time elapsed between sending the request and calling close() on the corresponding response received for that request. total_seconds() to correctly get the total elapsed seconds.
  • def .raise_for_status() - None
  • def .json() - Any
  • def .read() - bytes
  • def .iter_raw() - bytes iterator
  • def .iter_bytes() - bytes iterator
  • def .iter_text() - text iterator
  • def .iter_lines() - text iterator
  • def .close() - None
  • def .next() - Response
  • def .aread() - bytes
  • def .aiter_raw() - async bytes iterator
  • def .aiter_bytes() - async bytes iterator
  • def .aiter_text() - async text iterator
  • def .aiter_lines() - async text iterator
  • def .aclose() - None
  • def .anext() - Response

Request

An HTTP request. Can be constructed explicitly for more control over exactly what gets sent over the wire.

>>> request = httpx.Request("GET", "https://example.org", headers={'host': 'example.org'})
>>> response = client.send(request)
  • def __init__(method, url, [params], [data], [json], [headers], [cookies])
  • .method - str
  • .url - URL
  • .content - byte, byte iterator, or byte async iterator
  • .headers - Headers
  • .cookies - Cookies

URL

A normalized, IDNA supporting URL.

>>> url = URL("https://example.org/")
>>> url.host
'example.org'
  • def __init__(url, allow_relative=False, params=None)
  • .scheme - str
  • .authority - str
  • .host - str
  • .port - int
  • .path - str
  • .query - str
  • .full_path - str
  • .fragment - str
  • .is_ssl - bool
  • .origin - Origin
  • .is_absolute_url - bool
  • .is_relative_url - bool
  • def .copy_with([scheme], [authority], [path], [query], [fragment]) - URL
  • def .resolve_with(url) - URL

Origin

A normalized, IDNA supporting set of scheme/host/port info.

>>> Origin('https://example.org') == Origin('HTTPS://EXAMPLE.ORG:443')
True
  • def __init__(url)
  • .scheme - str
  • .is_ssl - bool
  • .host - str
  • .port - int

Headers

A case-insensitive multi-dict.

>>> headers = Headers({'Content-Type': 'application/json'})
>>> headers['content-type']
'application/json'
  • def __init__(self, headers)

Cookies

A dict-like cookie store.

>>> cookies = Cookies()
>>> cookies.set("name", "value", domain="example.org")
  • def __init__(cookies: [dict, Cookies, CookieJar])
  • .jar - CookieJar
  • def extract_cookies(response)
  • def set_cookie_header(request)
  • def set(name, value, [domain], [path])
  • def get(name, [domain], [path])
  • def delete(name, [domain], [path])
  • def clear([domain], [path])
  • Standard mutable mapping interface