small-cache 0.1.3__cp315-cp315-win_amd64.whl

small_cache/__init__.py

@@ -0,0 +1,14 @@
+"""""" # start delvewheel patch
+def _delvewheel_patch_1_13_1():
+    import os
+    if os.path.isdir(libs_dir := os.path.abspath(os.path.join(os.path.dirname(__file__), os.pardir, 'small_cache.libs'))):
+        os.add_dll_directory(libs_dir)
+
+
+_delvewheel_patch_1_13_1()
+del _delvewheel_patch_1_13_1
+# end delvewheel patch
+
+from ._small_cache_impl import SmallCache
+
+__all__ = ["SmallCache"]

small_cache/_small_cache_impl.pyi

@@ -0,0 +1,36 @@
+from collections.abc import Sequence
+
+
+class SmallCache:
+    def __init__(self, attribute_names: Sequence[str]) -> None:
+        """A cache of items with up to 96 attributes, named in this order."""
+
+    def begin_transaction(self, estimated_number_of_items: int = 0, remove_old_items: bool = True) -> None:
+        """
+        Start a load. Readers keep seeing the current data until end_transaction(). With remove_old_items, items not added during the load are dropped.
+        """
+
+    def end_transaction(self) -> None:
+        """Publish the load to readers."""
+
+    def abort_transaction(self) -> None:
+        """Discard the load; readers keep the current data."""
+
+    def add(self, item_id: str, attributes: dict[str, None | bool | int | float | str | bytes | list[str | bytes] | tuple[str | bytes, ...]]) -> None:
+        """
+        Add or replace an item in the open load. bytes are JSON text, embedded in answers as is; attributes not in the cache's names are ignored.
+        """
+
+    def get_one(self, id: str, attributes: Sequence[str]) -> bytes:
+        """
+        JSON array of the item's values in the order of `attributes` (null if unset); [] if there is no such item.
+        """
+
+    def get_many(self, ids: Sequence[str], attributes: Sequence[str]) -> bytes:
+        """JSON array with a get_one() row for each id."""
+
+    def get_all(self, attributes: Sequence[str]) -> bytes:
+        """JSON array with a get_one() row for each item, in get_all_ids() order."""
+
+    def get_all_ids(self) -> bytes:
+        """JSON array of all item ids."""

small_cache-0.1.3.dist-info/DELVEWHEEL

@@ -0,0 +1,2 @@
+Version: 1.13.1
+Arguments: ['C:\\Users\\runneradmin\\AppData\\Local\\Temp\\cibw-run-tonu1i82\\cp315-win_amd64\\build\\venv\\Scripts\\delvewheel', 'repair', '-w', 'C:\\Users\\runneradmin\\AppData\\Local\\Temp\\cibw-run-tonu1i82\\cp315-win_amd64\\repaired_wheel', '-v', 'C:\\Users\\runneradmin\\AppData\\Local\\Temp\\cibw-run-tonu1i82\\cp315-win_amd64\\built_wheel\\small_cache-0.1.3-cp315-cp315-win_amd64.whl']

small_cache-0.1.3.dist-info/METADATA

