hishel 0.1.4__py3-none-any.whl → 0.1.5__py3-none-any.whl

hishel/__init__.py

@@ -53,5 +53,5 @@ def install_cache() -> None:  # pragma: no cover
     httpx.Client = CacheClient  # type: ignore
 
 
-__version__ = "0.1.4"
+__version__ = "0.1.5"
 

hishel/beta/_core/_base/_storages/_base.py

@@ -87,6 +87,12 @@ class SyncBaseStorage(ABC):
         """
         raise NotImplementedError()
 
+    def close(self) -> None:
+        """
+        Close any resources held by the storage backend.
+        """
+        pass
+
     def is_soft_deleted(self, pair: IncompletePair | CompletePair) -> bool:
         """
         Check if a pair is soft deleted based on its metadata.
@@ -205,6 +211,12 @@ class AsyncBaseStorage(ABC):
         """
         raise NotImplementedError()
 
+    async def close(self) -> None:
+        """
+        Close any resources held by the storage backend.
+        """
+        pass
+
     def is_soft_deleted(self, pair: IncompletePair | CompletePair) -> bool:
         """
         Check if a pair is soft deleted based on its metadata.

hishel/beta/_core/_headers.py

@@ -1,117 +1,286 @@
 from __future__ import annotations
 
-import string
 from dataclasses import dataclass
-from typing import Any, Dict, Iterator, List, Literal, Mapping, MutableMapping, Optional, Union, cast
+from typing import Any, Iterator, List, Literal, Mapping, MutableMapping, Optional, Union, cast
+
+"""
+HTTP token and quoted-string parsing utilities.
 
-from hishel._exceptions import ParseError, ValidationError
+These functions implement RFC 7230 parsing rules for HTTP/1.1 tokens
+and quoted strings.
+"""
 
-## Grammar
 
