hishel 0.0.31__py3-none-any.whl → 0.0.33__py3-none-any.whl

hishel/__init__.py

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

hishel/_controller.py

@@ -1,3 +1,4 @@
+import logging
 import typing as tp
 
 from httpcore import Request, Response
@@ -10,10 +11,13 @@ from ._utils import (
     extract_header_values,
     extract_header_values_decoded,
     generate_key,
+    get_safe_url,
     header_presents,
     parse_date,
 )
 
+logger = logging.getLogger("hishel.controller")
+
 HEURISTICALLY_CACHEABLE_STATUS_CODES = (200, 203, 204, 206, 300, 301, 308, 404, 405, 410, 414, 501)
 HTTP_METHODS = ["GET", "HEAD", "POST", "PUT", "DELETE", "CONNECT", "OPTIONS", "TRACE", "PATCH"]
 
@@ -79,8 +83,10 @@ def get_heuristic_freshness(response: Response, clock: "BaseClock") -> int:
 
 
 def get_age(response: Response, clock: "BaseClock") -> int:
-    if not header_presents(response.headers, b"date"):  # pragma: no cover
-        raise RuntimeError("The `Date` header is missing in the response.")
+    if not header_presents(response.headers, b"date"):
+        # If the response does not have a date header, then it is impossible to calculate the age.
+        # Instead of raising an exception, we return infinity to be sure that the response is not considered fresh.
+        return float("inf")  # type: ignore
 
     date = parse_date(extract_header_values_decoded(response.headers, b"date")[0])
 
@@ -150,16 +156,41 @@ class Controller:
         force_cache = request.extensions.get("force_cache", None)
 
         if response.status not in self._cacheable_status_codes:
+            logger.debug(
+                (
+                    f"Considering the resource located at {get_safe_url(request.url)} "
+                    f"as not cachable since its status code ({response.status})"
+                    " is not in the list of cacheable status codes."
+                )
+            )
             return False
 
         if response.status in (301, 308):
+            logger.debug(
+                (
+                    f"Considering the resource located at {get_safe_url(request.url)} "
+                    "as cachable since its status code is a permanent redirect."
+                )
+            )
             return True
 
         # the request method is understood by the cache
         if method not in self._cacheable_methods:
+            logger.debug(
+                (
+                    f"Considering the resource located at {get_safe_url(request.url)} "
+                    f"as not cachable since the request method ({method}) is not in the list of cacheable methods."
+                )
+            )
             return False
 
         if force_cache if force_cache is not None else self._force_cache:
+            logger.debug(
+                (
+                    f"Considering the resource located at {get_safe_url(request.url)} "
+                    "as cachable since the request is forced to use the cache."
+                )
+            )
             return True
 
         response_cache_control = parse_cache_control(extract_header_values_decoded(response.headers, b"cache-control"))
@@ -167,21 +198,53 @@ class Controller:
 
         # the response status code is final
         if response.status // 100 == 1:
+            logger.debug(
+                (
+                    f"Considering the resource located at {get_safe_url(request.url)} "
+                    "as not cachable since its status code is informational."
+                )
+            )
             return False
 
         # the no-store cache directive is not present (see Section 5.2.2.5)
         if request_cache_control.no_store:
+            logger.debug(
+                (
+                    f"Considering the resource located at {get_safe_url(request.url)} "
+                    "as not cachable since the request contains the no-store directive."
+                )
+            )
             return False
 
         # note that the must-understand cache directive overrides
         # no-store in certain circumstances; see Section 5.2.2.3.
-        if response_cache_control.no_store and not response_cache_control.must_understand:
-            return False
+        if response_cache_control.no_store:
+            if response_cache_control.must_understand:
+                logger.debug(
+                    (
+                        f"Skipping the no-store directive for the resource located at {get_safe_url(request.url)} "
+                        "since the response contains the must-understand directive."
+                    )
+                )
+            else:
+                logger.debug(
+                    (
+                        f"Considering the resource located at {get_safe_url(request.url)} "
+                        "as not cachable since the response contains the no-store directive."
+                    )
+                )
+                return False
 
         # a shared cache must not store a response with private directive
         # Note that we do not implement special handling for the qualified form,
         # which would only forbid storing specified headers.
         if not self._cache_private and response_cache_control.private:
+            logger.debug(
+                (
+                    f"Considering the resource located at {get_safe_url(request.url)} "
+                    "as not cachable since the response contains the private directive."
+                )
+            )
             return False
 
         expires_presents = header_presents(response.headers, b"expires")
