PyPI - cachekit - Versions diffs - 0.24.1__tar.gz → 0.25.1__tar.gz - Mend

cachekit 0.24.1tar.gz → 0.25.1tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (90) hide show

{cachekit-0.24.1 → cachekit-0.25.1}/Cargo.lock RENAMED Viewed

@@ -1,6 +1,6 @@
 # This file is automatically @generated by Cargo.
 # It is not intended for manual editing.
-version = 3
+version = 4
 [[package]]
 name = "addr2line"
@@ -100,56 +100,12 @@ version = "0.1.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "4b46cbb362ab8752921c97e041f5e366ee6297bd428a31275b9fcf1e380f7299"
-[[package]]
-name = "anstream"
-version = "1.0.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "824a212faf96e9acacdbd09febd34438f8f711fb84e09a8916013cd7815ca28d"
-dependencies = [
- "anstyle",
- "anstyle-parse",
- "anstyle-query",
- "anstyle-wincon",
- "colorchoice",
- "is_terminal_polyfill",
- "utf8parse",
-]
 [[package]]
 name = "anstyle"
 version = "1.0.14"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "940b3a0ca603d1eade50a4846a2afffd5ef57a9feac2c0e2ec2e14f9ead76000"
-[[package]]
-name = "anstyle-parse"
-version = "1.0.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "52ce7f38b242319f7cabaa6813055467063ecdc9d355bbb4ce0c68908cd8130e"
-dependencies = [
- "utf8parse",
-]
-[[package]]
-name = "anstyle-query"
-version = "1.1.5"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "40c48f72fd53cd289104fc64099abca73db4166ad86ea0b4341abe65af83dadc"
-dependencies = [
- "windows-sys 0.60.2",
-]
-[[package]]
-name = "anstyle-wincon"
-version = "3.0.11"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "291e6a250ff86cd4a820112fb8898808a366d8f9f58ce16d1f538353ad55747d"
-dependencies = [
- "anstyle",
- "once_cell_polyfill",
- "windows-sys 0.60.2",
-]
 [[package]]
 name = "anyhow"
 version = "1.0.102"
@@ -240,29 +196,14 @@ version = "1.25.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "c8efb64bd706a16a1bdde310ae86b351e4d21550d98d056f22f8a7f7a2183fec"
-[[package]]
-name = "byteorder"
-version = "1.5.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "1fd0f2584146f6f2ef48085050886acf353beff7305ebd1ae69500e27c67f64b"
-[[package]]
-name = "bytes"
-version = "1.11.1"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "1e748733b7cbc798e1434b6ac524f0c1ff2ab456fe201501e6497c8417a4fc33"
 [[package]]
 name = "cachekit-core"