+def is_char(c: str) -> bool:
+    """
+    Check if character is a valid ASCII character (0-127).
 
-HTAB = "\t"
-SP = " "
-obs_text = "".join(chr(i) for i in range(0x80, 0xFF + 1))  # 0x80-0xFF
+    Per RFC 7230: CHAR = any US-ASCII character (octets 0 - 127)
+
+    Args:
+        c: Single character string
+
+    Returns:
+        True if character is valid ASCII (0-127), False otherwise
+    """
+    if not c:
+        return False
+    return ord(c) <= 127
+
+
+def is_ctl(c: str) -> bool:
+    """
+    Check if character is a control character.
+
+    Per RFC 7230: CTL = control characters (0-31 and 127)
+
+    Args:
+        c: Single character string
+
+    Returns:
+        True if character is a control character, False otherwise
+    """
+    if not c:
+        return False
+    b = ord(c)
+    return b <= 31 or b == 127
+
+
+def is_separator(c: str) -> bool:
+    """
+    Check if character is an HTTP separator.
+
+    Per RFC 2616 Section 2.2:
+    separators = "(" | ")" | "<" | ">" | "@"
+               | "," | ";" | ":" | "\" | <">
+               | "/" | "[" | "]" | "?" | "="
+               | "{" | "}" | SP | HT
+
+    Args:
+        c: Single character string
+
+    Returns:
+        True if character is a separator, False otherwise
+    """
+    if not c:
+        return False
+    return c in '()<>@,;:\\"/[]?={} \t'
+
+
+def is_token(c: str) -> bool:
+    """
+    Check if character is valid in an HTTP token.
+
+    Per RFC 7230 Section 3.2.6:
+    token = 1*tchar
+    tchar = "!" / "#" / "$" / "%" / "&" / "'" / "*"
+          / "+" / "-" / "." / "0"-"9" / "A"-"Z"
+          / "^" / "_" / "`" / "a"-"z" / "|" / "~"
+
+    Implementation: token chars are CHAR but not CTL or separators
+
+    Args:
+        c: Single character string
+
+    Returns:
+        True if character is valid in a token, False otherwise
+
+    Examples:
+        >>> is_token('a')
+        True
+        >>> is_token('Z')
+        True
+        >>> is_token('5')
+        True
+        >>> is_token('-')
+        True
+        >>> is_token('!')
+        True
+        >>> is_token(' ')
+        False
+        >>> is_token(',')
+        False
+        >>> is_token('=')
+        False
+    """
+    return is_char(c) and not is_ctl(c) and not is_separator(c)
+
+
+def is_qd_text(c: str) -> bool:
+    r"""
+    Check if character is valid in quoted-text.
+
+    Per RFC 7230 Section 3.2.6:
+    quoted-string = DQUOTE *( qdtext / quoted-pair ) DQUOTE
+    qdtext = HTAB / SP / %x21 / %x23-5B / %x5D-7E / obs-text
+    obs-text = %x80-FF
+
+    In other words:
+    - HTAB (0x09)
+    - SP (0x20)
+    - 0x21 (!)
+    - 0x23-0x5B (# to [, excluding " which is 0x22)
+    - 0x5D-0x7E (] to ~, excluding \ which is 0x5C)
+    - 0x80-0xFF (obs-text, extended ASCII)
+
+    Args:
+        c: Single character string
+
+    Returns:
+        True if character is valid quoted-text, False otherwise
+    """
+    if not c:
+        return False
+
+    b = ord(c)
+    return (
+        b == 0x09  # HTAB
+        or b == 0x20  # SP
+        or b == 0x21  # !
+        or (0x23 <= b <= 0x5B)  # # to [ (skips " which is 0x22)
+        or (0x5D <= b <= 0x7E)  # ] to ~ (skips \ which is 0x5C)
+        or b >= 0x80
+    )  # obs-text
+
+
+def http_unquote_pair(c: str) -> str:
+    """
+    Unquote a single escaped character from a quoted-pair.
+
+    Per RFC 7230 Section 3.2.6:
+    quoted-pair = "\" ( HTAB / SP / VCHAR / obs-text )
+    VCHAR = visible characters (0x21-0x7E)
+
+    Valid escaped characters:
+    - HTAB (0x09)
+    - SP (0x20)
+    - VCHAR (0x21-0x7E)
+    - obs-text (0x80-0xFF)
+
+    Invalid characters are replaced with '?'
+
+    Args:
+        c: Single character string (the character after the backslash)
+
+    Returns:
+        The unquoted character, or '?' if invalid
+
+    Examples:
+        >>> http_unquote_pair('"')
+        '"'
+        >>> http_unquote_pair('n')
+        'n'
+        >>> http_unquote_pair('\\')
+        '\\'
+    """
+    if not c:
+        return "?"
+
+    b = ord(c)
+    # Valid characters that can be escaped
+    if b == 0x09 or b == 0x20 or (0x21 <= b <= 0x7E) or b >= 0x80:
+        return c
+    return "?"
+
+
+def http_unquote(raw: str) -> tuple[int, str]:
+    """
+    Unquote an HTTP quoted-string.
+
+    Per RFC 7230 Section 3.2.6:
+    quoted-string = DQUOTE *( qdtext / quoted-pair ) DQUOTE
+    quoted-pair = "\" ( HTAB / SP / VCHAR / obs-text )
+
+    The raw string must begin with a double quote ("). Only the first
+    quoted string is parsed. The function returns the number of characters
+    consumed and the unquoted result.
+
+    Args:
+        raw: String that must start with a double quote
+
+    Returns:
+        Tuple of (eaten, result) where:
+        - eaten: number of characters consumed, or -1 on failure
+        - result: the unquoted string, or empty string on failure
+
+    Examples:
+        >>> http_unquote('"hello"')
+        (7, 'hello')
+        >>> http_unquote('"hello world"')
+        (13, 'hello world')
+        >>> http_unquote('"hello\\"world"')
+        (14, 'hello"world')
+        >>> http_unquote('"test')
+        (-1, '')
+        >>> http_unquote('not quoted')
+        (-1, '')
+    """
+    if not raw or raw[0] != '"':
+        return -1, ""
+
+    buf: list[str] = []
+    i = 1  # Start after opening quote
+
+    while i < len(raw):
+        b = raw[i]
+
+        if b == '"':
+            # Found closing quote - success
+            return i + 1, "".join(buf)
+
+        elif b == "\\":
+            # Escaped character (quoted-pair)
+            if i + 1 >= len(raw):
+                # Backslash at end of string - invalid
+                return -1, ""
+
+            # Unquote the next character
+            buf.append(http_unquote_pair(raw[i + 1]))
+            i += 2  # Skip both backslash and escaped char
+
+        else:
+            # Regular character
+            if is_qd_text(b):
+                buf.append(b)
+            else:
+                # Invalid character in quoted text
+                buf.append("?")
+            i += 1
+
+    # Reached end without finding closing quote - invalid
+    return -1, ""
 
-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(",")
+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()}
 
-    for directive in cache_control_splited:
-        key: str = ""
-        value: Optional[str] = None
-        dquote = False
+    def get_list(self, key: str) -> Optional[List[str]]:
+        return self._headers.get(key.lower(), None)
 
-        if not directive:
-            raise ParseError("The directive should not be left blank.")
+    def __getitem__(self, key: str) -> str:
+        return ", ".join(self._headers[key.lower()])
 
-        directive = strip_ows_around(directive)
+    def __setitem__(self, key: str, value: str) -> None:
+        self._headers.setdefault(key.lower(), []).append(value)
 
-        if not directive:
-            raise ParseError("The directive should not contain only whitespaces.")
+    def __delitem__(self, key: str) -> None:
+        del self._headers[key.lower()]
 
