Skip to content

API documentation

Client

class httpx_cache.Client(*, auth=None, params=None, headers=None, cookies=None, verify=True, cert=None, http1=True, http2=False, proxies=None, mounts=None, timeout=Timeout(timeout=5.0), follow_redirects=False, limits=Limits(max_connections=100, max_keepalive_connections=20, keepalive_expiry=5.0), max_redirects=20, event_hooks=None, base_url='', transport=None, app=None, trust_env=True, cache=None, cacheable_methods=('GET',), cacheable_status_codes=(200, 203, 300, 301, 308), always_cache=False)
auth

Authentication class used when none is passed at the request-level.

See also Authentication.

base_url

Base URL to use when sending requests with relative URLs.

build_request(self, method, url, *, content=None, data=None, files=None, json=None, params=None, headers=None, cookies=None, timeout=, extensions=None)

Build and return a request instance.

  • The params, headers and cookies arguments are merged with any values set on the client.
  • The url argument is merged with any base_url set on the client.

See also: Request instances

close(self)

Close transport and proxies.

cookies

Cookie values to include when sending requests.

delete(self, url, *, params=None, headers=None, cookies=None, auth=, follow_redirects=, timeout=, extensions=None)

Send a DELETE request.

Parameters: See httpx.request.

event_hooks
get(self, url, *, params=None, headers=None, cookies=None, auth=, follow_redirects=, timeout=, extensions=None)

Send a GET request.

Parameters: See httpx.request.

head(self, url, *, params=None, headers=None, cookies=None, auth=, follow_redirects=, timeout=, extensions=None)

Send a HEAD request.

Parameters: See httpx.request.

headers

HTTP headers to include when sending requests.

is_closed

Check if the client being closed

options(self, url, *, params=None, headers=None, cookies=None, auth=, follow_redirects=, timeout=, extensions=None)

Send an OPTIONS request.

Parameters: See httpx.request.

params

Query parameters to include in the URL when sending requests.

patch(self, url, *, content=None, data=None, files=None, json=None, params=None, headers=None, cookies=None, auth=, follow_redirects=, timeout=, extensions=None)

Send a PATCH request.

Parameters: See httpx.request.

post(self, url, *, content=None, data=None, files=None, json=None, params=None, headers=None, cookies=None, auth=, follow_redirects=, timeout=, extensions=None)

Send a POST request.

Parameters: See httpx.request.

put(self, url, *, content=None, data=None, files=None, json=None, params=None, headers=None, cookies=None, auth=, follow_redirects=, timeout=, extensions=None)

Send a PUT request.

Parameters: See httpx.request.

request(self, method, url, *, content=None, data=None, files=None, json=None, params=None, headers=None, cookies=None, auth=, follow_redirects=, timeout=, extensions=None)

Build and send a request.

Equivalent to:

request = client.build_request(...)
response = client.send(request, ...)

See Client.build_request(), Client.send() and Merging of configuration for how the various parameters are merged with client-level configuration.

send(self, request, *, stream=False, auth=, follow_redirects=)

Send a request.

The request is sent as-is, unmodified.

Typically you'll want to build one with Client.build_request() so that any client-level configuration is merged into the request, but passing an explicit httpx.Request() is supported as well.

See also: Request instances

stream(self, method, url, *, content=None, data=None, files=None, json=None, params=None, headers=None, cookies=None, auth=, follow_redirects=, timeout=, extensions=None)

Alternative to httpx.request() that streams the response body instead of loading it into memory at once.

Parameters: See httpx.request.

See also: Streaming Responses

timeout
trust_env
class httpx_cache.AsyncClient(*, auth=None, params=None, headers=None, cookies=None, verify=True, cert=None, http1=True, http2=False, proxies=None, mounts=None, timeout=Timeout(timeout=5.0), follow_redirects=False, limits=Limits(max_connections=100, max_keepalive_connections=20, keepalive_expiry=5.0), max_redirects=20, event_hooks=None, base_url='', transport=None, app=None, trust_env=True, cache=None, cacheable_methods=('GET',), cacheable_status_codes=(200, 203, 300, 301, 308), always_cache=False)
async aclose(self)

Close transport and proxies.

auth

Authentication class used when none is passed at the request-level.

See also Authentication.

base_url

Base URL to use when sending requests with relative URLs.

build_request(self, method, url, *, content=None, data=None, files=None, json=None, params=None, headers=None, cookies=None, timeout=, extensions=None)

Build and return a request instance.

  • The params, headers and cookies arguments are merged with any values set on the client.
  • The url argument is merged with any base_url set on the client.

See also: Request instances

cookies

Cookie values to include when sending requests.

async delete(self, url, *, params=None, headers=None, cookies=None, auth=, follow_redirects=, timeout=, extensions=None)

Send a DELETE request.

Parameters: See httpx.request.

event_hooks
async get(self, url, *, params=None, headers=None, cookies=None, auth=, follow_redirects=, timeout=, extensions=None)

Send a GET request.

Parameters: See httpx.request.

