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

hishel-1.0.0.dev0.dist-info/METADATA

@@ -0,0 +1,321 @@
+Metadata-Version: 2.4
+Name: hishel
+Version: 1.0.0.dev0
+Summary:  Elegant HTTP Caching for Python
+Project-URL: Homepage, https://hishel.com
+Project-URL: Source, https://github.com/karpetrosyan/hishel
+Author-email: Kar Petrosyan <kar.petrosyanpy@gmail.com>
+License-Expression: BSD-3-Clause
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Web Environment
+Classifier: Framework :: AsyncIO
+Classifier: Framework :: Trio
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet :: WWW/HTTP
+Requires-Python: >=3.9
+Requires-Dist: anyio>=4.9.0
+Requires-Dist: anysqlite>=0.0.5
+Requires-Dist: httpx>=0.28.0
+Requires-Dist: msgpack>=1.1.2
+Requires-Dist: typing-extensions>=4.14.1
+Provides-Extra: httpx
+Requires-Dist: httpx>=0.28.1; extra == 'httpx'
+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">
+</p>
+
+<h1 align="center">Hishel</h1>
+
+<p align="center">
+  <strong>Elegant HTTP Caching for Python</strong>
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/hishel">
+    <img src="https://img.shields.io/pypi/v/hishel.svg" alt="PyPI version">
+  </a>
+  <a href="https://pypi.org/project/hishel">
+    <img src="https://img.shields.io/pypi/pyversions/hishel.svg" alt="Python versions">
+  </a>
+  <a href="https://github.com/karpetrosyan/hishel/blob/master/LICENSE">
+    <img src="https://img.shields.io/pypi/l/hishel" alt="License">
+  </a>
+  <a href="https://coveralls.io/github/karpetrosyan/hishel">
+    <img src="https://img.shields.io/coverallsCoverage/github/karpetrosyan/hishel" alt="Coverage">
+  </a>
+  <a href="https://static.pepy.tech/badge/hishel/month">
+    <img src="https://static.pepy.tech/badge/hishel/month" alt="Downloads">
+  </a>
+</p>
+
+---
+
+**Hishel** (հիշել, *to remember* in Armenian) is a modern HTTP caching library for Python that implements [RFC 9111](https://www.rfc-editor.org/rfc/rfc9111.html) specifications. It provides seamless caching integration for popular HTTP clients with minimal code changes.
+
+## ✨ Features
+
+- 🎯 **RFC 9111 Compliant** - Fully compliant with the latest HTTP caching specification
+- 🔌 **Easy Integration** - Drop-in support for HTTPX and Requests
+- 💾 **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
+
+## 📦 Installation
+
+```bash
+pip install hishel
+```
+
+### Optional Dependencies
+
+Install with specific HTTP client support:
+
+```bash
+pip install hishel[httpx]      # For HTTPX support
+pip install hishel[requests]   # For Requests support
+```
+
+Or install both:
+
+```bash
+pip install hishel[httpx,requests]
+```
+
+## 🚀 Quick Start
+
+### With HTTPX
+
+**Synchronous:**
+
+```python
+from hishel.httpx import SyncCacheClient
+
+client = SyncCacheClient()
+
+# First request - fetches from origin
+response = client.get("https://api.example.com/data")
+print(response.extensions["hishel_from_cache"])  # False
+
+# Second request - served from cache
+response = client.get("https://api.example.com/data")
+print(response.extensions["hishel_from_cache"])  # True
+```
+
+**Asynchronous:**
+
+```python
+from hishel.httpx import AsyncCacheClient
+
+async with AsyncCacheClient() as client:
+    # First request - fetches from origin
+    response = await client.get("https://api.example.com/data")
+    print(response.extensions["hishel_from_cache"])  # False
+    
+    # Second request - served from cache
+    response = await client.get("https://api.example.com/data")
+    print(response.extensions["hishel_from_cache"])  # True
+```
+
+### With Requests
+
+```python
+import requests
+from hishel.requests import CacheAdapter
+
+session = requests.Session()
+session.mount("https://", CacheAdapter())
+session.mount("http://", CacheAdapter())
+
+# First request - fetches from origin
+response = session.get("https://api.example.com/data")
+
+# Second request - served from cache
+response = session.get("https://api.example.com/data")
+print(response.headers.get("X-Hishel-From-Cache"))  # "True"
+```
+
+## 🎛️ Advanced Configuration
+
+### Custom Cache Options
+
+```python
+from hishel import CacheOptions
+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
+    )
+)
+```
+
+### Custom Storage Backend
+
+```python
+from hishel import SyncSqliteStorage
+from hishel.httpx import SyncCacheClient
+
+storage = SyncSqliteStorage(
+    database_path="my_cache.db",
+    default_ttl=7200.0,           # Cache entries expire after 2 hours
+    refresh_ttl_on_access=True    # Reset TTL when accessing cached entries
+)
+
+client = SyncCacheClient(storage=storage)
+```
+
+## 🏗️ Architecture
+
+Hishel uses a **sans-I/O state machine** architecture that separates HTTP caching logic from I/O operations:
+
+- ✅ **Correct** - Fully RFC 9111 compliant
+- ✅ **Testable** - Easy to test without network dependencies
+- ✅ **Flexible** - Works with any HTTP client or server
+- ✅ **Type Safe** - Clear state transitions with full type hints
+
+## 🔮 Roadmap
+
+While Hishel currently supports HTTPX and Requests, we're actively working on:
+
+- 🎯 Additional HTTP client integrations
+- 🎯 Server-side caching support
+- 🎯 More storage backends
+- 🎯 Advanced caching strategies
+- 🎯 Performance optimizations
+
+## 📚 Documentation
+
+Comprehensive documentation is available at [https://hishel.com/dev](https://hishel.com/dev)
+
+- [Getting Started](https://hishel.com)
+- [HTTPX Integration](https://hishel.com/dev/integrations/httpx)
+- [Requests Integration](https://hishel.com/dev/integrations/requests)
+- [Storage Backends](https://hishel.com/dev/storages)
+- [RFC 9111 Specification](https://hishel.com/dev/specification)
+
+## 🤝 Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
+
+See our [Contributing Guide](https://hishel.com/dev/contributing) for more details.
+
+## 📄 License
+
+This project is licensed under the BSD-3-Clause License - see the [LICENSE](LICENSE) file for details.
+
+## 💖 Support
+
+If you find Hishel useful, please consider:
+
+- ⭐ Starring the repository
+- 🐛 Reporting bugs and issues
+- 💡 Suggesting new features
+- 📖 Improving documentation
+- ☕ [Buying me a coffee](https://buymeacoffee.com/karpetrosyan)
+
+## 🙏 Acknowledgments
+
+Hishel is inspired by and builds upon the excellent work in the Python HTTP ecosystem, particularly:
+
+- [HTTPX](https://github.com/encode/httpx) - A next-generation HTTP client for Python
+- [Requests](https://github.com/psf/requests) - The classic HTTP library for Python
+- [RFC 9111](https://www.rfc-editor.org/rfc/rfc9111.html) - HTTP Caching specification
+
+---
+
+<p align="center">
+  <strong>Made with ❤️ by <a href="https://github.com/karpetrosyan">Kar Petrosyan</a></strong>
+</p>
+
+## [1.0.0dev0] - 2025-10-19
+
+### ⚙️ Miscellaneous Tasks
+
+- *(docs)* Use mike powered versioning
+- *(docs)* Improve docs versioning, deploy dev doc on ci
+## [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 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
+
+### 🐛 Bug Fixes
+
+- Create an sqlite file in a cache folder
+- Fix beta imports
+
+### ⚙️ Miscellaneous Tasks
+
+- Improve CI (#369)
+- *(internal)* Remove src folder (#373)
+- *(internal)* Temporary remove python3.14 from CI
+- *(tests)* Add sqlite tests for new storage
+- *(tests)* Move some tests to beta
+## [0.1.3] - 2025-07-06
+
+### 🚀 Features
+
+- Support providing a path prefix to S3 storage (#342)
+
+### 📚 Documentation
+
+- Update link to httpx transports page (#337)
+## [0.1.2] - 2025-04-04
+
+### 🐛 Bug Fixes
+
+- Requirements.txt to reduce vulnerabilities (#263)
+## [0.0.30] - 2024-07-12
+
+### 🐛 Bug Fixes
+
+- Requirements.txt to reduce vulnerabilities (#245)
+- Requirements.txt to reduce vulnerabilities (#255)
+## [0.0.27] - 2024-05-31
+
+### 🐛 Bug Fixes
+
+- *(redis)* Do not update metadata with negative ttl (#231)
+## [0.0.1] - 2023-07-22

hishel-1.0.0.dev0.dist-info/RECORD

@@ -0,0 +1,19 @@
+hishel/__init__.py,sha256=byj_IhCjFMaBcp6R8iyRlQV-3R4uTfH44PQzB4lVe1g,1447
+hishel/_async_cache.py,sha256=gE5CygC7FG9htBMfxul7carRRNph8zcMlSoOcB_LNTY,6792
+hishel/_sync_cache.py,sha256=lfkWHJFK527peESMaufjKSbXBriidc09tOwBwub2t34,6538
+hishel/_utils.py,sha256=uO8PcY_E1sHSgBGzZ2GNB4kpKqAlzmnzPCc3s-yDd44,13826
+hishel/httpx.py,sha256=HcJ5iO9PgkEOp92ti8013N6m1IotLajwd9M_DLsmrX0,10997
+hishel/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+hishel/requests.py,sha256=eiWcwCId04DucnquCsU12tj9cDZcn-cjZ9MYniVuNeo,6429
+hishel/_core/__init__.py,sha256=byj_IhCjFMaBcp6R8iyRlQV-3R4uTfH44PQzB4lVe1g,1447
+hishel/_core/_headers.py,sha256=ii4x2L6GoQFpqpgg28OtFh7p2DoM9mhE4q6CjW6xUWc,17473
+hishel/_core/_spec.py,sha256=d2ZnTXttyT4zuVq9xHAO86VGJxAEBxD2a8WMyEgOuAo,102702
+hishel/_core/models.py,sha256=5qwo1WifrDeZdXag7M5rh0hJuVsm1N-sF3UagQ5LcLc,5519
+hishel/_core/_async/_storages/_sqlite.py,sha256=wIO0UaFzal9qoVqDVczzcsW0kGUjBQD-ikauc_MN414,14704
+hishel/_core/_base/_storages/_base.py,sha256=xLJGTBlFK8DVrQMgRMtGXJnYRUmNB-iYkk7S-BtMx8s,8516
+hishel/_core/_base/_storages/_packing.py,sha256=NFMpSvYYTDBNkzwpjj5l4w-JOPLc19oAEDqDEQJ7VZI,4873
+hishel/_core/_sync/_storages/_sqlite.py,sha256=TDm9jXIWtd54m4_8AiVApxZVmbBoeFVi3E6s-vGzDjs,14138
+hishel-1.0.0.dev0.dist-info/METADATA,sha256=EpqEHRIGfzVXqMiRefCa_NZ9AlbjzVToXfnK-GBrs9o,9993
+hishel-1.0.0.dev0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+hishel-1.0.0.dev0.dist-info/licenses/LICENSE,sha256=1qQj7pE0V2O9OIedvyOgLGLvZLaPd3nFEup3IBEOZjQ,1493
+hishel-1.0.0.dev0.dist-info/RECORD,,

hishel/_async/__init__.py

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

hishel/_async/_client.py

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

hishel/_async/_mock.py

@@ -1,43 +0,0 @@
-import typing as tp
-from types import TracebackType
-
-import httpcore
-import httpx
-from httpcore._async.interfaces import AsyncRequestInterface
-
-if tp.TYPE_CHECKING:  # pragma: no cover
-    from typing_extensions import Self
-
-__all__ = ("MockAsyncConnectionPool", "MockAsyncTransport")
-
-
-class MockAsyncConnectionPool(AsyncRequestInterface):
-    async def handle_async_request(self, request: httpcore.Request) -> httpcore.Response:
-        assert isinstance(request.stream, tp.AsyncIterable)
-        data = b"".join([chunk async for chunk in request.stream])  # noqa: F841
-        return self.mocked_responses.pop(0)
-
-    def add_responses(self, responses: tp.List[httpcore.Response]) -> None:
-        if not hasattr(self, "mocked_responses"):
-            self.mocked_responses = []
-        self.mocked_responses.extend(responses)
-
-    async def __aenter__(self) -> "Self":
-        return self
-
-    async def __aexit__(
-        self,
-        exc_type: tp.Optional[tp.Type[BaseException]] = None,
-        exc_value: tp.Optional[BaseException] = None,
-        traceback: tp.Optional[TracebackType] = None,
-    ) -> None: ...
-
-
-class MockAsyncTransport(httpx.AsyncBaseTransport):
-    async def handle_async_request(self, request: httpx.Request) -> httpx.Response:
-        return self.mocked_responses.pop(0)
-
-    def add_responses(self, responses: tp.List[httpx.Response]) -> None:
-        if not hasattr(self, "mocked_responses"):
-            self.mocked_responses = []
-        self.mocked_responses.extend(responses)

hishel/_async/_pool.py

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