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

hishel/__init__.py

@@ -1,57 +1,59 @@
-import httpx
-
-from ._async import *
-from ._controller import *
-from ._exceptions import *
-from ._headers import *
-from ._serializers import *
-from ._sync import *
-from ._lfu_cache import *
+from hishel._core._async._storages._sqlite import AsyncSqliteStorage
+from hishel._core._base._storages._base import (
+    AsyncBaseStorage as AsyncBaseStorage,
+    SyncBaseStorage as SyncBaseStorage,
+)
+from hishel._core._headers import Headers as Headers
+from hishel._core._spec import (
+    AnyState as AnyState,
+    CacheMiss as CacheMiss,
+    CacheOptions as CacheOptions,
+    CouldNotBeStored as CouldNotBeStored,
+    FromCache as FromCache,
+    IdleClient as IdleClient,
+    NeedRevalidation as NeedRevalidation,
+    NeedToBeUpdated as NeedToBeUpdated,
+    State as State,
+    StoreAndUse as StoreAndUse,
+    create_idle_state as create_idle_state,
+)
+from hishel._core._sync._storages._sqlite import SyncSqliteStorage
+from hishel._core.models import (
+    CompletePair as CompletePair,
+    IncompletePair as IncompletePair,
+    Pair as Pair,
+    PairMeta as PairMeta,
+    Request as Request,
+    Response,
+)
 
 __all__ = (
-    # Old API
-    "AsyncCacheClient",
-    "MockAsyncConnectionPool",
-    "MockAsyncTransport",
-    "AsyncCacheConnectionPool",
+    # New API
+    ## States
+    "AnyState",
+    "IdleClient",
+    "CacheMiss",
+    "FromCache",
+    "NeedRevalidation",
+    "AnyState",
+    "CacheOptions",
+    "NeedToBeUpdated",
+    "State",
+    "StoreAndUse",
+    "CouldNotBeStored",
+    "create_idle_state",
+    ## Models
+    "Request",
+    "Response",
+    "Pair",
+    "IncompletePair",
+    "CompletePair",
+    "PairMeta",
+    ## Headers
+    "Headers",
+    ## Storages
+    "SyncBaseStorage",
     "AsyncBaseStorage",
-    "AsyncFileStorage",
-    "AsyncInMemoryStorage",
-    "AsyncRedisStorage",
-    "AsyncS3Storage",
-    "AsyncSQLiteStorage",
-    "AsyncCacheTransport",
-    "HEURISTICALLY_CACHEABLE_STATUS_CODES",
-    "Controller",
-    "CacheControlError",
-    "ParseError",
-    "ValidationError",
-    "CacheControl",
-    "Vary",
-    "BaseSerializer",
-    "JSONSerializer",
-    "Metadata",
-    "PickleSerializer",
-    "YAMLSerializer",
-    "clone_model",
-    "CacheClient",
-    "MockConnectionPool",
-    "MockTransport",
-    "CacheConnectionPool",
-    "BaseStorage",
-    "FileStorage",
-    "InMemoryStorage",
-    "RedisStorage",
-    "S3Storage",
-    "SQLiteStorage",
-    "CacheTransport",
-    "LFUCache",
+    "SyncSqliteStorage",
+    "AsyncSqliteStorage",
 )
-
-def install_cache() -> None:  # pragma: no cover
-    httpx.AsyncClient = AsyncCacheClient  # type: ignore
-    httpx.Client = CacheClient  # type: ignore
-
-
-__version__ = "0.1.5"
-

hishel/{beta/_async_cache.py → _async_cache.py}

@@ -8,7 +8,7 @@ from typing import AsyncIterator, Awaitable, Callable
 
 from typing_extensions import assert_never
 
