snapclass 0.1.0__py3-none-any.whl

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/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/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/decorators.py

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

snapclass/formatters.py

@@ -0,0 +1,430 @@
+from __future__ import annotations
+
+import json
+from abc import ABC, abstractmethod
+from collections.abc import Mapping
+from io import StringIO
+from pathlib import Path
+from typing import Any, ClassVar, IO
+
+from ruamel.yaml import YAML as RuamelYAML
+
+
+def _empty_if_not_mapping(data: Any) -> dict[str, Any]:
+    if data is None:
+        return {}
+    if not isinstance(data, dict):
+        return {}
+    return data
+
+
+class FileFormatter(ABC):
+    extensions: ClassVar[set[str]] = set()
+
+    @classmethod
+    @abstractmethod
+    def loads(cls, text: str) -> dict[str, Any]:
+        raise NotImplementedError
+
+    @classmethod
+    @abstractmethod
+    def dumps(cls, data: dict[str, Any]) -> str:
+        raise NotImplementedError
+
+
+class Formatter(ABC):
+    """Application-level file format adapter."""
+
+    @classmethod
+    @abstractmethod
+    def extensions(cls) -> set[str]:
+        raise NotImplementedError
+
+    @classmethod
+    @abstractmethod
+    def deserialize(cls, file_object: IO[str]) -> dict[str, Any]:
+        raise NotImplementedError
+
+    @classmethod
+    @abstractmethod
+    def serialize(cls, data: Any) -> str:
+        raise NotImplementedError
+
+
+Format = Formatter
+
+
+class YAMLFormatter(FileFormatter):
+    extensions = {"", ".yml", ".yaml"}
+
+    @classmethod
+    def loads(cls, text: str) -> dict[str, Any]:
+        yaml = RuamelYAML()
+        yaml.preserve_quotes = True
+        data = yaml.load(text)
+        return _empty_if_not_mapping(data)
+
+    @classmethod
+    def dumps(cls, data: dict[str, Any]) -> str:
+        yaml = RuamelYAML()
+        yaml.indent(mapping=2, sequence=4, offset=2)
+        stream = StringIO()
+        yaml.dump(data, stream)
+        text = normalize_yaml_text(stream.getvalue())
+        if text == "{}\n":
+            return ""
+        return text
+
+
+class TextFormatter(FileFormatter):
+    extensions = {".txt"}
+
+    @classmethod
+    def loads(cls, text: str) -> dict[str, Any]:
+        return {"content": text}
+
+    @classmethod
+    def dumps(cls, data: dict[str, Any]) -> str:
+        values = list(data.values())
+        if len(values) != 1:
+            raise ValueError("TextFormatter expects exactly one serialized field")
+        value = values[0]
+        return "" if value is None else str(value)
+
+
+class TypedTextFormatter(FileFormatter):
+    extensions = {".txt"}
+    divider = "#-=-=-=-=-DO-NOT-EDIT-THIS-LINE-PLEASE-=-=-=-=-#"
+
+    _types = {
+        "bool": bool,
+        "float": float,
+        "int": int,
+        "NoneType": type(None),
+        "str": str,
+    }
+
+    @classmethod
+    def loads(cls, text: str) -> dict[str, Any]:
+        data: dict[str, Any] = {}
+        current_key: str | None = None
+        current_type: str | None = None
+        current_value: list[str] = []
+
+        for line in text.splitlines():
+            if line == cls.divider:
+                if current_key is None or current_type is None:
+                    raise ValueError("Misformatted typed text: divider without field header")
+                data[current_key] = cls._coerce("\n".join(current_value), current_type)
+                current_key = None
+                current_type = None
+                current_value = []
+                continue
+
+            if current_key is None:
+                try:
+                    key, type_name = line.split("|", 1)
+                except ValueError as exc:
+                    raise ValueError(f"Misformatted typed text field header: {line!r}") from exc
+                key = key.strip()
+                type_name = type_name.strip()
+                if not key:
+                    raise ValueError("Misformatted typed text: empty field name")
+                if type_name not in cls._types:
+                    raise ValueError(f"Unsupported typed text field type: {type_name!r}")
+                current_key = key
+                current_type = type_name
+                current_value = []
+            else:
+                current_value.append(line)
+
+        if current_key is not None:
+            raise ValueError(f"Misformatted typed text: missing divider for {current_key!r}")
+
+        return data
+
+    @classmethod
+    def dumps(cls, data: dict[str, Any]) -> str:
+        sections: list[str] = []
+        for key, value in data.items():
+            type_name = type(value).__name__
+            if type_name not in cls._types:
+                raise ValueError(f"Unsupported typed text field type: {type_name!r}")
+            rendered = "" if value is None else str(value)
+            sections.append(f"{key}|{type_name}\n{rendered}\n{cls.divider}\n")
+        return "".join(sections)
+
+    @classmethod
+    def _coerce(cls, value: str, type_name: str) -> Any:
+        if type_name == "NoneType":
+            return None
+        if type_name == "bool":
+            normalized = value.strip().lower()
+            if normalized in {"true", "1", "yes", "on"}:
+                return True
+            if normalized in {"false", "0", "no", "off", ""}:
+                return False
+            raise ValueError(f"Cannot parse bool typed text value: {value!r}")
+        return cls._types[type_name](value)
+
+
+class JSONFormatter(FileFormatter):
+    extensions = {".json"}
+
+    @classmethod
+    def loads(cls, text: str) -> dict[str, Any]:
+        data = json.loads(text)
+        return _empty_if_not_mapping(data)
+
+    @classmethod
+    def dumps(cls, data: dict[str, Any]) -> str:
+        return json.dumps(data, indent=2) + "\n"
+
+
+class JSON5Formatter(FileFormatter):
+    extensions = {".json5"}
+
+    @classmethod
+    def loads(cls, text: str) -> dict[str, Any]:
+        import json5
+
+        data = json5.loads(text)
+        return _empty_if_not_mapping(data)
+
+    @classmethod
+    def dumps(cls, data: dict[str, Any]) -> str:
+        import json5
+
+        return json5.dumps(data, indent=2) + "\n"
+
+
+class TOMLFormatter(FileFormatter):
+    extensions = {".toml"}
+
+    @classmethod
+    def loads(cls, text: str) -> dict[str, Any]:
+        import tomlkit
+
+        data = tomlkit.loads(text)
+        return _plain_mapping(data)
+
+    @classmethod
+    def dumps(cls, data: dict[str, Any]) -> str:
+        import tomlkit
+
+        return tomlkit.dumps(data)
+
+
+_DEFAULT_FILE_FORMATTERS: dict[str, type[FileFormatter]] = {
+    "": YAMLFormatter,
+    ".yml": YAMLFormatter,
+    ".yaml": YAMLFormatter,
+    ".json": JSONFormatter,
+    ".json5": JSON5Formatter,
+    ".toml": TOMLFormatter,
+    ".txt": TextFormatter,
+}
+
+
+def from_formatter(formatter: type) -> type[FileFormatter]:
+    class FormatterAdapter(FileFormatter):
+        extensions = set(formatter.extensions())
+
+        @classmethod
+        def loads(cls, text: str) -> dict[str, Any]:
+            data = formatter.deserialize(StringIO(text))
+            if data is None:
+                return {}
+            if not isinstance(data, dict):
+                return {}
+            return data
+
+        @classmethod
+        def loads_path(cls, path: Path, text: str) -> dict[str, Any]:
+            with path.open("r", encoding="utf-8") as file_object:
+                data = formatter.deserialize(file_object)
+            if data is None:
+                return {}
+            if not isinstance(data, dict):
+                return {}
+            return data
+
+        @classmethod
+        def dumps(cls, data: dict[str, Any]) -> str:
+            return formatter.serialize(data)
+
+    FormatterAdapter.__name__ = f"{formatter.__name__}FileFormatter"
+    return FormatterAdapter
+
+
+def normalize_formatters(
+    formatters: Mapping[str, type[FileFormatter] | type[Formatter]] | None,
+) -> dict[str, type[FileFormatter]]:
+    if formatters is None:
+        return {}
+    normalized: dict[str, type[FileFormatter]] = {}
+    for extension, formatter in formatters.items():
+        if not isinstance(extension, str):
+            raise TypeError("formatter extensions must be strings")
+        normalized[extension] = as_file_formatter(formatter)
+    return normalized
+
+
+def as_file_formatter(
+    formatter: type[FileFormatter] | type[Formatter],
+) -> type[FileFormatter]:
+    if not isinstance(formatter, type):
+        raise TypeError("formatter must be a formatter class")
+    if issubclass(formatter, FileFormatter):
+        return formatter
+    if issubclass(formatter, Formatter):
+        return from_formatter(formatter)
+    raise TypeError("formatter must be a Formatter subclass")
+
+
+def formatter_for(
+    path: Path,
+    explicit: type[FileFormatter] | None = None,
+    *,
+    formatters: Mapping[str, type[FileFormatter]] | None = None,
+) -> type[FileFormatter]:
+    if explicit is not None:
+        return explicit
+    suffix = path.suffix
+    if formatters is not None and suffix in formatters:
+        return formatters[suffix]
+    if suffix in _DEFAULT_FILE_FORMATTERS:
+        return _DEFAULT_FILE_FORMATTERS[suffix]
+    raise ValueError(f"Unsupported file extension: {suffix!r}")
+
+
+class JSON(Formatter):
+    @classmethod
+    def extensions(cls) -> set[str]:
+        return {".json"}
+
+    @classmethod
+    def deserialize(cls, file_object: IO[str]) -> dict[str, Any]:
+        return _empty_if_not_mapping(json.load(file_object))
+
+    @classmethod
+    def serialize(cls, data: Any) -> str:
+        return json.dumps(data, indent=2)
+
+
+class JSON5(Formatter):
+    @classmethod
+    def extensions(cls) -> set[str]:
+        return {".json5"}
+
+    @classmethod
+    def deserialize(cls, file_object: IO[str]) -> dict[str, Any]:
+        import json5
+
+        return _empty_if_not_mapping(json5.load(file_object))
+
+    @classmethod
+    def serialize(cls, data: Any) -> str:
+        import json5
+
+        return json5.dumps(data, indent=2)
+
+
+class TOML(Formatter):
+    @classmethod
+    def extensions(cls) -> set[str]:
+        return {".toml"}
+
+    @classmethod
+    def deserialize(cls, file_object: IO[str]) -> dict[str, Any]:
+        import tomlkit
+
+        return _plain_mapping(tomlkit.loads(file_object.read()))
+
+    @classmethod
+    def serialize(cls, data: Any) -> str:
+        import tomlkit
+
+        return tomlkit.dumps(data)
+
+
+class YAML(Formatter):
+    @classmethod
+    def extensions(cls) -> set[str]:
+        return {"", ".yml", ".yaml"}
+
+    @classmethod
+    def deserialize(cls, file_object: IO[str]) -> dict[str, Any]:
+        yaml = RuamelYAML()
+        yaml.preserve_quotes = True
+        return _empty_if_not_mapping(yaml.load(file_object))
+
+    @classmethod
+    def serialize(cls, data: Any) -> str:
+        yaml = RuamelYAML()
+        yaml.indent(mapping=2, sequence=4, offset=2)
+        stream = StringIO()
+        yaml.dump(data, stream)
+        text = normalize_yaml_text(stream.getvalue())
+        if text == "{}\n":
+            return ""
+        return text
+
+
+_DEFAULT_FORMATTERS: dict[str, type[Formatter]] = {
+    "": YAML,
+    ".yml": YAML,
+    ".yaml": YAML,
+    ".json": JSON,
+    ".json5": JSON5,
+    ".toml": TOML,
+}
+
+
+def deserialize(
+    path: Path,
+    extension: str,
+    *,
+    formatter: type[Formatter] | None = None,
+) -> dict[str, Any]:
+    formatter = formatter or _formatter_adapter_for(extension)
+    with path.open("r", encoding="utf-8") as file_object:
+        return _empty_if_not_mapping(formatter.deserialize(file_object))
+
+
+def serialize(
+    data: Any,
+    extension: str = ".yml",
+    *,
+    formatter: type[Formatter] | None = None,
+) -> str:
+    formatter = formatter or _formatter_adapter_for(extension)
+    return formatter.serialize(data)
+
+
+def _formatter_adapter_for(extension: str) -> type[Formatter]:
+    if extension in _DEFAULT_FORMATTERS:
+        return _DEFAULT_FORMATTERS[extension]
+    raise ValueError(f"Unsupported file extension: {extension!r}")
+
+
+def _plain_mapping(value: Any) -> Any:
+    if isinstance(value, dict):
+        return {key: _plain_mapping(item) for key, item in value.items()}
+    if isinstance(value, list):
+        return [_plain_mapping(item) for item in value]
+    return value
+
+
+def normalize_yaml_text(text: str) -> str:
+    text = text.replace("- \n", "-\n")
+    if text.startswith("  -"):
+        lines = (
+            line[2:] if line.startswith("  ") else line
+            for line in text.splitlines()
+        )
+        return "\n".join(lines) + "\n"
+    return text
+
+
+_normalize_yaml_text = normalize_yaml_text