@@ -194,6 +257,12 @@ class Controller:
         # - a cache extension that allows it to be cached (see Section 5.2.3); or
         # - a status code that is defined as heuristically cacheable (see Section 4.2.2).
         if self._allow_heuristics and response.status in HEURISTICALLY_CACHEABLE_STATUS_CODES:
+            logger.debug(
+                (
+                    f"Considering the resource located at {get_safe_url(request.url)} "
+                    "as cachable since its status code is heuristically cacheable."
+                )
+            )
             return True
 
         if not any(
@@ -204,8 +273,20 @@ class Controller:
                 response_cache_control.max_age is not None,
             ]
         ):
+            logger.debug(
+                (
+                    f"Considering the resource located at {get_safe_url(request.url)} "
+                    "as not cachable since it does not contain any of the required cache directives."
+                )
+            )
             return False
 
+        logger.debug(
+            (
+                f"Considering the resource located at {get_safe_url(request.url)} "
+                "as cachable since it meets the criteria for being stored in the cache."
+            )
+        )
         # response is a cachable!
         return True
 
@@ -221,11 +302,23 @@ class Controller:
 
         if header_presents(response.headers, b"last-modified"):
             last_modified = extract_header_values(response.headers, b"last-modified", single=True)[0]
+            logger.debug(
+                (
+                    f"Adding the 'If-Modified-Since' header with the value of '{last_modified.decode('ascii')}' "
+                    f"to the request for the resource located at {get_safe_url(request.url)}."
+                )
+            )
         else:
             last_modified = None
 
         if header_presents(response.headers, b"etag"):
             etag = extract_header_values(response.headers, b"etag", single=True)[0]
+            logger.debug(
+                (
+                    f"Adding the 'If-None-Match' header with the value of '{etag.decode('ascii')}' "
+                    f"to the request for the resource located at {get_safe_url(request.url)}."
+                )
+            )
         else:
             etag = None
 
@@ -278,6 +371,12 @@ class Controller:
         # Use of responses with status codes 301 and 308 is always
         # legal as long as they don't adhere to any caching rules.
         if response.status in (301, 308):
+            logger.debug(
+                (
+                    f"Considering the resource located at {get_safe_url(request.url)} "
+                    "as valid for cache use since its status code is a permanent redirect."
+                )
+            )
             return response
 
         response_cache_control = parse_cache_control(extract_header_values_decoded(response.headers, b"Cache-Control"))
@@ -287,11 +386,23 @@ class Controller:
         # response (if any) match those presented (see Section 4.1)
         if not self._validate_vary(request=request, response=response, original_request=original_request):
             # If the vary headers does not match, then do not use the response
+            logger.debug(
+                (
+                    f"Considering the resource located at {get_safe_url(request.url)} "
+                    "as invalid for cache use since the vary headers do not match."
+                )
+            )
             return None  # pragma: no cover
 
         # !!! this should be after the "vary" header validation.
         force_cache = request.extensions.get("force_cache", None)
         if force_cache if force_cache is not None else self._force_cache:
+            logger.debug(
+                (
+                    f"Considering the resource located at {get_safe_url(request.url)} "
+                    "as valid for cache use since the request is forced to use the cache."
+                )
+            )
             return response
 
         # the stored response does not contain the
@@ -303,15 +414,58 @@ class Controller:
             or response_cache_control.must_revalidate
             or request_cache_control.no_cache
         ):
+            if self._always_revalidate:
+                log_text = (
+                    f"Considering the resource located at {get_safe_url(request.url)} "
+                    "as needing revalidation since the cache is set to always revalidate."
+                )
+            elif response_cache_control.no_cache:
+                log_text = (
+                    f"Considering the resource located at {get_safe_url(request.url)} "
+                    "as needing revalidation since the response contains the no-cache directive."
+                )
+            elif response_cache_control.must_revalidate:
+                log_text = (
+                    f"Considering the resource located at {get_safe_url(request.url)} "
+                    "as needing revalidation since the response contains the must-revalidate directive."
+                )
+            elif request_cache_control.no_cache:
+                log_text = (
+                    f"Considering the resource located at {get_safe_url(request.url)} "
+                    "as needing revalidation since the request contains the no-cache directive."
+                )
+            else:
+                assert False, "Unreachable code "  # pragma: no cover
+            logger.debug(log_text)
             self._make_request_conditional(request=request, response=response)
             return request
 
         freshness_lifetime = get_freshness_lifetime(response)
 
         if freshness_lifetime is None:
