chestkey 0.1.0__tar.gz

chestkey-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Wannes Vantorre
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

chestkey-0.1.0/PKG-INFO

@@ -0,0 +1,44 @@
+Metadata-Version: 2.4
+Name: chestkey
+Version: 0.1.0
+Summary: A generic storage datatype based on deterministic identities.
+Keywords: cache,storage,memoization,content-addressed,deterministic
+Author: Wannes Vantorre
+Author-email: Wannes Vantorre <vantorrewannes@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Dist: blake3>=1.0.9
+Requires-Dist: dill>=0.4.1
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# chestkey
+
+A generic storage datatype based on deterministic identities.
+
+```python
+from pathlib import Path
+from chestkey import Chest, Key
+
+def add(x: int, y: int) -> int:
+    return x + y
+
+def cached_add(x: int, y: int) -> int:
+    chest = Chest(Path(".cache"))
+    key = Key((add.__code__, x, y))
+    if chest.contains(key):
+        return chest.get[int](key)
+
+    z = add(x, y)
+    chest.set(key, z)
+    return z
+```

chestkey-0.1.0/README.md

@@ -0,0 +1,21 @@
+# chestkey
+
+A generic storage datatype based on deterministic identities.
+
+```python
+from pathlib import Path
+from chestkey import Chest, Key
+
+def add(x: int, y: int) -> int:
+    return x + y
+
+def cached_add(x: int, y: int) -> int:
+    chest = Chest(Path(".cache"))
+    key = Key((add.__code__, x, y))
+    if chest.contains(key):
+        return chest.get[int](key)
+
+    z = add(x, y)
+    chest.set(key, z)
+    return z
+```

chestkey-0.1.0/pyproject.toml

@@ -0,0 +1,99 @@
+[project]
+name = "chestkey"
+version = "0.1.0"
+description = "A generic storage datatype based on deterministic identities."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.12"
+keywords = [
+    "cache",
+    "storage",
+    "memoization",
+    "content-addressed",
+    "deterministic",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Libraries",
+    "Typing :: Typed",
+]
+dependencies = [
+    "blake3>=1.0.9",
+    "dill>=0.4.1",
+]
+
+[[project.authors]]
+name = "Wannes Vantorre"
+email = "vantorrewannes@gmail.com"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.4",
+    "pytest-cov>=7.0",
+    "pytest-mock>=3.15.1",
+]
+
+[build-system]
+requires = ["uv_build>=0.12.7,<0.13.0"]
+build-backend = "uv_build"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "--import-mode=importlib"
+
+[tool.coverage.run]
+branch = true
+source_pkgs = ["chestkey"]
+
+[tool.coverage.report]
+show_missing = true
+fail_under = 100
+
+[tool.ruff]
+target-version = "py312"
+line-length = 88
+src = [
+    "src",
+    "tests",
+]
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = [
+    "CPY001",
+    "COM812",
+    "ISC001",
+    "D203",
+    "D213",
+    "D100",
+    "D104",
+    "D105",
+    "ANN401",
+    "FBT001",
+    "FBT002",
+    "TC001",
+    "TC002",
+    "TC003",
+    "EM101",
+    "EM102",
+    "TRY003",
+    "PLR2004",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = [
+    "S101",
+    "PLR2004",
+    "D103",
+    "INP001",
+]
+
+[tool.ruff.format]
+docstring-code-format = true

chestkey-0.1.0/pyproject.toml.orig

@@ -0,0 +1,94 @@
+[project]
+name = "chestkey"
+version = "0.1.0"
+description = "A generic storage datatype based on deterministic identities."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "Wannes Vantorre", email = "vantorrewannes@gmail.com" }
+]
+requires-python = ">=3.12"
+keywords = ["cache", "storage", "memoization", "content-addressed", "deterministic"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Libraries",
+    "Typing :: Typed",
+]
+dependencies = [
+    "blake3>=1.0.9",
+    "dill>=0.4.1",
+]
+
+[dependency-groups]
+dev = [
+    "pytest>=8.4",
+    "pytest-cov>=7.0",
+    "pytest-mock>=3.15.1",
+]
+
+[build-system]
+requires = ["uv_build>=0.12.7,<0.13.0"]
+build-backend = "uv_build"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "--import-mode=importlib"
+
+[tool.coverage.run]
+branch = true
+source_pkgs = ["chestkey"]
+
+[tool.coverage.report]
+show_missing = true
+fail_under = 100
+
+[tool.ruff]
+target-version = "py312"
+line-length = 88
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = [
+    "CPY001",
+
+    "COM812",
+    "ISC001",
+    "D203",
+    "D213",
+
+    "D100",
+    "D104",
+    "D105",
+
+    "ANN401",
+    "FBT001",
+    "FBT002",
+
+    "TC001",
+    "TC002",
+    "TC003",
+
+    "EM101",
+    "EM102",
+    "TRY003",
+    "PLR2004",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = [
+    "S101",
+    "PLR2004",
+    "D103",
+    "INP001",
+]
+
+[tool.ruff.format]
+docstring-code-format = true

chestkey-0.1.0/src/chestkey/__init__.py

@@ -0,0 +1,3 @@
+from chestkey.lib import Chest, Key, TypedGetter
+
+__all__ = ["Chest", "Key", "TypedGetter"]

chestkey-0.1.0/src/chestkey/lib.py

@@ -0,0 +1,69 @@
+from collections.abc import Callable
+from pathlib import Path
+
+import blake3
+import dill
+
+
+class Key:
+    """A deterministic identity derived from arbitrary content."""
+
+    __slots__ = ("digest",)
+
+    def __init__(self, seed: object) -> None:
+        """Derive the identity from the seed's serialized content."""
+        self.digest = blake3.blake3(dill.dumps(seed)).hexdigest()
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, Key):
+            return NotImplemented
+        return self.digest == other.digest
+
+    def __hash__(self) -> int:
+        return hash(self.digest)
+
+    def __repr__(self) -> str:
+        return f"Key({self.digest[:16]})"
+
+
+class TypedGetter[K]:
+    """Wrapper that makes a fetch method typed: `getter[T](key)`."""
+
+    __slots__ = ("fetch",)
+
+    def __init__(self, fetch: Callable[[K], object]) -> None:  # noqa: D107
+        self.fetch = fetch
+
+    def __getitem__[T](self, value_type: type[T]) -> Callable[[K], T]:
+        def get(key: K) -> T:
+            value = self.fetch(key)
+            if not isinstance(value, value_type):
+                stored = type(value).__name__
+                msg = f"{key}: stored {stored}, expected {value_type.__name__}"
+                raise TypeError(msg)
+            return value
+
+        return get
+
+
+class Chest:
+    """A generic storage datatype based on deterministic identities."""
+
+    def __init__(self, path: Path) -> None:
+        """Bind the storage location; nothing is created until first write."""
+        self.path = path
+        self.get = TypedGetter(self._fetch)
+
+    def contains(self, key: Key) -> bool:
+        """Answer whether the key has a stored value."""
+        return (self.path / key.digest).is_file()
+
+    def set(self, key: Key, value: object) -> None:
+        """Store the value at the key."""
+        self.path.mkdir(parents=True, exist_ok=True)
+        (self.path / key.digest).write_bytes(dill.dumps(value))
+
+    def _fetch(self, key: Key) -> object:
+        if not self.contains(key):
+            raise KeyError(key)
+        return dill.loads((self.path / key.digest).read_bytes())  # noqa: S301