cachekit 0.23.0__tar.gz → 0.24.0__tar.gz

{cachekit-0.23.0 → cachekit-0.24.0}/Cargo.lock

@@ -280,7 +280,7 @@ dependencies = [
 
 [[package]]
 name = "cachekit-rs"
-version = "0.23.0"
+version = "0.24.0"
 dependencies = [
  "cachekit-core",
  "criterion 0.8.2",

{cachekit-0.23.0 → cachekit-0.24.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cachekit
-Version: 0.23.0
+Version: 0.24.0
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License

{cachekit-0.23.0 → cachekit-0.24.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "maturin"
 
 [project]
 name = "cachekit"
-version = "0.23.0"
+version = "0.24.0"
 description = "Backend-agnostic caching for Python — intent-based decorators with circuit breaker, distributed locking, Prometheus metrics, and optional zero-knowledge AES-256-GCM encryption, on a Rust-powered core. Zero-config L1 in-memory; scales to Redis, Memcached, File, or CachekitIO."
 readme = "README.md"
 license = {text = "MIT"}
@@ -136,6 +136,7 @@ ignore = [
 [tool.ruff.lint.per-file-ignores]
 "__init__.py" = ["F401"]
 "tests/**/*" = ["S101", "S105", "S110", "S112", "S311", "D", "F841", "N802"]
+"journeys/**/*" = ["S101"]  # a journey states its promise as an assert
 "src/cachekit/logging.py" = ["S110"]  # Logging errors would create recursion
 "src/cachekit/reliability/async_metrics.py" = ["S101"]  # Internal invariant checks
 "src/cachekit/serializers/__init__.py" = ["S101"]  # Module-level validation
@@ -252,6 +253,9 @@ dev = [
     # OrjsonSerializer support — now the [json] optional extra; kept here so the
     # orjson tests, doctests, and markdown-docs still resolve it in dev/CI.
     "orjson>=3.9.0",
+    # ArrowSerializer return_format="polars" tests (zero-copy column aliasing). Not in `test`:
+    # polars ships abi3 wheels only, which a free-threaded interpreter cannot install.
+    "polars>=2.0.0",
 ]
 # Linux CI only - Atheris requires libFuzzer (not available on macOS without building LLVM)
 fuzz = [

{cachekit-0.23.0 → cachekit-0.24.0}/rust/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "cachekit-rs"
-version = "0.23.0"
+version = "0.24.0"
 edition = "2021"
 authors = ["cachekit Contributors"]
 description = "High-performance storage engine for caching with compression and encryption"

{cachekit-0.23.0 → cachekit-0.24.0}/src/cachekit/__init__.py

@@ -68,7 +68,7 @@ Example Usage:
     ```
 """
 
-__version__ = "0.23.0"
+__version__ = "0.24.0"
 
 from collections.abc import Callable
 from typing import Any, TypeVar

{cachekit-0.23.0 → cachekit-0.24.0}/src/cachekit/backends/base.py

@@ -186,9 +186,12 @@ class BufferHandle(Protocol):
     """A borrowed, zero-copy view of a cached value plus the resource backing it.
 
     Returned by ``BufferReadableBackend.get_buffer``. ``view`` aliases backend-owned memory (e.g.
-    mmap'd file pages), not a heap copy — so the consumer must finish reading and ``close()``
-    before the view is touched again. The view DANGLES after close (touching it can segfault), so
-    it must never be stored (e.g. in L1) nor returned past the read call frame (#171).
+    mmap'd file pages), not a heap copy. The consumer reads it, then calls ``close()``; the view
+    is unusable afterwards (unless the consumer exported the view itself, which keeps it readable
+    until that export dies), so it must never be stored (e.g. in L1) nor returned past the read
+    call frame (#171). An object built over the view (an Arrow table) keeps the backing memory
+    alive past ``close()`` through its buffer exports: the implementation must never free memory
+    that is still exported.
     """
 
     view: memoryview

{cachekit-0.23.0 → cachekit-0.24.0}/src/cachekit/backends/file/backend.py

@@ -22,6 +22,7 @@ import os
 import platform
 import stat
 import struct
+import sys
 import threading
 import time
 from collections.abc import Callable
@@ -72,6 +73,12 @@ MAX_TTL_SECONDS: int = 10 * 365 * 24 * 60 * 60  # 10 years max
 # unbounded region. Above this, get_buffer() returns None and the caller falls back to os.read.
 MMAP_MAX_BYTES: int = 512 * 1024 * 1024  # 512 MB
 
+# Python 3.13+ maps without keeping a duplicate of the file descriptor (trackfd=False). Before 3.13
+# every mmap object holds one descriptor until it is freed, so a result that keeps its mapping alive
+# also keeps a descriptor open, and a few hundred held results exhaust RLIMIT_NOFILE.
+MMAP_RELEASES_FD: bool = sys.version_info >= (3, 13)
+_MMAP_KWARGS: dict[str, Any] = {"trackfd": False} if MMAP_RELEASES_FD else {}
+
 
 def _warn_throttled(throttle: _WarnThrottle, msg: str, *args: object) -> None:
     """Log ``msg`` at WARNING once per throttle window, with the failures since the last one; DEBUG otherwise."""
@@ -134,9 +141,24 @@ class _MmapHandle:
     """Owns a read-only mmap of a cache file plus a memoryview of its payload (past the 14-byte
     header). Zero-copy: the view aliases mapped pages, never a heap copy.
 
-    The CALLER must ``close()`` once the consumer is done (after Arrow deserialize has copied the
-    data out via to_pandas). The view DANGLES after close — touching it segfaults — so the handle
-    must never escape the deserialize call frame and must never be stored in L1 (#171 blocker C).
+    The CALLER must ``close()`` once deserialize returns. Lifetime contract (CPython):
+
+    - ``close()`` releases the handle's own view, so touching ``handle.view`` afterwards raises
+      ``ValueError`` (unless a consumer exported ``handle.view`` itself: then the release refuses
+      and the view stays readable until that export dies). Either way the handle must never
+      escape the read call frame nor reach L1 (#171 blocker C).
+    - Anything deserialize built over the mapping (an Arrow table, a polars frame, or pandas
+      columns that are views) holds buffer exports of it. ``mmap.close()`` refuses with
+      ``BufferError`` while any export lives; ``close()`` swallows that, and the mapping is
+      unmapped when the last export is released. A result therefore never dangles.
+    - A mapping that outlives the read costs no file descriptor on Python 3.13+ (``trackfd=False``).
+      Before 3.13 the mmap object holds a duplicate descriptor until it is freed, which is why the
+      cache handler maps only pandas results there: they are meant to copy out, and only a pandas
+      column that stays a view of the mapped buffers keeps the mapping and its descriptor.
+    - The file's pages stay valid while mapped because cachekit never rewrites a cache file in
+      place: writes go to a temp file and ``rename``, eviction and delete ``unlink``, and both
+      leave an existing mapping intact. A process that truncates a cache file in place while a
+      result is held makes the next touch of those pages raise ``SIGBUS``.
     """
 
     __slots__ = ("_mm", "view")
@@ -151,11 +173,11 @@ class _MmapHandle:
         """Release the view then the mapping. Idempotent (safe to call more than once)."""
         try:
             self.view.release()  # must release exports before mmap.close(), else BufferError
-        except (ValueError, BufferError):  # pragma: no cover - defensive (already released / lingering sub-export)
+        except BufferError:  # a consumer exported this view itself; it keeps the mapping alive
             pass
         try:
             self._mm.close()
-        except (ValueError, BufferError):  # pragma: no cover - defensive (already closed)
+        except BufferError:  # a result still holds exports of the mapping: refcounting unmaps it later
             pass
 
 
@@ -395,7 +417,7 @@ class FileBackend:
                     if st_size <= HEADER_SIZE or st_size > MMAP_MAX_BYTES:
                         return None
 
-                    mm = mmap.mmap(fd, st_size, access=mmap.ACCESS_READ)
+                    mm = mmap.mmap(fd, st_size, access=mmap.ACCESS_READ, **_MMAP_KWARGS)
                     handle = _MmapHandle(mm)
                     mm = None  # ownership transferred to the handle; don't close it in finally
                     return handle

{cachekit-0.23.0 → cachekit-0.24.0}/src/cachekit/cache_handler.py

@@ -9,6 +9,7 @@ from __future__ import annotations
 import asyncio
 import contextlib
 import contextvars
+import sys
 import threading
 import types
 import warnings
@@ -27,6 +28,8 @@ from cachekit.backends.base import (
     LockableBackend,
     TTLInspectableBackend,
 )
+from cachekit.backends.file.backend import HEADER_SIZE as FILE_HEADER_SIZE
+from cachekit.backends.file.backend import MMAP_RELEASES_FD
 from cachekit.backends.provider import (
     BackendProviderInterface,
     DefaultBackendProvider,
@@ -72,6 +75,14 @@ if TYPE_CHECKING:
 # it chooses its decoder by inspecting the bytes.
 CROSS_SDK_SERIALIZER_NAMES = ("default", "std", "standard", "orjson", "arrow")
 
+# Uncompressed Arrow IPC alignment: the body follows the File header, the CK frame
+# prefix and ArrowSerializer's 8-byte xxHash3-64 checksum; 64 is Arrow's recommended alignment.
+_ARROW_IPC_ALIGN = 64
+_ARROW_CHECKSUM_SIZE = 8
+# Frame tags an ArrowSerializer can record: its string name, or the class name of an instance. A set
+# lookup on the tag screens every other serializer out before the type check, on every read and write.
+_ARROW_FRAME_TAGS = frozenset({"arrow", "ArrowSerializer"})
+
 # Global DI container instance with default registrations
 container = DIContainer()
 container.register(LoggerProvider, DefaultLoggerProvider)
@@ -659,7 +670,7 @@ class CacheSerializationHandler:
 
         Args:
             serializer_name: Serializer instance or name. Accepts either:
-                            - String name: "default" (MessagePack), "arrow" (DataFrame zero-copy), "orjson" (JSON)
+                            - String name: "default" (MessagePack), "arrow" (DataFrames as Arrow IPC), "orjson" (JSON)
                             - SerializerProtocol instance: Custom serializer implementing the protocol
             encryption: Tri-state encryption control (wraps serializer with EncryptionWrapper):
                         - None (default): no intent stated. Plaintext when no master key is present;
@@ -1137,7 +1148,12 @@ class CacheSerializationHandler:
             else:
                 # Convert metadata to dict if needed
                 metadata_dict = metadata.to_dict() if hasattr(metadata, "to_dict") else {}
-                wrapped = SerializationWrapper.wrap(serialized_data, metadata_dict, self._serializer_string_name)
+                if self._serializer_string_name in _ARROW_FRAME_TAGS:
+                    # One prefix builder for this path and write_serialized_to, so buffered and streamed
+                    # entries stay byte-identical (the payload is copied once, as in wrap()).
+                    wrapped = self._frame_prefix(metadata_dict) + serialized_data
+                else:
+                    wrapped = SerializationWrapper.wrap(serialized_data, metadata_dict, self._serializer_string_name)
         except ValueError:
             # Tenant extraction, cache_key missing, or an interop data-model
             # rejection (InteropError) — FAIL CLOSED / fail loud (re-raise).
@@ -1162,28 +1178,60 @@ class CacheSerializationHandler:
             )
         return wrapped
 
+    def _is_cachekit_arrow(self) -> bool:
+        """True iff the base serializer is exactly cachekit's ArrowSerializer, by object, not frame tag.
+
+        ``serializer="arrow"`` and an ``ArrowSerializer(...)`` instance both qualify; the instance's
+        frame tag is its class name, which is why the old ``== "arrow"`` test missed it. Exact type:
+        a subclass may override ``serialize`` and stays on the buffered paths. Read through
+        ``sys.modules`` so a handler that never loaded the module never imports pyarrow here.
+        """
+        if self._serializer_string_name not in _ARROW_FRAME_TAGS:
+            return False
+        module = sys.modules.get("cachekit.serializers.arrow_serializer")
+        return module is not None and type(self._base_serializer) is module.ArrowSerializer
+
+    def _frame_prefix(self, metadata: dict[str, Any]) -> bytes:
+        """The CK frame prefix for a plaintext payload with ``metadata``.
+
+        Uncompressed cachekit Arrow gets its header padded so the Arrow IPC body starts on a
+        64-byte boundary of a File-backend cache file (File header + prefix + 8-byte checksum):
+        polars copies every misaligned numeric column, and pyarrow prefers aligned buffers.
+        Compressed, encrypted and every other payload are left unpadded. The prefix depends only on
+        the serializer configuration, so other backends carry the same padding (and an unaligned body).
+        """
+        if not self.encryption and self._is_cachekit_arrow() and not metadata.get("compressed"):
+            return SerializationWrapper.wrap_prefix(
+                metadata, self._serializer_string_name, align=_ARROW_IPC_ALIGN, offset=FILE_HEADER_SIZE + _ARROW_CHECKSUM_SIZE
+            )
+        return SerializationWrapper.wrap_prefix(metadata, self._serializer_string_name)
+
     def supports_mmap_read(self) -> bool:
-        """True iff reads can use the zero-copy mmap fast path (#171).
+        """True iff reads can use the mmap fast path (#171).
 
-        Eligible only for PLAINTEXT Arrow that returns pandas:
-        - encrypted values can never mmap (AES-GCM decrypt owns its buffer);
-        - non-Arrow serializers gain nothing (they copy at the Rust/C boundary, rebuild objects);
-        - the "arrow" return_format yields a table that ALIASES the mapped pages, so closing the
-          handle would be a use-after-free — pandas (which copies out via to_pandas) only.
+        Eligible only for PLAINTEXT cachekit Arrow (``serializer="arrow"`` or an
+        ``ArrowSerializer(...)`` instance): encrypted values can never mmap (AES-GCM decrypt owns
+        its buffer), and other serializers copy at their Rust/C boundary anyway. Every return_format
+        is eligible on Python 3.13+, pandas only before it (see below). A result may keep the mapping
+        alive past the read; ``_MmapHandle`` states that lifetime contract.
 
         The backend must also support buffer reads (File/POSIX); that is checked separately, so a
         True here on a non-File backend simply means get_buffer returns None and we fall back.
         """
-        return (
-            not self.encryption
-            and self._serializer_string_name == "arrow"
-            and getattr(self._base_serializer, "return_format", None) == "pandas"
-        )
+        # The tag screen first: it keeps every other serializer's read free of the helper call.
+        if self.encryption or self._serializer_string_name not in _ARROW_FRAME_TAGS or not self._is_cachekit_arrow():
+            return False
+        # An Arrow or polars result keeps the mapping, and before Python 3.13 each mapping also keeps a
+        # file descriptor, so those return formats map only where the mapping holds none. A pandas
+        # result is meant to copy out; any pandas column that stays a view of the mapped Arrow
+        # buffers still keeps the mapping (and, before 3.13, its descriptor) until it is released.
+        return MMAP_RELEASES_FD or getattr(self._base_serializer, "return_format", None) == "pandas"
 
     def supports_streaming_write(self) -> bool:
         """True iff writes can stream the envelope to a capable backend (LAB-766).
 
-        Eligible only for PLAINTEXT Arrow:
+        Eligible only for PLAINTEXT cachekit Arrow (``serializer="arrow"`` or an
+        ``ArrowSerializer(...)`` instance):
         - encrypted values can never stream (AES-256-GCM emits its auth tag only after the
           whole ciphertext exists, so the secure path stays on buffered ``set(bytes)``);
         - interop/v1 stores raw documents with no CK envelope (different serializer, no benefit);
@@ -1193,7 +1241,12 @@ class CacheSerializationHandler:
         separately at the cache-handler layer, so True here on a non-streaming backend simply
         means the write falls back to the buffered path.
         """
-        return not self.encryption and not self.interop_mode and self._serializer_string_name == "arrow"
+        return (
+            not self.encryption
+            and not self.interop_mode
+            and self._serializer_string_name in _ARROW_FRAME_TAGS
+            and self._is_cachekit_arrow()
+        )
 
     def write_serialized_to(self, sink: BinaryIO, data: Any) -> None:
         """Streaming twin of :meth:`serialize_data` (LAB-766): write the SAME envelope bytes into
@@ -1223,7 +1276,7 @@ class CacheSerializationHandler:
             raise SerializationError(f"write_serialized_to requires the arrow serializer, got {type(serializer).__name__}")
 
         metadata = serializer.serialization_metadata()
-        prefix = SerializationWrapper.wrap_prefix(metadata.to_dict(), self._serializer_string_name)
+        prefix = self._frame_prefix(metadata.to_dict())
         sink.write(prefix)
         budget = get_settings().max_value_size - len(prefix)
         serializer.serialize_to_sink(data, sink, max_bytes=budget)
@@ -1490,9 +1543,10 @@ class CacheHit(NamedTuple):
     """A successful L2 read from :class:`CacheOperationHandler`.
 
     envelope is the serialized bytes so the decorator can backfill L1 without
-    re-serializing (re-encrypting) — None on the mmap fast path, where the
-    mapped view is confined to its frame and must never reach L1 (#171
-    blocker C). size_bytes is the envelope's byte length on every hit, mmap
+    re-serializing (re-encrypting) — None on the mmap fast path (sync reads
+    only), whose handle is confined to its frame and whose bytes never reach
+    L1 (#171 blocker C); the value itself may be an Arrow or polars result
+    over the mapping (see ``_MmapHandle``). size_bytes is the envelope's byte length on every hit, mmap
     included, so payload-size stats never depend on holding the bytes.
     A hit is distinguished from "no cache entry" by getting a CacheHit at
     all vs. None — there is no boolean slot (LAB-3757).
@@ -1734,10 +1788,12 @@ class CacheOperationHandler:
             if self._cache_handler is None:
                 raise RuntimeError("Cache handler must be set before calling get_cached_value")
 
-            # mmap fast path (#171): plaintext Arrow -> pandas on a buffer-readable backend (File,
+            # mmap fast path (#171): plaintext cachekit Arrow on a buffer-readable backend (File,
             # POSIX) reads zero-copy. The handle is confined to this frame and closed in `finally`,
-            # so the mmap never becomes the returned value and never reaches L1 (blocker C). A None
-            # from get_buffer (ineligible file, or a non-buffer backend) falls through to bytes.
+            # so the mmap never becomes the returned value and never reaches L1 (blocker C). An
+            # Arrow or polars result that aliases the mapping keeps it alive past that close (see
+            # _MmapHandle). A None from get_buffer (ineligible file, or a non-buffer backend)
+            # falls through to bytes.
             if self.serialization_handler.supports_mmap_read():
                 handle = self._cache_handler.get_buffer(cache_key)
                 if handle is not None:

{cachekit-0.23.0 → cachekit-0.24.0}/src/cachekit/config/decorator.py

@@ -132,7 +132,7 @@ class DecoratorConfig:
         ttl: Time-to-live in seconds (None = no expiration; every preset sets its own default — see each classmethod)
         namespace: Optional namespace prefix for cache keys
         serializer: Serializer instance or name. Accepts either:
-                   - String name: "default" (MessagePack), "arrow" (DataFrame zero-copy)
+                   - String name: "default" (MessagePack), "arrow" (DataFrames as Arrow IPC)
                    - SerializerProtocol instance: Custom serializer implementing the protocol
                    Default: "default" (MessagePack+LZ4+xxHash3-64 via Rust)
                    An EncryptionWrapper instance or the "encrypted" name raises ConfigurationError when
@@ -141,8 +141,17 @@ class DecoratorConfig:
                            All serializers use xxHash3-64 (8 bytes).
                            Set to False for @cache.minimal (speed-first, no integrity guarantee)
         key: Custom key function for complex types. Receives (*args, **kwargs) and returns str.
-             Use for numpy arrays, DataFrames, or cross-language cache sharing.
-             Example: @cache(key=lambda arr: hashlib.blake2b(arr.tobytes()).hexdigest())
+             Use for numpy arrays, DataFrames and other arguments the default key cannot hash.
+             The stored key is "{identity}-{namespace or 'default'}:{returned str}", where identity
+             is 16 hex of the blake3 hash of the function's module.qualname, so functions with
+             different module.qualnames never share an entry. Functions sharing one (closures from
+             one factory, lambdas, __main__ in two scripts) still do whenever "{namespace}:{returned str}"
+             is the same: give them distinct namespaces, none of them another plus ":".
+             Not for cross-SDK sharing: interop mode rejects key=.
+             Return a str that differs whenever the arguments differ and uses only [A-Za-z0-9_.:-]
+             (CachekitIO rejects other characters, Memcached whitespace), e.g. for a numeric numpy array:
+             @cache(key=lambda arr: hashlib.blake2b(f"{arr.dtype.str}{arr.shape}".encode() + arr.tobytes()).hexdigest())
+             (tobytes() alone ignores dtype and shape; an object array's bytes are pointers)
         refresh_ttl_on_get: Extend TTL on cache hit
         ttl_refresh_threshold: Minimum remaining TTL fraction (0.0-1.0) to trigger refresh
         backend: L2 backend (RedisBackend, HTTPBackend). None means L1-only (in-process, no network), as

{cachekit-0.23.0 → cachekit-0.24.0}/src/cachekit/config/settings.py

@@ -152,9 +152,8 @@ class CachekitConfig(RedactingSettings):
         description=(
             "Arrow IPC compression codec for DataFrame caching (ArrowSerializer, compression='auto'). "
             "'zstd'/'lz4' shrink the stored payload but must be decompressed into the heap on read. "
-            "'none' stores uncompressed Arrow IPC, which lets the File backend serve plaintext "
-            "DataFrame reads via a zero-copy mmap (low steady-state read RSS; peak transiently "
-            "higher) at the cost of a larger payload. Writes are codec-independent: plaintext "
+            "'none' stores uncompressed Arrow IPC, at the cost of a larger payload, and lets plaintext "
+            "File-backend hits stay zero-copy, depending on return_format and Python version (see ArrowSerializer). Writes are codec-independent: plaintext "
             "Arrow streams to the File backend without materializing the payload (encrypted "
             "values stay buffered). Env: CACHEKIT_ARROW_COMPRESSION."
         ),

{cachekit-0.23.0 → cachekit-0.24.0}/src/cachekit/decorators/wrapper.py

@@ -634,7 +634,7 @@ def create_cache_wrapper(
         ttl: Cache time-to-live in seconds (None = no expiration)
         namespace: Cache key namespace prefix
         serializer: Serializer instance or name. Accepts either:
-                   - String name: "default" (MessagePack), "arrow" (DataFrame zero-copy)
+                   - String name: "default" (MessagePack), "arrow" (DataFrames as Arrow IPC)
                    - SerializerProtocol instance: Custom serializer implementing the protocol
                    An EncryptionWrapper instance or the "encrypted" name raises ConfigurationError:
                    encrypt with encryption=True (@cache.secure) and pass the inner serializer here.
@@ -816,6 +816,8 @@ def create_cache_wrapper(
         _interop_sig = inspect.signature(func)
 
     # Key registry id: names this function's server-side tracking set on a KeyTrackableBackend.
+    # _registry_hash is also the identity every custom key= key starts with (_resolve_cache_key):
+    # changing it re-keys every key= entry, and the golden-vector test pins it.
     # 64-bit hash, not func_hash's 32: a registry collision makes one function's invalidation
     # drain another's keys. namespace=None and namespace="default" write different auto-mode
     # keys, so they get different sets (None -> empty segment). The "ck" namespace is reserved:
@@ -1501,7 +1503,13 @@ def create_cache_wrapper(
             custom_key = custom_key_func(*call_args, **call_kwargs)
             if not isinstance(custom_key, str):
                 raise TypeError(f"key function must return str, got {type(custom_key).__name__}")
-            return f"{namespace or 'default'}:{custom_key}"
+            # The function's 16-hex identity goes first, at a fixed width no namespace or key can shift, so
+            # two functions whose key functions return the same string never share an entry. First also keeps
+            # every key apart from the pre-fix "{namespace}:{key}" keys an earlier release writes, which start
+            # with a configured namespace: a crafted argument cannot plant one (unless a plain RedisBackend
+            # sharing the database uses namespace t or t:*, which can spell a tenant-scoped key). Generated
+            # keys start ns: or func:, so this key never equals one. CachekitIO files it in its default namespace.
+            return f"{_registry_hash}-{namespace or 'default'}:{custom_key}"
         # fast_mode: the only mode _generated_key_mode leaves once interop and key= are out.
         # Minimal key generation - no string formatting overhead (10-50μs savings)
         from ..hash_utils import cache_key_hash

{cachekit-0.23.0 → cachekit-0.24.0}/src/cachekit/reliability/metrics_collection.py

@@ -35,7 +35,7 @@ class MetricsCollector:
     Examples:
         Create and use a counter:
 
-        >>> counter = MetricsCollector("test_counter")
+        >>> counter = MetricsCollector("doctest_counter")
         >>> counter.inc()
         >>> counter.get()
         1.0
@@ -45,21 +45,21 @@ class MetricsCollector:
 
         Use with labels:
 
-        >>> counter = MetricsCollector("labeled_counter")
+        >>> counter = MetricsCollector("doctest_labeled_counter")
         >>> counter.inc({"operation": "get", "status": "success"})
         >>> counter.get({"operation": "get", "status": "success"})
         1.0
 
         Set gauge value:
 
-        >>> gauge = MetricsCollector("test_gauge")
+        >>> gauge = MetricsCollector("doctest_gauge")
         >>> gauge.set(42.0)
         >>> gauge.get()
         42.0
 
         Chain with labels() method:
 
-        >>> counter = MetricsCollector("chained")
+        >>> counter = MetricsCollector("doctest_chained")
         >>> counter.labels(operation="set").inc()
         >>> counter.get({"operation": "set"})
         1.0

{cachekit-0.23.0 → cachekit-0.24.0}/src/cachekit/serializers/arrow_serializer.py

@@ -1,6 +1,6 @@
 # pyright: reportOptionalMemberAccess=false
 # pyright: reportInvalidTypeForm=false
-"""Apache Arrow IPC serializer for zero-copy DataFrame caching.
+"""Apache Arrow IPC serializer for DataFrame caching.
 
 This module provides ArrowSerializer for high-performance DataFrame serialization
 using Apache Arrow's Inter-Process Communication (IPC) format.
@@ -133,6 +133,22 @@ class _HashingSink:
         return self._hasher.digest()
 
 
+def _views_of(table: pa.Table, source: pa.Buffer) -> bool:
+    """True iff every data buffer of ``table`` points into ``source``: an uncompressed IPC read.
+
+    A compressed read decompresses into new buffers. Checking every buffer, not the first, matters: a
+    codec may store a buffer that does not shrink raw, and the reader then slices that one from ``source``.
+    """
+    lo, hi = source.address, source.address + source.size
+    return all(
+        lo <= buf.address < hi
+        for column in table.columns
+        for chunk in column.chunks
+        for buf in chunk.buffers()
+        if buf is not None and buf.size
+    )
+
+
 class ArrowSerializer:
     """Apache Arrow IPC serializer for memory-efficient DataFrame caching with xxHash3-64 integrity.
 
@@ -155,6 +171,13 @@ class ArrowSerializer:
     - Deserialize: the envelope is sliced with a memoryview (no full-body copy), wrapped via
       pa.py_buffer (zero-copy), and Arrow->pandas conversion uses self_destruct + split_blocks
       to free Arrow buffers during conversion. zstd is decompressed transparently by the reader.
+    - Plaintext File-backend hits (POSIX) read over a memory map of the cache file ("arrow" and
+      "polars" on Python 3.13+ only, where a held mapping costs no file descriptor). A compressed
+      payload is decompressed out of the map; an uncompressed one stays zero-copy per return_format:
+      "arrow" returns a table whose buffers all alias the mapping (no heap copy); "polars" keeps
+      numeric, bool and temporal columns zero-copy and copies strings into polars' layout; "pandas"
+      copies once into a writable DataFrame. A zero-copy result keeps the mapping alive until it
+      is garbage-collected.
 
     Use cases:
     - Data science pipelines (pandas/polars DataFrames)
@@ -200,9 +223,11 @@ class ArrowSerializer:
 
         Args:
             return_format: Output format for deserialized data ("pandas", "polars", "arrow")
-                - "pandas": Convert to pandas.DataFrame (default)
+                - "pandas": Convert to pandas.DataFrame (default). Every column accepts in-place
+                  edits, as on an uncached result: none is a read-only view of the cached bytes.
                 - "polars": Convert to polars.DataFrame
-                - "arrow": Return pyarrow.Table (zero-copy, no conversion)
+                - "arrow": Return pyarrow.Table (no conversion; zero-copy on an uncompressed
+                  File-backend hit on Python 3.13+)
             enable_integrity_checking: Retained for API compatibility. The 8-byte xxHash3-64
                 checksum is now ALWAYS written and validated (silently returning corrupted
                 DataFrames is unacceptable, and 8 bytes is negligible), so this flag no longer
@@ -210,10 +235,10 @@ class ArrowSerializer:
             compression: Arrow IPC compression codec.
                 - "auto" (default): use the CACHEKIT_ARROW_COMPRESSION setting (itself "zstd" by default)
                 - "zstd" / "lz4": compress the payload (smaller wire/L1; must be decompressed on read)
-                - None or "none": store uncompressed Arrow IPC. Lets the File backend serve plaintext
-                  DataFrame reads (returned as pandas) via a zero-copy mmap — low steady-state read
-                  RSS (~0.32x), though peak is transiently higher from checksum verification + pandas
-                  materialization — at the cost of a larger stored payload. No effect on wire backends.
+                - None or "none": store uncompressed Arrow IPC, at the cost of a larger stored payload.
+                  Lets plaintext File-backend hits stay zero-copy (see the memory profile above);
+                  the checksum check still reads every page once. On wire backends it only skips
+                  the codec.
 
         Raises:
             ValueError: If return_format or compression is not a valid option
@@ -324,8 +349,7 @@ class ArrowSerializer:
             # batch makes the codec allocate a full-size working buffer — measured ~3.6x the
             # payload). Batches are sized by actual bytes (<= 8 MiB), not a uniform row-count
             # estimate, so the bound holds for skewed/wide frames too (#161). compression=None
-            # writes uncompressed IPC, which the File backend reads zero-copy via mmap (#171,
-            # plaintext, pandas return only).
+            # writes uncompressed IPC.
             sink = pa.BufferOutputStream()
             write_options = pa.ipc.IpcWriteOptions(compression=self.compression) if self.compression else None
             with pa.ipc.new_file(sink, table.schema, options=write_options) as writer:
@@ -452,11 +476,20 @@ class ArrowSerializer:
         """
         try:
             # pa.py_buffer over the memoryview is zero-copy; open_file decompresses transparently.
-            reader = pa.ipc.open_file(pa.py_buffer(body))
+            source = pa.py_buffer(body)
+            reader = pa.ipc.open_file(source)
             table = reader.read_all()
 
             # Convert to requested format
             if self.return_format == "pandas":
+                if reader.num_record_batches == 1:
+                    # pyarrow converts a single-chunk column (and categorical codes) zero-copy, as a
+                    # READ-ONLY numpy view of the IPC buffers, which alias the backend's bytes or the
+                    # File backend's mmap. A second, empty chunk makes it concatenate into fresh
+                    # arrays instead, as it already does for a multi-batch frame, so the caller gets
+                    # a frame it can edit in place and that owns its memory, like an uncached call's
+                    # (cachekit-py#157). One batch is at most _TARGET_BATCH_BYTES, so the copy is small.
+                    table = pa.concat_tables([table.slice(0, 0), table])
                 # self_destruct frees each Arrow column as it is converted (the table is a
                 # throwaway local here, so the experimental-invalidation caveat does not apply);
                 # split_blocks avoids the transient 2x of consolidated-block construction.
@@ -466,11 +499,16 @@ class ArrowSerializer:
                 try:
                     import polars as pl  # type: ignore[import-not-found]
 
-                    return pl.from_arrow(table)
+                    # Uncompressed IPC: the table's buffers are views of ``body`` (the mapped cache
+                    # file on a File-backend hit). rechunk=False keeps them, one chunk per record
+                    # batch, so aligned numeric, bool and temporal columns import zero-copy; the
+                    # default concatenates, which copies every column. A decompressed table is
+                    # already a heap copy, so it keeps the contiguous default.
+                    return pl.from_arrow(table, rechunk=not _views_of(table, source))
                 except ImportError as import_err:
                     raise SerializationError("polars not installed. Install with: pip install polars") from import_err
             else:  # return_format == "arrow"
-                return table  # zero-copy, no conversion
+                return table  # no conversion; aliases ``body`` when the IPC is uncompressed
 
         except (pa.ArrowInvalid, pa.ArrowSerializationError, OSError) as e:
             raise SerializationError(f"Failed to deserialize Arrow IPC data: {e}") from e

{cachekit-0.23.0 → cachekit-0.24.0}/src/cachekit/serializers/wrapper.py

@@ -7,7 +7,8 @@ Backend-agnostic: works with Redis, CachekitIO, Memcached, File, L1.
 Wire format (v3 binary frame)
 -----------------------------
     MAGIC b"CK" | VERSION u8 | HDR_LEN u32-BE | HEADER(json utf-8) | PAYLOAD(raw bytes)
-    HEADER = {"s": serializer_name, "m": metadata, "v": envelope_version}
+    HEADER = {"s": serializer_name, "m": metadata, "v": envelope_version}, optionally followed by
+             ASCII spaces (counted in HDR_LEN) that align the payload; see ``wrap_prefix``
 
 The payload (serializer output: MessagePack/Arrow IPC/ciphertext) is stored
 **raw** — no base64, no JSON-embedding. This matters because the previous
@@ -169,12 +170,28 @@ class SerializationWrapper:
     """
 
     @staticmethod
-    def wrap_prefix(metadata: dict[str, Any], serializer_name: str, version: str = "2.0") -> bytes:
+    def wrap_prefix(
+        metadata: dict[str, Any], serializer_name: str, version: str = "2.0", *, align: int = 1, offset: int = 0
+    ) -> bytes:
         """Build the v3 frame prefix (everything before the payload): MAGIC | VERSION | HDR_LEN | HEADER.
 
         The prefix depends only on the metadata/serializer name, never on the payload bytes, so
         the streaming write path (LAB-766) can emit it before a single payload byte exists and
         the stored frame stays byte-identical to a buffered ``wrap`` of the same payload.
+
+        ``align`` pads HEADER with trailing ASCII spaces, counted in HDR_LEN, until
+        ``offset + len(prefix)`` is a multiple of ``align``; ``offset`` counts the bytes outside the
+        prefix that precede the position to align. JSON allows trailing whitespace, so every reader
+        parses a padded header unchanged. The default (``align=1``) never pads. Raises ``ValueError``
+        for an ``align`` below 1, or for a negative ``offset`` when ``align`` is above 1; with
+        ``align=1`` nothing is padded, so ``offset`` is ignored.
+
+        >>> padded = SerializationWrapper.wrap_prefix({}, "arrow", align=64, offset=22)
+        >>> (22 + len(padded)) % 64
+        0
+        >>> payload, _, name = SerializationWrapper.unwrap(padded + b"payload")
+        >>> bytes(payload), name
+        (b'payload', 'arrow')
         """
         items = tuple(metadata.items())
         if (
@@ -182,8 +199,18 @@ class SerializationWrapper:
             and type(version) is str
             and all(type(k) is str and type(v) in _MEMO_VALUE_TYPES for k, v in items)
         ):
-            return _encode_prefix_memo(serializer_name, items, version)
-        return _encode_prefix(serializer_name, metadata, version)
+            prefix = _encode_prefix_memo(serializer_name, items, version)
+        else:
+            prefix = _encode_prefix(serializer_name, metadata, version)
+        if align == 1:
+            return prefix
+        if align < 1 or offset < 0:
+            raise ValueError(f"wrap_prefix needs align >= 1 and offset >= 0, got align={align}, offset={offset}")
+        pad = -(offset + len(prefix)) % align
+        if not pad:
+            return prefix
+        header = prefix[_PREFIX_LEN:] + b" " * pad
+        return b"".join((prefix[: _PREFIX_LEN - _HEADER_LEN_BYTES], len(header).to_bytes(_HEADER_LEN_BYTES, "big"), header))
 
     @staticmethod
     def wrap(data: bytes, metadata: dict[str, Any], serializer_name: str, version: str = "2.0") -> bytes: