hishel 1.0.0.dev2__py3-none-any.whl → 1.1.0__py3-none-any.whl

{hishel-1.0.0.dev2.dist-info → hishel-1.1.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hishel
-Version: 1.0.0.dev2
+Version: 1.1.0
 Summary:  Elegant HTTP Caching for Python
 Project-URL: Homepage, https://hishel.com
 Project-URL: Source, https://github.com/karpetrosyan/hishel
@@ -29,6 +29,8 @@ Requires-Dist: typing-extensions>=4.14.1
 Provides-Extra: async
 Requires-Dist: anyio>=4.9.0; extra == 'async'
 Requires-Dist: anysqlite>=0.0.5; extra == 'async'
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.119.1; extra == 'fastapi'
 Provides-Extra: httpx
 Requires-Dist: anyio>=4.9.0; extra == 'httpx'
 Requires-Dist: anysqlite>=0.0.5; extra == 'httpx'
@@ -37,6 +39,7 @@ Provides-Extra: requests
 Requires-Dist: requests>=2.32.5; extra == 'requests'
 Description-Content-Type: text/markdown
 
+
 <p align="center">
   <img alt="Hishel Logo" width="350" src="https://raw.githubusercontent.com/karpetrosyan/hishel/master/docs/static/Shelkopryad_350x250_yellow.png#gh-dark-mode-only">
   <img alt="Hishel Logo" width="350" src="https://raw.githubusercontent.com/karpetrosyan/hishel/master/docs/static/Shelkopryad_350x250_black.png#gh-light-mode-only">
@@ -73,14 +76,16 @@ Description-Content-Type: text/markdown
 ## ✨ Features
 
 - 🎯 **RFC 9111 Compliant** - Fully compliant with the latest HTTP caching specification
-- 🔌 **Easy Integration** - Drop-in support for HTTPX and Requests
+- 🔌 **Easy Integration** - Drop-in support for HTTPX, Requests, ASGI, FastAPI, and BlackSheep
 - 💾 **Flexible Storage** - SQLite backend with more coming soon
 - ⚡ **High Performance** - Efficient caching with minimal overhead
 - 🔄 **Async & Sync** - Full support for both synchronous and asynchronous workflows
 - 🎨 **Type Safe** - Fully typed with comprehensive type hints
 - 🧪 **Well Tested** - Extensive test coverage and battle-tested
-- 🎛️ **Configurable** - Fine-grained control over caching behavior
-- 🌐 **Future Ready** - Designed for easy integration with any HTTP client/server
+- 🎛️ **Configurable** - Fine-grained control over caching behavior with flexible policies
+- 💨 **Memory Efficient** - Streaming support prevents loading large payloads into memory
+- 🌐 **Universal** - Works with any ASGI application (Starlette, Litestar, BlackSheep, etc.)
+- 🎯 **GraphQL Support** - Cache GraphQL queries with body-sensitive content caching
 
 ## 📦 Installation
 
@@ -90,19 +95,23 @@ pip install hishel
 
 ### Optional Dependencies
 
-Install with specific HTTP client support:
+Install with specific integration support:
 
 ```bash
 pip install hishel[httpx]      # For HTTPX support
 pip install hishel[requests]   # For Requests support
+pip install hishel[fastapi]    # For FastAPI support (includes ASGI)
 ```
 
-Or install both:
+Or install multiple:
 
 ```bash
-pip install hishel[httpx,requests]
+pip install hishel[httpx,requests,fastapi]
 ```
 
+> [!NOTE]
+> ASGI middleware has no extra dependencies - it's included in the base installation.
+ 
 ## 🚀 Quick Start
 
 ### With HTTPX
@@ -156,23 +165,112 @@ response = session.get("https://api.example.com/data")
 print(response.headers.get("X-Hishel-From-Cache"))  # "True"
 ```
 
+### With ASGI Applications
+
+Add caching middleware to any ASGI application:
+
+```python
+from hishel.asgi import ASGICacheMiddleware
+
+# Wrap your ASGI app
+app = ASGICacheMiddleware(app)
+
+# Or configure with options
+from hishel import AsyncSqliteStorage, CacheOptions, SpecificationPolicy
+
+app = ASGICacheMiddleware(
+    app,
+    storage=AsyncSqliteStorage(),
+    policy=SpecificationPolicy(
+      cache_options=CacheOptions(shared=True)
+    ),
+)
+```
+
+### With FastAPI
+
+Add Cache-Control headers using the `cache()` dependency:
+
+```python
+from fastapi import FastAPI
+from hishel.fastapi import cache
+
+app = FastAPI()
+
+@app.get("/api/data", dependencies=[cache(max_age=300, public=True)])
+async def get_data():
+    # Cache-Control: public, max-age=300
+    return {"data": "cached for 5 minutes"}
+  
+# Optionally wrap with ASGI middleware for local caching according to specified rules
+from hishel.asgi import ASGICacheMiddleware
+from hishel import AsyncSqliteStorage
+
+app = ASGICacheMiddleware(app, storage=AsyncSqliteStorage())
+```
+
+### With BlackSheep
+
+Use BlackSheep's native `cache_control` decorator with Hishel's ASGI middleware:
+
+```python
+from blacksheep import Application, get
+from blacksheep.server.headers.cache import cache_control
+
+app = Application()
+
+@get("/api/data")
+@cache_control(max_age=300, public=True)
+async def get_data():
+    # Cache-Control: public, max-age=300
+    return {"data": "cached for 5 minutes"}
+```
+
 ## 🎛️ Advanced Configuration
 
-### Custom Cache Options
+### Caching Policies
+
+Hishel supports two types of caching policies:
+
+**SpecificationPolicy** - RFC 9111 compliant HTTP caching (default):
 
 ```python
-from hishel import CacheOptions
+from hishel import CacheOptions, SpecificationPolicy
 from hishel.httpx import SyncCacheClient
 
 client = SyncCacheClient(
-    cache_options=CacheOptions(
-        shared=False,                              # Use as private cache (browser-like)
-        supported_methods=["GET", "HEAD", "POST"], # Cache GET, HEAD, and POST
-        allow_stale=True                           # Allow serving stale responses
+    policy=SpecificationPolicy(
+        cache_options=CacheOptions(
+            shared=False,                              # Use as private cache (browser-like)
+            supported_methods=["GET", "HEAD", "POST"], # Cache GET, HEAD, and POST
+            allow_stale=True                           # Allow serving stale responses
+        )
+    )
+)
+```
+
+**FilterPolicy** - Custom filtering logic for fine-grained control:
+
+```python
+from hishel import FilterPolicy, BaseFilter, Request
+from hishel.httpx import AsyncCacheClient
+
+class CacheOnlyAPIRequests(BaseFilter[Request]):
+    def needs_body(self) -> bool:
+        return False
+    
+    def apply(self, item: Request, body: bytes | None) -> bool:
+        return "/api/" in str(item.url)
+
+client = AsyncCacheClient(
+    policy=FilterPolicy(
+        request_filters=[CacheOnlyAPIRequests()]
     )
 )
 ```
 
+[Learn more about policies →](https://hishel.com/dev/policies/)
+
 ### Custom Storage Backend
 
 ```python
@@ -188,6 +286,60 @@ storage = SyncSqliteStorage(
 client = SyncCacheClient(storage=storage)
 ```
 
+### GraphQL and Body-Sensitive Caching
+
+Cache GraphQL queries and other POST requests by including the request body in the cache key.
+
+**Using per-request header:**
+
+```python
+from hishel import FilterPolicy
+from hishel.httpx import SyncCacheClient
+
+client = SyncCacheClient(
+    policy=FilterPolicy()
+)
+
+# Cache GraphQL queries - different queries get different cache entries
+graphql_query = """
+    query GetUser($id: ID!) {
+        user(id: $id) {
+            name
+            email
+        }
+    }
+"""
+
+response = client.post(
+    "https://api.example.com/graphql",
+    json={"query": graphql_query, "variables": {"id": "123"}},
+    headers={"X-Hishel-Body-Key": "true"}  # Enable body-based caching
+)
+
+# Different query will be cached separately
+response = client.post(
+    "https://api.example.com/graphql",
+    json={"query": graphql_query, "variables": {"id": "456"}},
+    headers={"X-Hishel-Body-Key": "true"}
+)
+```
+
+**Using global configuration:**
+
+```python
+from hishel.httpx import SyncCacheClient
+from hishel import FilterPolicy
+
+# Enable body-based caching for all requests
+client = SyncCacheClient(policy=FilterPolicy(use_body_key=True))
+
+# All POST requests automatically include body in cache key
+response = client.post(
+    "https://api.example.com/graphql",
+    json={"query": graphql_query, "variables": {"id": "123"}}
+)
+```
+
 ## 🏗️ Architecture
 
 Hishel uses a **sans-I/O state machine** architecture that separates HTTP caching logic from I/O operations:
@@ -199,13 +351,11 @@ Hishel uses a **sans-I/O state machine** architecture that separates HTTP cachin
 
 ## 🔮 Roadmap
 
-While Hishel currently supports HTTPX and Requests, we're actively working on:
+We're actively working on:
 
-- 🎯 Additional HTTP client integrations
-- 🎯 Server-side caching support
-- 🎯 More storage backends
-- 🎯 Advanced caching strategies
 - 🎯 Performance optimizations
+- 🎯 More integrations
+- 🎯 Partial responses support
 
 ## 📚 Documentation
 
@@ -214,7 +364,12 @@ Comprehensive documentation is available at [https://hishel.com/dev](https://his
 - [Getting Started](https://hishel.com)
 - [HTTPX Integration](https://hishel.com/dev/integrations/httpx)
 - [Requests Integration](https://hishel.com/dev/integrations/requests)
+- [ASGI Integration](https://hishel.com/dev/asgi)
+- [FastAPI Integration](https://hishel.com/dev/fastapi)
+- [BlackSheep Integration](https://hishel.com/dev/integrations/blacksheep)
+- [GraphQL Integration](https://hishel.com/dev/integrations/graphql)
 - [Storage Backends](https://hishel.com/dev/storages)
+- [Request/Response Metadata](https://hishel.com/dev/metadata)
 - [RFC 9111 Specification](https://hishel.com/dev/specification)
 
 ## 🤝 Contributing
@@ -255,10 +410,62 @@ Hishel is inspired by and builds upon the excellent work in the Python HTTP ecos
 
 All notable changes to this project will be documented in this file.
 
+## 1.1.0 - 2025-10-31
+### ⚙️ Miscellaneous Tasks
+- Add in memory example
+
+### 🐛 Bug Fixes
+- Pass any response with non-expected status code on revalidation to client
+
+### 🚀 Features
+- Allow setting storage base with via `database_path` for sqlite storage
+
+## 1.0.0 - 2025-10-28
+### ⚙️ Miscellaneous Tasks
+- Add examples, improve docs
+
+## 1.0.0b1 - 2025-10-28
+### ♻️ Refactoring
+- Add policies
+
+### ⚙️ Miscellaneous Tasks
+- Improve sans-io diagram colors
+- Add graphql docs
+
+### 🐛 Bug Fixes
+- Body-sensitive responses caching
+- Filter out `Transfer-Encoding` header for asgi responses
+
+### 🚀 Features
+- Add global `use_body_key` setting
+
+## 1.0.0.dev3 - 2025-10-26
+### ♻️ Refactoring
+- Replace pairs with entries, simplify storage API
+- Automatically generate httpx sync integration from async
+
+### ⚙️ Miscellaneous Tasks
+- Simplify metadata docs
+- Add custom integrations docs
+- More robust compressed response caching
+
+### 🐛 Bug Fixes
+- Add missing permissions into `publish.yml`
+- Raise on consumed httpx streams, which we can't store as is (it's already decoded)
+- Fix compressed data caching for requests
+- Handle httpx iterable usage instead of iterator correctly
+- Add date header for proper age calculation
+
+### 🚀 Features
+- Add integrations with fastapi and asgi
+- Add blacksheep integration examples
+- Add logging for asgi
+
 ## 1.0.0.dev2 - 2025-10-21
 ### ⚙️ Miscellaneous Tasks
 - Remove redundant utils and tests
 - Add import without extras check in ci
+- Fix time travel date, explicitly specify the timezone
 
 ### 🐛 Bug Fixes
 - Fix check for storing auth requests

hishel-1.1.0.dist-info/RECORD

@@ -0,0 +1,24 @@
+hishel/__init__.py,sha256=XYnAlT2Wkrg0Cw5u4DLJAsC3TjWDOQJr5kqQMuXxEJI,1796
+hishel/_async_cache.py,sha256=4wm6YBL9ClNOg4WbEkALTJVCIXuzQU80MVem2C3hHrQ,8785
+hishel/_async_httpx.py,sha256=WB35o7CseRDz89dpqoWNLXYEkDxqeSo709eR3oPXP7Q,7536
+hishel/_policies.py,sha256=1ae_rmDF7oaG91-lQyOGVaTrRX8uI2GImmu5gN6WJa4,1135
+hishel/_sync_cache.py,sha256=k0AN0M--yR4Jc6SiAreaxPUFiwEt5Dx7wi9jqW9sy50,8510
+hishel/_sync_httpx.py,sha256=FbnJrdoLftPDVNUzYkAtz-JOTNtiBPJ2c1ZOcU0JnmE,7368
+hishel/_utils.py,sha256=kR7RnhFqLzFRmB-YNnZteQVP0iDPUouCscA0_FHHFls,3837
+hishel/asgi.py,sha256=ocXzqrrYGazeJxlKFcz1waoKvKGOqJ7YBEAmly4Towk,14998
+hishel/fastapi.py,sha256=CVWCyXTxBPwG_XALo-Oldekv4lqMgH2-W-PPZ9rZjXg,10826
+hishel/httpx.py,sha256=99a8X9COPiPHSgGW61O2uMWMZB7dY93Ty9DTCJ9C18Q,467
+hishel/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+hishel/requests.py,sha256=FbOBMvgNSWkH0Bh0qZdr-dhCYG6siR5Lmxcu5eMay3s,6409
+hishel/_core/_headers.py,sha256=hGaT6o1F-gs1pm5RpdGb0IMQL3uJYDH1xpwJLy28Cys,17514
+hishel/_core/_spec.py,sha256=YfZfMYS4--o0v-AQZ37vVzHfc-Mh-SEHcl9SrBM9Y7Y,102963
+hishel/_core/models.py,sha256=EabP2qnjYVzhPWhQer3QFmdDE6TDbqEBEqPHzv25VnA,7978
+hishel/_core/_storages/_async_base.py,sha256=iZ6Mb30P0ho5h4UU5bgOrcsSMZ1427j9tht-tupZs68,2106
+hishel/_core/_storages/_async_sqlite.py,sha256=QZEWroGZKGhCMf7CcYpZfKZdKd88R8elQCoPge0Khxc,15674
+hishel/_core/_storages/_packing.py,sha256=mC8LMFQ5uPfFOgingKm2WKFO_DwcZ1OjTgI6xc0hfJI,3708
+hishel/_core/_storages/_sync_base.py,sha256=qfOvcFY5qvrzSh4ztV2Trlxft-BF7An5SFsLlEb8EeE,2075
+hishel/_core/_storages/_sync_sqlite.py,sha256=P3vIp636tTtM553-sBTZkam3-sNv0EEkh1rRSd1Qw90,15167
+hishel-1.1.0.dist-info/METADATA,sha256=08BqqoUdS_tMtsQyo4JTS5mOuASXLW1cs5S_PrSAuGM,15759
+hishel-1.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+hishel-1.1.0.dist-info/licenses/LICENSE,sha256=1qQj7pE0V2O9OIedvyOgLGLvZLaPd3nFEup3IBEOZjQ,1493
+hishel-1.1.0.dist-info/RECORD,,

hishel/_core/__init__.py

@@ -1,59 +0,0 @@
-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__ = (
-    # 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",
-    "SyncSqliteStorage",
-    "AsyncSqliteStorage",
-)

hishel/_core/_base/_storages/_base.py

@@ -1,272 +0,0 @@
-from __future__ import annotations
-
-import abc
-import time
-import typing as tp
-import uuid
-from abc import ABC
-from pathlib import Path
-
-from hishel._core.models import CompletePair, IncompletePair, Request, Response
-
-
-class SyncBaseStorage(ABC):
-    @abc.abstractmethod
-    def create_pair(
-        self,
-        request: Request,
-        id: uuid.UUID | None = None,
-    ) -> IncompletePair:
-        """
-        Store a request in the backend under the given key.
-
-        Args:
-            request: The request object to store.
-
-        Returns:
-            The created IncompletePair object representing the stored request.
-
-        Raises:
-            NotImplementedError: Must be implemented in subclasses.
-        """
-        raise NotImplementedError()
-
-    @abc.abstractmethod
-    def add_response(self, pair_id: uuid.UUID, response: Response, key: str | bytes) -> CompletePair:
-        """
-        Add a response to an existing request pair.
-
-        Args:
-            pair_id: The unique identifier of the request pair.
-            response: The response object to add.
-            key: The cache key associated with the request pair.
-
-        Returns:
-            The updated response object.
-
-        Raises:
-            NotImplementedError: Must be implemented in subclasses.
-        """
-        raise NotImplementedError()
-
-    @abc.abstractmethod
-    def get_pairs(self, key: str) -> tp.List[CompletePair]:
-        """
-        Retrieve all responses associated with a given key.
-
-        Args:
-            key: The unique identifier for the request pairs.
-            complete_only: If True, only return pairs with responses. If False,
-                only return pairs without responses. If None, return all pairs.
-        """
-        raise NotImplementedError()
-
-    @abc.abstractmethod
-    def update_pair(
-        self,
-        id: uuid.UUID,
-        new_pair: tp.Union[CompletePair, tp.Callable[[CompletePair], CompletePair]],
-    ) -> tp.Optional[CompletePair]:
-        """
-        Update an existing request pair.
-
-        Args:
-            id: The unique identifier of the request pair to update.
-            new_pair: The new pair data or a callable that takes the current pair
-                and returns the updated pair.
-        """
-        raise NotImplementedError()
-
-    @abc.abstractmethod
-    def remove(self, id: uuid.UUID) -> None:
-        """
-        Remove a request pair from the storage.
-
-        Args:
-            id: The unique identifier of the request pair to remove.
-        """
-        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.
-
-        Args:
-            pair: The request pair to check.
-
-        Returns:
-            True if the pair is soft deleted, False otherwise.
-        """
-        return pair.meta.deleted_at is not None and pair.meta.deleted_at > 0
-
-    def is_safe_to_hard_delete(self, pair: IncompletePair | CompletePair) -> bool:
-        """
-        Check if a pair is safe to hard delete based on its metadata.
-
-        If the pair has been soft deleted for more than 1 hour, it is considered safe to hard delete.
-
-        Args:
-            pair: The request pair to check.
-
-        Returns:
-            True if the pair is safe to hard delete, False otherwise.
-        """
-        return bool(pair.meta.deleted_at is not None and (pair.meta.deleted_at + 3600 < time.time()))
-
-    @tp.overload
-    def mark_pair_as_deleted(self, pair: CompletePair) -> CompletePair: ...
-    @tp.overload
-    def mark_pair_as_deleted(self, pair: IncompletePair) -> IncompletePair: ...
-    def mark_pair_as_deleted(self, pair: CompletePair | IncompletePair) -> CompletePair | IncompletePair:
-        """
-        Mark a pair as soft deleted by setting its deleted_at timestamp.
-
-        Args:
-            pair: The request pair to mark as deleted.
-        Returns:
-            The updated request pair with the deleted_at timestamp set.
-        """
-        pair.meta.deleted_at = time.time()
-        return pair
-
-
-class AsyncBaseStorage(ABC):
-    @abc.abstractmethod
-    async def create_pair(
-        self,
-        request: Request,
-        id: uuid.UUID | None = None,
-    ) -> IncompletePair:
-        """
-        Store a request in the backend under the given key.
-
-        Args:
-            request: The request object to store.
-
-        Returns:
-            The created IncompletePair object representing the stored request.
-
-        Raises:
-            NotImplementedError: Must be implemented in subclasses.
-        """
-        raise NotImplementedError()
-
-    @abc.abstractmethod
-    async def add_response(self, pair_id: uuid.UUID, response: Response, key: str | bytes) -> CompletePair:
-        """
-        Add a response to an existing request pair.
-
-        Args:
-            pair_id: The unique identifier of the request pair.
-            response: The response object to add.
-            key: The cache key associated with the request pair.
-
-        Returns:
-            The updated response object.
-
-        Raises:
-            NotImplementedError: Must be implemented in subclasses.
-        """
-        raise NotImplementedError()
-
-    @abc.abstractmethod
-    async def get_pairs(self, key: str) -> tp.List[CompletePair]:
-        """
-        Retrieve all responses associated with a given key.
-
-        Args:
-            key: The unique identifier for the request pairs.
-        """
-        raise NotImplementedError()
-
-    @abc.abstractmethod
-    async def update_pair(
-        self,
-        id: uuid.UUID,
-        new_pair: tp.Union[CompletePair, tp.Callable[[CompletePair], CompletePair]],
-    ) -> tp.Optional[CompletePair]:
-        """
-        Update an existing request pair.
-
-        Args:
-            id: The unique identifier of the request pair to update.
-            new_pair: The new pair data or a callable that takes the current pair
-                and returns the updated pair.
-        """
-        raise NotImplementedError()
-
-    @abc.abstractmethod
-    async def remove(self, id: uuid.UUID) -> None:
-        """
-        Remove a request pair from the storage.
-
-        Args:
-            id: The unique identifier of the request pair to remove.
-        """
-        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.
-
-        Args:
-            pair: The request pair to check.
-
-        Returns:
-            True if the pair is soft deleted, False otherwise.
-        """
-        return pair.meta.deleted_at is not None and pair.meta.deleted_at > 0
-
-    def is_safe_to_hard_delete(self, pair: IncompletePair | CompletePair) -> bool:
-        """
-        Check if a pair is safe to hard delete based on its metadata.
-
-        If the pair has been soft deleted for more than 1 hour, it is considered safe to hard delete.
-
-        Args:
-            pair: The request pair to check.
-
-        Returns:
-            True if the pair is safe to hard delete, False otherwise.
-        """
-        return bool(pair.meta.deleted_at is not None and (pair.meta.deleted_at + 3600 < time.time()))
-
-    @tp.overload
-    def mark_pair_as_deleted(self, pair: CompletePair) -> CompletePair: ...
-    @tp.overload
-    def mark_pair_as_deleted(self, pair: IncompletePair) -> IncompletePair: ...
-    def mark_pair_as_deleted(self, pair: CompletePair | IncompletePair) -> CompletePair | IncompletePair:
-        """
-        Mark a pair as soft deleted by setting its deleted_at timestamp.
-
-        Args:
-            pair: The request pair to mark as deleted.
-        Returns:
-            The updated request pair with the deleted_at timestamp set.
-        """
-        pair.meta.deleted_at = time.time()
-        return pair
-
-
-def ensure_cache_dict(base_path: str | None = None) -> Path:
-    _base_path = Path(base_path) if base_path is not None else Path(".cache/hishel")
-    _gitignore_file = _base_path / ".gitignore"
-
-    _base_path.mkdir(parents=True, exist_ok=True)
-
-    if not _gitignore_file.is_file():
-        with open(_gitignore_file, "w", encoding="utf-8") as f:
-            f.write("# Automatically created by Hishel\n*")
-    return _base_path