Version 0.0.23 (#184)

* Version 0.0.23

* Change README text

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)

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?

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

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"