persistent-bundles 0.1.0__py3-none-any.whl

persistent_bundles/__init__.py

@@ -0,0 +1,2 @@
+def hello() -> str:
+    return "Hello from persistent-bundles!"

persistent_bundles/api.py

@@ -0,0 +1,68 @@
+from collections.abc import Mapping
+import json
+from pathlib import Path
+from typing import Any
+
+from persistent_bundles.exceptions import IncompatibleBundleVersionError
+from persistent_bundles.types import Loadable, Savable
+from persistent_bundles.utils import is_same_major_semver
+
+
+def save_bundle(
+    obj: Savable,
+    path: Path,
+    metadata: Mapping[str, Any] | None = None,  # pyright: ignore[reportExplicitAny]
+) -> None:
+    """Save an object and the metadata needed to load it later."""
+    assert str(path).endswith(".bundle")
+
+    object_path = path / "object"
+    object_path.mkdir(parents=True)
+    obj.save(object_path)
+
+    with (path / "manifest.json").open("w") as f:
+        json.dump(
+            {
+                "class_name": obj.__class__.__name__,
+                "class_version": obj.get_class_version(),
+            },
+            f,
+        )
+
+    if metadata is not None:
+        with (path / "metadata.json").open("w") as f:
+            json.dump(metadata, f)
+
+
+def load_bundle(
+    path: Path,
+    class_mapping: Mapping[str, type[Loadable]],
+    accept_incompatible_classes: bool = False,
+) -> tuple[Loadable, Mapping[str, Any]]:  # pyright: ignore[reportExplicitAny]
+    """Load a bundle object, returning both the object and metadata."""
+    assert str(path).endswith(".bundle")
+
+    with (path / "manifest.json").open("r") as f:
+        manifest = json.load(f)
+
+    class_name = manifest["class_name"]
+    class_to_be_loaded = class_mapping[class_name]
+    current_class_version = class_to_be_loaded.get_class_version()
+    saved_class_version = manifest["class_version"]
+
+    if not accept_incompatible_classes and not is_same_major_semver(
+        saved_class_version, current_class_version
+    ):
+        raise IncompatibleBundleVersionError(
+            "The loaded bundle does not have the same major class version as the current class"
+        )
+
+    obj = class_to_be_loaded.load(path / "object")
+
+    if (path / "metadata.json").exists():
+        with (path / "metadata.json").open("r") as f:
+            metadata = json.load(f)
+    else:
+        metadata = {}
+
+    return obj, metadata

persistent_bundles/exceptions.py

@@ -0,0 +1,2 @@
+class IncompatibleBundleVersionError(Exception):
+    """Raised when a bundle's saved class version cannot be loaded by the current class."""

persistent_bundles/types.py

@@ -0,0 +1,21 @@
+from pathlib import Path
+from typing import Protocol, Self
+
+
+class Savable(Protocol):
+    def save(self, path: Path) -> None: ...
+
+    @classmethod
+    def get_class_version(cls) -> str:
+        """Return the class version according to semantic versioning. A differing major version indicates incompatible states."""
+        ...
+
+
+class Loadable(Protocol):
+    @classmethod
+    def load(cls, path: Path) -> Self: ...
+
+    @classmethod
+    def get_class_version(cls) -> str:
+        """Return the class version according to semantic versioning. A differing major version indicates incompatible states."""
+        ...

persistent_bundles/utils.py

@@ -0,0 +1,2 @@
+def is_same_major_semver(s1: str, s2: str) -> bool:
+    return s1.split(".")[0] == s2.split(".")[0]

persistent_bundles-0.1.0.dist-info/METADATA

@@ -0,0 +1,78 @@
+Metadata-Version: 2.4
+Name: persistent-bundles
+Version: 0.1.0
+Summary: Save and load versioned Python object bundles with metadata.
+Keywords: bundles,persistence,serialization,versioning
+Author: Valter Schütz
+Author-email: Valter Schütz <valterschutz@proton.me>
+License-Expression: Unlicense
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: The Unlicense (Unlicense)
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.13
+Project-URL: Issues, https://github.com/valterschutz/persistent-bundles/issues
+Project-URL: Repository, https://github.com/valterschutz/persistent-bundles
+Description-Content-Type: text/markdown
+
+# persistent-bundles
+
+Save and load versioned Python object bundles with optional metadata.
+
+`persistent-bundles` is a small library for objects that manage their own on-disk persistence. It writes a bundle directory containing the saved object, a manifest with the object's class name and semantic version, and optional JSON metadata.
+
+## Installation
+
+```bash
+pip install persistent-bundles
+```
+
+## Usage
+
+```python
+import json
+from pathlib import Path
+from typing import Self, override
+
+from persistent_bundles.api import load_bundle, save_bundle
+from persistent_bundles.types import Loadable, Savable
+
+
+class MyObject(Savable, Loadable):
+    def __init__(self, number: int) -> None:
+        self.number = number
+
+    @override
+    def save(self, path: Path) -> None:
+        with (path / "number.json").open("w") as f:
+            json.dump({"number": self.number}, f)
+
+    @classmethod
+    @override
+    def load(cls, path: Path) -> Self:
+        with (path / "number.json").open("r") as f:
+            data = json.load(f)
+        return cls(data["number"])
+
+    @classmethod
+    @override
+    def get_class_version(cls) -> str:
+        return "1.0.0"
+
+
+path = Path("example.bundle")
+save_bundle(MyObject(42), path, metadata={"created_by": "example"})
+
+obj, metadata = load_bundle(path, {"MyObject": MyObject})
+```
+
+Bundles require a `.bundle` path suffix. When loading, the saved class version must have the same semantic-version major number as the current class version.
+
+## Development
+
+```bash
+uv run pytest
+uv build
+```

persistent_bundles-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+persistent_bundles/__init__.py,sha256=K9z1tbgmrh1vHYkhcKwJuBRbsvR8zg2y8R0usdokrjQ,64
+persistent_bundles/api.py,sha256=u2HY5MvfVChjsvHAkrtlcCVxB28n_F5hZ82cBKpgS3M,2132
+persistent_bundles/exceptions.py,sha256=PyVFA0EEK8ki2C50dhWxh_7nVqkbWMoN3ILfMqEEYOc,141
+persistent_bundles/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+persistent_bundles/types.py,sha256=SncsC3g-HA0lLR3W7TY7D72HBrWXnM2szDOhok5SCfw,616
+persistent_bundles/utils.py,sha256=CUDZAW2Aa5IjhUfFm_dFGkw9SKdI1tnJPPHQjH8GKtg,100
+persistent_bundles-0.1.0.dist-info/WHEEL,sha256=NHRAbdxxzyL9K3IO2LjmlNqKSyPZnKv2BD16YYVKo18,79
+persistent_bundles-0.1.0.dist-info/METADATA,sha256=EOeVjKHKkNH57lXwOTow7FGFu6CXj6Bnf1w_ea_0nLk,2325
+persistent_bundles-0.1.0.dist-info/RECORD,,

persistent_bundles-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.8.14
+Root-Is-Purelib: true
+Tag: py3-none-any