kvgit 0.2.1__tar.gz → 0.3.0__tar.gz

{kvgit-0.2.1 → kvgit-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kvgit
-Version: 0.2.1
+Version: 0.3.0
 Summary: Versioned key-value store with git-like commit, branch, and merge semantics.
 Author: ashenfad
 License: MIT
@@ -29,14 +29,26 @@ Provides-Extra: disk
 Requires-Dist: diskcache; extra == "disk"
 Provides-Extra: git
 Requires-Dist: gitpython>=3.1; extra == "git"
+Provides-Extra: numpy
+Requires-Dist: numpy>=1.24; extra == "numpy"
+Provides-Extra: pandas
+Requires-Dist: numpy>=1.24; extra == "pandas"
+Requires-Dist: pandas>=2.0; extra == "pandas"
+Provides-Extra: scientific
+Requires-Dist: numpy>=1.24; extra == "scientific"
+Requires-Dist: pandas>=2.0; extra == "scientific"
 Provides-Extra: all
 Requires-Dist: diskcache; extra == "all"
 Requires-Dist: gitpython>=3.1; extra == "all"
+Requires-Dist: numpy>=1.24; extra == "all"
+Requires-Dist: pandas>=2.0; extra == "all"
 Provides-Extra: dev
 Requires-Dist: pytest; extra == "dev"
 Requires-Dist: diskcache; extra == "dev"
 Requires-Dist: gitpython>=3.1; extra == "dev"
 Requires-Dist: ruff; extra == "dev"
+Requires-Dist: numpy>=1.24; extra == "dev"
+Requires-Dist: pandas>=2.0; extra == "dev"
 Dynamic: license-file
 
 # kvgit 🔀
@@ -49,15 +61,16 @@ Git-style versioning for your data. Commits, branches, and merges -- backed by a
 | **Commits** | Immutable, content-addressable snapshots with rollback |
 | **Branches** | Cheap forks with CAS-based optimistic concurrency |
 | **Three-way merge** | Auto-merges non-overlapping changes; pluggable merge fns for conflicts |
-| **Eviction** | High/low water rebase drops least-recently-used keys automatically |
 | **Pluggable backends** | In-memory, disk (diskcache), git (GitPython), IndexedDB (Pyodide/browser), or bring your own `KVStore` |
+| **Chunked codecs** | Optional content-addressed dedup for large numpy arrays and pandas DataFrames -- equal buffers stored once across keys, commits, and branches |
 
 ## Install
 
 ```bash
-pip install kvgit            # in-memory only
-pip install kvgit[disk]      # adds disk backend via diskcache
-pip install kvgit[git]       # adds git backend via GitPython (requires git on PATH)
+pip install kvgit              # in-memory only
+pip install kvgit[disk]        # adds disk backend via diskcache
+pip install kvgit[git]         # adds git backend via GitPython (requires git on PATH)
+pip install kvgit[scientific]  # adds chunked codecs for numpy / pandas
 # IndexedDB backend is available automatically in Pyodide (browser) environments
 ```
 
@@ -81,6 +94,26 @@ print(main["score"])  # 0   (main unchanged)
 print(dev["score"])   # 999 (dev branch)
 ```
 
+## Chunked codecs (numpy / pandas)
+
+Large numpy arrays and pandas DataFrames -- and any sliced views of them -- can be stored once and shared across keys, commits, and branches:
+
+```python
+import kvgit
+import numpy as np
+
+s = kvgit.store(codecs="scientific")
+
+big = np.arange(1_000_000, dtype="float64")  # ~8 MB
+s["full"] = big
+s["head"] = big[:100_000]
+s["tail"] = big[-100_000:]
+s.commit()
+# All three keys reference the same chunk on disk -- ~8 MB total, not ~24 MB.
+```
+
+Pandas DataFrames piggyback on the numpy codec via their underlying block ndarrays. See [`docs/quick-start.md`](docs/quick-start.md#storing-scientific-data-efficiently-chunked-codecs) and the [API reference](docs/api.md#chunked-codecs).
+
 ## Part of the agex stack
 
 kvgit provides versioned agent memory in [agex](https://github.com/ashenfad/agex) with branching and rollback. It also works as a versioned backing store for [monkeyfs](https://github.com/ashenfad/monkeyfs) virtual filesystems -- pass a `Staged` instance anywhere a dict is expected.

{kvgit-0.2.1 → kvgit-0.3.0}/README.md

@@ -8,15 +8,16 @@ Git-style versioning for your data. Commits, branches, and merges -- backed by a
 | **Commits** | Immutable, content-addressable snapshots with rollback |
 | **Branches** | Cheap forks with CAS-based optimistic concurrency |
 | **Three-way merge** | Auto-merges non-overlapping changes; pluggable merge fns for conflicts |
-| **Eviction** | High/low water rebase drops least-recently-used keys automatically |
 | **Pluggable backends** | In-memory, disk (diskcache), git (GitPython), IndexedDB (Pyodide/browser), or bring your own `KVStore` |
+| **Chunked codecs** | Optional content-addressed dedup for large numpy arrays and pandas DataFrames -- equal buffers stored once across keys, commits, and branches |
 
 ## Install
 
 ```bash
-pip install kvgit            # in-memory only
-pip install kvgit[disk]      # adds disk backend via diskcache
-pip install kvgit[git]       # adds git backend via GitPython (requires git on PATH)
+pip install kvgit              # in-memory only
+pip install kvgit[disk]        # adds disk backend via diskcache
+pip install kvgit[git]         # adds git backend via GitPython (requires git on PATH)
+pip install kvgit[scientific]  # adds chunked codecs for numpy / pandas
 # IndexedDB backend is available automatically in Pyodide (browser) environments
 ```
 
@@ -40,6 +41,26 @@ print(main["score"])  # 0   (main unchanged)
 print(dev["score"])   # 999 (dev branch)
 ```
 
+## Chunked codecs (numpy / pandas)
+
+Large numpy arrays and pandas DataFrames -- and any sliced views of them -- can be stored once and shared across keys, commits, and branches:
+
+```python
+import kvgit
+import numpy as np
+
+s = kvgit.store(codecs="scientific")
+
+big = np.arange(1_000_000, dtype="float64")  # ~8 MB
+s["full"] = big
+s["head"] = big[:100_000]
+s["tail"] = big[-100_000:]
+s.commit()
+# All three keys reference the same chunk on disk -- ~8 MB total, not ~24 MB.
+```
+
+Pandas DataFrames piggyback on the numpy codec via their underlying block ndarrays. See [`docs/quick-start.md`](docs/quick-start.md#storing-scientific-data-efficiently-chunked-codecs) and the [API reference](docs/api.md#chunked-codecs).
+
 ## Part of the agex stack
 
 kvgit provides versioned agent memory in [agex](https://github.com/ashenfad/agex) with branching and rollback. It also works as a versioned backing store for [monkeyfs](https://github.com/ashenfad/monkeyfs) virtual filesystems -- pass a `Staged` instance anywhere a dict is expected.

kvgit-0.3.0/kvgit/codecs/__init__.py

@@ -0,0 +1,107 @@
+"""Chunked codecs for kvgit.
+
+A chunked codec externalizes large sub-values (numpy buffers, Arrow
+tables, ...) as content-addressed chunks stored in a separate
+namespace, so equal data is stored once across keys, commits, and
+branches.
+
+Quick start::
+
+    from kvgit import store
+    from kvgit.codecs import compose
+    from kvgit.codecs.numpy import NumpyCodec
+
+    encoder, decoder = compose(NumpyCodec())
+    s = store(encoder=encoder, decoder=decoder)
+
+The encoder/decoder pair is plug-compatible with ``Staged``'s
+existing slots: it accepts a ``ChunkSink`` / ``ChunkReader`` second
+argument, and ``Staged`` detects the extended arity automatically.
+"""
+
+from __future__ import annotations
+
+from .base import ChunkReader, ChunkSink, Codec
+from .pickler import (
+    ChunkingPickler,
+    ChunkingUnpickler,
+    decode as _decode,
+    encode as _encode,
+)
+
+
+def compose(*codecs: Codec):
+    """Build an ``(encoder, decoder)`` pair from a list of codecs.
+
+    The codecs are tried in order during encoding; the first to
+    return a non-None token from ``try_externalize`` wins. Plain
+    pickling handles anything no codec claims — there is no need to
+    register a "pickle codec" explicitly.
+
+    Order matters when codecs claim overlapping types. Put the more
+    specific codec first.
+    """
+    codec_list = list(codecs)
+
+    def encoder(value, sink):
+        return _encode(value, sink, codec_list)
+
+    def decoder(blob, reader):
+        return _decode(blob, reader, codec_list)
+
+    return encoder, decoder
+
+
+def scientific():
+    """Return an ``(encoder, decoder)`` pair using scientific codecs.
+
+    Currently composes the numpy codec, which transparently handles
+    pandas ``DataFrame`` / ``Series`` block buffers via pandas' pickle
+    path. Future scientific codecs (Arrow, etc.) will slot in here
+    when both the codec and its dependency are available.
+
+    Raises:
+        ImportError: if numpy is not importable in this environment.
+            Install with ``pip install kvgit[scientific]``.
+    """
+    try:
+        from .numpy import NumpyCodec
+    except ImportError as e:
+        raise ImportError(
+            "kvgit.codecs.scientific() requires numpy. "
+            "Install with `pip install kvgit[scientific]`."
+        ) from e
+    return compose(NumpyCodec())
+
+
+# Registry of named codec presets used by ``kvgit.store(codecs=...)``.
+# Keep this sparse: each preset is a deliberate, well-documented bundle.
+_NAMED_PRESETS = {
+    "scientific": scientific,
+}
+
+
+def _resolve_named(name: str):
+    """Resolve a named codec preset to an ``(encoder, decoder)`` pair.
+
+    Internal helper used by ``kvgit.store(codecs=...)``. Raises
+    ``ValueError`` for unknown names with a list of valid options.
+    """
+    factory = _NAMED_PRESETS.get(name)
+    if factory is None:
+        raise ValueError(
+            f"unknown codec preset {name!r}. "
+            f"Available presets: {sorted(_NAMED_PRESETS)}"
+        )
+    return factory()
+
+
+__all__ = [
+    "ChunkReader",
+    "ChunkSink",
+    "ChunkingPickler",
+    "ChunkingUnpickler",
+    "Codec",
+    "compose",
+    "scientific",
+]

kvgit-0.3.0/kvgit/codecs/_hash.py

@@ -0,0 +1,29 @@
+"""Canonical buffer hashing for chunk references.
+
+Centralizes the hash function so all codecs and chunk-sink
+implementations agree on how a chunk is identified. The hash must
+be stable across processes, Python versions, and platforms — only
+the raw bytes are hashed; never object identity or implementation
+metadata.
+"""
+
+from __future__ import annotations
+
+import hashlib
+
+# 40 hex chars (160 bits) — same length as kvgit's commit hashes,
+# enough collision resistance for billions of chunks.
+HASH_LEN = 40
+
+
+def hash_bytes(data: bytes | memoryview) -> str:
+    """Hash arbitrary bytes-like data to a hex digest."""
+    h = hashlib.sha256()
+    if isinstance(data, memoryview):
+        # Cast to byte-level memoryview for a stable read regardless of
+        # original element format. ``hashlib.update`` accepts memoryview
+        # without copying.
+        h.update(data.cast("B"))
+    else:
+        h.update(data)
+    return h.hexdigest()[:HASH_LEN]

kvgit-0.3.0/kvgit/codecs/base.py

@@ -0,0 +1,79 @@
+"""Codec protocols for chunked encoding.
+
+A *codec* recognizes a specific value type during encoding, externalizes
+its bulk data as content-addressed chunks, and emits a small
+picklable token in place of the value. On decode it reads the token,
+fetches the chunks it references, and rebuilds the value.
+
+Codecs are composed via :func:`kvgit.codecs.compose`, which wraps them
+in a ``ChunkingPickler`` / ``ChunkingUnpickler`` pair. Pickle handles
+container traversal and primitive types; the codec only sees leaf
+objects it cares about.
+
+The kvgit core sees codecs as opaque ``(encoder, decoder)`` callables
+on ``Staged``. Users opt in by passing them at construction.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class ChunkSink(Protocol):
+    """Encoder-side: emit a chunk, get back a content-addressed reference.
+
+    Implementations hash the data once and cache the hash. Re-emitting
+    the same bytes within an encode session must short-circuit to the
+    same reference without rehashing — this matters for codecs that
+    can cheaply produce the same bytes from the same Python object
+    (e.g., the same ndarray reaching ``put`` twice via different
+    container paths).
+    """
+
+    def put(self, data: bytes | memoryview) -> str:
+        """Register a chunk and return its content-addressed reference."""
+        ...
+
+
+@runtime_checkable
+class ChunkReader(Protocol):
+    """Decoder-side: fetch chunks by reference."""
+
+    def get(self, ref: str) -> bytes:
+        """Fetch a single chunk. Raises ``KeyError`` if missing."""
+        ...
+
+    def get_many(self, refs: list[str]) -> dict[str, bytes]:
+        """Bulk-fetch. Returns only refs that exist; missing refs absent."""
+        ...
+
+    def prefetch(self, refs: list[str]) -> None:
+        """Hint that these refs will be needed soon. May be a no-op."""
+        ...
+
+
+@runtime_checkable
+class Codec(Protocol):
+    """A type-specific chunking codec.
+
+    Attributes:
+        name: Short tag stored in tokens (e.g. ``"np"``, ``"pa"``).
+            Must be unique within a composed codec set.
+    """
+
+    name: str
+
+    def try_externalize(self, obj: Any, sink: ChunkSink) -> Any | None:
+        """Recognize ``obj`` and emit chunks; return a picklable token.
+
+        Returns ``None`` to pass — the next codec in the chain (or
+        plain pickling) will handle the object. The returned token
+        becomes the second element of pickle's ``persistent_id``
+        (the first element is :attr:`name`).
+        """
+        ...
+
+    def materialize(self, token: Any, reader: ChunkReader) -> Any:
+        """Reconstruct the value from a token by fetching its chunks."""
+        ...

kvgit-0.3.0/kvgit/codecs/numpy.py

@@ -0,0 +1,237 @@
+"""NumPy ndarray codec.
+
+Externalizes the underlying buffer of an ndarray as a content-addressed
+chunk; the token records the dtype, shape, layout order, and (for
+views) the slice geometry needed to reconstruct the array against the
+chunked root buffer.
+
+Dedup story:
+
+* Two arrays with identical bytes hash to the same chunk reference.
+* A view (``arr.base is not None``) hashes its **root** buffer, not
+  the slice. Multiple slices of the same parent therefore share one
+  chunk on disk.
+* Both C-contiguous and F-contiguous roots are stored verbatim
+  (zero-copy via ``memoryview``) and the layout order is recorded
+  so the strides recovered for any view remain valid against the
+  exact bytes we wrote.
+* Roots with non-canonical layouts (neither C- nor F-contig — rare,
+  usually only created via ``as_strided`` abuse) are not safe to
+  reuse as a shared buffer; the codec falls back to a C-contiguous
+  copy of the input array, treating it as its own root. Dedup
+  against the original parent is lost in that case.
+* Object-dtype arrays hold Python pointers, not data — they fall
+  through to plain pickling (the elements may themselves be
+  externalized by other codecs).
+
+Materialized arrays are independent, writable copies — same mutation
+semantics as plain ``pickle.loads``. The dedup happens at the storage
+layer; reads always allocate a fresh array. (Reads pay one memcpy per
+key, equivalent to pickle's allocate-and-copy. The savings come from
+storing each unique buffer once instead of N times.)
+"""
+
+from __future__ import annotations
+
+from typing import Any, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    import numpy as np
+
+from .base import ChunkReader, ChunkSink
+
+# Below this size, the chunk indirection costs more than the savings.
+# Tunable via constructor; this default is conservative for IndexedDB
+# where each entry has hundreds of bytes of fixed overhead.
+DEFAULT_MIN_BYTES = 1024
+
+
+def _dtype_to_descr(dt) -> Any:
+    """Serialize a dtype to a JSON-safe descriptor.
+
+    ``dtype.str`` would lose metadata: a datetime64[ns] collapses to
+    ``'<M8'`` (no unit), a structured dtype collapses to ``'|V20'``
+    (no fields). ``np.lib.format.dtype_to_descr`` is the ``.npy``
+    format's serializer and preserves both — round-trips through
+    ``descr_to_dtype`` for every dtype numpy can ``.npy``-save.
+    """
+    from numpy.lib import format as npf
+
+    return npf.dtype_to_descr(dt)
+
+
+def _descr_to_dtype(descr):
+    from numpy.lib import format as npf
+
+    return npf.descr_to_dtype(descr)
+
+
+def _root_and_offset(arr: "np.ndarray") -> tuple["np.ndarray", int]:
+    """Walk ``.base`` to the root buffer; return (root, byte_offset).
+
+    Returns ``(arr, 0)`` if the .base chain leads somewhere we can't
+    safely interpret as a parent buffer (foreign owner, mismatched
+    address arithmetic).
+    """
+    import numpy as np
+
+    root = arr
+    while isinstance(root.base, np.ndarray):
+        root = root.base
+
+    # If the root is identical to the input, no view computation needed.
+    if root is arr:
+        return arr, 0
+
+    try:
+        arr_addr = arr.__array_interface__["data"][0]
+        root_addr = root.__array_interface__["data"][0]
+    except (KeyError, AttributeError, TypeError):
+        return arr, 0
+
+    offset = arr_addr - root_addr
+    if offset < 0 or offset + arr.nbytes > root.nbytes:
+        # The view's memory extends outside the root we walked to —
+        # likely a strided view with negative strides or some unusual
+        # layout. Treat the array as its own root for safety.
+        return arr, 0
+    return root, offset
+
+
+class NumpyCodec:
+    """Codec for :class:`numpy.ndarray` instances."""
+
+    name = "np"
+
+    def __init__(self, min_bytes: int = DEFAULT_MIN_BYTES) -> None:
+        self.min_bytes = min_bytes
+
+    def try_externalize(self, obj: Any, sink: ChunkSink) -> Any | None:
+        try:
+            import numpy as np
+        except ImportError:
+            return None
+        if not isinstance(obj, np.ndarray):
+            return None
+        # Object/struct-with-object dtypes contain Python pointers,
+        # not data — let pickle handle element-wise so other codecs
+        # can fire on the elements.
+        if obj.dtype.hasobject:
+            return None
+
+        is_view = isinstance(obj.base, np.ndarray)
+        # Small standalone arrays: chunk overhead exceeds savings.
+        if not is_view and obj.nbytes < self.min_bytes:
+            return None
+
+        root, byte_offset = _root_and_offset(obj)
+
+        # Pick a layout we can faithfully round-trip. C-contig and
+        # F-contig roots are both contiguous blocks of bytes — we
+        # store them verbatim and tag the order so materialize can
+        # reshape correctly. A non-contiguous root would force us to
+        # canonicalize the bytes (via ``tobytes()``) but the recorded
+        # strides would no longer describe that byte layout, leading
+        # to data corruption on reconstruction. Fall back to a
+        # C-contig copy of ``obj`` instead, treating it as its own
+        # root (loses dedup against the original parent for this
+        # branch, but keeps correctness).
+        if root.flags["C_CONTIGUOUS"]:
+            # ``.view(uint8)`` first: not all dtypes are buffer-protocol
+            # compatible (datetime64, timedelta64, structured void
+            # types all reject ``memoryview(arr)``), but every numpy
+            # array can be reinterpreted as raw bytes via a uint8 view,
+            # which then *is* buffer-compatible. The resulting view
+            # shares memory with ``root``, so this is zero-copy.
+            ref = sink.put(memoryview(root.view(np.uint8)))
+            order = "C"
+        elif root.flags["F_CONTIGUOUS"]:
+            # ``memoryview.cast`` only accepts C-contig sources, so
+            # collapse to a 1-D view in memory order. ``ravel(order='K')``
+            # is zero-copy when strides are positive (always true for
+            # F-contig arrays produced via numpy's normal APIs); the
+            # uint8 view is then buffer-compatible regardless of dtype.
+            ref = sink.put(memoryview(np.ravel(root, order="K").view(np.uint8)))
+            order = "F"
+        else:
+            canonical = np.ascontiguousarray(obj)
+            ref = sink.put(memoryview(canonical.view(np.uint8)))
+            return {
+                "ref": ref,
+                "root_shape": list(canonical.shape),
+                "root_dtype": _dtype_to_descr(canonical.dtype),
+                "shape": list(obj.shape),
+                "dtype": _dtype_to_descr(obj.dtype),
+                "strides": list(canonical.strides),
+                "offset": 0,
+                "order": "C",
+            }
+
+        return {
+            "ref": ref,
+            "root_shape": list(root.shape),
+            "root_dtype": _dtype_to_descr(root.dtype),
+            "shape": list(obj.shape),
+            "dtype": _dtype_to_descr(obj.dtype),
+            "strides": list(obj.strides),
+            "offset": int(byte_offset),
+            "order": order,
+        }
+
+    def materialize(self, token: Any, reader: ChunkReader) -> Any:
+        import numpy as np
+
+        raw = reader.get(token["ref"])
+        root_dtype = _descr_to_dtype(token["root_dtype"])
+        # ``order`` defaults to 'C' for tokens written before the field
+        # existed (those tokens are only correct for C-contig roots,
+        # which is the only path the older code took without bugs).
+        order = token.get("order", "C")
+
+        offset = token["offset"]
+        out_dtype = _descr_to_dtype(token["dtype"])
+        out_shape = tuple(token["shape"])
+        out_strides = tuple(token["strides"])
+        root_shape = tuple(token["root_shape"])
+
+        # Build a read-only view of the requested data first (zero-copy
+        # against the chunk bytes), then ``np.array(view)`` allocates a
+        # fresh, writable, independent copy. This matches plain
+        # ``pickle.loads`` semantics: the array the caller gets back is
+        # safe to mutate and won't surprise neighbouring keys that share
+        # the same chunk on the underlying store. The dedup story still
+        # holds — chunks are stored once on disk, decoded into private
+        # copies on demand.
+
+        # Fast path: the array IS the root (identical shape/dtype, no
+        # offset). Reshape the bytes in the recorded memory order.
+        if offset == 0 and out_shape == root_shape and out_dtype == root_dtype:
+            view = np.frombuffer(raw, dtype=root_dtype).reshape(root_shape, order=order)
+            # ``order='K'`` is np.array's default but we spell it out
+            # so an F-contig source comes back as F-contig.
+            return np.array(view, order="K")
+
+        # General path: reconstruct the view via stride tricks against
+        # the raw bytes. Critically, we go through a 1-D uint8 view
+        # of ``raw`` rather than a multi-dim view of the reshaped
+        # root. ``ndarray.view(uint8)`` on a multi-dim array preserves
+        # the leading dimensions, so ``[offset:]`` would silently
+        # slice the wrong axis when the root has rank > 1 — producing
+        # data corruption for any non-trivial offset (e.g., a
+        # row-slice tail of a multi-column DataFrame block).
+        flat_bytes = np.frombuffer(raw, dtype=np.uint8)
+        if offset:
+            flat_bytes = flat_bytes[offset:]
+        typed = flat_bytes.view(out_dtype)
+        view = np.lib.stride_tricks.as_strided(
+            typed,
+            shape=out_shape,
+            strides=out_strides,
+            writeable=False,
+        )
+        # ``np.array`` honours the view's strides while allocating
+        # contiguous, writable storage — exactly the shape/contents
+        # the caller would get from a fresh pickle.loads. ``order='K'``
+        # picks F-contig vs C-contig based on the input view's stride
+        # pattern, so an F-strided slice round-trips as F-contig.
+        return np.array(view, order="K")

kvgit-0.3.0/kvgit/codecs/pandas.py

@@ -0,0 +1,28 @@
+"""Pandas codec — currently a thin alias for the numpy codec.
+
+When pandas pickles a ``DataFrame`` or ``Series``, its
+``BlockManager.__reduce__`` exposes the per-block ndarrays as Python
+objects. Pickle visits those ndarrays before reducing them, which is
+exactly when our ``persistent_id`` hook fires — the numpy codec then
+catches the block buffers and chunks them.
+
+Net effect: ``compose(NumpyCodec(), ...)`` already deduplicates the
+underlying buffers of DataFrames and Series with no extra code. We
+re-export under a pandas-flavored name for clarity in user code.
+
+Caveats (no-op cases that fall back to opaque pickle, no chunking):
+
+* Extension dtypes whose pickle path doesn't expose an ndarray:
+  ``ArrowDtype``, ``CategoricalDtype.codes`` is ndarray-backed
+  (so it chunks), but ``categories`` may not always; ``MaskedArray``
+  surfaces ``.data`` and ``.mask`` ndarrays cleanly.
+* DataFrames with non-default attrs / index types may grow the
+  pickle size slightly because the non-block parts still pickle in
+  full. The block buffers — usually 99% of the bytes — still chunk.
+"""
+
+from __future__ import annotations
+
+from .numpy import NumpyCodec as PandasCodec
+
+__all__ = ["PandasCodec"]