Merge branch 'master' into dependabot/pip/ruff-0.6.3

.github/workflows/main.yml

@@ -13,7 +13,7 @@ jobs:
 
     strategy:
       matrix:
-        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12" ]
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13" ]
 
     env: 
       CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}

.github/workflows/publish.yml

@@ -16,7 +16,7 @@ jobs:
       - uses: "actions/checkout@v4"
       - uses: "actions/setup-python@v5"
         with:
-          python-version: 3.8
+          python-version: 3.13
       - name: "Install dependencies"
         run: "pip install -r requirements.txt"
       - name: "Build"

CHANGELOG.md

@@ -1,8 +1,27 @@
 # Changelog
 
-## development
+## 0.1.1 (2nd Nov, 2024)
+
+- FIx typig extensions nor found. (#290)
+
+## 0.1.0 (2nd Nov, 2024)
+
+- Add support for Python 3.12 / drop Python 3.8. (#286)
+- Specify usedforsecurity=False in blake2b. (#285)
+
+## 0.0.33 (4th Oct, 2024)
+
+- Added a [Logging](https://hishel.com/advanced/logging/) section to the documentation.
+
+## 0.0.32 (27th Sep, 2024)
+
+- Don't raise an exception if the `Date` header is not present. (#273)
+
+## 0.0.31 (22nd Sep, 2024)
 
 - Ignore file not found error when cleaning up a file storage. (#264)  
+- Fix `AssertionError` on `client.close()` when use SQLiteStorage. (#269)  
+- Fix ignored flags when use `force_cache`. (#271)  
 
 ## 0.0.30 (12th July, 2024)
 

README.md

@@ -1,8 +1,15 @@
-<p align="center">
-  <a href=""><img width="350" height="250" src="https://raw.githubusercontent.com/karpetrosyan/hishel/master/.github/logo.jpg" alt='HTTPX'></a>
+<p align="center" class="logo">
+    <div align="center">
+        <picture>
+            <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/karpetrosyan/hishel/master/docs/static/Shelkopryad_350x250_yellow.png">
+            <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/karpetrosyan/hishel/master/docs/static/Shelkopryad_350x250_black.png">
+            <img alt="Logo" src="https://raw.githubusercontent.com/karpetrosyan/hishel/master/docs/static/Shelkopryad_350x250_yellow.png">
+        </picture>
+    </div>
 </p>
 
 
+
 <p align="center"><strong>Hishel</strong> <em>- An elegant HTTP Cache implementation for httpx and httpcore.</em></p>
 
 <p align="center">

docs/advanced/logging.md

@@ -0,0 +1,73 @@
+---
+icon: material/file-document-edit
+---
+
+[Logging](https://en.wikipedia.org/wiki/Logging_(computing)) is an important part of every application that helps developers better understand how the program operates. Hishel supports a variety of logs that can show you how the library impacts your program.
+
+Hishel will support several loggers for different parts of the program. Currently, we support only one logger called `hishel.controller`, which logs any event related to the cache. For example, it logs when a response is considered stale, when revalidation occurs, when a response is used from the cache, and more.
+
+## Controller logs
+
+The [controller](./controllers.md) is a part of the Hishel library that interprets the caching specification. It determines whether a response can be cached or retrieved from the cache.
+
+You can configure the controller logger for debugging purposes or to better understand how caching works. It can also be crucial when you're just starting out and want to understand why a particular response isn't being cached.
+
+For example, let's enable logging and see what gets logged when making an HTTP request to the Hishel documentation.
+
+```python
+import logging
+import hishel
+
+logging.basicConfig(
+    level=logging.WARNING,
+    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+)
+logging.getLogger("hishel.controller").setLevel(logging.DEBUG)
+
+client = hishel.CacheClient()
+
+response = client.get(
+    "https://hishel.com",
+)
+```
+
+Here is what Hishel will log for this program:
+
+```
+2024-09-30 16:32:34,799 - hishel.controller - DEBUG - Considering the resource located at https://hishel.com/ as cachable since it meets the criteria for being stored in the cache.
+```
+
+If you run this program a second time, you will receive the response from the cache because hishel.com sends all the necessary caching headers. So, for the second run, you will see a log entry about the successfully reused response.
+
+```
+2024-09-30 16:35:14,102 - hishel.controller - DEBUG - Considering the resource located at https://hishel.com/ as valid for cache use since it is fresh.
+```
+
+If we wait some time, the cached response will, of course, become stale. After some time, you can run this program again and see that the response needs to be revalidated from the server to obtain the most recent data. The logs could look like this:
+
+```
+2024-09-30 16:39:42,502 - hishel.controller - DEBUG - Considering the resource located at https://hishel.com/ as needing revalidation since it is not fresh.
+2024-09-30 16:39:42,502 - hishel.controller - DEBUG - Adding the 'If-Modified-Since' header with the value of 'Fri, 27 Sep 2024 07:42:28 GMT' to the request for the resource located at https://hishel.com/.
+```
+
+The controller will indicate not only that the response was cached but also why it was considered cacheable.
+
+Examples:
+
+- For permanent redirects
+```
+2024-09-30 16:43:04,672 - hishel.controller - DEBUG - Considering the resource located at https://www.github.com/ as cachable since its status code is a permanent redirect.
+```
+
+- When [force_cache](./extensions.md#force_cache) is enabled
+```
+2024-09-30 16:45:10,468 - hishel.controller - DEBUG - Considering the resource located at https://www.google.com/ as valid for cache use since the request is forced to use the cache.
+```
+
+Or when it's considered as not cachable
+
+```
+2024-09-30 17:02:24,961 - hishel.controller - DEBUG - Considering the resource located at https://www.python.org/ as not cachable since it does not contain any of the required cache directives.
+```
+
+[Here](https://github.com/karpetrosyan/hishel/pull/275) you can find a full list of the controller logs. Note that this is the list of initial logs; any logs added later will not be updated in this list.

docs/index.md

@@ -1,5 +1,8 @@
-<p align="center">
-  <a href=""><img width="350" height="250" src="https://raw.githubusercontent.com/karpetrosyan/hishel/master/.github/logo.jpg" alt='HTTPX'></a>
+<p align="center" class="logo">
+    <div align="center">
+        <a href=""><img width="350" height="250" src="https://raw.githubusercontent.com/karpetrosyan/hishel/master/docs/static/Shelkopryad_350x250_yellow.png#only-dark" alt='HTTPX'></a>
+        <a href=""><img width="350" height="250" src="https://raw.githubusercontent.com/karpetrosyan/hishel/master/docs/static/Shelkopryad_350x250_black.png#only-light" alt='HTTPX'></a>
+    </div>
 </p>
 
 

hishel/__init__.py

@@ -14,4 +14,4 @@ def install_cache() -> None:  # pragma: no cover
     httpx.Client = CacheClient  # type: ignore
 
 
-__version__ = "0.0.30"
+__version__ = "0.1.1"

hishel/_async/_storages.py

@@ -23,7 +23,9 @@
     anysqlite = None  # type: ignore
 
 from httpcore import Request, Response
-from typing_extensions import TypeAlias
+
+if t.TYPE_CHECKING:  # pragma: no cover
+    from typing_extensions import TypeAlias
 
 from hishel._serializers import BaseSerializer, clone_model
 
@@ -377,8 +379,8 @@ async def retrieve(self, key: str) -> tp.Optional[StoredResponse]:
             return self._serializer.loads(cached_response)
 
     async def aclose(self) -> None:  # pragma: no cover
-        assert self._connection
-        await self._connection.close()
+        if self._connection is not None:
+            await self._connection.close()
 
     async def _remove_expired_caches(self) -> None:
         assert self._connection