requests_cache.models package


requests_cache.models.raw_response module

class requests_cache.models.raw_response.CachedHTTPResponse(*args, body=None, **kwargs)[source]

Bases: urllib3.response.HTTPResponse

A serializable dataclass that extends/emulates HTTPResponse. Supports streaming requests and generator usage.

The only action this doesn’t support is explicitly calling read() with decode_content=False, but a use case for this has not come up yet.

decode_content: bool
classmethod from_response(original_response)[source]

Create a CachedHTTPResponse based on an original response

headers: urllib3._collections.HTTPHeaderDict
read(amt=None, decode_content=None, **kwargs)[source]

Simplified reader for cached content that emulates

reason: str

No-op for compatibility

request_url: str

Reset raw response file pointer, and optionally update content

status: int
stream(amt=None, **kwargs)[source]

Simplified generator over cached content that emulates

strict: int
version: int

requests_cache.models.request module

Classes to wrap cached response objects

class requests_cache.models.request.CachedRequest(body=None, cookies=NOTHING, headers=NOTHING, method=None, url=None)[source]

Bases: object

A serializable dataclass that emulates requests.PreparedResponse

classmethod from_request(original_request)[source]

Create a CachedRequest based on an original request object

Return type



Convert the CachedRequest back into a PreparedRequest

Return type



requests_cache.models.response module

Classes to wrap cached response objects

class requests_cache.models.response.CachedResponse(content=None, next=None, url=None, status_code=0, cache_key=None, cookies=NOTHING, created_at=NOTHING, elapsed=NOTHING, expires=None, encoding=None, headers=NOTHING, history=NOTHING, reason=None, request=NOTHING, raw=NOTHING)[source]

Bases: requests.models.Response

A serializable dataclass that emulates requests.Response. Public attributes and methods on CachedResponse objects will behave the same as those from the original response, but with different internals optimized for serialization.

This means doing some pre- and post-initialization steps common to all serializers, such as breaking nested objects down into their basic attributes and lazily re-initializing them, which saves a bit of memory and deserialization steps when those objects aren’t accessed.

cache_key: str
cookies: requests.cookies.RequestsCookieJar

A CookieJar of Cookies the server sent back.

created_at: datetime.datetime
elapsed: datetime.timedelta

The amount of time elapsed between sending the request and the arrival of the response (as a timedelta). This property specifically measures the time taken between sending the first byte of the request and finishing parsing the headers. It is therefore unaffected by consuming the response content or the value of the stream keyword argument.

encoding: str

Encoding to decode with when accessing r.text.

expires: Optional[datetime.datetime]
property from_cache: bool
Return type


classmethod from_response(original_response, **kwargs)[source]

Create a CachedResponse based on an original response object

headers: requests.structures.CaseInsensitiveDict

Case-insensitive Dictionary of Response Headers. For example, headers['content-encoding'] will return the value of a 'Content-Encoding' response header.

history: List[requests_cache.models.response.CachedResponse]

A list of Response objects from the history of the Request. Any redirect responses will end up here. The list is sorted from the oldest to the most recent request.

property is_expired: bool

Determine if this cached response is expired

Return type


property next: Optional[requests.models.PreparedRequest]

Returns a PreparedRequest for the next request in a redirect chain, if there is one.

Return type


raw: requests_cache.models.raw_response.CachedHTTPResponse

File-like object representation of response (for advanced usage). Use of raw requires that stream=True be set on the request. This requirement does not apply for use internally to Requests.

reason: str

Textual reason of responded HTTP Status, e.g. “Not Found” or “OK”.

request: requests_cache.models.request.CachedRequest

The PreparedRequest object to which this is a response.


Set a new expiration for this response, and determine if it is now expired

Return type


property size: int

Get the size of the response body in bytes

Return type


status_code: int

Integer Code of responded HTTP Status, e.g. 404 or 200.

url: str

Final URL location of Response.


Get a formatted datetime string in the local time zone

Return type



Convert a file size in bytes into a human-readable format

Return type


requests_cache.models.response.set_response_defaults(response, cache_key=None)[source]

Set some default CachedResponse values on a requests.Response object, so they can be expected to always be present

Return type

Union[Response, CachedResponse]