async head(self, url, *, params=None, headers=None, cookies=None, auth=, follow_redirects=, timeout=, extensions=None)

Send a HEAD request.

Parameters: See httpx.request.

headers

HTTP headers to include when sending requests.

is_closed

Check if the client being closed

async options(self, url, *, params=None, headers=None, cookies=None, auth=, follow_redirects=, timeout=, extensions=None)

Send an OPTIONS request.

Parameters: See httpx.request.

params

Query parameters to include in the URL when sending requests.

async patch(self, url, *, content=None, data=None, files=None, json=None, params=None, headers=None, cookies=None, auth=, follow_redirects=, timeout=, extensions=None)

Send a PATCH request.

Parameters: See httpx.request.

async post(self, url, *, content=None, data=None, files=None, json=None, params=None, headers=None, cookies=None, auth=, follow_redirects=, timeout=, extensions=None)

Send a POST request.

Parameters: See httpx.request.

async put(self, url, *, content=None, data=None, files=None, json=None, params=None, headers=None, cookies=None, auth=, follow_redirects=, timeout=, extensions=None)

Send a PUT request.

Parameters: See httpx.request.

async request(self, method, url, *, content=None, data=None, files=None, json=None, params=None, headers=None, cookies=None, auth=, follow_redirects=, timeout=, extensions=None)

Build and send a request.

Equivalent to:

request = client.build_request(...)
response = await client.send(request, ...)

See AsyncClient.build_request(), AsyncClient.send() and Merging of configuration for how the various parameters are merged with client-level configuration.

async send(self, request, *, stream=False, auth=, follow_redirects=)

Send a request.

The request is sent as-is, unmodified.

Typically you'll want to build one with AsyncClient.build_request() so that any client-level configuration is merged into the request, but passing an explicit httpx.Request() is supported as well.

See also: Request instances

stream(self, method, url, *, content=None, data=None, files=None, json=None, params=None, headers=None, cookies=None, auth=, follow_redirects=, timeout=, extensions=None)

Alternative to httpx.request() that streams the response body instead of loading it into memory at once.

Parameters: See httpx.request.

See also: Streaming Responses

timeout
trust_env

Transport

class httpx_cache.CacheControlTransport(*, transport=None, cache=None, cacheable_methods=('GET',), cacheable_status_codes=(200, 203, 300, 301, 308), always_cache=False)

CacheControl transport for httpx_cache.

Args: transport (optional): an existing httpx transport, if no transport is given, defaults to an httpx.HTTPTransport with default args. cache (optional): cache to use with this transport, defaults to httpx_cache.DictCache cacheable_methods: methods that are allowed to be cached, defaults to ['GET'] cacheable_status_codes: status codes that are allowed to be cached, defaults to: (200, 203, 300, 301, 308)

close(self)
handle_request(self, request)
class httpx_cache.AsyncCacheControlTransport(*, transport=None, cache=None, cacheable_methods=('GET',), cacheable_status_codes=(200, 203, 300, 301, 308), always_cache=False)

Async CacheControl transport for httpx_cache.

Args: transport (optional): an existing httpx async-transport, if no transport is given, defaults to an httpx.AsyncHTTPTransport with default args. cache (optional): cache to use with this transport, defaults to httpx_cache.DictCache cacheable_methods: methods that are allowed to be cached, defaults to ['GET'] cacheable_status_codes: status codes that are allowed to be cached, defaults to: (200, 203, 300, 301, 308)

async aclose(self)
async handle_async_request(self, request)

CacheControl

class httpx_cache.CacheControl(*, cacheable_methods=('GET',), cacheable_status_codes=(200, 203, 300, 301, 308), always_cache=False)

Cache controller for httpx-cache.

Uses 'cache-contol' header direcrives for using/skipping cache.

If no cache-control directive is set, the cache is used by default (except if there is an expires header in the response.)

is_request_cacheable(self, request)

Checks if an httpx request has the necessary requirement to support caching.

A request is cacheable if:

- url is absolute
- method is defined as cacheable (by default only GET methods are cached)
- request has no 'no-cache' cache-control header directive
- request has no 'max-age=0' cache-control header directive

Args: request: httpx.Request

Returns: True if request cacheable else False

is_response_cacheable(self, *, request, response)

Check if an httpx response is cacheable.

A respons is cacheable if:

- response status_code is cacheable
- request method is cacheable
- One of:
    - always_cache is True
OR:
    - Response has no 'no-store' cache-control header
    - Request has no 'no-store' cache-control header

Args: request: httpx.Request response: httpx.Response

Returns: wether response is cacheable or not.

is_response_fresh(self, *, request, response)

Checks wether a cached response is fresh or not.

Args: request: httpx.Request response: httpx.Response

Returns: True if request is fresh else False

Cache

class httpx_cache.DictCache(data=None, serializer=None)

Simple in-memory dict cache.

Uses a lock/async_lock to make sure each get/set/delete operation is safe.

Args: data: Optional initial data for the cache {str: Any}, default to {} serializer: Optional serializer for the data to cache, defaults to: httpx_cache.MsgPackSerializer

