syncwave 0.1.4__tar.gz → 0.2.0__tar.gz

syncwave-0.2.0/PKG-INFO

@@ -0,0 +1,220 @@
+Metadata-Version: 2.3
+Name: syncwave
+Version: 0.2.0
+Summary: Make your code reactive; Turn plain JSONs into a live data store, two-way synced with Python objects.
+Keywords: 
+Author: Lucas Iannitello
+Author-email: Lucas Iannitello <lucas.iannitello@protonmail.com>
+License: MIT License
+         
+         Copyright (c) 2025 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.12.5
+Requires-Dist: typing-extensions>=4.15.0
+Requires-Dist: watchdog>=6.0.0
+Requires-Python: >=3.9
+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
+
+Make your code reactive; Turn plain JSONs into a live data store, two-way synced with Python objects.
+
+> ⚠️ **Warning**
+>
+> Syncwave is under active development. Until version **1.0**, any minor release (`0.x`) may introduce breaking changes. Pin the exact version in production.
+>
+> Version **1.0** will be released when the library is stable, feature-complete, and tested.
+
+## Installation
+
+Install from [PyPI](https://pypi.org/project/syncwave/).
+
+```shell
+# pip
+pip install syncwave
+
+# uv
+uv add syncwave
+```
+
+Requires Python 3.9+.
+
+## Quick Start
+
+Bind in-memory data to a JSON file with `@syncwave.register`. _Syncwave_ automatically synchronizes the file with your in-memory objects.
+
+```python
+from pydantic import BaseModel
+
+from syncwave import Syncwave
+
+syncwave = Syncwave()
+
+
+# Register a model — creates `syncstores/customers.json` automatically.
+# If the file already exists, its data is loaded into the store.
+@syncwave.register(name="customers")
+class Customer(BaseModel):
+    key: int
+    name: str
+    age: int
+
+
+customers = syncwave["customers"]
+
+# Add entries — dicts and model instances both work.
+customers[1] = {"key": 1, "name": "John Doe", "age": 30}
+customers[2] = Customer(key=2, name="Jane Doe", age=25)
+
+# Grab a reference and mutate — changes are written to disk automatically.
+john = customers[1]
+john.age = 31  # syncstores/customers.json is updated
+
+# The store is a dict-like object that can be printed.
+print(customers)  # {1: key=1 name='John Doe' age=31, 2: key=2 name='Jane Doe' age=25}
+print(syncwave)  # {'customers': ...}
+
+# Delete an entry.
+del customers[1]  # removed from memory and from the file
+
+# External edits propagate back.
+input("Go edit syncstores/customers.json, then press Enter... ")
+print(customers)  # reflects the external changes
+```
+
+## The Reactive System
+
+See [`docs/reactivity.md`](docs/reactivity.md).
+
+## API Reference
+
+### `Syncwave`
+
+The entry point. A `MutableMapping[str, Any]` where each key is a store name and each value is the store's data (which may or may not be reactive). Each store maps to a single JSON file.
+
+```python
+from syncwave import Syncwave
+
+syncwave = Syncwave(root_path="data")
+```
+
+- `root_path` (optional): Directory for JSON files. Defaults to `./syncstores`.
+- `syncwave.root_path`: Read-only property returning the resolved path.
+
+**Methods:**
+
+- `syncwave.create_store(tp, *, name, default)` — Creates a store for a given type. The type can be anything supported by Pydantic, including reactive types. Creates or loads the associated JSON file. A `default` is required when the file is empty and the type has no natural empty form (e.g., `int`).
+- `syncwave.make_reactive(cls, *, cls_name)` — Turns a Pydantic model into a `SyncModel` class.
+- `@syncwave.register(*, name, collection)` — Class decorator that makes a model reactive and creates a store for it in one step. See [Collection Wrapping](#collection-wrapping) below.
+
+Standard `MutableMapping` operations are supported: `syncwave[name]`, `syncwave[name] = value`, `del syncwave[name]`, `len(syncwave)`, iteration, etc.
+
+### `SyncDict`, `SyncList`, `SyncSet`
+
+Reactive counterparts of `dict`, `list`, and `set`. They behave like their standard equivalents (`MutableMapping`, `MutableSequence`, `MutableSet`) but every mutation is validated by Pydantic, persisted to disk, and propagated from disk.
+
+They are parameterized like their standard counterparts:
+
+```python
+from syncwave import SyncDict, SyncList, SyncSet
+
+syncwave.create_store(SyncDict[str, int], name="settings")
+syncwave.create_store(SyncList[str], name="tags")
+syncwave.create_store(SyncSet[int], name="ids")
+```
+
+Reactive collections can be nested: `SyncDict[str, SyncList[int]]`, `SyncList[SyncDict[str, str]]`, etc. `SyncSet` cannot hold reactive items (since reactive objects are mutable and therefore not hashable).
+
+`SyncCollection` is the abstract base for all three — useful for `isinstance` checks.
+
+### `SyncModel`
+
+A user-defined Pydantic model that Syncwave has made reactive. Attribute access and assignment are intercepted to keep the data in sync.
+
+Created via `syncwave.make_reactive` or `@syncwave.register`. The supported model types are:
+
+1. subclasses of `pydantic.BaseModel`,
+2. subclasses of `pydantic.RootModel`,
+3. classes decorated with `@pydantic.dataclasses.dataclass`.
+
+`@syncwave.register` returns the **original class**, not the `SyncModel`. You can keep using it normally — Syncwave handles the reactive wrapping internally.
+
+### `Reactive`
+
+Abstract base class that all reactive types inherit from. Provides the `sync_live` property, which is `True` while the object is connected to a store and `False` after it has been killed (e.g., by deleting the store or replacing the entry). Operations on a dead reference raise `DeadReferenceError`.
+
+```python
+from syncwave import Reactive
+
+ref = syncwave["customers"][1]
+isinstance(ref, Reactive)  # True
+ref.sync_live               # True
+
+del syncwave["customers"][1]
+ref.sync_live               # False
+```
+
+### `is_sync_model_supported`
+
+Type guard that returns `True` if a class can be made reactive (i.e., it is a `BaseModel`, `RootModel`, or Pydantic dataclass, and is not already a `SyncModel`).
+
+```python
+from syncwave import is_sync_model_supported
+
+is_sync_model_supported(Customer)  # True
+is_sync_model_supported(int)       # False
+```
+
+## Collection Wrapping
+
+When using `@syncwave.register`, the `collection` parameter controls how the model is stored:
+
+| Model shape             | Wrapping                      | Access pattern              |
+| ----------------------- | ----------------------------- | --------------------------- |
+| Has a `key` field       | `SyncDict[<key type>, Model]` | `store[key]`                |
+| No `key` field          | `SyncList[Model]`             | `store[index]`              |
+| Subclass of `RootModel` | No wrapping                   | `syncwave["name"]` directly |
+
+This is the default `collection="auto"` behavior. You can override it:
+
+```python
+from syncwave import SyncList
+
+
+# Force a list even though the model has a `key` field.
+@syncwave.register(name="items", collection=SyncList)
+class Item(BaseModel):
+    key: int  # ignored
+    name: str
+
+
+# No wrapping — the store holds a single model instance.
+@syncwave.register(name="config", collection=None)
+class Config(BaseModel):
+    theme: str
+    debug: bool
+```
+
+## License
+
+Syncwave is licensed under the MIT License.

syncwave-0.2.0/README.md

@@ -0,0 +1,183 @@
+# Syncwave
+
+Make your code reactive; Turn plain JSONs into a live data store, two-way synced with Python objects.
+
+> ⚠️ **Warning**
+>
+> Syncwave is under active development. Until version **1.0**, any minor release (`0.x`) may introduce breaking changes. Pin the exact version in production.
+>
+> Version **1.0** will be released when the library is stable, feature-complete, and tested.
+
+## Installation
+
+Install from [PyPI](https://pypi.org/project/syncwave/).
+
+```shell
+# pip
+pip install syncwave
+
+# uv
+uv add syncwave
+```
+
+Requires Python 3.9+.
+
+## Quick Start
+
+Bind in-memory data to a JSON file with `@syncwave.register`. _Syncwave_ automatically synchronizes the file with your in-memory objects.
+
+```python
+from pydantic import BaseModel
+
+from syncwave import Syncwave
+
+syncwave = Syncwave()
+
+
+# Register a model — creates `syncstores/customers.json` automatically.
+# If the file already exists, its data is loaded into the store.
+@syncwave.register(name="customers")
+class Customer(BaseModel):
+    key: int
+    name: str
+    age: int
+
+
+customers = syncwave["customers"]
+
+# Add entries — dicts and model instances both work.
+customers[1] = {"key": 1, "name": "John Doe", "age": 30}
+customers[2] = Customer(key=2, name="Jane Doe", age=25)
+
+# Grab a reference and mutate — changes are written to disk automatically.
+john = customers[1]
+john.age = 31  # syncstores/customers.json is updated
+
+# The store is a dict-like object that can be printed.
+print(customers)  # {1: key=1 name='John Doe' age=31, 2: key=2 name='Jane Doe' age=25}
+print(syncwave)  # {'customers': ...}
+
+# Delete an entry.
+del customers[1]  # removed from memory and from the file
+
+# External edits propagate back.
+input("Go edit syncstores/customers.json, then press Enter... ")
+print(customers)  # reflects the external changes
+```
+
+## The Reactive System
+
+See [`docs/reactivity.md`](docs/reactivity.md).
+
+## API Reference
+
+### `Syncwave`
+
+The entry point. A `MutableMapping[str, Any]` where each key is a store name and each value is the store's data (which may or may not be reactive). Each store maps to a single JSON file.
+
+```python
+from syncwave import Syncwave
+
+syncwave = Syncwave(root_path="data")
+```
+
+- `root_path` (optional): Directory for JSON files. Defaults to `./syncstores`.
+- `syncwave.root_path`: Read-only property returning the resolved path.
+
+**Methods:**
+
+- `syncwave.create_store(tp, *, name, default)` — Creates a store for a given type. The type can be anything supported by Pydantic, including reactive types. Creates or loads the associated JSON file. A `default` is required when the file is empty and the type has no natural empty form (e.g., `int`).
+- `syncwave.make_reactive(cls, *, cls_name)` — Turns a Pydantic model into a `SyncModel` class.
+- `@syncwave.register(*, name, collection)` — Class decorator that makes a model reactive and creates a store for it in one step. See [Collection Wrapping](#collection-wrapping) below.
+
+Standard `MutableMapping` operations are supported: `syncwave[name]`, `syncwave[name] = value`, `del syncwave[name]`, `len(syncwave)`, iteration, etc.
+
+### `SyncDict`, `SyncList`, `SyncSet`
+
+Reactive counterparts of `dict`, `list`, and `set`. They behave like their standard equivalents (`MutableMapping`, `MutableSequence`, `MutableSet`) but every mutation is validated by Pydantic, persisted to disk, and propagated from disk.
+
+They are parameterized like their standard counterparts:
+
+```python
+from syncwave import SyncDict, SyncList, SyncSet
+
+syncwave.create_store(SyncDict[str, int], name="settings")
+syncwave.create_store(SyncList[str], name="tags")
+syncwave.create_store(SyncSet[int], name="ids")
+```
+
+Reactive collections can be nested: `SyncDict[str, SyncList[int]]`, `SyncList[SyncDict[str, str]]`, etc. `SyncSet` cannot hold reactive items (since reactive objects are mutable and therefore not hashable).
+
+`SyncCollection` is the abstract base for all three — useful for `isinstance` checks.
+
+### `SyncModel`
+
+A user-defined Pydantic model that Syncwave has made reactive. Attribute access and assignment are intercepted to keep the data in sync.
+
+Created via `syncwave.make_reactive` or `@syncwave.register`. The supported model types are:
+
+1. subclasses of `pydantic.BaseModel`,
+2. subclasses of `pydantic.RootModel`,
+3. classes decorated with `@pydantic.dataclasses.dataclass`.
+
+`@syncwave.register` returns the **original class**, not the `SyncModel`. You can keep using it normally — Syncwave handles the reactive wrapping internally.
+
+### `Reactive`
+
+Abstract base class that all reactive types inherit from. Provides the `sync_live` property, which is `True` while the object is connected to a store and `False` after it has been killed (e.g., by deleting the store or replacing the entry). Operations on a dead reference raise `DeadReferenceError`.
+
+```python
+from syncwave import Reactive
+
+ref = syncwave["customers"][1]
+isinstance(ref, Reactive)  # True
+ref.sync_live               # True
+
+del syncwave["customers"][1]
+ref.sync_live               # False
+```
+
+### `is_sync_model_supported`
+
+Type guard that returns `True` if a class can be made reactive (i.e., it is a `BaseModel`, `RootModel`, or Pydantic dataclass, and is not already a `SyncModel`).
+
+```python
+from syncwave import is_sync_model_supported
+
+is_sync_model_supported(Customer)  # True
+is_sync_model_supported(int)       # False
+```
+
+## Collection Wrapping
+
+When using `@syncwave.register`, the `collection` parameter controls how the model is stored:
+
+| Model shape             | Wrapping                      | Access pattern              |
+| ----------------------- | ----------------------------- | --------------------------- |
+| Has a `key` field       | `SyncDict[<key type>, Model]` | `store[key]`                |
+| No `key` field          | `SyncList[Model]`             | `store[index]`              |
+| Subclass of `RootModel` | No wrapping                   | `syncwave["name"]` directly |
+
+This is the default `collection="auto"` behavior. You can override it:
+
+```python
+from syncwave import SyncList
+
+
+# Force a list even though the model has a `key` field.
+@syncwave.register(name="items", collection=SyncList)
+class Item(BaseModel):
+    key: int  # ignored
+    name: str
+
+
+# No wrapping — the store holds a single model instance.
+@syncwave.register(name="config", collection=None)
+class Config(BaseModel):
+    theme: str
+    debug: bool
+```
+
+## License
+
+Syncwave is licensed under the MIT License.

{syncwave-0.1.4 → syncwave-0.2.0}/pyproject.toml

@@ -1,12 +1,13 @@
 [project]
 name = "syncwave"
-version = "0.1.4"
+version = "0.2.0"
 description = "Make your code reactive; Turn plain JSONs into a live data store, two-way synced with Python objects."
 readme = "README.md"
 authors = [{ name = "Lucas Iannitello", email = "lucas.iannitello@protonmail.com" }]
 requires-python = ">=3.9"
 dependencies = [
-    "pydantic>=2.11.7",
+    "pydantic>=2.12.5",
+    "typing-extensions>=4.15.0",
     "watchdog>=6.0.0",
 ]
 license = { file = "LICENSE" }
@@ -24,22 +25,29 @@ build-backend = "uv_build"
 
 [dependency-groups]
 dev = [
-    "ruff>=0.12.9",
+    "fastapi[standard]>=0.128.8",
+    "ruff>=0.15.4",
+    "ty>=0.0.20",
 ]
 
 [tool.ruff.lint]
 select = [
-    "E",  # pycodestyle errors
-    "F",  # pyflakes
-    "I",  # isort
-    "B",  # flake8-bugbear
-    "C4",  # flake8-comprehensions
+    "E",    # pycodestyle errors
+    "F",    # pyflakes
+    "I",    # isort
+    "B",    # flake8-bugbear
+    "C4",   # flake8-comprehensions
     "SIM",  # flake8-simplify
     "ANN",  # flake8-annotations
     "RUF",  # ruff
-    "UP",  # pyupgrade
+    "UP",   # pyupgrade
 ]
 
+ignore = [
+    "ANN401"
+]
+
+
 unfixable = [
     "F401"  # disable fix for unused imports
 ]
@@ -49,3 +57,4 @@ unfixable = [
 
 [tool.ruff.lint.isort]
 required-imports = ["from __future__ import annotations"]
+extra-standard-library = ["typing_extensions"]

syncwave-0.2.0/src/syncwave/__init__.py

@@ -0,0 +1,18 @@
+__version__ = "0.2.0"
+
+
+from .reactive import Reactive
+from .sync_collection import SyncCollection, SyncDict, SyncList, SyncSet
+from .sync_model import SyncModel, is_sync_model_supported
+from .syncwave import Syncwave
+
+__all__ = [
+    "Reactive",
+    "SyncCollection",
+    "SyncDict",
+    "SyncList",
+    "SyncModel",
+    "SyncSet",
+    "Syncwave",
+    "is_sync_model_supported",
+]

syncwave-0.2.0/src/syncwave/io.py

@@ -0,0 +1,164 @@
+from __future__ import annotations
+
+import contextlib
+import os
+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 .watcher import watcher
+
+PendingWrite = tuple[Any, TypeAdapter, Timer]
+
+
+class EmptyFileType: ...
+
+
+EmptyFile: Final = EmptyFileType()
+
+
+class _IO:
+    ENCODING: Final[str] = "utf-8"
+    DUMPS_CONFIG: Final[dict[str, Any]] = {"indent": 2, "warnings": "error"}
+    DEBOUNCE_WINDOW: Final[float] = 0.05
+
+    _any_ta = TypeAdapter(Any)
+
+    def __init__(self) -> None:
+        self._lock = Lock()
+        self._pending_writes: dict[Path, PendingWrite] = {}
+
+    def file_name_guard(self, name: str) -> None:
+        # assumes name is already validated to be a non-empty string
+        if os.sep in name or (os.altsep is not None and os.altsep in name):
+            sep = repr(os.sep) + (f" or {os.altsep!r}" if os.altsep is not None else "")
+            raise ValueError(f"File name cannot contain path separators ({sep}).")
+        if Path(name).is_absolute():
+            raise ValueError("File name cannot be an absolute path.")
+        try:
+            with TemporaryDirectory() as td:
+                (Path(td) / name).mkdir()
+        except OSError as e:
+            raise ValueError(f"File name {name!r} is not valid: {e.strerror}") from None
+
+    def sanitize_path(self, path: Path | str) -> Path:
+        path_str = os.fspath(path)
+        path_str = os.path.expandvars(path_str)
+        path_str = os.path.expanduser(path_str)
+        return Path(path_str).resolve()
+
+    def create_dir(self, path: Path) -> None:
+        if path.exists() and not path.is_dir():
+            raise FileExistsError(f"Path '{path}' exists and is not a directory.")
+        try:
+            path.mkdir(parents=True, exist_ok=True)
+        except PermissionError as e:
+            raise PermissionError(f"Permission denied to create dir '{path}'.") from e
+        except OSError as e:
+            raise OSError(f"Unable to create dir '{path}'.") from e
+
+    def create_file(self, path: Path) -> None:
+        self.create_dir(path.parent)
+        if path.exists() and not path.is_file():
+            raise FileExistsError(f"Path '{path}' exists and is not a file.")
+        try:
+            path.touch()
+        except PermissionError as e:
+            raise PermissionError(f"Permission denied to create file '{path}'.") from e
+        except OSError as e:
+            raise OSError(f"Unable to create file '{path}'.") from e
+
+    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)
+
+    def init_json(self, path: Path, ta: TypeAdapter = _any_ta) -> Any | EmptyFileType:
+        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:
+        # 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)
+                return self._deserialize(text, ta, path)
+        text = path.read_text(encoding=self.ENCODING).strip()
+        return self._deserialize(text, ta, path)
+
+    def write_json(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()
+            timer = Timer(self.DEBOUNCE_WINDOW, self._scheduled_write, args=(path,))
+            self._pending_writes[path] = (value, ta, timer)
+            timer.start()
+
+    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))
+
+    def _atomic_write(self, path: Path, text: str) -> None:
+        fd, tmp_path = mkstemp(prefix=watcher.TMP_FILE_PREFIX, dir=path.parent)
+        try:
+            with os.fdopen(fd, "w", encoding=self.ENCODING) as tmp_file:
+                tmp_file.write(text)
+                tmp_file.write("\n")
+                tmp_file.flush()
+                os.fsync(tmp_file.fileno())
+
+            # 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
+            with contextlib.suppress(OSError):
+                os.remove(tmp_path)
+            raise OSError(
+                f"Failed to write JSON to '{path}'. "
+                f"Temporary file '{tmp_path}' removed. Original error: {e}"
+            ) from e
+
+    def _serialize(self, value: Any, ta: TypeAdapter) -> str:
+        return ta.dump_json(value, **self.DUMPS_CONFIG).decode(self.ENCODING)
+
+    def _deserialize(self, text: str, ta: TypeAdapter, path: Path) -> Any:
+        try:
+            return 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
+
+    def _get_default(self, ta: TypeAdapter) -> Any | EmptyFileType:
+        defaults = [{}, [], "", None]
+        for default in defaults:
+            try:
+                return ta.validate_python(default)
+            except ValidationError:
+                continue
+        return EmptyFile
+
+
+io = _IO()