syncwave 0.2.0__tar.gz → 0.3.0__tar.gz

{syncwave-0.2.0 → syncwave-0.3.0}/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Lucas Iannitello
+Copyright (c) 2026 Lucas Iannitello
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

syncwave-0.3.0/PKG-INFO

@@ -0,0 +1,84 @@
+Metadata-Version: 2.3
+Name: syncwave
+Version: 0.3.0
+Summary: Turn plain JSON files into a live data store, two-way synced with your Python objects.
+Keywords: 
+Author: Lucas Iannitello
+Author-email: Lucas Iannitello <lucas.iannitello@protonmail.com>
+License: MIT License
+         
+         Copyright (c) 2026 Lucas Iannitello
+         
+         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.
+Requires-Dist: pydantic>=2.13.5
+Requires-Dist: typing-extensions>=4.16.0
+Requires-Dist: watchdog>=6.0.0
+Requires-Python: >=3.10
+Project-URL: Homepage, https://github.com/iannitello/syncwave
+Project-URL: Issues, https://github.com/iannitello/syncwave/issues
+Project-URL: Repository, https://github.com/iannitello/syncwave
+Description-Content-Type: text/markdown
+
+# Syncwave
+
+Turn plain JSON files into a live data store, two-way synced with your Python objects.
+
+## Documentation
+
+Read the docs at https://syncwave.dev/.
+
+A few useful links:
+
+- [Cheat Sheet](https://syncwave.dev/cheat_sheet/)
+- [Usage Guide](https://syncwave.dev/usage/syncwave/)
+- [API Reference](https://syncwave.dev/api/syncwave/)
+
+## Installation
+
+Install from [PyPI](https://pypi.org/project/syncwave/).
+
+```shell
+# uv
+uv add syncwave
+
+# pip
+pip install syncwave
+```
+
+## What Is Syncwave
+
+Syncwave keeps in-memory Python objects and JSON files synchronized, in both directions:
+
+- Change your data from Python (an `append`, a dict assignment, a model field update) and the JSON file is updated.
+- Edit the JSON file, by hand or from another process, and your Python objects are updated in place.
+- Every change, from either side, is validated with [Pydantic](https://pydantic.dev/docs/validation/latest/get-started/) against the store's declared type.
+
+You get persistence with _zero_ setup: no database to install, no ORM, no serialization code. Your data lives in JSON files you can open and edit at any time.
+
+If you know Python type hints and Pydantic models, you already know everything you need.
+
+Requires Python 3.10+.
+
+## Versioning
+
+Syncwave is under active development, and until version 1.0, new releases may introduce backward-incompatible changes.
+
+## License
+
+Syncwave is licensed under the MIT License.

syncwave-0.3.0/README.md

@@ -0,0 +1,47 @@
+# Syncwave
+
+Turn plain JSON files into a live data store, two-way synced with your Python objects.
+
+## Documentation
+
+Read the docs at https://syncwave.dev/.
+
+A few useful links:
+
+- [Cheat Sheet](https://syncwave.dev/cheat_sheet/)
+- [Usage Guide](https://syncwave.dev/usage/syncwave/)
+- [API Reference](https://syncwave.dev/api/syncwave/)
+
+## Installation
+
+Install from [PyPI](https://pypi.org/project/syncwave/).
+
+```shell
+# uv
+uv add syncwave
+
+# pip
+pip install syncwave
+```
+
+## What Is Syncwave
+
+Syncwave keeps in-memory Python objects and JSON files synchronized, in both directions:
+
+- Change your data from Python (an `append`, a dict assignment, a model field update) and the JSON file is updated.
+- Edit the JSON file, by hand or from another process, and your Python objects are updated in place.
+- Every change, from either side, is validated with [Pydantic](https://pydantic.dev/docs/validation/latest/get-started/) against the store's declared type.
+
+You get persistence with _zero_ setup: no database to install, no ORM, no serialization code. Your data lives in JSON files you can open and edit at any time.
+
+If you know Python type hints and Pydantic models, you already know everything you need.
+
+Requires Python 3.10+.
+
+## Versioning
+
+Syncwave is under active development, and until version 1.0, new releases may introduce backward-incompatible changes.
+
+## License
+
+Syncwave is licensed under the MIT License.

syncwave-0.3.0/pyproject.toml

@@ -0,0 +1,97 @@
+[project]
+name = "syncwave"
+version = "0.3.0"
+description = "Turn plain JSON files into a live data store, two-way synced with your Python objects."
+readme = "README.md"
+authors = [
+    { name = "Lucas Iannitello", email = "lucas.iannitello@protonmail.com" },
+]
+requires-python = ">=3.10"
+dependencies = [
+    "pydantic>=2.13.5",
+    "typing-extensions>=4.16.0",
+    "watchdog>=6.0.0",
+]
+license = { file = "LICENSE" }
+keywords = []
+classifiers = []
+
+[project.urls]
+Homepage = "https://github.com/iannitello/syncwave"
+Issues = "https://github.com/iannitello/syncwave/issues"
+Repository = "https://github.com/iannitello/syncwave"
+
+[build-system]
+requires = ["uv_build>=0.8.4,<0.9.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "fastapi[standard]>=0.141.1",
+    "mkdocstrings-python>=2.0.8",
+    "ruff>=0.16.8",
+    "ty>=0.0.82",
+    "zensical>=0.0.62",
+]
+
+[tool.uv]
+exclude-newer = "28 days"
+
+[tool.ruff.format]
+preview = true
+docstring-code-format = true
+
+[tool.ruff.lint]
+preview = true
+select = [
+    "E",   # pycodestyle errors
+    "F",   # pyflakes
+    "I",   # isort
+    "D",   # pydocstyle
+    "A",   # flake8-builtins
+    "B",   # flake8-bugbear
+    "C4",  # flake8-comprehensions
+    "ANN", # flake8-annotations
+    "FBT", # flake8-boolean-trap
+    "ICN", # flake8-import-conventions
+    "PYI", # flake8-pyi
+    "SIM", # flake8-simplify
+    "RUF", # ruff
+    "UP",  # pyupgrade
+]
+extend-select = [
+    "non-imperative-mood",                   # D401
+    "docstring-starts-with-this",            # D404
+    "missing-blank-line-after-last-section", # D413
+]
+ignore = [
+    "undocumented-magic-method", # D105
+    "any-type",                  # ANN401
+]
+unfixable = [
+    "unused-import", # F401
+]
+pydocstyle = { convention = "google" }
+
+[tool.ruff.lint.per-file-ignores]
+"__init__.py" = [
+    "missing-required-import",      # I002
+    "missing-terminal-punctuation", # D415
+]
+"!src/**.py" = ["D"]
+"!src/__init__.py" = [
+    "undocumented-public-module", # D100
+]
+
+[tool.ruff.lint.isort]
+required-imports = ["from __future__ import annotations"]
+extra-standard-library = ["typing_extensions"]
+known-third-party = ["fastapi", "pydantic", "syncwave"]
+combine-as-imports = true
+
+[tool.ruff.lint.flake8-import-conventions]
+banned-from = ["os"]
+
+[tool.ruff.lint.flake8-import-conventions.extend-aliases]
+"collections.abc.Callable" = "F"
+"pydantic.dataclasses.dataclass" = "py_dataclass"

syncwave-0.3.0/src/syncwave/__init__.py

@@ -0,0 +1,43 @@
+"""Syncwave 🌊
+
+Turn plain JSON files into a live data store, two-way synced with your Python objects.
+
+Imports available from this module:
+
+- [Syncwave](https://syncwave.dev/api/syncwave/#syncwave.Syncwave)
+- [SyncCollection](https://syncwave.dev/api/sync_collections/#syncwave.SyncCollection)
+- [SyncDict](https://syncwave.dev/api/sync_collections/#syncwave.SyncDict)
+- [SyncList](https://syncwave.dev/api/sync_collections/#syncwave.SyncList)
+- [SyncSet](https://syncwave.dev/api/sync_collections/#syncwave.SyncSet)
+- [SyncModel](https://syncwave.dev/api/sync_model/#syncwave.SyncModel)
+- [SyncRoot](https://syncwave.dev/api/sync_model/#syncwave.SyncRoot)
+- [sync_dataclass](https://syncwave.dev/api/sync_model/#syncwave.sync_dataclass)
+- [is_sync_dataclass](https://syncwave.dev/api/sync_model/#syncwave.is_sync_dataclass)
+- [SyncState](https://syncwave.dev/api/reactive/#syncwave.SyncState)
+- [Reactive](https://syncwave.dev/api/reactive/#syncwave.Reactive)
+- [DeadReferenceError](https://syncwave.dev/api/errors/#syncwave.DeadReferenceError)
+"""
+
+__version__ = "0.3.0"
+
+
+from .errors import DeadReferenceError
+from .reactive import Reactive, SyncState
+from .sync_collection import SyncCollection, SyncDict, SyncList, SyncSet
+from .sync_model import SyncModel, SyncRoot, is_sync_dataclass, sync_dataclass
+from .syncwave import Syncwave
+
+__all__ = [
+    "DeadReferenceError",
+    "Reactive",
+    "SyncCollection",
+    "SyncDict",
+    "SyncList",
+    "SyncModel",
+    "SyncRoot",
+    "SyncSet",
+    "SyncState",
+    "Syncwave",
+    "is_sync_dataclass",
+    "sync_dataclass",
+]

syncwave-0.3.0/src/syncwave/errors.py

@@ -0,0 +1,62 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, NoReturn
+
+__all__ = ["DeadReferenceError"]
+
+
+if TYPE_CHECKING:
+    from .reactive import ReactiveLike
+
+
+class DeadReferenceError(RuntimeError):
+    """Raised when an operation is attempted on a dead reactive object.
+
+    A reactive object dies when it's removed from its store, e.g. when its key or the
+    whole store is deleted. Check `sync_live` to know if an object is still usable.
+
+    Example:
+    ```python
+    from syncwave import DeadReferenceError, SyncModel, Syncwave
+
+    syncwave = Syncwave()
+
+
+    @syncwave.store(name="customers")
+    class Customer(SyncModel):
+        name: str
+        age: int
+
+
+    customers = syncwave["customers"]
+    customers.append({"name": "Alice", "age": 30})
+    alice = customers[0]
+    del customers[0]
+
+    try:
+        alice.age = 31
+    except DeadReferenceError as e:
+        print(e)
+    ```
+
+    ---
+
+    Abstract: Usage Documentation
+        [Lifecycle](https://syncwave.dev/usage/reactivity/#lifecycle-and-syncstate)
+
+    """
+
+    def __init__(self, *, reference: ReactiveLike) -> None:  # ruff: ignore[undocumented-public-init]
+        message = f"Operation attempted on a dead reference: {reference!r}"
+        super().__init__(message)
+
+
+class _InternalError(RuntimeError): ...
+
+
+def unreachable(detail: str = "", /, *, from_: Exception | None = None) -> NoReturn:
+    message = (detail or "Unreachable code was reached.") + "\n\n"
+    message += "This is a bug in Syncwave, please report it at https://github.com/iannitello/syncwave/issues."
+    if from_ is not None:
+        raise _InternalError(message) from from_
+    raise _InternalError(message)

{syncwave-0.2.0 → syncwave-0.3.0}/src/syncwave/io.py

@@ -2,22 +2,32 @@ from __future__ import annotations
 
 import contextlib
 import os
+from dataclasses import dataclass
 from pathlib import Path
 from tempfile import TemporaryDirectory, mkstemp
 from threading import Lock, Timer
 from typing import Any, Final
 
 from pydantic import TypeAdapter, ValidationError
+from pydantic_core import PydanticSerializationError
 
+from .errors import unreachable
 from .watcher import watcher
 
-PendingWrite = tuple[Any, TypeAdapter, Timer]
+__all__ = []
 
 
-class EmptyFileType: ...
+@dataclass(frozen=True)
+class PendingWrite:
+    value: Any
+    ta: TypeAdapter
+    timer: Timer
 
 
-EmptyFile: Final = EmptyFileType()
+class Void: ...
+
+
+void: Final = Void()
 
 
 class _IO:
@@ -74,46 +84,82 @@ class _IO:
     def remove_file(self, path: Path) -> None:
         if path.exists() and not path.is_file():
             raise OSError(f"Path '{path}' exists but is not a regular file.")
-        path.unlink(missing_ok=True)
+        with self._lock:
+            if path in self._pending_writes:
+                self._pending_writes.pop(path).timer.cancel()
+            path.unlink(missing_ok=True)
+
+    def init_json(
+        self,
+        path: Path,
+        ta: TypeAdapter = _any_ta,
+        default: Any | Void = void,
+    ) -> Any | Void:
 
-    def init_json(self, path: Path, ta: TypeAdapter = _any_ta) -> Any | EmptyFileType:
+        created = not path.exists()
         self.create_file(path)
         content = path.read_text(encoding=self.ENCODING).strip()
-        if content == "":
-            default = self._get_default(ta)
-            if default is not EmptyFile:
-                self._atomic_write(path, self._serialize(default, ta))
-            return default
-        init_value = self._deserialize(content, ta, path)
-        self._atomic_write(path, self._serialize(init_value, ta))
-        return init_value
-
-    def read_json(self, path: Path, ta: TypeAdapter = _any_ta) -> Any:
+        if content:
+            value = self._deserialize(content, ta, path)
+        else:
+            value = default if default is not void else self._get_default(ta)
+            if value is void:
+                if created:
+                    path.unlink()
+                return void
+        self._atomic_write(path, self._serialize(value, ta))
+        return value
+
+    def load(self, path: Path, ta: TypeAdapter = _any_ta) -> Any:
         # never returns EmptyFile, it throws an error if the file is empty
         with self._lock:
             if path in self._pending_writes:
-                value, previous_ta, _ = self._pending_writes[path]
-                if previous_ta is ta:
-                    return value
-                text = self._serialize(value, previous_ta)
+                pending = self._pending_writes[path]
+                if pending.ta is ta:
+                    return pending.value
+                text = self._serialize(pending.value, pending.ta)
                 return self._deserialize(text, ta, path)
-        text = path.read_text(encoding=self.ENCODING).strip()
+        text = path.read_text(encoding=self.ENCODING)
         return self._deserialize(text, ta, path)
 
-    def write_json(self, path: Path, value: Any, ta: TypeAdapter = _any_ta) -> None:
+    def dump(self, path: Path, value: Any, ta: TypeAdapter = _any_ta) -> None:
         with self._lock:
             if path in self._pending_writes:
-                self._pending_writes[path][2].cancel()
+                self._pending_writes[path].timer.cancel()
             timer = Timer(self.DEBOUNCE_WINDOW, self._scheduled_write, args=(path,))
-            self._pending_writes[path] = (value, ta, timer)
+            self._pending_writes[path] = PendingWrite(value, ta, timer)
             timer.start()
 
+    def read_json(self, path: Path) -> str:
+        with self._lock:
+            if path in self._pending_writes:
+                pending = self._pending_writes[path]
+                return self._serialize(pending.value, pending.ta)
+        return path.read_text(encoding=self.ENCODING)
+
+    def write_json(self, path: Path, text: str) -> None:
+        with self._lock:
+            if path in self._pending_writes:
+                self._pending_writes.pop(path).timer.cancel()
+        self._atomic_write(path, text)
+
     def _scheduled_write(self, path: Path) -> None:
         with self._lock:
-            if path not in self._pending_writes:
-                return  # defensive check, should never happen
-            value, ta, _ = self._pending_writes.pop(path)
-        self._atomic_write(path, self._serialize(value, ta))
+            # `cancel()` is best effort: this could run with a missing pending write.
+            try:
+                pending = self._pending_writes.pop(path)
+            except KeyError:
+                return  # A newer `dump` or `write_json` has taken over, nothing to do.
+
+        # Only guarded `_serialize`: runs on a timer thread (the traceback is useless).
+        try:
+            text = self._serialize(pending.value, pending.ta)
+        except PydanticSerializationError as e:
+            # Failing here is a bug. The value comes from a store, it should serialize.
+            err = f"An invalid value reached the store associated with file '{path}'."
+            unreachable(err, from_=e)
+
+        self._atomic_write(path, text)
 
     def _atomic_write(self, path: Path, text: str) -> None:
         fd, tmp_path = mkstemp(prefix=watcher.TMP_FILE_PREFIX, dir=path.parent)
@@ -127,7 +173,6 @@ class _IO:
             # Atomically replace the target file
             watcher.mark_self_write(path)
             os.replace(tmp_path, path)
-            # print(f"Wrote JSON to {path}")
 
         except Exception as e:
             # Attempt to remove temporary file on error
@@ -143,22 +188,30 @@ class _IO:
 
     def _deserialize(self, text: str, ta: TypeAdapter, path: Path) -> Any:
         try:
-            return ta.validate_json(text)
+            value = ta.validate_json(text)
         except ValidationError as e:
             try:
                 self._any_ta.validate_json(text)
             except ValidationError:
                 raise ValueError(f"File '{path}' contains malformed JSON.") from None
             raise ValueError(f"File '{path}' contains unexpected data type.") from e
+        # Validate_json can succeed while dump_json fails, e.g. in case of an invalid
+        # default_factory or a validator/serializer mismatch.
+        try:
+            ta.dump_json(value, warnings="error")
+        except PydanticSerializationError as e:
+            err = f"The store associated with file '{path}' cannot be serialized."
+            raise ValueError(err) from e
+        return value
 
-    def _get_default(self, ta: TypeAdapter) -> Any | EmptyFileType:
+    def _get_default(self, ta: TypeAdapter) -> Any | Void:
         defaults = [{}, [], "", None]
         for default in defaults:
             try:
                 return ta.validate_python(default)
             except ValidationError:
                 continue
-        return EmptyFile
+        return void
 
 
 io = _IO()

syncwave-0.3.0/src/syncwave/ownership.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from typing import Any, Final
+
+from pydantic import TypeAdapter
+
+from .reactive import is_reactive
+
+__all__ = []
+
+
+_IMMUTABLE_TYPES: Final = (int, float, bool, str, bytes, type(None))
+
+
+def detach(value: Any, ta: TypeAdapter) -> Any:
+    if type(value) in _IMMUTABLE_TYPES or is_reactive(value):
+        return value
+    return ta.validate_json(ta.dump_json(value))
+
+
+def ingest(value: Any, ta: TypeAdapter) -> Any:
+    # Implicitly guards against dead references: all reactive values run `dead_guard`.
+    validated = ta.validate_python(value)
+
+    # Must run before the immutable fast path: a type inconsistent with its validator,
+    # e.g. `Annotated[int, AfterValidator(str)]`, yields an immutable `str`.
+    json = ta.dump_json(validated, warnings="error")
+
+    if type(validated) in _IMMUTABLE_TYPES:
+        return validated
+    return ta.validate_json(json)