snapclass 0.1.0__tar.gz

snapclass-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mattie Casper
+
+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.

snapclass-0.1.0/PKG-INFO

@@ -0,0 +1,123 @@
+Metadata-Version: 2.4
+Name: snapclass
+Version: 0.1.0
+Summary: Human-readable file persistence for Python dataclasses.
+Author: Mattie Casper
+License-Expression: MIT
+Project-URL: Repository, https://github.com/Mattie/snapclass
+Project-URL: Issues, https://github.com/Mattie/snapclass/issues
+Keywords: dataclasses,persistence,serialization,yaml,toml
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: json5<1,>=0.9
+Requires-Dist: ruamel.yaml<0.20,>=0.18
+Requires-Dist: tomlkit<0.16,>=0.10
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Provides-Extra: typing
+Requires-Dist: mypy<3,>=1.11; extra == "typing"
+Dynamic: license-file
+
+# snapclass
+
+Human-readable file persistence for Python dataclasses, an adaptation of the cool [`datafiles` project](https://github.com/jacebrowning/datafiles).
+
+`snapclass` is a small persistence layer built around Python dataclasses.
+Decorate a dataclass, give it a path pattern, and its instances can save and
+load themselves as readable YAML, JSON, TOML, or text.
+
+It is built for the stuff that belongs in a repo or project folder: prompts,
+configs, fixtures, lightweight app state, and little durable objects with names.
+
+You can use a `Stash` to pick a different location for the
+serialized file (with env overrides) and have special format rules when you
+need. You can also include a `sidecar` when you have a doc or binary you want to save next to it.
+
+
+
+## ORM is a snap!
+
+```python
+from snapclass import snapclass
+
+@snapclass("{self.name}.yml")
+class Note:
+    name: str
+    title: str
+    body: str = ""
+
+mynote = Note(
+    "first_note",
+    "Today I used snapclass!",
+    "It was my first day of snapclass. My note was saved to YAML for me!",
+)
+mynote.snapshot.save()
+
+# Load it back later with the same name.
+same_note = Note.snapshots.get("first_note")
+```
+
+```python
+from snapclass import snapclass, Stash, Fresh
+
+# Create a default location with an environment override.
+runsloc = Stash("./runs", env="RUNS_DIR")
+
+@snapclass("{self.name}.yml", stash=runsloc)
+class RunData:
+    name: str
+    # shortcuts for common boilerplate factory code
+    metrics: dict[str, float] = Fresh.Dict
+
+RunData("baseline", {"accuracy": 0.98, "loss": 0.04}).snapshot.save()
+```
+
+```python
+from snapclass import snapclass, Stash, sidecar
+
+@snapclass
+class Style:
+    voice: str
+    temperature: float
+
+# Locations can be nested with stashes.
+app = Stash("./myapp", env="MYAPP_DATA")
+articles = app / "articles"
+
+@snapclass("{self.slug}/article.yml", stash=articles)
+class Article:
+    slug: str
+    title: str
+    style: Style
+    body: str = sidecar.text("{self.slug}.md")
+
+article = Article(
+    "dusk-court",
+    "Dusk Court",
+    Style("warm", 0.4),
+    body="# Dusk Court\n\nBe brief, warm, and useful.\n",
+)
+loaded = Article.snapshots.get("dusk-court")
+```
+
+## FAQ
+
+### Why use `snapclass` over `datafiles`?
+
+`datafiles` is great and you should absolutely use it for your app or script! I love it so much and use it in project after project. After years of use, I've run into a few limitations-- like issues when multiple modules needed different `datafiles` behavior in one process (because much of the behavior control is global). I designed `snapclass` to isolate some of that via stashes and added some extra features I liked along the way.
+
+## License
+
+snapclass is licensed under the MIT License. See [LICENSE](LICENSE).
+
+Much of snapclass's core behavior, along with portions of its implementation
+and test suite, is adapted from the wonderful [`datafiles`](https://github.com/jacebrowning/datafiles) project by [Jace Browning](https://github.com/jacebrowning). See [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).

snapclass-0.1.0/README.md

@@ -0,0 +1,94 @@
+# snapclass
+
+Human-readable file persistence for Python dataclasses, an adaptation of the cool [`datafiles` project](https://github.com/jacebrowning/datafiles).
+
+`snapclass` is a small persistence layer built around Python dataclasses.
+Decorate a dataclass, give it a path pattern, and its instances can save and
+load themselves as readable YAML, JSON, TOML, or text.
+
+It is built for the stuff that belongs in a repo or project folder: prompts,
+configs, fixtures, lightweight app state, and little durable objects with names.
+
+You can use a `Stash` to pick a different location for the
+serialized file (with env overrides) and have special format rules when you
+need. You can also include a `sidecar` when you have a doc or binary you want to save next to it.
+
+
+
+## ORM is a snap!
+
+```python
+from snapclass import snapclass
+
+@snapclass("{self.name}.yml")
+class Note:
+    name: str
+    title: str
+    body: str = ""
+
+mynote = Note(
+    "first_note",
+    "Today I used snapclass!",
+    "It was my first day of snapclass. My note was saved to YAML for me!",
+)
+mynote.snapshot.save()
+
+# Load it back later with the same name.
+same_note = Note.snapshots.get("first_note")
+```
+
+```python
+from snapclass import snapclass, Stash, Fresh
+
+# Create a default location with an environment override.
+runsloc = Stash("./runs", env="RUNS_DIR")
+
+@snapclass("{self.name}.yml", stash=runsloc)
+class RunData:
+    name: str
+    # shortcuts for common boilerplate factory code
+    metrics: dict[str, float] = Fresh.Dict
+
+RunData("baseline", {"accuracy": 0.98, "loss": 0.04}).snapshot.save()
+```
+
+```python
+from snapclass import snapclass, Stash, sidecar
+
+@snapclass
+class Style:
+    voice: str
+    temperature: float
+
+# Locations can be nested with stashes.
+app = Stash("./myapp", env="MYAPP_DATA")
+articles = app / "articles"
+
+@snapclass("{self.slug}/article.yml", stash=articles)
+class Article:
+    slug: str
+    title: str
+    style: Style
+    body: str = sidecar.text("{self.slug}.md")
+
+article = Article(
+    "dusk-court",
+    "Dusk Court",
+    Style("warm", 0.4),
+    body="# Dusk Court\n\nBe brief, warm, and useful.\n",
+)
+loaded = Article.snapshots.get("dusk-court")
+```
+
+## FAQ
+
+### Why use `snapclass` over `datafiles`?
+
+`datafiles` is great and you should absolutely use it for your app or script! I love it so much and use it in project after project. After years of use, I've run into a few limitations-- like issues when multiple modules needed different `datafiles` behavior in one process (because much of the behavior control is global). I designed `snapclass` to isolate some of that via stashes and added some extra features I liked along the way.
+
+## License
+
+snapclass is licensed under the MIT License. See [LICENSE](LICENSE).
+
+Much of snapclass's core behavior, along with portions of its implementation
+and test suite, is adapted from the wonderful [`datafiles`](https://github.com/jacebrowning/datafiles) project by [Jace Browning](https://github.com/jacebrowning). See [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).

snapclass-0.1.0/pyproject.toml

@@ -0,0 +1,59 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "snapclass"
+version = "0.1.0"
+description = "Human-readable file persistence for Python dataclasses."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+  { name = "Mattie Casper" },
+]
+keywords = [
+  "dataclasses",
+  "persistence",
+  "serialization",
+  "yaml",
+  "toml",
+]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "Typing :: Typed",
+]
+dependencies = [
+  "json5>=0.9,<1",
+  "ruamel.yaml>=0.18,<0.20",
+  "tomlkit>=0.10,<0.16",
+]
+
+[project.optional-dependencies]
+test = [
+  "pytest>=8",
+]
+typing = [
+  "mypy>=1.11,<3",
+]
+
+[project.urls]
+Repository = "https://github.com/Mattie/snapclass"
+Issues = "https://github.com/Mattie/snapclass/issues"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+snapclass = ["py.typed"]

snapclass-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

snapclass-0.1.0/src/snapclass/__init__.py

@@ -0,0 +1,42 @@
+from dataclasses import field
+
+from . import serializers, formatters, hooks, plugins, sessions, sidecar, types
+from .schemas import (
+    Collection,
+    Config,
+    SnapclassError,
+    Missing,
+    Model,
+    Snapshot,
+    auto,
+    create_model,
+    snapclass,
+    frozen,
+    sync,
+)
+from .fresh import Fresh
+from .stash import Stash
+
+__all__ = [
+    "Fresh",
+    "Missing",
+    "SnapclassError",
+    "Collection",
+    "Config",
+    "Model",
+    "Snapshot",
+    "Stash",
+    "auto",
+    "serializers",
+    "create_model",
+    "snapclass",
+    "field",
+    "formatters",
+    "frozen",
+    "hooks",
+    "plugins",
+    "sessions",
+    "sidecar",
+    "sync",
+    "types",
+]

snapclass-0.1.0/src/snapclass/collections.py

@@ -0,0 +1,133 @@
+from __future__ import annotations
+
+import dataclasses
+import os
+from collections.abc import Iterator
+from typing import Any
+
+from . import sessions
+from .stash import Stash
+
+_missing_argument = object()
+
+
+class CollectionDescriptor:
+    def __get__(self, obj: object, cls: type) -> "Collection":
+        return Collection(cls)
+
+
+class Collection:
+    def __init__(self, cls: type, stash: Stash | None = None) -> None:
+        self.model = cls
+        self._stash = stash
+
+    def __call__(self, stash: Stash | str | os.PathLike[str]) -> "Collection":
+        from .schemas import _coerce_stash
+
+        return Collection(self.model, _coerce_stash(stash))
+
+    def get(self, *args: Any, **kwargs: Any) -> Any:
+        from .schemas import _attach_snapshot
+
+        __tracebackhide__ = sessions.HIDDEN_TRACEBACK
+        instance = self._empty_instance(*args, **kwargs)
+        _attach_snapshot(instance, self.model.__snapclass_config__, self._stash)
+        instance.snapshot.load(_initial=True)
+        return instance
+
+    def get_or_none(self, *args: Any, **kwargs: Any) -> Any | None:
+        __tracebackhide__ = sessions.HIDDEN_TRACEBACK
+        try:
+            return self.get(*args, **kwargs)
+        except FileNotFoundError:
+            return None
+
+    def get_or_create(self, *args: Any, **kwargs: Any) -> Any:
+        from .schemas import _attach_snapshot, _write_lock_for
+
+        __tracebackhide__ = sessions.HIDDEN_TRACEBACK
+        instance = self._empty_instance(*args, **kwargs, include_defaults=True)
+        _attach_snapshot(instance, self.model.__snapclass_config__, self._stash)
+        with _write_lock_for(instance.snapshot._require_path()):
+            if instance.snapshot.exists:
+                instance.snapshot.load(_initial=True)
+            else:
+                instance.snapshot.save()
+            return instance
+
+    def all(self, *, _exclude: str = "") -> Iterator[Any]:
+        from .schemas import _PatternMatcher, _attach_snapshot, _has_path_value
+
+        __tracebackhide__ = sessions.HIDDEN_TRACEBACK
+        if not self.model.__snapclass_config__.pattern:
+            raise RuntimeError("'pattern' must be set")
+        try:
+            matcher = _PatternMatcher(self.model, self._stash)
+        except ValueError as exc:
+            raise ValueError(
+                f"Unable to scan {self.model.__name__}: {exc}"
+            ) from exc
+        for path in matcher.iter_candidates():
+            if path.is_dir():
+                continue
+            values = matcher.values_from(path)
+            if _exclude and values and str(values[0]).startswith(_exclude):
+                continue
+            if matcher.has_recursive_wildcard or _has_path_value(values):
+                instance = self._empty_instance(*values)
+                _attach_snapshot(instance, self.model.__snapclass_config__, self._stash)
+                instance.snapshot.load(path, _initial=True)
+                yield instance
+            else:
+                yield self.get(*values)
+
+    def filter(self, *, _exclude: str = "", **query: Any) -> Iterator[Any]:
+        from .schemas import _lookup
+
+        __tracebackhide__ = sessions.HIDDEN_TRACEBACK
+        for item in self.all(_exclude=_exclude):
+            if all(_lookup(item, key) == value for key, value in query.items()):
+                yield item
+
+    def _empty_instance(self, *args: Any, include_defaults: bool = False, **kwargs: Any) -> Any:
+        from .schemas import (
+            Missing,
+            _coerce,
+            _field_default,
+            _is_missing,
+            _placeholder_for,
+        )
+
+        instance = self.model.__new__(self.model)
+        fields = [f for f in dataclasses.fields(self.model) if f.init]
+        hints = self.model.__snapclass_config__.type_hints
+        pattern = self.model.__snapclass_config__.pattern or ""
+        arg_iter = iter(args)
+        for field in fields:
+            try:
+                value = next(arg_iter)
+            except StopIteration:
+                value = kwargs.get(field.name, _missing_argument)
+            if value is _missing_argument:
+                default = _field_default(field)
+                if include_defaults:
+                    value = default
+                elif not _is_missing(default):
+                    value = default
+                elif _placeholder_for(field.name) in pattern:
+                    value = default
+                    if _is_missing(value):
+                        raise TypeError(
+                            "Collection.get() missing required placeholder field "
+                            f"argument: '{field.name}'"
+                        )
+                else:
+                    value = Missing
+            elif _placeholder_for(field.name) in pattern:
+                value = _coerce(value, hints.get(field.name))
+            object.__setattr__(instance, field.name, value)
+        object.__setattr__(instance, "_snapclass_initializing", False)
+        return instance
+
+
+__all__ = ["Collection", "CollectionDescriptor"]

snapclass-0.1.0/src/snapclass/containers.py

@@ -0,0 +1,11 @@
+from .schemas import TrackedDict, TrackedList, _track_value, _wrap_mutables
+from .types import Dict, List
+
+__all__ = [
+    "Dict",
+    "List",
+    "TrackedDict",
+    "TrackedList",
+    "_track_value",
+    "_wrap_mutables",
+]

snapclass-0.1.0/src/snapclass/decorators.py

@@ -0,0 +1,5 @@
+"""Decorator API re-exports."""
+
+from .schemas import auto, snapclass, sync
+
+__all__ = ["auto", "snapclass", "sync"]