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

hishel/_sync/_transports.py

@@ -1,282 +0,0 @@
-from __future__ import annotations
-
-import types
-import typing as tp
-
-import httpcore
-import httpx
-from httpx import SyncByteStream, Request, Response
-from httpx._exceptions import ConnectError
-
-from .._controller import Controller, allowed_stale
-from .._headers import parse_cache_control
-from .._serializers import JSONSerializer, Metadata
-from .._utils import extract_header_values_decoded, normalized_url
-from ._storages import BaseStorage, FileStorage
-
-if tp.TYPE_CHECKING:  # pragma: no cover
-    from typing_extensions import Self
-
-__all__ = ("CacheTransport",)
-
-
-def fake_stream(content: bytes) -> tp.Iterable[bytes]:
-    yield content
-
-
-def generate_504() -> Response:
-    return Response(status_code=504)
-
-
-class CacheStream(SyncByteStream):
-    def __init__(self, httpcore_stream: tp.Iterable[bytes]):
-        self._httpcore_stream = httpcore_stream
-
-    def __iter__(self) -> tp.Iterator[bytes]:
-        for part in self._httpcore_stream:
-            yield part
-
-    def close(self) -> None:
-        if hasattr(self._httpcore_stream, "close"):
-            self._httpcore_stream.close()
-
-
-class CacheTransport(httpx.BaseTransport):
-    """
-    An HTTPX Transport that supports HTTP caching.
-
-    :param transport: `Transport` that our class wraps in order to add an HTTP Cache layer on top of
-    :type transport: httpx.BaseTransport
-    :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,
-        transport: httpx.BaseTransport,
-        storage: tp.Optional[BaseStorage] = None,
-        controller: tp.Optional[Controller] = None,
-    ) -> None:
-        self._transport = transport
-
-        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: httpx.Request
-        :return: An HTTP response
-        :rtype: httpx.Response
-        """
-
-        if request.extensions.get("cache_disabled", False):
-            request.headers.update(
-                [
-                    ("Cache-Control", "no-store"),
-                    ("Cache-Control", "no-cache"),
-                    *[("cache-control", value) for value in request.headers.get_list("cache-control")],
-                ]
-            )
-
-        if request.method not in ["GET", "HEAD"]:
-            # If the HTTP method is, for example, POST,
-            # we must also use the request data to generate the hash.
-            body_for_key = request.read()
-            request.stream = CacheStream(fake_stream(body_for_key))
-        else:
-            body_for_key = b""
-
-        # Construct the HTTPCore request because Controllers and Storages work with HTTPCore requests.
-        httpcore_request = httpcore.Request(
-            method=request.method,
-            url=httpcore.URL(
-                scheme=request.url.raw_scheme,
-                host=request.url.raw_host,
-                port=request.url.port,
-                target=request.url.raw_path,
-            ),
-            headers=request.headers.raw,
-            content=request.stream,
-            extensions=request.extensions,
-        )
-
-        key = self._controller._key_generator(httpcore_request, body_for_key)
-        stored_data = self._storage.retrieve(key)
-
-        request_cache_control = parse_cache_control(
-            extract_header_values_decoded(request.headers.raw, 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=httpcore_request,
-                response=stored_response,
-                original_request=stored_request,
-            )
-
-            if isinstance(res, httpcore.Response):
-                # Simply use the response if the controller determines it is ready for use.
-                return self._create_hishel_response(
-                    key=key,
-                    response=res,
-                    request=httpcore_request,
-                    cached=True,
-                    revalidated=False,
-                    metadata=metadata,
-                )
-
-            if request_cache_control.only_if_cached:
-                return generate_504()
-
-            if isinstance(res, httpcore.Request):
-                # Controller has determined that the response needs to be re-validated.
-                assert isinstance(res.stream, tp.Iterable)
-                revalidation_request = Request(
-                    method=res.method.decode(),
-                    url=normalized_url(res.url),
-                    headers=res.headers,
-                    stream=CacheStream(res.stream),
-                    extensions=res.extensions,
-                )
-                try:
-                    revalidation_response = self._transport.handle_request(revalidation_request)
-                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=httpcore_request,
-                            cached=True,
-                            revalidated=False,
-                            metadata=metadata,
-                        )
-                    raise  # pragma: no cover
-                assert isinstance(revalidation_response.stream, tp.Iterable)
-                httpcore_revalidation_response = httpcore.Response(
-                    status=revalidation_response.status_code,
-                    headers=revalidation_response.headers.raw,
-                    content=CacheStream(revalidation_response.stream),
-                    extensions=revalidation_response.extensions,
-                )
-
-                # Merge headers with the stale response.
-                final_httpcore_response = self._controller.handle_validation_response(
-                    old_response=stored_response,
-                    new_response=httpcore_revalidation_response,
-                )
-
-                final_httpcore_response.read()
-                revalidation_response.close()
-
-                assert isinstance(final_httpcore_response.stream, tp.Iterable)
-
-                # 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_code != 304 and self._controller.is_cachable(
-                    request=httpcore_request, response=final_httpcore_response
-                ):
-                    self._storage.store(key, response=final_httpcore_response, request=httpcore_request)
-
-                return self._create_hishel_response(
-                    key=key,
-                    response=final_httpcore_response,
-                    request=httpcore_request,
-                    cached=revalidation_response.status_code == 304,
-                    revalidated=True,
-                    metadata=metadata,
-                )
-
-        regular_response = self._transport.handle_request(request)
-        try:
-            # Prefer already-read content, if available
-            stream = fake_stream(regular_response.content)
-        except httpx.ResponseNotRead:
-            # Fall back to stream if not yet read
-            assert isinstance(regular_response.stream, tp.Iterable)
-            stream = regular_response.stream
-        httpcore_regular_response = httpcore.Response(
-            status=regular_response.status_code,
-            headers=regular_response.headers.raw,
-            content=CacheStream(stream),
-            extensions=regular_response.extensions,
-        )
-        httpcore_regular_response.read()
-        httpcore_regular_response.close()
-
-        if self._controller.is_cachable(request=httpcore_request, response=httpcore_regular_response):
-            self._storage.store(
-                key,
-                response=httpcore_regular_response,
-                request=httpcore_request,
-            )
-
-        return self._create_hishel_response(
-            key=key,
-            response=httpcore_regular_response,
-            request=httpcore_request,
-            cached=False,
-            revalidated=False,
-        )
-
-    def _create_hishel_response(
-        self,
-        key: str,
-        response: httpcore.Response,
-        request: httpcore.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(
-            status_code=response.status,
-            headers=response.headers,
-            stream=CacheStream(fake_stream(response.content)),
-            extensions=response.extensions,
-        )
-
-    def close(self) -> None:
-        self._storage.close()
-        self._transport.close()
-
-    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[types.TracebackType] = None,
-    ) -> None:
-        self.close()