-        for i, key_char in enumerate(directive):
-            if key_char == "=":
-                value = directive[i + 1 :]
+    def __iter__(self) -> Iterator[str]:
+        return iter(self._headers)
 
-                if not value:
-                    raise ParseError("The directive value cannot be left blank.")
+    def __len__(self) -> int:
+        return len(self._headers)
 
-                if value[0] == '"':
-                    dquote = True
-                if dquote and value[-1] != '"':
-                    raise ParseError("Invalid quotes around the value.")
+    def __repr__(self) -> str:
+        return repr(self._headers)
 
-                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
+    def __str__(self) -> str:
+        return str(self._headers)
 
-            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)
+    def __eq__(self, other_headers: Any) -> bool:
+        return isinstance(other_headers, Headers) and self._headers == other_headers._headers  # type: ignore
 
 
 class Vary:
@@ -128,28 +297,6 @@ class Vary:
         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"]
@@ -182,120 +329,308 @@ class Range:
 
 
 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
+    """
+    Unified Cache-Control directives for both requests and responses.
+
+    Supports all standard directives from RFC9111 and experimental directives.
+    Uses None for unset values instead of -1.
+
+    Supported Directives:
+    - immutable [RFC8246]
+    - max-age [RFC9111, Section 5.2.1.1, 5.2.2.1]
+    - max-stale [RFC9111, Section 5.2.1.2]
+    - min-fresh [RFC9111, Section 5.2.1.3]
+    - must-revalidate [RFC9111, Section 5.2.2.2]
+    - must-understand [RFC9111, Section 5.2.2.3]
+    - no-cache [RFC9111, Section 5.2.1.4, 5.2.2.4]
+    - no-store [RFC9111, Section 5.2.1.5, 5.2.2.5]
+    - no-transform [RFC9111, Section 5.2.1.6, 5.2.2.6]
+    - only-if-cached [RFC9111, Section 5.2.1.7]
+    - private [RFC9111, Section 5.2.2.7]
+    - proxy-revalidate [RFC9111, Section 5.2.2.8]
+    - public [RFC9111, Section 5.2.2.9]
+    - s-maxage [RFC9111, Section 5.2.2.10]
+    - stale-if-error [RFC5861, Section 4]
+    - stale-while-revalidate [RFC5861, Section 3]
+
+    no_cache and private can be:
+        - None: directive not present
+        - True: directive present without field names
+        - List[str]: directive present with specific field names
+    """
+
+    def __init__(self) -> None:
+        # Common directives
+        self.max_age: Optional[int] = None
+        self.no_store: bool = False
+        self.no_transform: bool = False
+
+        # Request-specific
+        self.max_stale: Optional[int] = None
+        self.min_fresh: Optional[int] = None
+        self.only_if_cached: bool = False
+
+        # Response-specific
+        self.must_revalidate: bool = False
+        self.must_understand: bool = False
+        self.public: bool = False
+        self.proxy_revalidate: bool = False
+        self.s_maxage: Optional[int] = None
+        self.immutable: bool = False
+
+        # Can be boolean or contain field names
+        self.no_cache: Union[bool, List[str]] = False
+        self.private: Union[bool, List[str]] = False
+
+        # Experimental
+        self.stale_if_error: Optional[int] = None
+        self.stale_while_revalidate: Optional[int] = None
+
+        # Extensions (unrecognized directives)
+        self.extensions: List[str] = []
+
+
+def parse_int_value(value: str) -> Optional[int]:
+    """Parse integer value, return None if invalid."""
+    try:
+        val = int(value)
+        # Cap at max int32 for compatibility
+        return min(val, 2147483647) if val >= 0 else None
+    except (ValueError, OverflowError):
+        return None
+
+
+def parse_field_names(value: str) -> List[str]:
+    """Parse comma-separated field names and canonicalize them."""
+    fields = []
+    for field in value.split(","):
+        field = field.strip()
+        if field:
+            # Convert to canonical header form (Title-Case)
+            canonical = "-".join(word.capitalize() for word in field.split("-"))
+            fields.append(canonical)
+    return fields
+
+
+def has_field_names(token: str) -> bool:
+    """Check if token can have comma-separated field names."""
+    return token in ("no-cache", "private")
+
+
+def parse(value: str) -> CacheControl:
+    """
+    Parse a Cache-Control header value character by character.
+
+    This parser handles quoted values and field names correctly,
+    allowing commas within field name lists.
+
+    Args:
+        value: The Cache-Control header value string
+
+    Returns:
+        CacheControl object with parsed directives
+    """
+    cc = CacheControl()
+
+    if not value:
+        return cc
+
+    i = 0
+    length = len(value)
+
+    while i < length:
+        # Skip leading whitespace and commas
+        while i < length and (value[i] in (" ", "\t", ",")):
+            i += 1
+
+        if i >= length:
+            break
+
+        # Find end of token
+        j = i
+        while j < length and is_token(value[j]):
+            j += 1
+
+        if j == i:
+            # No valid token found, skip this character
+            i += 1
+            continue
+
+        token = value[i:j].lower()
+        token_has_fields = has_field_names(token)
+
+        # Skip whitespace after token
+        while j < length and value[j] in (" ", "\t"):
+            j += 1
+
+        # Check if token has a value (token=value)
+        if j < length and value[j] == "=":
+            k = j + 1
+
+            # Skip whitespace after equals sign
+            while k < length and value[k] in (" ", "\t"):
+                k += 1
+
+            if k >= length:
+                # Directive ends with '=' but no value
+                i = k
+                continue
+
+            # Check for quoted value
+            if value[k] == '"':
+                eaten, result = http_unquote(value[k:])
+                if eaten == -1:
+                    # Quote mismatch, skip to next directive
+                    i = k + 1
+                    continue
+
+                i = k + eaten
+                handle_directive_with_value(cc, token, result)
+            else:
+                # Unquoted value
+                z = k
+                while z < length:
+                    if token_has_fields:
+                        # For directives with field names, stop only at whitespace
+                        if value[z] in (" ", "\t"):
+                            break
+                    else:
+                        # For other directives, stop at whitespace or comma
+                        if value[z] in (" ", "\t", ","):
+                            break
+                    z += 1
+
+                result = value[k:z]
+
+                # Remove trailing comma if present
+                if result and result[-1] == ",":
+                    result = result[:-1]
 
