HTTP Headers
You can use the request Cache-Control directives defined in RFC 9111 to make the cache behavior more explicit in some situations.
only-if-cached
If this directive is present in the request headers, the cache should either use the cached response or return the 504 status code.
Note
It is guaranteed that the client will not make any requests; instead, it will try to find a response from the cache that can be used for this request.
>>> import hishel
>>>
>>> client = hishel.CacheClient()
>>> response = client.get("https://example.com", headers=[("Cache-Control", "only-if-cached")])
>>> response
<Response [504 Gateway Timeout]>
or
>>> import hishel
>>>
>>> client = hishel.CacheClient()
>>> client.get("https://google.com") # will cache
>>> response = client.get("https://google.com", headers=[("Cache-Control", "only-if-cached")])
>>> response
<Response [301 Moved Permanently]>
max-age
If this directive is present in the request headers, the cache should ignore responses that are older than the specified number.
Example:
import hishel
client = hishel.CacheClient()
client.get("https://example.com", headers=[("Cache-Control", "max-age=3600")])
max-stale
If this directive is present in the request headers, the cache should ignore responses that have exceeded their freshness lifetime by more than the specified number of seconds.
import hishel
client = hishel.CacheClient()
client.get("https://example.com", headers=[("Cache-Control", "max-stale=3600")])
min-fresh
If this directive is present in the request headers, the cache should ignore responses that will not be fresh for at least the number of seconds specified.
import hishel
client = hishel.CacheClient()
client.get("https://example.com", headers=[("Cache-Control", "min-fresh=3600")])
no-cache
If this directive is present in the request headers, the cache should not use the response to this request unless it has been validated.
import hishel
client = hishel.CacheClient()
client.get("https://example.com", headers=[("Cache-Control", "no-cache")])
no-store
If this directive is present in the request headers, the cache should not save the response to this request.