hishel/_synchronization.py

@@ -1,37 +0,0 @@
-import types
-import typing as tp
-from threading import Lock as T_LOCK
-
-import anyio
-
-
-class AsyncLock:
-    def __init__(self) -> None:
-        self._lock = anyio.Lock()
-
-    async def __aenter__(self) -> None:
-        await self._lock.acquire()
-
-    async def __aexit__(
-        self,
-        exc_type: tp.Optional[tp.Type[BaseException]] = None,
-        exc_value: tp.Optional[BaseException] = None,
-        traceback: tp.Optional[types.TracebackType] = None,
-    ) -> None:
-        self._lock.release()
-
-
-class Lock:
-    def __init__(self) -> None:
-        self._lock = T_LOCK()
-
-    def __enter__(self) -> None:
-        self._lock.acquire()
-
-    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._lock.release()

hishel/beta/_core/_headers.py

@@ -1,301 +0,0 @@
-from __future__ import annotations
-
-import string
-from dataclasses import dataclass
-from typing import Any, Dict, Iterator, List, Literal, Mapping, MutableMapping, Optional, Union, cast
-
-from hishel._exceptions import ParseError, ValidationError
-
-## Grammar
-
-
-HTAB = "\t"
-SP = " "
-obs_text = "".join(chr(i) for i in range(0x80, 0xFF + 1))  # 0x80-0xFF
-
-tchar = "!#$%&'*+-.^_`|~0123456789" + string.ascii_letters
-qdtext = "".join(
-    [
-        HTAB,
-        SP,
-        "\x21",
-        "".join(chr(i) for i in range(0x23, 0x5B + 1)),  # 0x23-0x5b
-        "".join(chr(i) for i in range(0x5D, 0x7E + 1)),  # 0x5D-0x7E
-        obs_text,
-    ]
-)
-
-TIME_FIELDS = [
-    "max_age",
-    "max_stale",
-    "min_fresh",
-    "s_maxage",
-]
-
-BOOLEAN_FIELDS = [
-    "immutable",
-    "must_revalidate",
-    "must_understand",
-    "no_store",
-    "no_transform",
-    "only_if_cached",
-    "public",
-    "proxy_revalidate",
-]
-
-LIST_FIELDS = ["no_cache", "private"]
-
-__all__ = (
-    "CacheControl",
-    "Vary",
-)
-
-
-def strip_ows_around(text: str) -> str:
-    return text.strip(" ").strip("\t")
-
-
-def normalize_directive(text: str) -> str:
-    return text.replace("-", "_")
-
-
-def parse_cache_control(cache_control_value: Optional[str]) -> "CacheControl":
-    if cache_control_value is None:
-        return CacheControl()
-    directives = {}
-
-    if "no-cache=" in cache_control_value or "private=" in cache_control_value:
-        cache_control_splited = [cache_control_value]
-    else:
-        cache_control_splited = cache_control_value.split(",")
-
-    for directive in cache_control_splited:
-        key: str = ""
-        value: Optional[str] = None
-        dquote = False
-
-        if not directive:
-            raise ParseError("The directive should not be left blank.")
-
-        directive = strip_ows_around(directive)
-
-        if not directive:
-            raise ParseError("The directive should not contain only whitespaces.")
-
-        for i, key_char in enumerate(directive):
-            if key_char == "=":
-                value = directive[i + 1 :]
-
-                if not value:
-                    raise ParseError("The directive value cannot be left blank.")
-
-                if value[0] == '"':
-                    dquote = True
-                if dquote and value[-1] != '"':
-                    raise ParseError("Invalid quotes around the value.")
-
-                if not dquote:
-                    for value_char in value:
-                        if value_char not in tchar:
-                            raise ParseError(
-                                f"The character '{value_char!r}' is not permitted for the unquoted values."
-                            )
-                else:
-                    for value_char in value[1:-1]:
-                        if value_char not in qdtext:
-                            raise ParseError(f"The character '{value_char!r}' is not permitted for the quoted values.")
-                break
-
-            if key_char not in tchar:
-                raise ParseError(f"The character '{key_char!r}' is not permitted in the directive name.")
-            key += key_char
-        directives[key] = value
-    validated_data = CacheControl.validate(directives)
-    return CacheControl(**validated_data)
-
-
-class Vary:
-    def __init__(self, values: List[str]) -> None:
-        self.values = values
-
-    @classmethod
-    def from_value(cls, vary_value: str) -> "Vary":
-        values = []
-
-        for field_name in vary_value.split(","):
-            field_name = field_name.strip()
-            values.append(field_name)
-        return Vary(values)
-
-
-@dataclass
-class ContentRange:
-    unit: Literal["bytes"]
-    range: tuple[int, int] | None
-    size: int | None
-
-    @classmethod
-    def from_str(cls, content_range: str) -> "ContentRange":
-        words = [word for word in content_range.split(" ") if word != ""]
-
-        unit = words[0]
-        range, size = words[1].split("/")
-
-        splited_range = range.split("-")
-
-        return cls(
-            unit=cast(Literal["bytes"], unit),
-            range=None if range == "*" else (int(splited_range[0]), int(splited_range[1])),
-            size=None if size == "*" else int(size),
-        )
-
-
-@dataclass
-class Range:
-    unit: Literal["bytes"]
-    range: tuple[int | None, int | None]
-
-    @classmethod
-    def try_from_str(cls, range_header: str) -> "Range" | None:
-        # Example: "bytes=0-99,200-299,-500,100-"
-        unit, values = range_header.split("=")
-        unit = unit.strip()
-        parts = [p.strip() for p in values.split(",")]
-
-        parsed: list[tuple[int | None, int | None]] = []
-        for part in parts:
-            if "-" not in part:
-                raise ValueError(f"Invalid range part: {part}")
-            start_str, end_str = part.split("-", 1)
-            start = int(start_str) if start_str else None
-            end = int(end_str) if end_str else None
-            parsed.append((start, end))
-
-        if len(parsed) != 1:
-            # we don't support multiple ranges
-            return None
-
-        return cls(
-            unit=cast(Literal["bytes"], unit),
-            range=parsed[0],
-        )
-
-
-class CacheControl:
-    def __init__(
-        self,
-        immutable: bool = False,  # [RFC8246]
-        max_age: Optional[int] = None,  # [RFC9111, Section 5.2.1.1, 5.2.2.1]
-        max_stale: Optional[int] = None,  # [RFC9111, Section 5.2.1.2]
-        min_fresh: Optional[int] = None,  # [RFC9111, Section 5.2.1.3]
-        must_revalidate: bool = False,  # [RFC9111, Section 5.2.2.2]
-        must_understand: bool = False,  # [RFC9111, Section 5.2.2.3]
-        no_cache: Union[bool, List[str]] = False,  # [RFC9111, Section 5.2.1.4, 5.2.2.4]
-        no_store: bool = False,  # [RFC9111, Section 5.2.1.5, 5.2.2.5]
-        no_transform: bool = False,  # [RFC9111, Section 5.2.1.6, 5.2.2.6]
-        only_if_cached: bool = False,  # [RFC9111, Section 5.2.1.7]
-        private: Union[bool, List[str]] = False,  # [RFC9111, Section 5.2.2.7]
-        proxy_revalidate: bool = False,  # [RFC9111, Section 5.2.2.8]
-        public: bool = False,  # [RFC9111, Section 5.2.2.9]
-        s_maxage: Optional[int] = None,  # [RFC9111, Section 5.2.2.10]
-    ) -> None:
-        self.immutable = immutable
-        self.max_age = max_age
-        self.max_stale = max_stale
-        self.min_fresh = min_fresh
-        self.must_revalidate = must_revalidate
-        self.must_understand = must_understand
-        self.no_cache = no_cache
-        self.no_store = no_store
-        self.no_transform = no_transform
-        self.only_if_cached = only_if_cached
-        self.private = private
-        self.proxy_revalidate = proxy_revalidate
-        self.public = public
-        self.s_maxage = s_maxage
-
-    @classmethod
-    def validate(cls, directives: Dict[str, Any]) -> Dict[str, Any]:
-        validated_data: Dict[str, Any] = {}
-
-        for key, value in directives.items():
-            key = normalize_directive(key)
-            if key in TIME_FIELDS:
-                if value is None:
-                    raise ValidationError(f"The directive '{key}' necessitates a value.")
-
-                if value[0] == '"' or value[-1] == '"':
-                    raise ValidationError(f"The argument '{key}' should be an integer, but a quote was found.")
-
-                try:
-                    validated_data[key] = int(value)
-                except Exception:
-                    raise ValidationError(f"The argument '{key}' should be an integer, but got '{value!r}'.")
-            elif key in BOOLEAN_FIELDS:
-                if value is not None:
-                    raise ValidationError(f"The directive '{key}' should have no value, but it does.")
-                validated_data[key] = True
-            elif key in LIST_FIELDS:
-                if value is None:
-                    validated_data[key] = True
-                else:
-                    values = []
-                    for list_value in value[1:-1].split(","):
-                        if not list_value:
-                            raise ValidationError("The list value must not be empty.")
-                        list_value = strip_ows_around(list_value)
-                        values.append(list_value)
-                    validated_data[key] = values
-
-        return validated_data
-
-    def __repr__(self) -> str:
-        fields = ""
-
-        for key in TIME_FIELDS:
-            key = key.replace("-", "_")
-            value = getattr(self, key)
-            if value:
-                fields += f"{key}={value}, "
-
-        for key in BOOLEAN_FIELDS:
-            key = key.replace("-", "_")
-            value = getattr(self, key)
-            if value:
-                fields += f"{key}, "
-
-        fields = fields[:-2]
-
-        return f"<{type(self).__name__} {fields}>"
-
-
-class Headers(MutableMapping[str, str]):
-    def __init__(self, headers: Mapping[str, Union[str, List[str]]]) -> None:
-        self._headers = {k.lower(): ([v] if isinstance(v, str) else v[:]) for k, v in headers.items()}
-
-    def get_list(self, key: str) -> Optional[List[str]]:
-        return self._headers.get(key.lower(), None)
-
-    def __getitem__(self, key: str) -> str:
-        return ", ".join(self._headers[key.lower()])
-
-    def __setitem__(self, key: str, value: str) -> None:
-        self._headers.setdefault(key.lower(), []).append(value)
-
-    def __delitem__(self, key: str) -> None:
-        del self._headers[key.lower()]
-
-    def __iter__(self) -> Iterator[str]:
-        return iter(self._headers)
-
-    def __len__(self) -> int:
-        return len(self._headers)
-
-    def __repr__(self) -> str:
-        return repr(self._headers)
-
-    def __str__(self) -> str:
-        return str(self._headers)
-
-    def __eq__(self, other_headers: Any) -> bool:
-        return isinstance(other_headers, Headers) and self._headers == other_headers._headers  # type: ignore