-    @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
+                i = z
+                handle_directive_with_value(cc, token, result)
+        else:
+            # Token without value
+            handle_directive_without_value(cc, token)
+            i = j
+
+    return cc
 
-    def __repr__(self) -> str:
-        fields = ""
 
-        for key in TIME_FIELDS:
-            key = key.replace("-", "_")
-            value = getattr(self, key)
-            if value:
-                fields += f"{key}={value}, "
+def handle_directive_with_value(cc: CacheControl, token: str, value: str) -> None:
+    """Handle a directive that has a value."""
+    if token == "max-age":
+        cc.max_age = parse_int_value(value)
+
+    elif token == "s-maxage":
+        cc.s_maxage = parse_int_value(value)
+
+    elif token == "max-stale":
+        cc.max_stale = parse_int_value(value)
+
+    elif token == "min-fresh":
+        cc.min_fresh = parse_int_value(value)
+
+    elif token == "stale-if-error":
+        cc.stale_if_error = parse_int_value(value)
+
+    elif token == "stale-while-revalidate":
+        cc.stale_while_revalidate = parse_int_value(value)
+
+    elif token == "no-cache":
+        # no-cache with field names
+        cc.no_cache = parse_field_names(value)
+
+    elif token == "private":
+        # private with field names
+        cc.private = parse_field_names(value)
 
-        for key in BOOLEAN_FIELDS:
-            key = key.replace("-", "_")
-            value = getattr(self, key)
-            if value:
-                fields += f"{key}, "
+    else:
+        # Unrecognized directive with value
+        cc.extensions.append(f"{token}={value}")
 
-        fields = fields[:-2]
 
-        return f"<{type(self).__name__} {fields}>"
+def handle_directive_without_value(cc: CacheControl, token: str) -> None:
+    """Handle a directive that doesn't have a value."""
+    if token == "max-stale":
+        # max-stale without value means accept any stale response
+        cc.max_stale = 2147483647  # max int32
 
+    elif token == "no-cache":
+        cc.no_cache = True
 
-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()}
+    elif token == "private":
+        cc.private = True
 
-    def get_list(self, key: str) -> Optional[List[str]]:
-        return self._headers.get(key.lower(), None)
+    elif token == "no-store":
+        cc.no_store = True
 
-    def __getitem__(self, key: str) -> str:
-        return ", ".join(self._headers[key.lower()])
+    elif token == "no-transform":
+        cc.no_transform = True
 
-    def __setitem__(self, key: str, value: str) -> None:
-        self._headers.setdefault(key.lower(), []).append(value)
+    elif token == "only-if-cached":
+        cc.only_if_cached = True
 
-    def __delitem__(self, key: str) -> None:
-        del self._headers[key.lower()]
+    elif token == "must-revalidate":
+        cc.must_revalidate = True
 
-    def __iter__(self) -> Iterator[str]:
-        return iter(self._headers)
+    elif token == "must-understand":
+        cc.must_understand = True
 
-    def __len__(self) -> int:
-        return len(self._headers)
+    elif token == "public":
+        cc.public = True
 
-    def __repr__(self) -> str:
-        return repr(self._headers)
+    elif token == "proxy-revalidate":
+        cc.proxy_revalidate = True
 
-    def __str__(self) -> str:
-        return str(self._headers)
+    elif token == "immutable":
+        cc.immutable = True
 