-version = "0.6.0"
+version = "0.7.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "93adc5646956ba8da140f4179a02e60a2cc7a401b83ebb1270cc4d03748e1fac"
+checksum = "101672176881ef05b17e8399476eb6fc2082e6a5c33788c84c9bb4d1a8d512d7"
 dependencies = [
  "aes",
  "aes-gcm",
- "byteorder",
- "bytes",
- "cbindgen",
  "generic-array",
  "getrandom 0.2.17",
  "hkdf",
@@ -280,7 +221,7 @@ dependencies = [
 [[package]]
 name = "cachekit-rs"
-version = "0.24.1"
+version = "0.25.1"
 dependencies = [
  "cachekit-core",
  "criterion 0.8.2",
@@ -300,25 +241,6 @@ version = "0.3.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "37b2a672a2cb129a2e41c10b1224bb368f9f37a2b16b612598138befd7b37eb5"
-[[package]]
-name = "cbindgen"
-version = "0.29.2"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "befbfd072a8e81c02f8c507aefce431fe5e7d051f83d48a23ffc9b9fe5a11799"
-dependencies = [
- "clap",
- "heck",
- "indexmap",
- "log",
- "proc-macro2",
- "quote",
- "serde",
- "serde_json",
- "syn",
- "tempfile",
- "toml",
-]
 [[package]]
 name = "cc"
 version = "1.2.57"
@@ -387,10 +309,8 @@ version = "4.6.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "714a53001bf66416adb0e2ef5ac857140e7dc3a0c48fb28b2f10762fc4b5069f"
 dependencies = [
- "anstream",
  "anstyle",
  "clap_lex",
- "strsim",
  "terminal_size",
 ]
@@ -400,12 +320,6 @@ version = "1.1.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "c8d4a3bb8b1e0c1050499d1815f5ab16d04f0959b233085fb31653fbfc9d98f9"
-[[package]]
-name = "colorchoice"
-version = "1.0.5"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "1d07550c9036bf2ae0c684c4297d503f838287c83c53686d05370d0e139ae570"
 [[package]]
 name = "condtype"
 version = "1.3.0"
@@ -667,7 +581,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "39cab71617ae0d63f51a36d69f866391735b51691dbda63cf6f96d042b63efeb"
 dependencies = [
  "libc",
- "windows-sys 0.52.0",
+ "windows-sys 0.61.2",
 ]
 [[package]]
@@ -888,15 +802,9 @@ checksum = "3640c1c38b8e4e43584d8df18be5fc6b0aa314ce6ebf51b53313d4306cca8e46"
 dependencies = [
  "hermit-abi",
  "libc",
- "windows-sys 0.52.0",
+ "windows-sys 0.61.2",
 ]
-[[package]]
-name = "is_terminal_polyfill"
-version = "1.70.2"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "a6cb138bb79a146c1bd460005623e142ef0181e3d0219cb493e02f7d08a35695"
 [[package]]
 name = "itertools"
 version = "0.10.5"
@@ -987,9 +895,6 @@ name = "lz4_flex"
 version = "0.12.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "90071f8077f8e40adfc4b7fe9cd495ce316263f19e75c2211eeff3fdf475a3d9"
-dependencies = [
- "twox-hash",
-]
 [[package]]
 name = "memchr"
@@ -1060,12 +965,6 @@ version = "1.21.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50"
-[[package]]
-name = "once_cell_polyfill"
-version = "1.70.2"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "384b8ab6d37215f3c5301a95a4accb5d64aa607f1fcb26a11b5303878451b4fe"
 [[package]]
 name = "oorandom"
 version = "11.1.5"
@@ -1538,7 +1437,7 @@ dependencies = [
  "errno",
  "libc",
  "linux-raw-sys 0.12.1",
- "windows-sys 0.52.0",
+ "windows-sys 0.61.2",
 ]
 [[package]]
@@ -1633,15 +1532,6 @@ dependencies = [
  "zmij",
 ]
-[[package]]
-name = "serde_spanned"
-version = "1.0.4"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "f8bbf91e5a4d6315eee45e704372590b30e260ee83af6639d64557f51b067776"
-dependencies = [
- "serde_core",
-]
 [[package]]
 name = "sha2"
 version = "0.10.9"
@@ -1686,12 +1576,6 @@ version = "0.1.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "9091b6114800a5f2141aee1d1b9d6ca3592ac062dc5decb3764ec5895a47b4eb"
-[[package]]
-name = "strsim"
-version = "0.11.1"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "7da8b5736845d9f2fcb837ea5d9e2628564b3b043a70948a3f0b778838c5fb4f"
 [[package]]
 name = "subtle"
 version = "2.6.1"
@@ -1748,7 +1632,7 @@ dependencies = [
  "getrandom 0.3.4",
  "once_cell",
  "rustix 1.1.4",
- "windows-sys 0.52.0",
+ "windows-sys 0.61.2",
 ]
 [[package]]
@@ -1811,51 +1695,6 @@ dependencies = [
  "serde_json",
 ]
-[[package]]
-name = "toml"
-version = "0.9.12+spec-1.1.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "cf92845e79fc2e2def6a5d828f0801e29a2f8acc037becc5ab08595c7d5e9863"
-dependencies = [
- "indexmap",
- "serde_core",
- "serde_spanned",
- "toml_datetime",
- "toml_parser",
- "toml_writer",
- "winnow",
-]
-[[package]]
-name = "toml_datetime"
-version = "0.7.5+spec-1.1.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "92e1cfed4a3038bc5a127e35a2d360f145e1f4b971b551a2ba5fd7aedf7e1347"
-dependencies = [
- "serde_core",
-]
-[[package]]
-name = "toml_parser"
-version = "1.0.9+spec-1.1.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "702d4415e08923e7e1ef96cd5727c0dfed80b4d2fa25db9647fe5eb6f7c5a4c4"
-dependencies = [
- "winnow",
-]
-[[package]]
-name = "toml_writer"
-version = "1.0.6+spec-1.1.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "ab16f14aed21ee8bfd8ec22513f7287cd4a91aa92e44edfe2c17ddd004e92607"
-[[package]]
-name = "twox-hash"
-version = "2.1.2"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "9ea3136b675547379c4bd395ca6b938e5ad3c3d20fad76e7fe85f9e0d011419c"
 [[package]]
 name = "typenum"
 version = "1.19.0"
@@ -1890,12 +1729,6 @@ version = "0.9.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "8ecb6da28b8a351d773b68d5825ac39017e680750f980f3a1a85cd8dd28a47c1"
-[[package]]
-name = "utf8parse"
-version = "0.2.2"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "06abde3611657adf66d383f00b093d7faecc7fa57071cce2578660c9f1010821"
 [[package]]
 name = "uuid"
 version = "1.22.0"
@@ -2035,7 +1868,7 @@ version = "0.1.11"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "c2a7b1c03c876122aa43f3020e6c3c3ee5c05081c9a00739faf7503aeba10d22"
 dependencies = [
- "windows-sys 0.52.0",
+ "windows-sys 0.61.2",
 ]
 [[package]]
@@ -2215,12 +2048,6 @@ version = "0.53.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "d6bbff5f0aada427a1e5a6da5f1f98158182f26556f345ac9e04d36d0ebed650"
-[[package]]
-name = "winnow"
-version = "0.7.15"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "df79d97927682d2fd8adb29682d1140b343be4ac0f08fd68b7765d9c059d3945"
 [[package]]
 name = "wit-bindgen"
 version = "0.51.0"

{cachekit-0.24.1 → cachekit-0.25.1}/PKG-INFO RENAMED Viewed

@@ -1,16 +1,16 @@
 Metadata-Version: 2.4
 Name: cachekit
-Version: 0.24.1
+Version: 0.25.1
 Classifier: Development Status :: 4 - Beta
 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.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: Programming Language :: Python :: 3.15
 Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: Programming Language :: Rust
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
@@ -24,7 +24,6 @@ Requires-Dist: redis[hiredis]>=4.6.0
 Requires-Dist: pydantic>=2.0.0
 Requires-Dist: pydantic-settings>=2.13.0
 Requires-Dist: prometheus-client>=0.22.1
-Requires-Dist: psutil>=7.0.0
 Requires-Dist: blake3>=1.0.5
 Requires-Dist: msgpack>=1.2.1
 Requires-Dist: xxhash>=3.5.0
@@ -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.10
+Requires-Python: >=3.11
 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
@@ -297,9 +296,9 @@ def test_cached_function():
 │  │   Breaker   │  │  Timeouts   │  │      Locking        │  │
 │  └─────────────┘  └─────────────┘  └─────────────────────┘  │
 ├─────────────────────────────────────────────────────────────┤
-│  L1 Cache (In-Memory)  │  L2 Cache (Pluggable Backend)     │
-│       ~50ns            │  Redis / CachekitIO / File /      │
-│                        │  Memcached    ~2-50ms             │
+│  L1 Cache (In-Memory)  │  L2 Cache (Pluggable Backend)      │
+│       in-process       │  Redis / CachekitIO / File /       │
+│                        │  Memcached: one backend round trip │
 ├─────────────────────────────────────────────────────────────┤
 │                    Rust Core (PyO3)                         │
 │  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
@@ -314,12 +313,31 @@ def test_cached_function():
 ---
+## Performance
+What a call costs inside your process, from the wall-clock guards in `tests/performance/` run on a GitHub-hosted `ubuntu-latest` runner (AMD EPYC 7763, 4 vCPUs) with CPython 3.14.7. Each figure is the mean of five run medians with its 95% band.
+| Path | Time per call |
+|:-----|--------------:|
+| `@cache(backend=None)` L1 hit, 100-user nested dict (23.5 KB as MessagePack) | 0.906 ± 0.007 µs |
+| `@cache(backend=None)` L1 hit, 10K-row DataFrame | 0.91 ± 0.01 µs |
+| L1 hit with an L2 backend configured, same dict | 310 ± 20 µs |
+| Redis L2 hit with L1 disabled, same dict, Redis in a container on the same machine | 551 ± 18 µs |
+- With no backend, L1 keeps the returned object itself, whatever the payload's size, and a repeat call with a few short scalar arguments finds its cache key in a per-function memo instead of building it again ([which calls](https://github.com/cachekit-io/cachekit-py/blob/main/docs/performance.md#decorator--l1-hit-hot-path)). Any other call builds its key every time, as does every call to a function with a backend.
+- With an L2 backend, L1 holds the serialized bytes and every hit deserializes them: for this dict, about 340 times the L1-only hit. Encryption adds a decrypt to each such hit; on this run that added 10 ± 21 µs, inside the noise.
+- An L2 hit adds the backend's round trip. A Redis on another machine adds its network latency to the last row.
+Hosted runners come with other CPU models too: in a run of an earlier commit, an EPYC 9V45 runner took about half as long on every row, and other machines give other figures. The [Performance Guide](https://github.com/cachekit-io/cachekit-py/blob/main/docs/performance.md#github-hosted-runner) names the guard behind each figure and how to run it, and the repository's `Bench` workflow repeats the run.
+---
 ## Features
 ### Production Hardened
 - Circuit breaker with graceful degradation
-- Connection pooling with thread affinity (+28% throughput)
+- Connection pooling with thread affinity
 - CachekitIO keeps idle connections pooled until the server closes them, with TCP keepalive probes, so a request after a pause skips a new TLS handshake
 - Distributed locking prevents cache stampedes
 - Pluggable backend abstraction (Redis, CachekitIO, File, Memcached, custom)
@@ -333,7 +351,7 @@ def test_cached_function():
 | Serializer | Speed | Use Case |
 |:-----------|:-----:|:---------|
 | **StandardSerializer** | ★★★★☆ | General Python types; not NumPy arrays or pandas objects |
-| **OrjsonSerializer** | ★★★★★ | JSON APIs (2-5x faster than stdlib) — requires `cachekit[json]` |
+| **OrjsonSerializer** | ★★★★★ | JSON APIs — requires `cachekit[json]` |
 | **ArrowSerializer** | — | pandas DataFrames (columnar, exact round trip) |
 | **+ Encryption** | ★★★★☆ | Any serializer above, AES-256-GCM encrypted: `@cache.secure(master_key=..., serializer=...)` |
@@ -383,15 +401,18 @@ assert calls == 1
 ### Integrity Checking
 > [!IMPORTANT]
-> All serializers support **configurable checksums** for corruption detection using xxHash3-64 (8 bytes). Enabled by default in `@cache.production` and `@cache.secure`.
+> Serializers detect corrupted entries with an xxHash3-64 checksum. It is on by default. `@cache.minimal` and `@cache.test` turn it off where the serializer allows it (`ArrowSerializer` always checks); `@cache.secure` refuses to turn it off.
+Each checksum is an 8-byte digest, plus one pass over the payload on each write and read. What `enable_integrity_checking=False` changes depends on the serializer, and for `AutoSerializer` on the value:
-**Performance Impact** (benchmark-proven):
+| Serializer | Checking on (default) | Checking off |
+|:-----------|:----------------------|:-------------|
+| `StandardSerializer`, and `AutoSerializer` for values other than the two below | MessagePack in an LZ4 envelope that carries the checksum | Plain MessagePack: no checksum, no LZ4 |
+| `AutoSerializer`, NumPy arrays | The checksum, then the raw array bytes (never compressed) | The raw array bytes |
+| `AutoSerializer`, pandas DataFrames with pyarrow installed, and `ArrowSerializer` | The checksum, then the Arrow IPC data | No change: Arrow always checks |
+| `OrjsonSerializer` | The checksum, then the JSON | Plain JSON |
-| Data Type | Latency Reduction (disabled) | Size Overhead |
-|:----------|:----------------------------:|:-------------:|
-| MessagePack (default) | 60-90% | 8 bytes |
-| Arrow DataFrames | 35-49% | 8 bytes |
-| JSON (orjson) | 37-68% | 8 bytes |
+Where the switch drops the LZ4 envelope, an entry gets larger only when LZ4 saved more than the envelope's overhead of about 25 to 30 bytes; otherwise it stays the same size or gets smaller. Measure on your own payloads before you trade that.
 ### Security
@@ -428,7 +449,7 @@ make security-fast     # Run fast checks (< 3 min)
 | Tier | Time | Coverage |
 |:-----|:----:|:---------|
 | Fast | < 3 min | Vulnerability scanning, license checks, linting |
-| Medium | < 15 min | Unsafe code analysis, API stability, Miri subset |
+| Medium | < 15 min | Unsafe code analysis (cargo-geiger) |
 | Deep | < 2 hours | Formal verification, extended fuzzing, full sanitizers |
 See [SECURITY.md][security-url] for vulnerability reporting and detailed documentation.
@@ -470,11 +491,14 @@ exposition setup.
 <details>
 <summary><strong>Thread Safety Details</strong></summary>
-**Free-threaded CPython (3.14t):** the core suites run green on
-free-threaded 3.14 with the GIL verified disabled (CI job
+**Free-threaded CPython (3.15t, 3.14t):** the core suites run green on
+free-threaded 3.14 and 3.15 with the GIL verified disabled (CI job
 `test-freethreaded`), and the Rust extension declares free-threaded safety
-(`gil_used = false`). Free-threaded wheels are **not yet published** and
-free-threaded builds are not officially supported — blocked upstream on
+(`gil_used = false`). **From the release after 0.24.1, 3.15t has a wheel**:
+the 3.15+ wheel is `abi3t`, so it installs on 3.15t without a Rust toolchain
+(pip 26.1+ or uv 0.11.3+). **3.14t is tested
+but has no wheel** (it builds from source). Free-threaded builds are not
+officially supported yet — blocked upstream on
 orjson (no free-threaded wheels) and hiredis (re-enables the GIL on import;
 cachekit loads redis-py only for its Redis backend, and keeps hiredis out there,
 so redis-py uses its pure-Python parser). See
@@ -483,7 +507,7 @@ full concurrency audit: [docs/free-threading.md](docs/free-threading.md).
 **Per-Function Statistics:**
 - Statistics tracked per function identity (`module.qualname`), shared across all calls and across re-decorations of the same function
-- Thread-safe via RLock (all methods safe for concurrent access)
+- Thread-safe: every count is exact (L1 hits on an atomic counter, everything else under an RLock), and all methods are safe for concurrent access
 - Fork-safe: a forked child starts with zeroed counters and its own session ID
 ```python
@@ -532,6 +556,7 @@ info = expensive_func.cache_info()
 | [Reference Caching][reference-caching-url] | `@cache.local()` for non-serializable objects |
 | [Rust Serialization][rust-serialization-url] | ByteStorage layer: LZ4, xxHash3, AES-256-GCM |
 | [SSRF Protection][ssrf-url] | URL allowlisting for the CachekitIO backend |
+| [Write-Behind][write-behind-url] | Opt-in `write_behind=True`: a miss returns before its L2 write lands |
 ---
@@ -585,7 +610,7 @@ See [CONTRIBUTING.md][contributing-url] for full development guidelines.
 | Component | Version |
 |:----------|:--------|
-| Python | 3.10+ |
+| Python | 3.11+ |
 ---
@@ -623,6 +648,7 @@ MIT License - see [LICENSE][license-file-url] for details.
 [reference-caching-url]: docs/features/reference-caching.md
 [rust-serialization-url]: docs/features/rust-serialization.md
 [ssrf-url]: docs/features/ssrf-protection.md
+[write-behind-url]: docs/features/write-behind.md
 [contributing-url]: CONTRIBUTING.md
 [license-file-url]: LICENSE
 [github-url]: https://github.com/cachekit-io/cachekit-py

{cachekit-0.24.1 → cachekit-0.25.1}/README.md RENAMED Viewed

@@ -243,9 +243,9 @@ def test_cached_function():
 │  │   Breaker   │  │  Timeouts   │  │      Locking        │  │
 │  └─────────────┘  └─────────────┘  └─────────────────────┘  │
 ├─────────────────────────────────────────────────────────────┤
-│  L1 Cache (In-Memory)  │  L2 Cache (Pluggable Backend)     │
-│       ~50ns            │  Redis / CachekitIO / File /      │
-│                        │  Memcached    ~2-50ms             │
+│  L1 Cache (In-Memory)  │  L2 Cache (Pluggable Backend)      │
+│       in-process       │  Redis / CachekitIO / File /       │
+│                        │  Memcached: one backend round trip │
 ├─────────────────────────────────────────────────────────────┤
 │                    Rust Core (PyO3)                         │
 │  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
@@ -260,12 +260,31 @@ def test_cached_function():
 ---
+## Performance
+What a call costs inside your process, from the wall-clock guards in `tests/performance/` run on a GitHub-hosted `ubuntu-latest` runner (AMD EPYC 7763, 4 vCPUs) with CPython 3.14.7. Each figure is the mean of five run medians with its 95% band.
+| Path | Time per call |
+|:-----|--------------:|
+| `@cache(backend=None)` L1 hit, 100-user nested dict (23.5 KB as MessagePack) | 0.906 ± 0.007 µs |
+| `@cache(backend=None)` L1 hit, 10K-row DataFrame | 0.91 ± 0.01 µs |
+| L1 hit with an L2 backend configured, same dict | 310 ± 20 µs |
+| Redis L2 hit with L1 disabled, same dict, Redis in a container on the same machine | 551 ± 18 µs |
+- With no backend, L1 keeps the returned object itself, whatever the payload's size, and a repeat call with a few short scalar arguments finds its cache key in a per-function memo instead of building it again ([which calls](https://github.com/cachekit-io/cachekit-py/blob/main/docs/performance.md#decorator--l1-hit-hot-path)). Any other call builds its key every time, as does every call to a function with a backend.
+- With an L2 backend, L1 holds the serialized bytes and every hit deserializes them: for this dict, about 340 times the L1-only hit. Encryption adds a decrypt to each such hit; on this run that added 10 ± 21 µs, inside the noise.
+- An L2 hit adds the backend's round trip. A Redis on another machine adds its network latency to the last row.
+Hosted runners come with other CPU models too: in a run of an earlier commit, an EPYC 9V45 runner took about half as long on every row, and other machines give other figures. The [Performance Guide](https://github.com/cachekit-io/cachekit-py/blob/main/docs/performance.md#github-hosted-runner) names the guard behind each figure and how to run it, and the repository's `Bench` workflow repeats the run.
+---
 ## Features
 ### Production Hardened
 - Circuit breaker with graceful degradation
-- Connection pooling with thread affinity (+28% throughput)
+- Connection pooling with thread affinity
 - CachekitIO keeps idle connections pooled until the server closes them, with TCP keepalive probes, so a request after a pause skips a new TLS handshake
 - Distributed locking prevents cache stampedes
 - Pluggable backend abstraction (Redis, CachekitIO, File, Memcached, custom)
@@ -279,7 +298,7 @@ def test_cached_function():
 | Serializer | Speed | Use Case |
 |:-----------|:-----:|:---------|
 | **StandardSerializer** | ★★★★☆ | General Python types; not NumPy arrays or pandas objects |
-| **OrjsonSerializer** | ★★★★★ | JSON APIs (2-5x faster than stdlib) — requires `cachekit[json]` |
+| **OrjsonSerializer** | ★★★★★ | JSON APIs — requires `cachekit[json]` |
 | **ArrowSerializer** | — | pandas DataFrames (columnar, exact round trip) |
 | **+ Encryption** | ★★★★☆ | Any serializer above, AES-256-GCM encrypted: `@cache.secure(master_key=..., serializer=...)` |
@@ -329,15 +348,18 @@ assert calls == 1
 ### Integrity Checking
 > [!IMPORTANT]
-> All serializers support **configurable checksums** for corruption detection using xxHash3-64 (8 bytes). Enabled by default in `@cache.production` and `@cache.secure`.
+> Serializers detect corrupted entries with an xxHash3-64 checksum. It is on by default. `@cache.minimal` and `@cache.test` turn it off where the serializer allows it (`ArrowSerializer` always checks); `@cache.secure` refuses to turn it off.
+Each checksum is an 8-byte digest, plus one pass over the payload on each write and read. What `enable_integrity_checking=False` changes depends on the serializer, and for `AutoSerializer` on the value:
-**Performance Impact** (benchmark-proven):
+| Serializer | Checking on (default) | Checking off |
+|:-----------|:----------------------|:-------------|
+| `StandardSerializer`, and `AutoSerializer` for values other than the two below | MessagePack in an LZ4 envelope that carries the checksum | Plain MessagePack: no checksum, no LZ4 |
+| `AutoSerializer`, NumPy arrays | The checksum, then the raw array bytes (never compressed) | The raw array bytes |
+| `AutoSerializer`, pandas DataFrames with pyarrow installed, and `ArrowSerializer` | The checksum, then the Arrow IPC data | No change: Arrow always checks |
+| `OrjsonSerializer` | The checksum, then the JSON | Plain JSON |
-| Data Type | Latency Reduction (disabled) | Size Overhead |
-|:----------|:----------------------------:|:-------------:|
-| MessagePack (default) | 60-90% | 8 bytes |
-| Arrow DataFrames | 35-49% | 8 bytes |
-| JSON (orjson) | 37-68% | 8 bytes |
+Where the switch drops the LZ4 envelope, an entry gets larger only when LZ4 saved more than the envelope's overhead of about 25 to 30 bytes; otherwise it stays the same size or gets smaller. Measure on your own payloads before you trade that.
 ### Security
@@ -374,7 +396,7 @@ make security-fast     # Run fast checks (< 3 min)
 | Tier | Time | Coverage |
 |:-----|:----:|:---------|
 | Fast | < 3 min | Vulnerability scanning, license checks, linting |
-| Medium | < 15 min | Unsafe code analysis, API stability, Miri subset |
+| Medium | < 15 min | Unsafe code analysis (cargo-geiger) |
 | Deep | < 2 hours | Formal verification, extended fuzzing, full sanitizers |
 See [SECURITY.md][security-url] for vulnerability reporting and detailed documentation.
@@ -416,11 +438,14 @@ exposition setup.
 <details>
 <summary><strong>Thread Safety Details</strong></summary>
-**Free-threaded CPython (3.14t):** the core suites run green on
-free-threaded 3.14 with the GIL verified disabled (CI job
+**Free-threaded CPython (3.15t, 3.14t):** the core suites run green on
+free-threaded 3.14 and 3.15 with the GIL verified disabled (CI job
 `test-freethreaded`), and the Rust extension declares free-threaded safety
-(`gil_used = false`). Free-threaded wheels are **not yet published** and
-free-threaded builds are not officially supported — blocked upstream on
+(`gil_used = false`). **From the release after 0.24.1, 3.15t has a wheel**:
+the 3.15+ wheel is `abi3t`, so it installs on 3.15t without a Rust toolchain
+(pip 26.1+ or uv 0.11.3+). **3.14t is tested
+but has no wheel** (it builds from source). Free-threaded builds are not
+officially supported yet — blocked upstream on
 orjson (no free-threaded wheels) and hiredis (re-enables the GIL on import;
 cachekit loads redis-py only for its Redis backend, and keeps hiredis out there,
 so redis-py uses its pure-Python parser). See
@@ -429,7 +454,7 @@ full concurrency audit: [docs/free-threading.md](docs/free-threading.md).
 **Per-Function Statistics:**
 - Statistics tracked per function identity (`module.qualname`), shared across all calls and across re-decorations of the same function
-- Thread-safe via RLock (all methods safe for concurrent access)
+- Thread-safe: every count is exact (L1 hits on an atomic counter, everything else under an RLock), and all methods are safe for concurrent access
 - Fork-safe: a forked child starts with zeroed counters and its own session ID
 ```python
@@ -478,6 +503,7 @@ info = expensive_func.cache_info()
 | [Reference Caching][reference-caching-url] | `@cache.local()` for non-serializable objects |
 | [Rust Serialization][rust-serialization-url] | ByteStorage layer: LZ4, xxHash3, AES-256-GCM |
 | [SSRF Protection][ssrf-url] | URL allowlisting for the CachekitIO backend |
+| [Write-Behind][write-behind-url] | Opt-in `write_behind=True`: a miss returns before its L2 write lands |
 ---
@@ -531,7 +557,7 @@ See [CONTRIBUTING.md][contributing-url] for full development guidelines.
 | Component | Version |
 |:----------|:--------|
-| Python | 3.10+ |
+| Python | 3.11+ |
 ---
@@ -569,6 +595,7 @@ MIT License - see [LICENSE][license-file-url] for details.
 [reference-caching-url]: docs/features/reference-caching.md
 [rust-serialization-url]: docs/features/rust-serialization.md
 [ssrf-url]: docs/features/ssrf-protection.md
+[write-behind-url]: docs/features/write-behind.md
 [contributing-url]: CONTRIBUTING.md
 [license-file-url]: LICENSE
 [github-url]: https://github.com/cachekit-io/cachekit-py

cachekit 0.24.1__tar.gz → 0.25.1__tar.gz

cachekit 0.24.1tar.gz → 0.25.1tar.gz