hishel 0.1.5__tar.gz → 1.0.0.dev0__tar.gz

{hishel-0.1.5 → hishel-1.0.0.dev0}/.gitignore

@@ -4,4 +4,5 @@ __pycache__/
 .coverage
 .cache/
 .idea/
-coverage.xml
+coverage.xml
+site

{hishel-0.1.5 → hishel-1.0.0.dev0}/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [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

hishel-1.0.0.dev0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,214 @@
+<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>
+

{hishel-0.1.5/hishel/beta → hishel-1.0.0.dev0/hishel}/__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-0.1.5/hishel/beta → hishel-1.0.0.dev0/hishel}/_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-1.0.0.dev0/hishel/_core/__init__.py

@@ -0,0 +1,59 @@
+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-0.1.5/hishel/beta → hishel-1.0.0.dev0/hishel}/_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-0.1.5/hishel/beta → hishel-1.0.0.dev0/hishel}/_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):