-    def __eq__(self, other_headers: Any) -> bool:
-        return isinstance(other_headers, Headers) and self._headers == other_headers._headers  # type: ignore
+    else:
+        # Unrecognized directive without value
+        cc.extensions.append(token)
+
+
+def parse_cache_control(value: str | None) -> CacheControl:
+    """
+    Parse a Cache-Control header from either a request or response.
+
+    This is the main entry point for parsing.
+
+    Args:
+        value: The Cache-Control header value
+
+    Returns:
+        CacheControl object containing all parsed directives
+
+    Examples:
+        >>> # Response example
+        >>> cc = parse_cache_control("public, max-age=3600, must-revalidate")
+        >>> cc.public
+        True
+        >>> cc.max_age
+        3600
+        >>> cc.must_revalidate
+        True
+
+        >>> # Request example
+        >>> cc = parse_cache_control("max-age=0, no-cache")
+        >>> cc.max_age
+        0
+        >>> cc.no_cache
+        True
+
+        >>> # With field names
+        >>> cc = parse_cache_control('no-cache="Set-Cookie, Authorization"')
+        >>> cc.no_cache
+        ['Set-Cookie', 'Authorization']
+
+        >>> # Experimental directives
+        >>> cc = parse_cache_control("immutable, stale-while-revalidate=86400")
+        >>> cc.immutable
+        True
+        >>> cc.stale_while_revalidate
+        86400
+    """
+    if value is None:
+        return CacheControl()
+    return parse(value)

hishel/beta/httpx.py

@@ -21,6 +21,9 @@ SOCKET_OPTION = t.Union[
     t.Tuple[int, int, None, int],
 ]
 
+# 128 KB
+CHUNK_SIZE = 131072
+
 
 class IteratorStream(httpx.SyncByteStream, httpx.AsyncByteStream):
     def __init__(self, iterator: Iterator[bytes] | AsyncIterator[bytes]) -> None:
@@ -86,7 +89,11 @@ def httpx_to_internal(
         stream = AnyIterable(value.content)
     except (httpx.RequestNotRead, httpx.ResponseNotRead):
         if isinstance(value, httpx.Response):
-            stream = value.iter_raw() if isinstance(value.stream, Iterable) else value.aiter_raw()
+            stream = (
+                value.iter_raw(chunk_size=CHUNK_SIZE)
+                if isinstance(value.stream, Iterable)
+                else value.aiter_raw(chunk_size=CHUNK_SIZE)
+            )
         else:
             stream = value.stream  # type: ignore
     if isinstance(value, httpx.Request):
@@ -125,6 +132,7 @@ class SyncCacheTransport(httpx.BaseTransport):
             cache_options=cache_options,
             ignore_specification=ignore_specification,
         )
+        self.storage = self._cache_proxy.storage
 
     def handle_request(
         self,
@@ -137,6 +145,7 @@ class SyncCacheTransport(httpx.BaseTransport):
 
     def close(self) -> None:
         self.next_transport.close()
+        self.storage.close()
         super().close()
 
     def sync_send_request(self, request: Request) -> Response:
@@ -235,6 +244,7 @@ class AsyncCacheTransport(httpx.AsyncBaseTransport):
             cache_options=cache_options,
             ignore_specification=ignore_specification,
         )
+        self.storage = self._cache_proxy.storage
 
     async def handle_async_request(
         self,
@@ -247,6 +257,7 @@ class AsyncCacheTransport(httpx.AsyncBaseTransport):
 
     async def aclose(self) -> None:
         await self.next_transport.aclose()
+        await self.storage.close()
         await super().aclose()
 
     async def async_send_request(self, request: Request) -> Response:

hishel/beta/requests.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 from io import RawIOBase
-from typing import Iterator, Mapping, Optional, overload
+from typing import Any, Iterator, Mapping, Optional, overload
 
 from typing_extensions import assert_never
 
@@ -23,6 +23,9 @@ except ImportError:  # pragma: no cover
         "Install hishel with 'pip install hishel[requests]'."
     )
 
+# 128 KB
+CHUNK_SIZE = 131072
+
 
 class IteratorStream(RawIOBase):
     def __init__(self, iterator: Iterator[bytes]):
@@ -90,7 +93,7 @@ def requests_to_internal(
         )
     elif isinstance(model, requests.models.Response):
         try:
-            stream = model.raw.stream(amt=8192)
+            stream = model.raw.stream(amt=CHUNK_SIZE, decode_content=None)
         except requests.exceptions.StreamConsumedError:
             stream = iter([model.content])
 
@@ -113,7 +116,6 @@ def internal_to_requests(model: Request | Response) -> requests.models.Response
         response = requests.models.Response()
 
         assert isinstance(model.stream, Iterator)