+            logger.debug(
+                (
+                    "Could not determine the freshness lifetime of "
+                    f"the resource located at {get_safe_url(request.url)}, "
+                    "trying to use heuristics to calculate it."
+                )
+            )
             if self._allow_heuristics and response.status in HEURISTICALLY_CACHEABLE_STATUS_CODES:
                 freshness_lifetime = get_heuristic_freshness(response=response, clock=self._clock)
+                logger.debug(
+                    (
+                        f"Successfully calculated the freshness lifetime of the resource located at "
+                        f"{get_safe_url(request.url)} using heuristics."
+                    )
+                )
             else:
+                logger.debug(
+                    (
+                        "Could not calculate the freshness lifetime of "
+                        f"the resource located at {get_safe_url(request.url)}. "
+                        "Making a conditional request to revalidate the response."
+                    )
+                )
                 # If Freshness cannot be calculated, then send the request
                 self._make_request_conditional(request=request, response=response)
                 return request
@@ -326,6 +480,13 @@ class Controller:
         # be fresh for at least the specified number of seconds.
         if request_cache_control.min_fresh is not None:
             if freshness_lifetime < (age + request_cache_control.min_fresh):
+                logger.debug(
+                    (
+                        f"Considering the resource located at {get_safe_url(request.url)} "
+                        "as invalid for cache use since the time left for "
+                        "freshness is less than the min-fresh directive."
+                    )
+                )
                 return None
 
         # The max-stale request directive indicates that the
@@ -338,7 +499,21 @@ class Controller:
             exceeded_freshness_lifetime = age - freshness_lifetime
 
             if request_cache_control.max_stale < exceeded_freshness_lifetime:
+                logger.debug(
+                    (
+                        f"Considering the resource located at {get_safe_url(request.url)} "
+                        "as invalid for cache use since the freshness lifetime has been exceeded more than max-stale."
+                    )
+                )
                 return None
+            else:
+                logger.debug(
+                    (
+                        f"Considering the resource located at {get_safe_url(request.url)} "
+                        "as valid for cache use since the freshness lifetime has been exceeded less than max-stale."
+                    )
+                )
+                return response
 
         # The max-age request directive indicates that
         # the client prefers a response whose age is
@@ -347,9 +522,12 @@ class Controller:
         # the client does not wish to receive a stale response.
         if request_cache_control.max_age is not None:
             if request_cache_control.max_age < age:
-                return None
-
-            if request_cache_control.max_stale is None and not is_fresh:
+                logger.debug(
+                    (
+                        f"Considering the resource located at {get_safe_url(request.url)} "
+                        "as invalid for cache use since the age of the response exceeds the max-age directive."
+                    )
+                )
                 return None
 
         # the stored response is one of the following:
@@ -357,8 +535,20 @@ class Controller:
         #   allowed to be served stale (see Section 4.2.4), or
         #   successfully validated (see Section 4.3).
         if is_fresh:
+            logger.debug(
+                (
+                    f"Considering the resource located at {get_safe_url(request.url)} "
+                    "as valid for cache use since it is fresh."
+                )
+            )
             return response
         else:
+            logger.debug(
+                (
+                    f"Considering the resource located at {get_safe_url(request.url)} "
+                    "as needing revalidation since it is not fresh."
+                )
+            )
             # Otherwise, make a conditional request
             self._make_request_conditional(request=request, response=response)
             return request

hishel/_utils.py

@@ -6,6 +6,7 @@ from hashlib import blake2b
 
 import anyio
 import httpcore
+import httpx
 
 HEADERS_ENCODING = "iso-8859-1"
 
@@ -33,6 +34,16 @@ def normalized_url(url: tp.Union[httpcore.URL, str, bytes]) -> str:
     assert False, "Invalid type for `normalized_url`"  # pragma: no cover
 
 
+def get_safe_url(url: httpcore.URL) -> str:
+    httpx_url = httpx.URL(bytes(url).decode("ascii"))
+
+    schema = httpx_url.scheme
+    host = httpx_url.host
+    path = httpx_url.path
+
+    return f"{schema}://{host}{path}"
+
+
 def generate_key(request: httpcore.Request, body: bytes = b"") -> str:
     encoded_url = normalized_url(request.url).encode("ascii")
 

