hishel 1.0.0.dev1__tar.gz → 1.0.0.dev3__tar.gz

hishel-1.0.0.dev3/CHANGELOG.md

@@ -0,0 +1,86 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## 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
+- Don't raise an error on 3xx during revalidation
+
+### 🚀 Features
+- Add hishel_created_at response metadata
+
+## 1.0.0.dev1 - 2025-10-21
+### ⚙️ Miscellaneous Tasks
+- Remove some redundant utils methods
+
+### 📦 Dependencies
+- Make httpx and async libs optional dependencies
+- Make `anysqlite` optional dependency
+- Install async extra with httpx
+- Improve git-cliff
+
+## 1.0.0.dev0 - 2025-10-19
+### ⚙️ Miscellaneous Tasks
+- Use mike powered versioning
+- Improve docs versioning, deploy dev doc on ci
+
+## 0.1.5 - 2025-10-18
+### ⚙️ Miscellaneous Tasks
+- Remove some redundant files from repo
+
+### 🐛 Bug Fixes
+- Fix some line breaks
+
+### 🚀 Features
+- Set chunk size to 128KB for httpx to reduce SQLite read/writes
+- Better cache-control parsing
+- Add close method to storages API (#384)
+- Increase requests buffer size to 128KB, disable charset detection
+
+## 0.1.4 - 2025-10-14
+### ⚙️ Miscellaneous Tasks
+- Improve CI (#369)
+- Remove src folder (#373)
+- Temporary remove python3.14 from CI
+- Add sqlite tests for new storage
+- Move some tests to beta
+
+### 🐛 Bug Fixes
+- Create an sqlite file in a cache folder
+- Fix beta imports
+
+### 🚀 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
+

{hishel-1.0.0.dev1 → hishel-1.0.0.dev3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hishel
-Version: 1.0.0.dev1
+Version: 1.0.0.dev3
 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,15 @@ 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
+- � **Memory Efficient** - Streaming support prevents loading large payloads into memory
+- 🌐 **Universal** - Works with any ASGI application (Starlette, Litestar, BlackSheep, etc.)
 
 ## 📦 Installation
 
@@ -90,19 +94,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,6 +164,65 @@ 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
+
+app = ASGICacheMiddleware(
+    app,
+    storage=AsyncSqliteStorage(),
+    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
@@ -214,7 +281,11 @@ 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)
 - [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,44 +326,85 @@ 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.0.0dev1 - 2025-10-21
-### <!-- 7 -->⚙️ Miscellaneous Tasks
+## 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
+- Don't raise an error on 3xx during revalidation
+
+### 🚀 Features
+- Add hishel_created_at response metadata
+
+## 1.0.0.dev1 - 2025-10-21
+### ⚙️ Miscellaneous Tasks
 - Remove some redundant utils methods
 
+### 📦 Dependencies
+- Make httpx and async libs optional dependencies
+- Make `anysqlite` optional dependency
+- Install async extra with httpx
+- Improve git-cliff
+
 ## 1.0.0.dev0 - 2025-10-19
-### <!-- 7 -->⚙️ Miscellaneous Tasks
+### ⚙️ Miscellaneous Tasks
 - Use mike powered versioning
 - Improve docs versioning, deploy dev doc on ci
 
 ## 0.1.5 - 2025-10-18
-### <!-- 0 -->🚀 Features
+### ⚙️ Miscellaneous Tasks
+- Remove some redundant files from repo
+
+### 🐛 Bug Fixes
+- Fix some line breaks
+
+### 🚀 Features
 - Set chunk size to 128KB for httpx to reduce SQLite read/writes
 - Better cache-control parsing
 - Add close method to storages API (#384)
 - Increase requests buffer size to 128KB, disable charset detection
 
-### <!-- 1 -->🐛 Bug Fixes
-- Fix some line breaks
+## 0.1.4 - 2025-10-14
+### ⚙️ Miscellaneous Tasks
+- Improve CI (#369)
+- Remove src folder (#373)
+- Temporary remove python3.14 from CI
+- Add sqlite tests for new storage
+- Move some tests to beta
 
-### <!-- 7 -->⚙️ Miscellaneous Tasks
-- Remove some redundant files from repo
+### 🐛 Bug Fixes
+- Create an sqlite file in a cache folder
+- Fix beta imports
 
-## 0.1.4 - 2025-10-14
-### <!-- 0 -->🚀 Features
+### 🚀 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
 
-### <!-- 1 -->🐛 Bug Fixes
-- Create an sqlite file in a cache folder
-- Fix beta imports
-
-### <!-- 7 -->⚙️ Miscellaneous Tasks
-- Improve CI (#369)
-- Remove src folder (#373)
-- Temporary remove python3.14 from CI
-- Add sqlite tests for new storage
-- Move some tests to beta
-

{hishel-1.0.0.dev1 → hishel-1.0.0.dev3}/README.md

@@ -1,3 +1,4 @@
+
 <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">
@@ -34,14 +35,15 @@
 ## ✨ 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
+- � **Memory Efficient** - Streaming support prevents loading large payloads into memory
+- 🌐 **Universal** - Works with any ASGI application (Starlette, Litestar, BlackSheep, etc.)
 
 ## 📦 Installation
 
@@ -51,19 +53,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
@@ -117,6 +123,65 @@ 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
+
+app = ASGICacheMiddleware(
+    app,
+    storage=AsyncSqliteStorage(),
+    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
@@ -175,7 +240,11 @@ 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)
 - [Storage Backends](https://hishel.com/dev/storages)
+- [Request/Response Metadata](https://hishel.com/dev/metadata)
 - [RFC 9111 Specification](https://hishel.com/dev/specification)
 
 ## 🤝 Contributing

{hishel-1.0.0.dev1 → hishel-1.0.0.dev3}/hishel/__init__.py

@@ -1,8 +1,7 @@
-from hishel._core._async._storages._sqlite import AsyncSqliteStorage
-from hishel._core._base._storages._base import (
-    AsyncBaseStorage as AsyncBaseStorage,
-    SyncBaseStorage as SyncBaseStorage,
-)
+from hishel._core._storages._async_sqlite import AsyncSqliteStorage
+from hishel._core._storages._async_base import AsyncBaseStorage
+from hishel._core._storages._sync_sqlite import SyncSqliteStorage
+from hishel._core._storages._sync_base import SyncBaseStorage
 from hishel._core._headers import Headers as Headers
 from hishel._core._spec import (
     AnyState as AnyState,
@@ -11,21 +10,21 @@ from hishel._core._spec import (
     CouldNotBeStored as CouldNotBeStored,
     FromCache as FromCache,
     IdleClient as IdleClient,
+    InvalidateEntries,
     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,
+    Entry as Entry,
+    EntryMeta as EntryMeta,
     Request as Request,
     Response,
 )
+from hishel._async_cache import AsyncCacheProxy as AsyncCacheProxy
+from hishel._sync_cache import SyncCacheProxy as SyncCacheProxy
 
 __all__ = (
     # New API
@@ -41,14 +40,13 @@ __all__ = (
     "State",
     "StoreAndUse",
     "CouldNotBeStored",
+    "InvalidateEntries",
     "create_idle_state",
     ## Models
     "Request",
     "Response",
-    "Pair",
-    "IncompletePair",
-    "CompletePair",
-    "PairMeta",
+    "Entry",
+    "EntryMeta",
     ## Headers
     "Headers",
     ## Storages
@@ -56,4 +54,7 @@ __all__ = (
     "AsyncBaseStorage",
     "SyncSqliteStorage",
     "AsyncSqliteStorage",
+    # Proxy
+    "AsyncCacheProxy",
+    "SyncCacheProxy",
 )