hishel 0.1.4__py3-none-any.whl → 1.0.0.dev0__py3-none-any.whl

hishel/_serializers.py

@@ -1,329 +0,0 @@
-import base64
-import json
-import pickle
-import typing as tp
-from datetime import datetime
-
-from httpcore import Request, Response
-
-from ._utils import normalized_url
-
-try:
-    import yaml
-except ImportError:  # pragma: no cover
-    yaml = None  # type: ignore
-
-HEADERS_ENCODING = "iso-8859-1"
-KNOWN_RESPONSE_EXTENSIONS = ("http_version", "reason_phrase")
-KNOWN_REQUEST_EXTENSIONS = ("timeout", "sni_hostname")
-
-__all__ = ("BaseSerializer", "JSONSerializer", "Metadata", "PickleSerializer", "YAMLSerializer", "clone_model")
-
-T = tp.TypeVar("T", Request, Response)
-
-
-def clone_model(model: T) -> T:
-    if isinstance(model, Response):
-        return Response(
-            status=model.status,
-            headers=model.headers,
-            content=model.content,
-            extensions={key: value for key, value in model.extensions.items() if key in KNOWN_RESPONSE_EXTENSIONS},
-        )  # type: ignore
-    else:
-        return Request(
-            method=model.method,
-            url=normalized_url(model.url),
-            headers=model.headers,
-            extensions={key: value for key, value in model.extensions.items() if key in KNOWN_REQUEST_EXTENSIONS},
-        )  # type: ignore
-
-
-class Metadata(tp.TypedDict):
-    number_of_uses: int
-    created_at: datetime
-    cache_key: str
-
-
-class BaseSerializer:
-    def dumps(self, response: Response, request: Request, metadata: Metadata) -> tp.Union[str, bytes]:
-        raise NotImplementedError()
-
-    def loads(self, data: tp.Union[str, bytes]) -> tp.Tuple[Response, Request, Metadata]:
-        raise NotImplementedError()
-
-    @property
-    def is_binary(self) -> bool:
-        raise NotImplementedError()
-
-
-class PickleSerializer(BaseSerializer):
-    """
-    A simple pickle-based serializer.
-    """
-
-    def dumps(self, response: Response, request: Request, metadata: Metadata) -> tp.Union[str, bytes]:
-        """
-        Dumps the HTTP response and its HTTP request.
-
-        :param response: An HTTP response
-        :type response: Response
-        :param request: An HTTP request
-        :type request: Request
-        :param metadata: Additional information about the stored response
-        :type metadata: Metadata
-        :return: Serialized response
-        :rtype: tp.Union[str, bytes]
-        """
-        clone_response = clone_model(response)
-        clone_request = clone_model(request)
-        return pickle.dumps((clone_response, clone_request, metadata))
-
-    def loads(self, data: tp.Union[str, bytes]) -> tp.Tuple[Response, Request, Metadata]:
-        """
-        Loads the HTTP response and its HTTP request from serialized data.
-
-        :param data: Serialized data
-        :type data: tp.Union[str, bytes]
-        :return: HTTP response and its HTTP request
-        :rtype: tp.Tuple[Response, Request, Metadata]
-        """
-        assert isinstance(data, bytes)
-        return tp.cast(tp.Tuple[Response, Request, Metadata], pickle.loads(data))
-
-    @property
-    def is_binary(self) -> bool:  # pragma: no cover
-        return True
-
-
-class JSONSerializer(BaseSerializer):
-    """A simple json-based serializer."""
-
-    def dumps(self, response: Response, request: Request, metadata: Metadata) -> tp.Union[str, bytes]:
-        """
-        Dumps the HTTP response and its HTTP request.
-
-        :param response: An HTTP response
-        :type response: Response
-        :param request: An HTTP request
-        :type request: Request
-        :param metadata: Additional information about the stored response
-        :type metadata: Metadata
-        :return: Serialized response
-        :rtype: tp.Union[str, bytes]
-        """
-        response_dict = {
-            "status": response.status,
-            "headers": [
-                (key.decode(HEADERS_ENCODING), value.decode(HEADERS_ENCODING)) for key, value in response.headers
-            ],
-            "content": base64.b64encode(response.content).decode("ascii"),
-            "extensions": {
-                key: value.decode("ascii")
-                for key, value in response.extensions.items()
-                if key in KNOWN_RESPONSE_EXTENSIONS
-            },
-        }
-
-        request_dict = {
-            "method": request.method.decode("ascii"),
-            "url": normalized_url(request.url),
-            "headers": [
-                (key.decode(HEADERS_ENCODING), value.decode(HEADERS_ENCODING)) for key, value in request.headers
-            ],
-            "extensions": {key: value for key, value in request.extensions.items() if key in KNOWN_REQUEST_EXTENSIONS},
-        }
-
-        metadata_dict = {
-            "cache_key": metadata["cache_key"],
-            "number_of_uses": metadata["number_of_uses"],
-            "created_at": metadata["created_at"].strftime("%a, %d %b %Y %H:%M:%S GMT"),
-        }
-
-        full_json = {
-            "response": response_dict,
-            "request": request_dict,
-            "metadata": metadata_dict,
-        }
-
-        return json.dumps(full_json, indent=4)
-
-    def loads(self, data: tp.Union[str, bytes]) -> tp.Tuple[Response, Request, Metadata]:
-        """
-        Loads the HTTP response and its HTTP request from serialized data.
-
-        :param data: Serialized data
-        :type data: tp.Union[str, bytes]
-        :return: HTTP response and its HTTP request
-        :rtype: tp.Tuple[Response, Request, Metadata]
-        """
-
-        full_json = json.loads(data)
-
-        response_dict = full_json["response"]
-        request_dict = full_json["request"]
-        metadata_dict = full_json["metadata"]
-        metadata_dict["created_at"] = datetime.strptime(
-            metadata_dict["created_at"],
-            "%a, %d %b %Y %H:%M:%S GMT",
-        )
-
-        response = Response(
-            status=response_dict["status"],
-            headers=[
-                (key.encode(HEADERS_ENCODING), value.encode(HEADERS_ENCODING))
-                for key, value in response_dict["headers"]
-            ],
-            content=base64.b64decode(response_dict["content"].encode("ascii")),
-            extensions={
-                key: value.encode("ascii")
-                for key, value in response_dict["extensions"].items()
-                if key in KNOWN_RESPONSE_EXTENSIONS
-            },
-        )
-
-        request = Request(
-            method=request_dict["method"],
-            url=request_dict["url"],
-            headers=[
-                (key.encode(HEADERS_ENCODING), value.encode(HEADERS_ENCODING)) for key, value in request_dict["headers"]
-            ],
-            extensions={
-                key: value for key, value in request_dict["extensions"].items() if key in KNOWN_REQUEST_EXTENSIONS
-            },
-        )
-
-        metadata = Metadata(
-            cache_key=metadata_dict["cache_key"],
-            created_at=metadata_dict["created_at"],
-            number_of_uses=metadata_dict["number_of_uses"],
-        )
-
-        return response, request, metadata
-
-    @property
-    def is_binary(self) -> bool:
-        return False
-
-
-class YAMLSerializer(BaseSerializer):
-    """A simple yaml-based serializer."""
-
-    def dumps(self, response: Response, request: Request, metadata: Metadata) -> tp.Union[str, bytes]:
-        """
-        Dumps the HTTP response and its HTTP request.
-
-        :param response: An HTTP response
-        :type response: Response
-        :param request: An HTTP request
-        :type request: Request
-        :param metadata: Additional information about the stored response
-        :type metadata: Metadata
-        :return: Serialized response
-        :rtype: tp.Union[str, bytes]
-        """
-        if yaml is None:  # pragma: no cover
-            raise RuntimeError(
-                f"The `{type(self).__name__}` was used, but the required packages were not found. "
-                "Check that you have `Hishel` installed with the `yaml` extension as shown.\n"
-                "```pip install hishel[yaml]```"
-            )
-        response_dict = {
-            "status": response.status,
-            "headers": [
-                (key.decode(HEADERS_ENCODING), value.decode(HEADERS_ENCODING)) for key, value in response.headers
-            ],
-            "content": base64.b64encode(response.content).decode("ascii"),
-            "extensions": {
-                key: value.decode("ascii")
-                for key, value in response.extensions.items()
-                if key in KNOWN_RESPONSE_EXTENSIONS
-            },
-        }
-
-        request_dict = {
-            "method": request.method.decode("ascii"),
-            "url": normalized_url(request.url),
-            "headers": [
-                (key.decode(HEADERS_ENCODING), value.decode(HEADERS_ENCODING)) for key, value in request.headers
-            ],
-            "extensions": {key: value for key, value in request.extensions.items() if key in KNOWN_REQUEST_EXTENSIONS},
-        }
-
-        metadata_dict = {
-            "cache_key": metadata["cache_key"],
-            "number_of_uses": metadata["number_of_uses"],
-            "created_at": metadata["created_at"].strftime("%a, %d %b %Y %H:%M:%S GMT"),
-        }
-
-        full_json = {
-            "response": response_dict,
-            "request": request_dict,
-            "metadata": metadata_dict,
-        }
-
-        return yaml.safe_dump(full_json, sort_keys=False)
-
-    def loads(self, data: tp.Union[str, bytes]) -> tp.Tuple[Response, Request, Metadata]:
-        """
-        Loads the HTTP response and its HTTP request from serialized data.
-
-        :param data: Serialized data
-        :type data: tp.Union[str, bytes]
-        :raises RuntimeError: When used without the `yaml` extension installed
-        :return: HTTP response and its HTTP request
-        :rtype: tp.Tuple[Response, Request, Metadata]
-        """
-        if yaml is None:  # pragma: no cover
-            raise RuntimeError(
-                f"The `{type(self).__name__}` was used, but the required packages were not found. "
-                "Check that you have `Hishel` installed with the `yaml` extension as shown.\n"
-                "```pip install hishel[yaml]```"
-            )
-
-        full_json = yaml.safe_load(data)
-
-        response_dict = full_json["response"]
-        request_dict = full_json["request"]
-        metadata_dict = full_json["metadata"]
-        metadata_dict["created_at"] = datetime.strptime(
-            metadata_dict["created_at"],
-            "%a, %d %b %Y %H:%M:%S GMT",
-        )
-
-        response = Response(
-            status=response_dict["status"],
-            headers=[
-                (key.encode(HEADERS_ENCODING), value.encode(HEADERS_ENCODING))
-                for key, value in response_dict["headers"]
-            ],
-            content=base64.b64decode(response_dict["content"].encode("ascii")),
-            extensions={
-                key: value.encode("ascii")
-                for key, value in response_dict["extensions"].items()
-                if key in KNOWN_RESPONSE_EXTENSIONS
-            },
-        )
-
-        request = Request(
-            method=request_dict["method"],
-            url=request_dict["url"],
-            headers=[
-                (key.encode(HEADERS_ENCODING), value.encode(HEADERS_ENCODING)) for key, value in request_dict["headers"]
-            ],
-            extensions={
-                key: value for key, value in request_dict["extensions"].items() if key in KNOWN_REQUEST_EXTENSIONS
-            },
-        )
-
-        metadata = Metadata(
-            cache_key=metadata_dict["cache_key"],
-            created_at=metadata_dict["created_at"],
-            number_of_uses=metadata_dict["number_of_uses"],
-        )
-
-        return response, request, metadata
-
-    @property
-    def is_binary(self) -> bool:  # pragma: no cover
-        return False