@@ -0,0 +1,192 @@
+Metadata-Version: 2.4
+Name: small-cache
+Version: 0.1.3
+Summary: Compact in-process snapshot cache for structured items
+Author: kam1k4dze
+License-Expression: BSD-3-Clause
+License-File: LICENSE
+Project-URL: Homepage, https://github.com/kam1k4dze/small_cache
+Requires-Python: <3.16,>=3.15
+Description-Content-Type: text/markdown
+
+# small_cache
+
+A memory-efficient in-process cache for structured items with typed attributes, implemented in C++23 and exposed to Python via [nanobind](https://github.com/wjakob/nanobind).
+
+| CI | Status |
+|----|--------|
+| wheels | [![Wheel Action Status][actions-wheels-badge]][actions-wheels-link] |
+
+[actions-wheels-link]: https://github.com/kam1k4dze/small_cache/actions?query=workflow%3AWheels
+[actions-wheels-badge]: https://github.com/kam1k4dze/small_cache/workflows/Wheels/badge.svg
+
+## Features
+
+- Store items with up to **96 named attributes** per cache instance
+- Supported attribute types: `bool`, `int` (64-bit), `float`, `str`, JSON (`bytes`), lists of `str`/JSON, `None` —
+  each comes back as the type it was stored as
+- **JSON answers** — getters return JSON written directly from the cache, with stored JSON embedded as is
+- **Flat, compact storage** — every distinct string is stored once; strings of 64+ bytes are zstd-compressed
+  with a dictionary trained on the data; each item is one packed record (absent and `None` attributes take no space)
+- **Snapshots** — a reload is built aside and published at once; reads never block and never see a half-finished load
+- **Transaction model** — bulk-update the cache, optionally evicting items the reload did not contain
+
+## Installation
+
+```bash
+pip install small-cache
+```
+
+Only binary wheels are published, for CPython 3.15, regular and free-threaded (3.15t), on Linux, macOS and
+Windows (64-bit). With free-threading the cache runs without the GIL: reads and loading proceed in parallel.
+
+Build from source:
+
+```bash
+git clone https://github.com/kam1k4dze/small_cache
+pip install ./small_cache
+```
+
+**Requirements:** Python ≥ 3.15 and < 3.16; to build: CMake ≥ 3.28 and a C++23 compiler
+(build dependencies: scikit-build-core 1.1.1, nanobind 3.1.0)
+
+## Quick Start
+
+```python
+from small_cache import SmallCache
+
+# Declare the attributes you care about (max 96)
+cache = SmallCache(["name", "price", "in_stock", "tags"])
+
+# A transaction wraps a full cache refresh cycle
+cache.begin_transaction(estimated_number_of_items=1000)
+
+cache.add("sku-001", {
+    "name": "Widget",
+    "price": 9.99,
+    "in_stock": True,
+    "tags": ["sale", "hardware"],
+})
+cache.add("sku-002", {"name": "Gadget", "price": 24.99, "in_stock": False})
+
+cache.end_transaction()  # publishes the new data; items not re-added are evicted
+
+# Answers are JSON bytes
+cache.get_one("sku-001", ["name", "price"])
+# b'["Widget",9.99]'
+
+# Batch retrieval: an unknown id gets an empty row
+cache.get_many(["sku-001", "sku-002", "sku-999"], ["name", "in_stock"])
+# b'[["Widget",true],["Gadget",false],[]]'
+
+cache.get_all_ids()
+# b'["sku-001","sku-002"]'
+```
+
+## Transaction Model
+
+`begin_transaction()` / `end_transaction()` bracket a full reload cycle:
+
+- Items written with `add()` go into a new snapshot that readers cannot see yet. Until
+  `end_transaction()`, every read is served from the current snapshot.
+- `end_transaction()` publishes the new snapshot at once. Items that were **not** written in the transaction
+  are dropped, or carried over unchanged with `remove_old_items=False`.
+- `abort_transaction()` throws the new snapshot away; the current one keeps being served. Call it when a
+  reload fails half-way, so a partial load is never published.
+- Reads take no lock and can run from any thread. While a reload is being built, the old and the new
+  snapshot are both in memory.
+
+```python
+# Keep stale items (incremental update)
+cache.begin_transaction(remove_old_items=False)
+cache.add("sku-003", {"name": "New item", "price": 5.0})
+cache.end_transaction()  # pre-existing items survive
+
+# Never publish a failed reload
+cache.begin_transaction()
+try:
+    for item_id, attributes in fetch_items():
+        cache.add(item_id, attributes)
+except Exception:
+    cache.abort_transaction()
+    raise
+cache.end_transaction()
+```
+
+## API Reference
+
+### `SmallCache(attribute_names: list[str])`
+
+Construct a cache instance. `attribute_names` lists every attribute that may be stored. Maximum 96 attributes; raises `RuntimeError` if the list is empty or exceeds the limit.
+
+### `begin_transaction(estimated_number_of_items: int = 0, remove_old_items: bool = True)`
+
+Open a write transaction. Optionally pre-allocates capacity. Raises `RuntimeError` if a transaction is already open.
+
+### `end_transaction()`
+
+Publish the transaction. With `remove_old_items=True` (default), items not written during this transaction are evicted. Raises `RuntimeError` if no transaction is open.
+
+### `abort_transaction()`
+
+Discard the transaction; the cache keeps serving what it had. Raises `RuntimeError` if no transaction is open.
+
+### `add(item_id: str, attributes: dict[str, None | bool | int | float | str | bytes | list[str | bytes]])`
+
+Insert or replace an item. Must be called inside a transaction. Attributes absent from `attribute_names` are
+silently ignored. `bytes` is JSON text, kept as is: the getters write it into their answers unchanged, so it
+must be valid JSON. List items are `str` or such JSON `bytes`. An `int` is stored as an integer and a `float` as
+a float; any other type, or an `int` outside the signed 64-bit range, raises `TypeError`.
+
+### `get_one(id: str, attributes: list[str]) -> bytes`
+
+The item's values for `attributes`, in that order, as a UTF-8 JSON array. Attributes that were not set, or whose
+name is not registered, are `null`; stored JSON is embedded as is; floats always carry a decimal point or exponent,
+so they stay floats. `[]` if the item does not exist or `attributes` is empty. The answer is built without holding
+the GIL. To return it from a JSON API without decoding it, wrap it, e.g. in `msgspec.Raw`.
+
+### `get_many(ids: list[str], attributes: list[str]) -> bytes`
+
+A JSON array with one `get_one` row per requested id.
+
+### `get_all(attributes: list[str]) -> bytes`
+
+A JSON array with one `get_one` row per item, in `get_all_ids()` order.
+
+### `get_all_ids() -> bytes`
+
+A JSON array of all item ids: the order items were added in, items carried over by `remove_old_items=False` last.
+
+## Building from Source
+
+```bash
+git clone https://github.com/kam1k4dze/small_cache
+cd small_cache
+pip install -e .
+```
+
+Native C++ unit tests and benchmark (requires CMake ≥ 3.28, Ninja and a C++23 compiler with modules support):
+
+```bash
+cmake -B build -G Ninja && cmake --build build
+./build/small_cache_native_test
+```
+
+`small_cache_bench` replays a recording of `add()` calls (JSON lines: a header `{"attributes": [...]}`, then one
+`{"id": ..., "a": {...}}` per call) as a series of reloads and reports memory and timings:
+
+```bash
+./build/small_cache_bench adds.jsonl --cycles 3
+heaptrack ./build/small_cache_bench adds.jsonl --cycles 2
+```
+
+Python tests:
+
+```bash
+pip install pytest
+pytest tests/
+```
+
+## License
+
+BSD-3-Clause — see [LICENSE](./LICENSE).

small_cache-0.1.3.dist-info/RECORD

@@ -0,0 +1,10 @@
+small_cache/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+small_cache/_small_cache_impl.cp315-win_amd64.pyd,sha256=D6h2LZW9Q-4VQCC0efPVomwQLs_C175cTLvGApRdFVQ,696320
+small_cache/_small_cache_impl.pyi,sha256=PZKFo2sK-JDfIo8vAHfnlAF6vPRDDm18oVIjkBNWp_o,1602
+small_cache/__init__.py,sha256=HJIgqC465XmEv0_efSyD5_zN0Ya6vdKbTla4o7i1ftI,404
+small_cache-0.1.3.dist-info/DELVEWHEEL,sha256=7Bfnufz_8-yCmxIqCBvK11Hx7ejOBKQ6mnKzE5llErU,410
+small_cache-0.1.3.dist-info/METADATA,sha256=C23pQJaktgo4OpIFM-skXTarGdIZrVFBnIgaX_lFF64,7171
+small_cache-0.1.3.dist-info/RECORD,,
+small_cache-0.1.3.dist-info/WHEEL,sha256=lX_s9_PODHQdPEziwqn30Su2CEVeLs-HsvaJqybfX_g,105
+small_cache-0.1.3.dist-info/licenses/LICENSE,sha256=zBrz9KYdq8ONytsas0TAkOopMFXkrfGHqbyieoAEHo0,1545
+small_cache.libs/msvcp140-a4c2229bdc2a2a630acdc095b4d86008.dll,sha256=pMIim9wqKmMKzcCVtNhgCOXD47x3cxdDVPPaT1vrnN4,575056

small_cache-0.1.3.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: scikit-build-core 1.1.1
+Root-Is-Purelib: false
+Tag: cp315-cp315-win_amd64
+

small_cache-0.1.3.dist-info/licenses/LICENSE

@@ -0,0 +1,26 @@
+Copyright (c) 2025-2026 kam1k4dze <me@kam1k4dze.com>, All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors
+   may be used to endorse or promote products derived from this software
+   without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.