snapclass/fresh.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+import copy as _copy
+from collections import Counter, defaultdict, deque
+from collections.abc import Callable
+from dataclasses import field
+from typing import Any
+
+_MISSING = object()
+
+
+class _Fresh:
+    def __call__(self, factory: Callable[[], Any]):
+        return field(default_factory=factory)
+
+    @property
+    def List(self):
+        return field(default_factory=list)
+
+    @property
+    def Dict(self):
+        return field(default_factory=dict)
+
+    @property
+    def Set(self):
+        return field(default_factory=set)
+
+    @property
+    def Deque(self):
+        return field(default_factory=deque)
+
+    @property
+    def Counter(self):
+        return field(default_factory=Counter)
+
+    def DefaultDict(
+        self,
+        factory: Callable[[], Any] | object = _MISSING,
+        *,
+        value: Callable[[], Any] | object = _MISSING,
+    ):
+        if factory is not _MISSING and value is not _MISSING:
+            raise TypeError(
+                "Fresh.DefaultDict accepts either a positional factory or value=, "
+                "not both"
+            )
+        default_factory = value if value is not _MISSING else factory
+        if default_factory is _MISSING:
+            raise TypeError("Fresh.DefaultDict requires a missing-value factory")
+        return field(default_factory=lambda: defaultdict(default_factory))
+
+    def copy(self, template: Any):
+        return field(default_factory=lambda: _copy.deepcopy(template))
+
+
+Fresh = _Fresh()
+
+__all__ = ["Fresh"]