async aclose(self)

(Async) Close cache.

async adelete(self, request)
async aget(self, request)
async aset(self, *, request, response, content=None)
async_lock
close(self)

Close cache.

delete(self, request)
get(self, request)
lock
set(self, *, request, response, content=None)
class httpx_cache.FileCache(cache_dir=None, serializer=None)

File cache that stores cached responses in files on disk.

Uses a lock/async_lock to make sure each get/set/delete operation is safe.

Args: cache_dir: Optional custom cache_dir where to store cache files, defaults to ~/.cache/httpx-cache serializer: Optional serializer for the data to cache, defaults to: httpx_cache.MsgPackSerializer

async aclose(self)

(Async) Close cache.

async adelete(self, request)
async aget(self, request)
async aset(self, *, request, response, content=None)
async_lock
close(self)

Close cache.

delete(self, request)
get(self, request)
lock

A reader/writer lock.

This lock allows for simultaneous readers to exist but only one writer to exist for use-cases where it is useful to have such types of locks.

Currently a reader can not escalate its read lock to a write lock and a writer can not acquire a read lock while it is waiting on the write lock.

In the future these restrictions may be relaxed.

This can be eventually removed if http://bugs.python.org/issue8800 ever gets accepted into the python standard threading library...

set(self, *, request, response, content=None)
class httpx_cache.cache.redis.RedisCache(serializer=None, namespace='httpx_cache', redis_url='', redis=None, aredis=None, default_ttl=None)

Redis cache that stores cached responses in Redis.

Uses a lock/async_lock to make sure each get/set/delete operation is safe.

You can either provide an instance of 'Redis'/'AsyncRedis' or a redis url to have RedisCache create the connection for you.

Args: serializer: Optional serializer for the data to cache, defaults to: httpx_cache.MsgPackSerializer namespace: Optional namespace for the cache keys, defaults to "httpx_cache" redis_url: Optional redis url, defaults to empty string redis: Optional redis instance, defaults to None aredis: Optional async redis instance, defaults to None default_ttl: Optional default ttl for cached responses, defaults to None

async aclose(self)
async adelete(self, request)
async aget(self, request)
async aset(self, *, request, response, content=None)
async_lock
close(self)
delete(self, request)
get(self, request)
lock

A reader/writer lock.

This lock allows for simultaneous readers to exist but only one writer to exist for use-cases where it is useful to have such types of locks.

Currently a reader can not escalate its read lock to a write lock and a writer can not acquire a read lock while it is waiting on the write lock.

In the future these restrictions may be relaxed.

This can be eventually removed if http://bugs.python.org/issue8800 ever gets accepted into the python standard threading library...

set(self, *, request, response, content=None)

!!! Note FileCache and RedisCache only supports httpx_cache.MsgPackSerializer and httpx_cache.BytesJsonSerializer serializers.

Serializer

class httpx_cache.DictSerializer()

Dumps and loads and httpx.Response into/from a python dict.

The dict contains the state of the response, with all necessary info to recreate it.

dumps(self, *, response, content=None)

Converts and httpx.Response into a dict with it's state.

The goal is that this state we are able later to reconstruct the same response later on.

In case the response does not yet have a '_content' property, content should be provided in the optional 'content' kwarg (usually using a callback)

Args: response: httpx.Response content (bytes, optional): Defaults to None, should be provided in case response that not have yet content.

Raises: httpx.ResponseNotRead: if response does not have content and no content is provided

Returns: Dict[str, Any]

loads(self, *, cached, request=None)

Convert a dict (contains response state) to an httpx.Response instance.

Args: state: Dict of the state of teh response to create request (httpx.Request, optional): Defaults to None, request to optionally attach to the response

Returns: httpx.Response

class httpx_cache.StringJsonSerializer()

Serialize an httpx.Response using python Json Encoder.

Serialized data is returned as a JSON string.

The serialized data contains the state of the response, with all necessary info to recreate it.

NB: bytes are automatically parsed as strings when using this serializer, when recreating response the loader is smart enough to know which key/value need to be bytes and not strings (like: _content/stream)

dumps(self, *, response, content=None)

Dump an httpx.Response to json string.

loads(self, *, cached, request=None)

Load an httpx.Response from a json string

class httpx_cache.BytesJsonSerializer()

Same as httpx_cache.StringJsonSerializer, but converts the dumped strings into bytes (encoded/decode with utf-8).

dumps(self, *, response, content=None)

Dump an httpx.Response to an utf-8 encoded bytes string.

loads(self, *, cached, request=None)

Load an httpx.Response to an utf-8 encoded bytes string.

class httpx_cache.MsgPackSerializer()

Serialize an httpx.Response using msgpack.

Serialized data is returned as a bytes.

The serialized data contains the state of the response, with all necessary info to recreate it.

dumps(self, *, response, content=None)

Dump an httpx.Response to msgapck bytes.

loads(self, *, cached, request=None)

Load an httpx.Response from a msgapck bytes.