From 489e0ff74d161ae185d4ac42a981bbcfa412ac6a Mon Sep 17 00:00:00 2001 From: Kar Petrosyan <92274156+karpetrosyan@users.noreply.github.com> Date: Wed, 14 Feb 2024 10:36:48 +0400 Subject: [PATCH] Version 0.0.23 (#184) * Version 0.0.23 * Change README text --- CHANGELOG.md | 2 +- README.md | 60 ++++++++++++++++++++++++++++++---------------- docs/index.md | 60 ++++++++++++++++++++++++++++++---------------- hishel/__init__.py | 2 +- 4 files changed, 80 insertions(+), 44 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 02a8824e..fab23c5b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,6 @@ # Changelog -## Unreleased +## 0.0.23 (12th February, 2024) - Make `S3Storage` to check staleness of all cache files with set interval. (#182) - Fix an issue where an empty file in `FileCache` could cause a parsing error. (#181) diff --git a/README.md b/README.md index 06f1a790..8239ed1c 100644 --- a/README.md +++ b/README.md @@ -70,40 +70,58 @@ async with hishel.AsyncCacheClient() as client: await client.get("https://hishel.com") # takes from the cache ``` -## HTTPX and HTTP Core +## Configurations -`Hishel` also supports the transports of `HTTPX` and the connection pools of `HTTP Core`. +Configure when and how you want to store your responses. -`Hishel` respects existing **transports** and **connection pools** and can therefore work **on top of them**, making hishel a very **compatible and flexible library**. +```python +import hishel +# All the specification configs +controller = hishel.Controller( + # Cache only GET and POST methods + cacheable_methods=["GET", "POST"], -**Transports** example: + # Cache only 200 status codes + cacheable_status_codes=[200], -``` python -import httpx -import hishel + # Use the stale response if there is a connection issue and the new response cannot be obtained. + allow_stale=True, -transport = httpx.HTTPTransport() -cache_transport = hishel.CacheTransport(transport=transport) + # First, revalidate the response and then utilize it. + # If the response has not changed, do not download the + # entire response data from the server; instead, + # use the one you have because you know it has not been modified. + always_revalidate=True, +) -req = httpx.Request("GET", "https://hishel.com") +# All the storage configs +storage = hishel.S3Storage( + bucket_name="my_bucket_name", # store my cache files in the `my_bucket_name` bucket + ttl=3600, # delete the response if it is in the cache for more than an hour +) +client = hishel.CacheClient(controller=controller, storage=storage) -cache_transport.handle_request(req) -cache_transport.handle_request(req) # takes from the cache -``` -**Connection Pool** example: +# Ignore the fact that the server does not recommend you cache this request! +client.post( + "https://example.com", + extensions={"force_cache": True} +) -```python -import httpcore -import hishel - -pool = hishel.CacheConnectionPool(pool=httpcore.ConnectionPool()) +# Return a regular response if it is in the cache; else, return a 504 status code. DO NOT SEND A REQUEST! +client.post( + "https://example.com", + headers=[("Cache-Control", "only-if-cached")] +) -pool.request("GET", "https://hishel.com") -pool.request("GET", "https://hishel.com") # takes from the cache +# Ignore cached responses and do not store incoming responses! +response = client.post( + "https://example.com", + extensions={"cache_disabled": True} +) ``` ## How and where are the responses saved? diff --git a/docs/index.md b/docs/index.md index ce0e2879..099fd69c 100644 --- a/docs/index.md +++ b/docs/index.md @@ -67,40 +67,58 @@ async with hishel.AsyncCacheClient() as client: await client.get("https://hishel.com") # takes from the cache ``` -## HTTPX and HTTP Core +## Configurations -`Hishel` also supports the transports of `HTTPX` and the connection pools of `HTTP Core`. +Configure when and how you want to store your responses. -`Hishel` respects existing **transports** and **connection pools** and can therefore work **on top of them**, making hishel a very **compatible and flexible library**. +```python +import hishel +# All the specification configs +controller = hishel.Controller( + # Cache only GET and POST methods + cacheable_methods=["GET", "POST"], -**Transports** example: + # Cache only 200 status codes + cacheable_status_codes=[200], -``` python -import httpx -import hishel + # Use the stale response if there is a connection issue and the new response cannot be obtained. + allow_stale=True, -transport = httpx.HTTPTransport() -cache_transport = hishel.CacheTransport(transport=transport) + # First, revalidate the response and then utilize it. + # If the response has not changed, do not download the + # entire response data from the server; instead, + # use the one you have because you know it has not been modified. + always_revalidate=True, +) -req = httpx.Request("GET", "https://hishel.com") +# All the storage configs +storage = hishel.S3Storage( + bucket_name="my_bucket_name", # store my cache files in the `my_bucket_name` bucket + ttl=3600, # delete the response if it is in the cache for more than an hour +) +client = hishel.CacheClient(controller=controller, storage=storage) -cache_transport.handle_request(req) -cache_transport.handle_request(req) # takes from the cache -``` -**Connection Pool** example: +# Ignore the fact that the server does not recommend you cache this request! +client.post( + "https://example.com", + extensions={"force_cache": True} +) -```python -import httpcore -import hishel - -pool = hishel.CacheConnectionPool(pool=httpcore.ConnectionPool()) +# Return a regular response if it is in the cache; else, return a 504 status code. DO NOT SEND A REQUEST! +client.post( + "https://example.com", + headers=[("Cache-Control", "only-if-cached")] +) -pool.request("GET", "https://hishel.com") -pool.request("GET", "https://hishel.com") # takes from the cache +# Ignore cached responses and do not store incoming responses! +response = client.post( + "https://example.com", + extensions={"cache_disabled": True} +) ``` ## Support the project diff --git a/hishel/__init__.py b/hishel/__init__.py index 853e7c19..372d3d3f 100644 --- a/hishel/__init__.py +++ b/hishel/__init__.py @@ -14,4 +14,4 @@ def install_cache() -> None: # pragma: no cover httpx.Client = CacheClient # type: ignore -__version__ = "0.0.22" +__version__ = "0.0.23"