hishel/_sync/__init__.py

@@ -1,5 +0,0 @@
-from ._client import *  # noqa: F403
-from ._mock import *  # noqa: F403
-from ._pool import *  # noqa: F403
-from ._storages import *  # noqa: F403
-from ._transports import *  # noqa: F403

hishel/_sync/_client.py

@@ -1,30 +0,0 @@
-import typing as tp
-
-import httpx
-
-from ._transports import CacheTransport
-
-__all__ = ("CacheClient",)
-
-
-class CacheClient(httpx.Client):
-    def __init__(self, *args: tp.Any, **kwargs: tp.Any):
-        self._storage = kwargs.pop("storage") if "storage" in kwargs else None
-        self._controller = kwargs.pop("controller") if "controller" in kwargs else None
-        super().__init__(*args, **kwargs)
-
-    def _init_transport(self, *args, **kwargs) -> CacheTransport:  # type: ignore
-        _transport = super()._init_transport(*args, **kwargs)
-        return CacheTransport(
-            transport=_transport,
-            storage=self._storage,
-            controller=self._controller,
-        )
-
-    def _init_proxy_transport(self, *args, **kwargs) -> CacheTransport:  # type: ignore
-        _transport = super()._init_proxy_transport(*args, **kwargs)  # pragma: no cover
-        return CacheTransport(  # pragma: no cover
-            transport=_transport,
-            storage=self._storage,
-            controller=self._controller,
-        )