-from hishel.beta import (
+from hishel import (
     AnyState,
     AsyncBaseStorage,
     AsyncSqliteStorage,
@@ -24,8 +24,8 @@ from hishel.beta import (
     StoreAndUse,
     create_idle_state,
 )
-from hishel.beta._core._spec import InvalidatePairs, vary_headers_match
-from hishel.beta._core.models import CompletePair
+from hishel._core._spec import InvalidatePairs, vary_headers_match
+from hishel._core.models import CompletePair
 
 logger = logging.getLogger("hishel.integrations.clients")
 

hishel/{beta → _core}/__init__.py

@@ -1,10 +1,10 @@
-from hishel.beta._core._async._storages._sqlite import AsyncSqliteStorage
-from hishel.beta._core._base._storages._base import (
+from hishel._core._async._storages._sqlite import AsyncSqliteStorage
+from hishel._core._base._storages._base import (
     AsyncBaseStorage as AsyncBaseStorage,
     SyncBaseStorage as SyncBaseStorage,
 )
-from hishel.beta._core._headers import Headers as Headers
-from hishel.beta._core._spec import (
+from hishel._core._headers import Headers as Headers
+from hishel._core._spec import (
     AnyState as AnyState,
     CacheMiss as CacheMiss,
     CacheOptions as CacheOptions,
@@ -17,8 +17,8 @@ from hishel.beta._core._spec import (
     StoreAndUse as StoreAndUse,
     create_idle_state as create_idle_state,
 )
-from hishel.beta._core._sync._storages._sqlite import SyncSqliteStorage
-from hishel.beta._core.models import (
+from hishel._core._sync._storages._sqlite import SyncSqliteStorage
+from hishel._core.models import (
     CompletePair as CompletePair,
     IncompletePair as IncompletePair,
     Pair as Pair,

hishel/{beta/_core → _core}/_async/_storages/_sqlite.py

@@ -15,9 +15,9 @@ from typing import (
 
 import anysqlite
 
-from hishel.beta._core._base._storages._base import AsyncBaseStorage, ensure_cache_dict
-from hishel.beta._core._base._storages._packing import pack, unpack
-from hishel.beta._core.models import (
+from hishel._core._base._storages._base import AsyncBaseStorage, ensure_cache_dict
+from hishel._core._base._storages._packing import pack, unpack
+from hishel._core.models import (
     CompletePair,
     IncompletePair,
     Pair,

hishel/{beta/_core → _core}/_base/_storages/_base.py

@@ -7,7 +7,7 @@ import uuid
 from abc import ABC
 from pathlib import Path
 
-from hishel.beta._core.models import CompletePair, IncompletePair, Request, Response
+from hishel._core.models import CompletePair, IncompletePair, Request, Response
 
 
 class SyncBaseStorage(ABC):

hishel/{beta/_core → _core}/_base/_storages/_packing.py

@@ -6,8 +6,8 @@ from typing import TYPE_CHECKING, Any, Mapping, Optional, Union, overload
 import msgpack
 from typing_extensions import Literal, cast
 
-from hishel.beta._core._headers import Headers
-from hishel.beta._core.models import PairMeta, Request, Response
+from hishel._core._headers import Headers
+from hishel._core.models import PairMeta, Request, Response
 
 
 def filter_out_hishel_metadata(data: Mapping[str, Any]) -> dict[str, Any]:
@@ -15,7 +15,7 @@ def filter_out_hishel_metadata(data: Mapping[str, Any]) -> dict[str, Any]:
 
 
 if TYPE_CHECKING:
-    from hishel.beta import CompletePair, IncompletePair
+    from hishel import CompletePair, IncompletePair
 
 
 @overload
@@ -39,7 +39,7 @@ def pack(
     /,
     kind: Literal["pair", "entry_db_key_index"],
 ) -> bytes:
-    from hishel.beta import CompletePair, IncompletePair
+    from hishel import CompletePair, IncompletePair
 
     if kind == "entry_db_key_index":
         assert isinstance(value, uuid.UUID)
@@ -115,7 +115,7 @@ def unpack(
     /,
     kind: Literal["pair", "entry_db_key_index"],
 ) -> Union["CompletePair", "IncompletePair", uuid.UUID, None]:
-    from hishel.beta import CompletePair, IncompletePair
+    from hishel import CompletePair, IncompletePair
 
     if value is None:
         return None

hishel/{beta/_core → _core}/_spec.py

@@ -15,11 +15,11 @@ from typing import (
     Union,
 )
 
+from hishel._core._headers import Headers, Range, Vary, parse_cache_control
 from hishel._utils import parse_date, partition
-from hishel.beta._core._headers import Headers, Range, Vary, parse_cache_control
 
 if TYPE_CHECKING:
-    from hishel.beta import CompletePair, Request, Response
+    from hishel import CompletePair, Request, Response
 
 
 TState = TypeVar("TState", bound="State")
@@ -41,9 +41,96 @@ logger = logging.getLogger("hishel.core.spec")
 
 @dataclass
 class CacheOptions:
+    """
+    Configuration options for HTTP cache behavior.
+
+    These options control how the cache interprets and applies RFC 9111 caching rules.
+    All options have sensible defaults that follow the specification.
+
+    Attributes:
+    ----------
+    shared : bool
+        Determines whether the cache operates as a shared cache or private cache.
+
+        RFC 9111 Section 3.5: Authenticated Responses
+        https://www.rfc-editor.org/rfc/rfc9111.html#section-3.5
+
+        - Shared cache (True): Acts as a proxy, CDN, or gateway cache serving multiple users.
+          Must respect private directives and Authorization header restrictions.
+          Can use s-maxage directive instead of max-age for shared-specific freshness.
+
+        - Private cache (False): Acts as a browser or user-agent cache for a single user.
+          Can cache private responses and ignore s-maxage directives.
+
+        Default: True (shared cache)
+
+        Examples:
+        --------
+        >>> # Shared cache (proxy/CDN)
+        >>> options = CacheOptions(shared=True)
+
+        >>> # Private cache (browser)
+        >>> options = CacheOptions(shared=False)
+
+    supported_methods : list[str]
+        HTTP methods that are allowed to be cached by this cache implementation.
+
+        RFC 9111 Section 3, paragraph 2.1:
+        https://www.rfc-editor.org/rfc/rfc9111.html#section-3-2.1.1
+
+        "A cache MUST NOT store a response to a request unless:
+         - the request method is understood by the cache"
+
+        Default: ["GET", "HEAD"] (most commonly cached methods)
+
+        Examples:
+        --------
+        >>> # Default: cache GET and HEAD only
+        >>> options = CacheOptions()
+        >>> options.supported_methods
+        ['GET', 'HEAD']
+
+        >>> # Cache POST responses (advanced use case)
+        >>> options = CacheOptions(supported_methods=["GET", "HEAD", "POST"])
+
+    allow_stale : bool
+        Controls whether stale responses can be served without revalidation.
+
+        RFC 9111 Section 4.2.4: Serving Stale Responses
+        https://www.rfc-editor.org/rfc/rfc9111.html#section-4.2.4
+
+        "A cache MUST NOT generate a stale response unless it is disconnected or
+        doing so is explicitly permitted by the client or origin server (e.g., by
+        the max-stale request directive in Section 5.2.1, extension directives
+        such as those defined in [RFC5861], or configuration in accordance with
+        an out-of-band contract)."
+
+        Default: False (no stale responses)
+
+        Examples:
+        --------
+        >>> # Conservative: never serve stale
+        >>> options = CacheOptions(allow_stale=False)
+
+        >>> # Permissive: serve stale when allowed
+        >>> options = CacheOptions(allow_stale=True)
+
+        >>> # Stale-while-revalidate pattern (RFC 5861)
+        >>> # Even with allow_stale=True, directives are respected
+        >>> options = CacheOptions(allow_stale=True)
+    """
+
     shared: bool = True
+    """
+    When True, the cache operates as a shared cache (proxy/CDN).
+    When False, as a private cache (browser).
+    """
+
     supported_methods: list[str] = field(default_factory=lambda: ["GET", "HEAD"])
+    """HTTP methods that are allowed to be cached."""
+
     allow_stale: bool = False
+    """When True, stale responses can be served without revalidation."""
 
 
 @dataclass

hishel/{beta/_core → _core}/_sync/_storages/_sqlite.py

@@ -15,9 +15,9 @@ from typing import (
 
 import sqlite3
 
-from hishel.beta._core._base._storages._base import SyncBaseStorage, ensure_cache_dict
-from hishel.beta._core._base._storages._packing import pack, unpack
-from hishel.beta._core.models import (
+from hishel._core._base._storages._base import SyncBaseStorage, ensure_cache_dict
+from hishel._core._base._storages._packing import pack, unpack
+from hishel._core.models import (
     CompletePair,
     IncompletePair,
     Pair,

hishel/{beta/_core → _core}/models.py

@@ -12,7 +12,7 @@ from typing import (
     TypedDict,
 )
 
-from hishel.beta._core._headers import Headers
+from hishel._core._headers import Headers
 
 
 class AnyIterable:

hishel/{beta/_sync_cache.py → _sync_cache.py}

@@ -8,7 +8,7 @@ from typing import Iterator, Awaitable, Callable
 
 from typing_extensions import assert_never
 
-from hishel.beta import (
+from hishel import (
     AnyState,
     SyncBaseStorage,
     SyncSqliteStorage,
@@ -24,8 +24,8 @@ from hishel.beta import (
     StoreAndUse,
     create_idle_state,
 )
-from hishel.beta._core._spec import InvalidatePairs, vary_headers_match
-from hishel.beta._core.models import CompletePair
+from hishel._core._spec import InvalidatePairs, vary_headers_match
+from hishel._core.models import CompletePair
 
 logger = logging.getLogger("hishel.integrations.clients")
 

hishel/{beta/httpx.py → httpx.py}

@@ -6,14 +6,14 @@ from typing import AsyncIterator, Iterable, Iterator, Union, overload
 
 import httpx
 
-from hishel.beta import Headers, Request, Response
-from hishel.beta._async_cache import AsyncCacheProxy
-from hishel.beta._core._base._storages._base import AsyncBaseStorage, SyncBaseStorage
-from hishel.beta._core._spec import (
+from hishel import Headers, Request, Response
+from hishel._async_cache import AsyncCacheProxy
+from hishel._core._base._storages._base import AsyncBaseStorage, SyncBaseStorage
+from hishel._core._spec import (
     CacheOptions,
 )
-from hishel.beta._core.models import AnyIterable
-from hishel.beta._sync_cache import SyncCacheProxy
+from hishel._core.models import AnyIterable
+from hishel._sync_cache import SyncCacheProxy
 
 SOCKET_OPTION = t.Union[
     t.Tuple[int, int, int],

hishel/{beta/requests.py → requests.py}

@@ -5,12 +5,12 @@ from typing import Any, Iterator, Mapping, Optional, overload
 
 from typing_extensions import assert_never
 
+from hishel import Headers, Request, Response as Response
+from hishel._core._base._storages._base import SyncBaseStorage
+from hishel._core._spec import CacheOptions
+from hishel._core.models import extract_metadata_from_headers
+from hishel._sync_cache import SyncCacheProxy
 from hishel._utils import snake_to_header
-from hishel.beta import Headers, Request, Response as Response
-from hishel.beta._core._base._storages._base import SyncBaseStorage
-from hishel.beta._core._spec import CacheOptions
-from hishel.beta._core.models import extract_metadata_from_headers
-from hishel.beta._sync_cache import SyncCacheProxy
 
 try:
     import requests