cachekit 0.8.0__tar.gz → 0.9.1__tar.gz

{cachekit-0.8.0 → cachekit-0.9.1}/Cargo.lock

@@ -245,9 +245,9 @@ checksum = "1e748733b7cbc798e1434b6ac524f0c1ff2ab456fe201501e6497c8417a4fc33"
 
 [[package]]
 name = "cachekit-core"
-version = "0.2.0"
+version = "0.2.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "9622b3c3e47fcf7abfde287c557e6171674e37842a2dd26fda03f63720542f17"
+checksum = "01870e86fa79ca9ee521b5b9c2bcff8428eab95fb343f75d35a6fce159bb1577"
 dependencies = [
  "aes",
  "aes-gcm",
@@ -271,7 +271,7 @@ dependencies = [
 
 [[package]]
 name = "cachekit-rs"
-version = "0.8.0"
+version = "0.9.1"
 dependencies = [
  "cachekit-core",
  "criterion",
@@ -676,12 +676,6 @@ version = "1.0.7"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "3f9eec918d3f24069decb9af1554cad7c880e2da24a9afd88aca000531ab82c1"
 
-[[package]]
-name = "foldhash"
-version = "0.1.5"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d9c4f5dac5e15c24eb999c26181a6ca40b39fe946cbe4c263c7209467bc83af2"
-
 [[package]]
 name = "generic-array"
 version = "0.14.7"
@@ -713,23 +707,10 @@ checksum = "899def5c37c4fd7b2664648c28120ecec138e4d395b459e5ca34f9cce2dd77fd"
 dependencies = [
  "cfg-if",
  "libc",
- "r-efi 5.3.0",
+ "r-efi",
  "wasip2",
 ]
 
-[[package]]
-name = "getrandom"
-version = "0.4.2"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "0de51e6874e94e7bf76d726fc5d13ba782deca734ff60d5bb2fb2607c7406555"
-dependencies = [
- "cfg-if",
- "libc",
- "r-efi 6.0.0",
- "wasip2",
- "wasip3",
-]
-
 [[package]]
 name = "ghash"
 version = "0.5.1"
@@ -757,15 +738,6 @@ dependencies = [
  "zerocopy",
 ]
 
-[[package]]
-name = "hashbrown"
-version = "0.15.5"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "9229cfe53dfd69f0609a49f65461bd93001ea1ef889cd5529dd176593f5338a1"
-dependencies = [
- "foldhash",
-]
-
 [[package]]
 name = "hashbrown"
 version = "0.16.1"
@@ -847,12 +819,6 @@ dependencies = [
  "serde",
 ]
 
-[[package]]
-name = "id-arena"
-version = "2.3.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "3d3067d79b975e8844ca9eb072e16b31c3c1c36928edf9c6789548c524d0d954"
-
 [[package]]
 name = "indexmap"
 version = "2.13.0"
@@ -860,18 +826,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "7714e70437a7dc3ac8eb7e6f8df75fd8eb422675fc7678aff7364301092b1017"
 dependencies = [
  "equivalent",
- "hashbrown 0.16.1",
- "serde",
- "serde_core",
-]
-
-[[package]]
-name = "indoc"
-version = "2.0.7"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "79cf5c93f93228cf8efb3ba362535fb11199ac548a09ce117c9b1adc3030d706"
-dependencies = [
- "rustversion",
+ "hashbrown",
 ]
 
 [[package]]
@@ -949,12 +904,6 @@ version = "1.5.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "bbd2bcb4c963f2ddae06a2efc7e9f3591312473c50c6685e1f298068316e66fe"
 
-[[package]]
-name = "leb128fmt"
-version = "0.1.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "09edd9e8b54e49e587e4f6295a7d29c3ea94d469cb40ab8ca70b288248a81db2"
-
 [[package]]
 name = "libc"
 version = "0.2.183"
@@ -1012,15 +961,6 @@ dependencies = [
  "libc",
 ]
 
-[[package]]
-name = "memoffset"
-version = "0.9.1"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "488016bfae457b036d996092f6cb448677611ce4449e970ceaf42695203f218a"
-dependencies = [
- "autocfg",
-]
-
 [[package]]
 name = "miniz_oxide"
 version = "0.8.9"
@@ -1173,16 +1113,6 @@ dependencies = [
  "zerocopy",
 ]
 
-[[package]]
-name = "prettyplease"
-version = "0.2.37"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "479ca8adacdd7ce8f1fb39ce9ecccbfe93a3f1344b3d0d97f20bc0196208f62b"
-dependencies = [
- "proc-macro2",
- "syn",
-]
-
 [[package]]
 name = "proc-macro-error-attr2"
 version = "2.0.0"
@@ -1286,36 +1216,32 @@ dependencies = [
 
 [[package]]
 name = "pyo3"
-version = "0.25.1"
+version = "0.29.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "8970a78afe0628a3e3430376fc5fd76b6b45c4d43360ffd6cdd40bdde72b682a"
+checksum = "cd274650b21d4bfc26a0a47587962c1edb425f69287324355cd040c3ea66071c"
 dependencies = [
- "indoc",
  "libc",
- "memoffset",
  "once_cell",
  "portable-atomic",
  "pyo3-build-config",
  "pyo3-ffi",
  "pyo3-macros",
- "unindent",
 ]
 
 [[package]]
 name = "pyo3-build-config"
-version = "0.25.1"
+version = "0.29.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "458eb0c55e7ece017adeba38f2248ff3ac615e53660d7c71a238d7d2a01c7598"
+checksum = "c5e2a7d2f0d013342f295c048ad19237add5154a55b1c5a254c0ec93d4109078"
 dependencies = [
- "once_cell",
  "target-lexicon",
 ]
 
 [[package]]
 name = "pyo3-ffi"
-version = "0.25.1"
+version = "0.29.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "7114fe5457c61b276ab77c5055f206295b812608083644a5c5b2640c3102565c"
+checksum = "ca85c467da1bbc8d866eea5deff9cf29ea5f7785054a17da36e65bda9c05845b"
 dependencies = [
  "libc",
  "pyo3-build-config",
@@ -1323,9 +1249,9 @@ dependencies = [
 
 [[package]]
 name = "pyo3-macros"
-version = "0.25.1"
+version = "0.29.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "a8725c0a622b374d6cb051d11a0983786448f7785336139c3c94f5aa6bef7e50"
+checksum = "9ac53762fd065daa3194dd09337a38bd793a188100fd1a9304c4ab312d901771"
 dependencies = [
  "proc-macro2",
  "pyo3-macros-backend",
@@ -1335,13 +1261,12 @@ dependencies = [
 
 [[package]]
 name = "pyo3-macros-backend"
-version = "0.25.1"
+version = "0.29.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "4109984c22491085343c05b0dbc54ddc405c3cf7b4374fc533f5c3313a572ccc"
+checksum = "4ca3a1557399783172dc5bf39cfca835157732532cba56b71d2292161e53b362"
 dependencies = [
  "heck",
  "proc-macro2",
- "pyo3-build-config",
  "quote",
  "syn",
 ]
@@ -1376,12 +1301,6 @@ version = "5.3.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "69cdb34c158ceb288df11e18b4bd39de994f6657d83847bdffdbd7f346754b0f"
 
-[[package]]
-name = "r-efi"
-version = "6.0.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "f8dcc9c7d52a811697d2151c701e0d08956f92b0e24136cf4cf27b57a6a0d9bf"
-
 [[package]]
 name = "rand"
 version = "0.9.2"
@@ -1771,7 +1690,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "32497e9a4c7b38532efcdebeef879707aa9f794296a4f0244f6f69e9bc8574bd"
 dependencies = [
  "fastrand",
- "getrandom 0.4.2",
+ "getrandom 0.3.4",
  "once_cell",
  "rustix 1.1.4",
  "windows-sys 0.61.2",
@@ -1900,18 +1819,6 @@ version = "1.0.24"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "e6e4313cd5fcd3dad5cafa179702e2b244f760991f45397d14d4ebf38247da75"
 
-[[package]]
-name = "unicode-xid"
-version = "0.2.6"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "ebc1c04c71510c7f702b52b7c350734c9ff1295c464a03335b00bb84fc54f853"
-
-[[package]]
-name = "unindent"
-version = "0.2.4"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "7264e107f553ccae879d21fbea1d6724ac785e8c3bfc762137959b5802826ef3"
-
 [[package]]
 name = "universal-hash"
 version = "0.5.1"
@@ -1984,15 +1891,6 @@ dependencies = [
  "wit-bindgen",
 ]
 
-[[package]]
-name = "wasip3"
-version = "0.4.0+wasi-0.3.0-rc-2026-01-06"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "5428f8bf88ea5ddc08faddef2ac4a67e390b88186c703ce6dbd955e1c145aca5"
-dependencies = [
- "wit-bindgen",
-]
-
 [[package]]
 name = "wasm-bindgen"
 version = "0.2.114"
@@ -2038,40 +1936,6 @@ dependencies = [
  "unicode-ident",
 ]
 
-[[package]]
-name = "wasm-encoder"
-version = "0.244.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "990065f2fe63003fe337b932cfb5e3b80e0b4d0f5ff650e6985b1048f62c8319"
-dependencies = [
- "leb128fmt",
- "wasmparser",
-]
-
-[[package]]
-name = "wasm-metadata"
-version = "0.244.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "bb0e353e6a2fbdc176932bbaab493762eb1255a7900fe0fea1a2f96c296cc909"
-dependencies = [
- "anyhow",
- "indexmap",
- "wasm-encoder",
- "wasmparser",
-]
-
-[[package]]
-name = "wasmparser"
-version = "0.244.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "47b807c72e1bac69382b3a6fb3dbe8ea4c0ed87ff5629b8685ae6b9a611028fe"
-dependencies = [
- "bitflags 2.11.0",
- "hashbrown 0.15.5",
- "indexmap",
- "semver",
-]
-
 [[package]]
 name = "web-sys"
 version = "0.3.91"
@@ -2307,88 +2171,6 @@ name = "wit-bindgen"
 version = "0.51.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "d7249219f66ced02969388cf2bb044a09756a083d0fab1e566056b04d9fbcaa5"
-dependencies = [
- "wit-bindgen-rust-macro",
-]
-
-[[package]]
-name = "wit-bindgen-core"
-version = "0.51.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "ea61de684c3ea68cb082b7a88508a8b27fcc8b797d738bfc99a82facf1d752dc"
-dependencies = [
- "anyhow",
- "heck",
- "wit-parser",
-]
-
-[[package]]
-name = "wit-bindgen-rust"
-version = "0.51.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b7c566e0f4b284dd6561c786d9cb0142da491f46a9fbed79ea69cdad5db17f21"
-dependencies = [
- "anyhow",
- "heck",
- "indexmap",
- "prettyplease",
- "syn",
- "wasm-metadata",
- "wit-bindgen-core",
- "wit-component",
-]
-
-[[package]]
-name = "wit-bindgen-rust-macro"
-version = "0.51.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "0c0f9bfd77e6a48eccf51359e3ae77140a7f50b1e2ebfe62422d8afdaffab17a"
-dependencies = [
- "anyhow",
- "prettyplease",
- "proc-macro2",
- "quote",
- "syn",
- "wit-bindgen-core",
- "wit-bindgen-rust",
-]
-
-[[package]]
-name = "wit-component"
-version = "0.244.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "9d66ea20e9553b30172b5e831994e35fbde2d165325bec84fc43dbf6f4eb9cb2"
-dependencies = [
- "anyhow",
- "bitflags 2.11.0",
- "indexmap",
- "log",
- "serde",
- "serde_derive",
- "serde_json",
- "wasm-encoder",
- "wasm-metadata",
- "wasmparser",
- "wit-parser",
-]
-
-[[package]]
-name = "wit-parser"
-version = "0.244.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "ecc8ac4bc1dc3381b7f59c34f00b67e18f910c2c0f50015669dde7def656a736"
-dependencies = [
- "anyhow",
- "id-arena",
- "indexmap",
- "log",
- "semver",
- "serde",
- "serde_derive",
- "serde_json",
- "unicode-xid",
- "wasmparser",
-]
 
 [[package]]
 name = "xxhash-rust"

{cachekit-0.8.0 → cachekit-0.9.1}/Cargo.toml

@@ -4,7 +4,7 @@ members = ["rust"]
 exclude = ["rust/fuzz"]
 
 [workspace.dependencies]
-pyo3 = { version = "0.25", features = ["extension-module"] }
+pyo3 = { version = "0.29", features = ["extension-module"] }
 serde = { version = "1.0", features = ["derive"] }
 serde_json = "1.0"
 bincode = "1.3"

{cachekit-0.8.0 → cachekit-0.9.1}/PKG-INFO

@@ -1,12 +1,11 @@
 Metadata-Version: 2.4
 Name: cachekit
-Version: 0.8.0
+Version: 0.9.1
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
@@ -44,7 +43,7 @@ Home-Page: https://github.com/cachekit-io/cachekit-py
 Author-email: cachekit Contributors <noreply@cachekit.io>
 Maintainer-email: cachekit Contributors <noreply@cachekit.io>
 License: MIT
-Requires-Python: >=3.9
+Requires-Python: >=3.10
 Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
 Project-URL: Changelog, https://github.com/cachekit-io/cachekit-py/blob/main/CHANGELOG.md
 Project-URL: Documentation, https://github.com/cachekit-io/cachekit-py#readme
@@ -119,7 +118,17 @@ Or with [uv][uv-url] (recommended):
 uv add cachekit
 ```
 
-### Setup (Redis — recommended default)
+### Setup (choose a backend)
+
+cachekit exposes one decorator API over a pluggable backend abstraction. Pick the
+backend that fits your infrastructure — they're peers behind the same `@cache` API:
+
+| Backend | Best for | Select with |
+|---------|----------|-------------|
+| Redis | Self-hosted, full control | `REDIS_URL` / `CACHEKIT_REDIS_URL` |
+| CachekitIO | Managed, zero-ops (alpha) | `CACHEKIT_API_KEY` |
+| Memcached | High-throughput, existing infra | `CACHEKIT_MEMCACHED_SERVERS` |
+| File / L1-only | Local dev, tests, no external deps | `CACHEKIT_FILE_CACHE_DIR` / `backend=None` |
 
 ```bash
 # Run Redis locally or use your existing infrastructure
@@ -129,7 +138,7 @@ export REDIS_URL="redis://localhost:6379"
 ```python
 from cachekit import cache
 
-@cache  # Uses Redis backend by default
+@cache  # Auto-detects backend (defaults to Redis at localhost)
 def expensive_api_call(user_id: int):
     return fetch_user_data(user_id)
 ```
@@ -207,26 +216,37 @@ def get_user_profile(user_id: int):
     return db.fetch_user(user_id)
 ```
 
-| Feature | `@cache.minimal` | `@cache.production` | `@cache.secure` | `@cache.io()` | `@cache.local()` |
-|:--------|:----------------:|:-------------------:|:---------------:|:-------------:|:----------------:|
-| Circuit Breaker | - | ✅ | ✅ | ✅ | - |
-| Adaptive Timeouts | - | ✅ | ✅ | ✅ | - |
-| Monitoring | - | ✅ Full | ✅ Full | ✅ Full | ✅ Basic |
-| Integrity Checking | - | ✅ Enabled | ✅ Enforced | ✅ Enabled | - |
-| Encryption | - | - | ✅ Required | - | - |
-| Backend | Redis | Redis | Redis | CachekitIO SaaS | In-process |
-| **Use Case** | High throughput | Production reliability | Compliance/security | Managed cloud | Opaque objects |
+| Feature | `@cache.minimal` | `@cache.dev` | `@cache.test` | `@cache.production` | `@cache.secure` |
+|:--------|:----------------:|:------------:|:-------------:|:-------------------:|:---------------:|
+| Circuit Breaker | - | ✅ | - | ✅ | ✅ |
+| Adaptive Timeouts | - | ✅ | - | ✅ | ✅ |
+| Backpressure | ✅ | ✅ | - | ✅ | ✅ |
+| Integrity Checking | - | ✅ | - | ✅ | ✅ 🔒 |
+| Encryption | - | - | - | - | ✅ Required |
+| L1 SWR | - | ✅ | - | ✅ | ✅ |
+| L1 Invalidation | - | - | - | ✅ | ✅ |
+| L1 Namespace Index | - | - | - | ✅ | ✅ |
+| Prometheus Metrics | - | - | - | ✅ | ✅ |
+| Tracing | - | ✅ | - | ✅ | ✅ |
+| Structured Logging | - | ✅ | - | ✅ | ✅ |
+| **Use Case** | High throughput | Local debugging | Deterministic tests | Production reliability | Compliance/security |
+
+> 🔒 `@cache.secure` forces `integrity_checking=True` — it cannot be overridden.
+>
+> **`@cache.io()`** mirrors `@cache.production` (full reliability + observability) but routes to the managed CachekitIO SaaS backend instead of Redis. **`@cache.local()`** is a separate in-process path backed by `ObjectCache` (raw object references, entry-count LRU, no serialization) — the reliability and encryption features listed above do not apply to it.
 
 <details>
-<summary><strong>Additional Presets</strong></summary>
+<summary><strong>Additional Presets: <code>@cache.dev</code> and <code>@cache.test</code></strong></summary>
+
+See the comparison table above for the exact feature set of each preset.
 
 ```python
-# Development: debugging with verbose output
+# Development: verbose logging, integrity checks on, Prometheus off
 @cache.dev
 def debug_expensive_call():
     return complex_computation()
 
-# Testing: deterministic, no randomness
+# Testing: deterministic, all protections off (no circuit breaker, no backpressure)
 @cache.test
 def test_cached_function():
     return fixed_test_value()
@@ -356,12 +376,36 @@ See [SECURITY.md][security-url] for vulnerability reporting and detailed documen
 
 </details>
 
-### Built-in Monitoring
+### Monitoring & Observability
 
-- **Prometheus metrics** - Production-ready observability
+- **Per-function statistics** - `cache_info()` on every decorated function, modelled on `functools.lru_cache`
+- **Prometheus metrics** - Recorded by default (your app owns exposition)
 - **Structured logging** - Context-aware with correlation IDs
 - **Health checks** - Comprehensive status endpoints
-- **Performance tracking** - Built-in latency monitoring
+
+Every decorated function exposes `cache_info()`, returning a `CacheInfo` named tuple with
+hit/miss counts, the L1/L2 split, and average backend latency:
+
+```python
+@cache()
+def get_score(x):
+    return x ** 2
+
+get_score(2)
+get_score(2)  # served from cache
+
+info = get_score.cache_info()
+# CacheInfo has 9 fields: hits, misses, l1_hits, l2_hits, maxsize,
+# currsize, l2_avg_latency_ms, last_operation_at, session_id
+assert info.l1_hits + info.l2_hits == info.hits  # every hit is L1 or L2
+```
+
+`maxsize` and `currsize` are always `None` (the cache lives in an external store, not a
+bounded in-process dict); they exist only for `lru_cache` API parity. See the
+[API Reference](docs/api-reference.md#per-function-statistics-via-cache_info) for the full
+field reference and a sample stats endpoint, and the
+[Prometheus Metrics guide](docs/features/prometheus-metrics.md) for metric names and
+exposition setup.
 
 <details>
 <summary><strong>Thread Safety Details</strong></summary>
@@ -381,8 +425,10 @@ def expensive_func(x):
 with ThreadPoolExecutor(max_workers=10) as executor:
     results = list(executor.map(expensive_func, range(100)))
 
-print(expensive_func.cache_info())
-# CacheInfo(hits=90, misses=10, maxsize=None, currsize=10)
+info = expensive_func.cache_info()
+# CacheInfo(hits=..., misses=..., l1_hits=..., l2_hits=...,
+#           maxsize=None, currsize=None, l2_avg_latency_ms=...,
+#           last_operation_at=..., session_id=...)
 ```
 
 </details>
@@ -459,7 +505,7 @@ See [CONTRIBUTING.md][contributing-url] for full development guidelines.
 
 | Component | Version |
 |:----------|:--------|
-| Python | 3.9+ |
+| Python | 3.10+ |
 
 ---