hishel/_sync/_mock.py

@@ -1,43 +0,0 @@
-import typing as tp
-from types import TracebackType
-
-import httpcore
-import httpx
-from httpcore._sync.interfaces import RequestInterface
-
-if tp.TYPE_CHECKING:  # pragma: no cover
-    from typing_extensions import Self
-
-__all__ = ("MockConnectionPool", "MockTransport")
-
-
-class MockConnectionPool(RequestInterface):
-    def handle_request(self, request: httpcore.Request) -> httpcore.Response:
-        assert isinstance(request.stream, tp.Iterable)
-        data = b"".join([chunk for chunk in request.stream])  # noqa: F841
-        return self.mocked_responses.pop(0)
-
-    def add_responses(self, responses: tp.List[httpcore.Response]) -> None:
-        if not hasattr(self, "mocked_responses"):
-            self.mocked_responses = []
-        self.mocked_responses.extend(responses)
-
-    def __enter__(self) -> "Self":
-        return self
-
-    def __exit__(
-        self,
-        exc_type: tp.Optional[tp.Type[BaseException]] = None,
-        exc_value: tp.Optional[BaseException] = None,
-        traceback: tp.Optional[TracebackType] = None,
-    ) -> None: ...
-
-
-class MockTransport(httpx.BaseTransport):
-    def handle_request(self, request: httpx.Request) -> httpx.Response:
-        return self.mocked_responses.pop(0)
-
-    def add_responses(self, responses: tp.List[httpx.Response]) -> None:
-        if not hasattr(self, "mocked_responses"):
-            self.mocked_responses = []
-        self.mocked_responses.extend(responses)