-        # Collect all chunks from the internal stream
         stream = IteratorStream(model.stream)
 
         urllib_response = HTTPResponse(
@@ -121,7 +123,7 @@ def internal_to_requests(model: Request | Response) -> requests.models.Response
             headers={**model.headers, **{snake_to_header(k): str(v) for k, v in model.metadata.items()}},
             status=model.status_code,
             preload_content=False,
-            decode_content=True,
+            decode_content=False,
         )
 
         # Set up the response object
@@ -130,7 +132,6 @@ def internal_to_requests(model: Request | Response) -> requests.models.Response
         response.headers.update(model.headers)
         response.headers.update({snake_to_header(k): str(v) for k, v in model.metadata.items()})
         response.url = ""  # Will be set by requests
-        response.encoding = response.apparent_encoding
 
         return response
     else:
@@ -167,6 +168,7 @@ class CacheAdapter(HTTPAdapter):
             cache_options=cache_options,
             ignore_specification=ignore_specification,
         )
+        self.storage = self._cache_proxy.storage
 
     def send(
         self,
@@ -191,3 +193,6 @@ class CacheAdapter(HTTPAdapter):
         requests_request = internal_to_requests(request)
         response = super().send(requests_request, stream=True)
         return requests_to_internal(response)
+
+    def close(self) -> Any:
+        self.storage.close()

{hishel-0.1.4.dist-info → hishel-0.1.5.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hishel
-Version: 0.1.4
+Version: 0.1.5
 Summary: Persistent cache implementation for httpx and httpcore
 Project-URL: Homepage, https://hishel.com
 Project-URL: Source, https://github.com/karpetrosyan/hishel
@@ -192,19 +192,31 @@ You have complete control over them; you can change storage or even write your o
 You can support the project by simply leaving a GitHub star ⭐ or by [contributing](https://hishel.com/contributing/).
 Help us grow and continue developing good software for you ❤️
 
+## [0.1.5] - 2025-10-18
+
+### 🚀 Features
+
+- *(perf)* Set chunk size to 128KB for httpx to reduce SQLite read/writes
+- Better cache-control parsing
+- Add close method to storages API (#384)
+- *(perf)* Increase requests buffer size to 128KB, disable charset detection
+
+### 🐛 Bug Fixes
+
+- *(docs)* Fix some line breaks
+
+### ⚙️ Miscellaneous Tasks
+
+- Remove some redundant files from repo
 ## [0.1.4] - 2025-10-14
 
 ### 🚀 Features
 
-- Add support for requests library
-- Add support for Python 3.14
 - Add support for a sans-IO API (#366)
 - Allow already consumed streams with `CacheTransport` (#377)
 - Add sqlite storage for beta storages
 - Get rid of some locks from sqlite storage
 - Better async implemetation for sqlite storage
-- Added `Metadata` to public API. (#363)
-- Fix race condition in FileStorage initialization. (#353)
 
 ### 🐛 Bug Fixes
 
@@ -218,187 +230,29 @@ Help us grow and continue developing good software for you ❤️
 - *(internal)* Temporary remove python3.14 from CI
 - *(tests)* Add sqlite tests for new storage
 - *(tests)* Move some tests to beta
-## 0.1.3 (1st July, 2025)
-
-- Remove `types-redis` from dev dependencies (#336)
-- Bump redis to 6.0.0 and address async `.close()` deprecation warning (#336)
-- Avoid race condition when unlinking files in `FileStorage`. (#334)  
-- Allow prodiving a `path_prefix` in `S3Storage` and `AsyncS3Storage`. (#342)
-
-## 0.1.2 (5th April, 2025)
-
-- Add check for fips compliant python. (#325)
-- Fix compatibility with httpx. (#291)
-- Use `SyncByteStream` instead of `ByteStream`. (#298)
-- Don't raise exceptions if date-containing headers are invalid. (#318)
-- Fix for S3 Storage missing metadata in API request. (#320)
-
-## 0.1.1 (2nd Nov, 2024)
-
-- Fix typing extensions not 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)
-
-- Fix cache update on revalidation response with content (rfc9111 section 4.3.3) (#239)
-- Fix request extensions that were not passed into revalidation request for transport-based implementation (but were
-  passed for the pool-based impl) (#247).
-- Add `cache_private` property to the controller to support acting as shared cache. (#224)
-- Improve efficiency of scanning cached responses in `FileStorage` by reducing number of syscalls. (#252)
-- Add `remove` support for storages (#241)
-
-## 0.0.29 (23th June, 2024)
-
-- Documentation hotfix. (#244)
-
-## 0.0.28 (23th June, 2024)
-
-- Add `revalidated` response extension. (#242)
-
-## 0.0.27 (31th May, 2024)
-
-- Fix `RedisStorage` when using without ttl. (#231)
-
-## 0.0.26 (12th April, 2024)
-
-- Expose `AsyncBaseStorage` and `BaseStorage`. (#220)
-- Prevent cache hits from resetting the ttl. (#215)
-
-## 0.0.25 (26th March, 2024)
-
-- Add `force_cache` property to the controller, allowing RFC9111 rules to be completely disabled. (#204)
-- Add `.gitignore` to cache directory created by `FIleStorage`. (#197)
-- Remove `stale_*` headers from the `CacheControl` class. (#199)
-
-## 0.0.24 (14th February, 2024)
-
-- Fix `botocore is not installed` exception when using any kind of storage. (#186)
+## [0.1.3] - 2025-07-06
 
-## 0.0.23 (14th 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)
-- Support caching for `POST` and other HTTP methods. (#183)
-
-## 0.0.22 (31th January, 2024)
-
-- Make `FileStorage` to check staleness of all cache files with set interval. (#169)
-- Support AWS S3 storages. (#164)
-- Move `typing_extensions` from requirements.txt to pyproject.toml. (#161)
-
-## 0.0.21 (29th December, 2023)
-
-- Fix inner transport and connection pool instances closing. (#147)
-- Improved error message when the storage type is incorrect. (#138)
-
-## 0.0.20 (12th December, 2023)
-
-- Add in-memory storage. (#133)
-- Allow customization of cache key generation. (#130)
-
-## 0.0.19 (30th November, 2023)
-
-- Add `force_cache` extension to enforce the request to be cached, ignoring the HTTP headers. (#117)
-- Fix issue where sqlite storage cache get deleted immediately. (#119)
-- Support float numbers for storage ttl. (#107)
-
-## 0.0.18 (23rd November, 2023)
-
-- Fix issue where freshness cannot be calculated to re-send request. (#104)
-- Add `cache_disabled` extension to temporarily disable the cache (#109)
-- Update `datetime.datetime.utcnow()` to `datetime.datetime.now(datetime.timezone.utc)` since `datetime.datetime.utcnow()` has been deprecated. (#111)
-
-## 0.0.17 (6th November, 2023)
-
-- Fix `Last-Modified` validation.
-
-## 0.0.16 (25th October, 2023)
-
-- Add `install_cache` function. (#95)
-- Add sqlite support. (#92)
-- Move `ttl` argument to `BaseStorage` class. (#94)
-
-## 0.0.14 (23rd October, 2023)
-
-- Replace `AsyncResponseStream` with `AsyncCacheStream`. (#86)
-- Add `must-understand` response directive support. (#90)
-
-## 0.0.13 (5th October, 2023)
-
-- Add support for Python 3.12. (#71)
-- Fix connections releasing from the connection pool. (#83)
-
-## 0.0.12 (8th September, 2023)
-
-- Add metadata into the response extensions. (#56)
-
-## 0.0.11 (15th August, 2023)
-
-- Add support for request `cache-control` directives. (#42)
-- Drop httpcore dependency. (#40)
-- Support HTTP methods only if they are defined as cacheable. (#37)
-
-## 0.0.10 (7th August, 2023)
-
-- Add Response metadata. (#33)
-- Add API Reference documentation. (#30)
-- Use stale responses only if the client is disconnected. (#28)
-
-## 0.0.9 (1st August, 2023)
-
-- Expose Controller API. (#23)
-
-## 0.0.8 (31st July, 2023)
-
-- Skip redis tests if the server was not found. (#16)
-- Decrease sleep time for the storage ttl tests. (#18)
-- Fail coverage under 100. (#19)
-
-## 0.0.7 (30th July, 2023)
-
-- Add support for `Heuristic Freshness`. (#11)
-- Change `Controller.cache_heuristically` to `Controller.allow_heuristics`. (#12)
-- Handle import errors. (#13)
-
-## 0.0.6 (29th July, 2023)
+### 🚀 Features
 
-- Fix `Vary` header validation. (#8)
-- Dump original requests with the responses. (#7)
+- Support providing a path prefix to S3 storage (#342)
 
-## 0.0.5 (29th July, 2023)
+### 📚 Documentation
 
-- Fix httpx response streaming.
+- Update link to httpx transports page (#337)
+## [0.1.2] - 2025-04-04
 
-## 0.0.4 (29th July, 2023)
+### 🐛 Bug Fixes
 
-- Change `YamlSerializer` name to `YAMLSerializer`.
+- Requirements.txt to reduce vulnerabilities (#263)
+## [0.0.30] - 2024-07-12
 
-## 0.0.3 (28th July, 2023)
+### 🐛 Bug Fixes
 
-- Add `from_cache` response extension.
-- Add `typing_extensions` into the requirements.
+- Requirements.txt to reduce vulnerabilities (#245)
+- Requirements.txt to reduce vulnerabilities (#255)
+## [0.0.27] - 2024-05-31
 
-## 0.0.2 (25th July, 2023)
+### 🐛 Bug Fixes
 
-- Add [redis](https://redis.io/) support.
-- Make backends thread and task safe.
-- Add black as a new linter.
-- Add an expire time for cached responses.
+- *(redis)* Do not update metadata with negative ttl (#231)
+## [0.0.1] - 2023-07-22

{hishel-0.1.4.dist-info → hishel-0.1.5.dist-info}/RECORD

@@ -1,4 +1,4 @@
-hishel/__init__.py,sha256=uFPxYPm-vFegjbeEvYmTqIE7ALymqYf837Z1mMZNVdM,1221
+hishel/__init__.py,sha256=4HWxHaEihJ5bsey4XEZA28meUO2Iw3mJrOFhQtWu4FY,1221
 hishel/_controller.py,sha256=nQMEF-upuBf6-r0wyjd2CGYgBhB-JbEw6IgGxtvADJ4,24629
 hishel/_exceptions.py,sha256=qbg55RNlzwhv5JreWY9Zog_zmmiKdn5degtqJKijuRs,198
 hishel/_files.py,sha256=7J5uX7Nnzd7QQWfYuDGh8v6XGLG3eUDBjoJZ4aTaY1c,2228
@@ -25,17 +25,17 @@ hishel/_sync/_transports.py,sha256=ivPztcm84PxObIXMZ3hLD_o5HMo8XXGhRlSg0Lm_sNo,1
 hishel/beta/__init__.py,sha256=VzlIfaGQaYfpesqOujNcG0HMCaIF9CzEyhIY04A4c8g,1477
 hishel/beta/_async_cache.py,sha256=vhdTyRIjMpKzc4qKPZGVoFQa9-60aCXLNGltOE1mDg8,6807
 hishel/beta/_sync_cache.py,sha256=a0fcNY5qApPBXQ_kCUBW2Ccwwj0bEkNTVmv-6W3cqPI,6553
-hishel/beta/httpx.py,sha256=KkK3_ZY3FyjWHDJFNLucXoEBph-pMkI2wuHdagXn_lo,10729
-hishel/beta/requests.py,sha256=Q6hPs8ZoFM6802ZCV9_ERG5BVRacMOMwpw5IanmPrYQ,6393
+hishel/beta/httpx.py,sha256=zOnUUafa1zyi2hmcWeP7uaifcj7OIHlXvvuh19gKfL0,11027
+hishel/beta/requests.py,sha256=20i5H7m67BH90iT7RzEbeyiNsbS8lx7eU6kAdWInfQY,6454
 hishel/beta/_core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-hishel/beta/_core/_headers.py,sha256=vkdHZFFg734TO-kDpAZ271I7dXpwFUtAOuX3vS2LatU,9809
+hishel/beta/_core/_headers.py,sha256=ii4x2L6GoQFpqpgg28OtFh7p2DoM9mhE4q6CjW6xUWc,17473
 hishel/beta/_core/_spec.py,sha256=5z5kZ7Q9BO8yZynQIiDiIly77iTMzUljekhmrF1Otyc,99529
 hishel/beta/_core/models.py,sha256=rbU72bCT_lpwASIs5Qzmo3vcjiDm-lu0C99-CgYWl7k,5524
 hishel/beta/_core/_async/_storages/_sqlite.py,sha256=_PZ4t8KXk-YErTCze80Uh8XnG8WZ2323VrRd0NwoKHY,14719
-hishel/beta/_core/_base/_storages/_base.py,sha256=XvhNNQhMNEc2Jt2p0k8SNW5_yLoDfmYMFfPncmKbmX0,8267
+hishel/beta/_core/_base/_storages/_base.py,sha256=mHOQ1p1BTuhV5vgeIdn61OAbVjiD8vu4S4CCal6sS5A,8521
 hishel/beta/_core/_base/_storages/_packing.py,sha256=8s0UxYTLdwzs4A_1E896EVj5VPT8Aqv9UabWbeMD8lw,4898
 hishel/beta/_core/_sync/_storages/_sqlite.py,sha256=1sBU_geVbUSC8e46gao5p_k8MogYEWnZodse55FQQ6Q,14153
-hishel-0.1.4.dist-info/METADATA,sha256=GBT-r6kU3dotaAozdL7xlqDQ5jPt1D88kBcXKceGV1U,14344
-hishel-0.1.4.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-hishel-0.1.4.dist-info/licenses/LICENSE,sha256=1qQj7pE0V2O9OIedvyOgLGLvZLaPd3nFEup3IBEOZjQ,1493
-hishel-0.1.4.dist-info/RECORD,,
+hishel-0.1.5.dist-info/METADATA,sha256=ZB-4dyu3L8icekMrIwMEhZrjlSfryzlSBITW0-b7BCQ,9310
+hishel-0.1.5.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+hishel-0.1.5.dist-info/licenses/LICENSE,sha256=1qQj7pE0V2O9OIedvyOgLGLvZLaPd3nFEup3IBEOZjQ,1493
+hishel-0.1.5.dist-info/RECORD,,