{hishel-0.0.31.dist-info → hishel-0.0.33.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: hishel
-Version: 0.0.31
+Version: 0.0.33
 Summary: Persistent cache implementation for httpx and httpcore
 Project-URL: Homepage, https://hishel.com
 Project-URL: Source, https://github.com/karpetrosyan/hishel
@@ -175,6 +175,14 @@ Help us grow and continue developing good software for you ❤️
 
 # Changelog
 
+## 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)  

{hishel-0.0.31.dist-info → hishel-0.0.33.dist-info}/RECORD

@@ -1,5 +1,5 @@
-hishel/__init__.py,sha256=XNbMtsi4tkqZZ6AgwVBDu6BumB6WkK3alKCqk-JVDWs,369
-hishel/_controller.py,sha256=kfWAAtgP4RCYNPH33XeDJRJ-zajqS_w0ZbM0M0CsKiY,15875
+hishel/__init__.py,sha256=PqLQGkHTPzUnEDcEGVCMakiBjeU7jvbg4Pu4opBqbrs,369
+hishel/_controller.py,sha256=F7hj1ePUvau2Wj5r6zzdYr8UXPq4osfmMxkmx_Ig2L8,24390
 hishel/_exceptions.py,sha256=qbg55RNlzwhv5JreWY9Zog_zmmiKdn5degtqJKijuRs,198
 hishel/_files.py,sha256=7J5uX7Nnzd7QQWfYuDGh8v6XGLG3eUDBjoJZ4aTaY1c,2228
 hishel/_headers.py,sha256=TWuHi7sRoeS2xxdNGujKmqWtgncUqfhNGCgHKYpRU-I,7329
@@ -7,7 +7,7 @@ hishel/_lfu_cache.py,sha256=GBxToQI8u_a9TzYnLlZMLhgZ8Lb83boPHzTvIgqV6pA,2707
 hishel/_s3.py,sha256=JqRlygITK5uAryviC15HZKQlKY7etUOPWcazTJeYKBI,3736
 hishel/_serializers.py,sha256=gepVb8JC4aBkGw9kLcbAsyo-1XgK_lzTssLr_8av4SQ,11640
 hishel/_synchronization.py,sha256=xOmU9_8KAWTAv3r8EpqPISrtSF3slyh1J0Sc7ZQO1rg,897
-hishel/_utils.py,sha256=cgLGjBI7H-T_DkYBXiHiEEf8SGjGeZ6Cc2IHbLAZybU,2501
+hishel/_utils.py,sha256=lnnFmDnKNDb_-OxlZncOJK5IEbtJeTywpITpYFf6WOk,2736
 hishel/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 hishel/_async/__init__.py,sha256=_oAltH4emAtUF7_9SSxz_KKGYzSXL34o_EGgGvoPG7E,187
 hishel/_async/_client.py,sha256=AkVSSbNTTHmK0gX6PRYVQ-3aDbuCX2Im4VKbLkwLiBU,1101
@@ -21,7 +21,7 @@ hishel/_sync/_mock.py,sha256=im88tZr-XhP9BpzvIt3uOjndAlNcJvFP7Puv3H-6lKU,1430
 hishel/_sync/_pool.py,sha256=VcAknzyAL2i4-zcyE2fOTmTjfBZ2wkBVNYTvSw0OjVQ,7940
 hishel/_sync/_storages.py,sha256=RYzYXqnv0o2JO3RoEmlEUp0yOg_ungXfz4dLN7UTpIQ,27909
 hishel/_sync/_transports.py,sha256=G3_8SdPwlnrHZRvE1gqFLE4oZadVqNgg5mvxghDMih0,10838
-hishel-0.0.31.dist-info/METADATA,sha256=-hIw1fiLfsgB3RmeHqw4odYGvdE4iezkjqZijkD6JvM,11478
-hishel-0.0.31.dist-info/WHEEL,sha256=1yFddiXMmvYK7QYTqtRNtX66WJ0Mz8PYEiEUoOUUxRY,87
-hishel-0.0.31.dist-info/licenses/LICENSE,sha256=1qQj7pE0V2O9OIedvyOgLGLvZLaPd3nFEup3IBEOZjQ,1493
-hishel-0.0.31.dist-info/RECORD,,
+hishel-0.0.33.dist-info/METADATA,sha256=fVzp5e0XfMlqDkvEzZFfS3F_QfjrUA9wi-A696LNjkc,11694
+hishel-0.0.33.dist-info/WHEEL,sha256=1yFddiXMmvYK7QYTqtRNtX66WJ0Mz8PYEiEUoOUUxRY,87
+hishel-0.0.33.dist-info/licenses/LICENSE,sha256=1qQj7pE0V2O9OIedvyOgLGLvZLaPd3nFEup3IBEOZjQ,1493
+hishel-0.0.33.dist-info/RECORD,,