hishel/_sync/_pool.py

@@ -1,201 +0,0 @@
-from __future__ import annotations
-
-import types
-import typing as tp
-
-from httpcore._sync.interfaces import RequestInterface
-from httpcore._exceptions import ConnectError
-from httpcore._models import Request, Response
-
-from .._controller import Controller, allowed_stale
-from .._headers import parse_cache_control
-from .._serializers import JSONSerializer, Metadata
-from .._utils import extract_header_values_decoded
-from ._storages import BaseStorage, FileStorage
-
-T = tp.TypeVar("T")
-
-__all__ = ("CacheConnectionPool",)
-
-
-def fake_stream(content: bytes) -> tp.Iterable[bytes]:
-    yield content
-
-
-def generate_504() -> Response:
-    return Response(status=504)
-
-
-class CacheConnectionPool(RequestInterface):
-    """An HTTP Core Connection Pool that supports HTTP caching.
-
-    :param pool: `Connection Pool` that our class wraps in order to add an HTTP Cache layer on top of
-    :type pool: RequestInterface
-    :param storage: Storage that handles how the responses should be saved., defaults to None
-    :type storage: tp.Optional[BaseStorage], optional
-    :param controller: Controller that manages the cache behavior at the specification level, defaults to None
-    :type controller: tp.Optional[Controller], optional
-    """
-
-    def __init__(
-        self,
-        pool: RequestInterface,
-        storage: tp.Optional[BaseStorage] = None,
-        controller: tp.Optional[Controller] = None,
-    ) -> None:
-        self._pool = pool
-
-        self._storage = storage if storage is not None else FileStorage(serializer=JSONSerializer())
-
-        if not isinstance(self._storage, BaseStorage):  # pragma: no cover
-            raise TypeError(f"Expected subclass of `BaseStorage` but got `{storage.__class__.__name__}`")
-
-        self._controller = controller if controller is not None else Controller()
-
-    def handle_request(self, request: Request) -> Response:
-        """
-        Handles HTTP requests while also implementing HTTP caching.
-
-        :param request: An HTTP request
-        :type request: httpcore.Request
-        :return: An HTTP response
-        :rtype: httpcore.Response
-        """
-
-        if request.extensions.get("cache_disabled", False):
-            request.headers.extend([(b"cache-control", b"no-cache"), (b"cache-control", b"max-age=0")])
-
-        if request.method.upper() not in [b"GET", b"HEAD"]:
-            # If the HTTP method is, for example, POST,
-            # we must also use the request data to generate the hash.
-            assert isinstance(request.stream, tp.Iterable)
-            body_for_key = b"".join([chunk for chunk in request.stream])
-            request.stream = fake_stream(body_for_key)
-        else:
-            body_for_key = b""
-
-        key = self._controller._key_generator(request, body_for_key)
-        stored_data = self._storage.retrieve(key)
-
-        request_cache_control = parse_cache_control(extract_header_values_decoded(request.headers, b"Cache-Control"))
-
-        if request_cache_control.only_if_cached and not stored_data:
-            return generate_504()
-
-        if stored_data:
-            # Try using the stored response if it was discovered.
-
-            stored_response, stored_request, metadata = stored_data
-
-            # Immediately read the stored response to avoid issues when trying to access the response body.
-            stored_response.read()
-
-            res = self._controller.construct_response_from_cache(
-                request=request,
-                response=stored_response,
-                original_request=stored_request,
-            )
-
-            if isinstance(res, Response):
-                # Simply use the response if the controller determines it is ready for use.
-                return self._create_hishel_response(
-                    key=key,
-                    response=stored_response,
-                    request=request,
-                    metadata=metadata,
-                    cached=True,
-                    revalidated=False,
-                )
-
-            if request_cache_control.only_if_cached:
-                return generate_504()
-
-            if isinstance(res, Request):
-                # Controller has determined that the response needs to be re-validated.
-
-                try:
-                    revalidation_response = self._pool.handle_request(res)
-                except ConnectError:
-                    # If there is a connection error, we can use the stale response if allowed.
-                    if self._controller._allow_stale and allowed_stale(response=stored_response):
-                        return self._create_hishel_response(
-                            key=key,
-                            response=stored_response,
-                            request=request,
-                            metadata=metadata,
-                            cached=True,
-                            revalidated=False,
-                        )
-                    raise  # pragma: no cover
-                # Merge headers with the stale response.
-                final_response = self._controller.handle_validation_response(
-                    old_response=stored_response, new_response=revalidation_response
-                )
-
-                final_response.read()
-
-                # RFC 9111: 4.3.3. Handling a Validation Response
-                # A 304 (Not Modified) response status code indicates that the stored response can be updated and
-                # reused. A full response (i.e., one containing content) indicates that none of the stored responses
-                # nominated in the conditional request are suitable. Instead, the cache MUST use the full response to
-                # satisfy the request. The cache MAY store such a full response, subject to its constraints.
-                if revalidation_response.status != 304 and self._controller.is_cachable(
-                    request=request, response=final_response
-                ):
-                    self._storage.store(key, response=final_response, request=request)
-
-                return self._create_hishel_response(
-                    key=key,
-                    response=final_response,
-                    request=request,
-                    cached=revalidation_response.status == 304,
-                    revalidated=True,
-                    metadata=metadata,
-                )
-
-        regular_response = self._pool.handle_request(request)
-        regular_response.read()
-
-        if self._controller.is_cachable(request=request, response=regular_response):
-            self._storage.store(key, response=regular_response, request=request)
-
-        return self._create_hishel_response(
-            key=key, response=regular_response, request=request, cached=False, revalidated=False
-        )
-
-    def _create_hishel_response(
-        self,
-        key: str,
-        response: Response,
-        request: Request,
-        cached: bool,
-        revalidated: bool,
-        metadata: Metadata | None = None,
-    ) -> Response:
-        if cached:
-            assert metadata
-            metadata["number_of_uses"] += 1
-            self._storage.update_metadata(key=key, request=request, response=response, metadata=metadata)
-            response.extensions["from_cache"] = True  # type: ignore[index]
-            response.extensions["cache_metadata"] = metadata  # type: ignore[index]
-        else:
-            response.extensions["from_cache"] = False  # type: ignore[index]
-        response.extensions["revalidated"] = revalidated  # type: ignore[index]
-        return response
-
-    def close(self) -> None:
-        self._storage.close()
-
-        if hasattr(self._pool, "close"):  # pragma: no cover
-            self._pool.close()
-
-    def __enter__(self: T) -> T:
-        return self
-
-    def __exit__(
-        self,
-        exc_type: tp.Optional[tp.Type[BaseException]] = None,
-        exc_value: tp.Optional[BaseException] = None,
-        traceback: tp.Optional[types.TracebackType] = None,
-    ) -> None:
-        self.close()