syncwave 0.2.0__tar.gz → 0.2.1__tar.gz

{syncwave-0.2.0 → syncwave-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: syncwave
-Version: 0.2.0
+Version: 0.2.1
 Summary: Make your code reactive; Turn plain JSONs into a live data store, two-way synced with Python objects.
 Keywords: 
 Author: Lucas Iannitello

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

@@ -1,6 +1,6 @@
 [project]
 name = "syncwave"
-version = "0.2.0"
+version = "0.2.1"
 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" }]
@@ -26,35 +26,47 @@ build-backend = "uv_build"
 [dependency-groups]
 dev = [
     "fastapi[standard]>=0.128.8",
+    "mkdocs-material>=9.7.5",
+    "mkdocstrings-python>=1.18.2",
     "ruff>=0.15.4",
     "ty>=0.0.20",
 ]
 
+[tool.ruff.format]
+docstring-code-format = true
+
 [tool.ruff.lint]
 select = [
     "E",    # pycodestyle errors
     "F",    # pyflakes
     "I",    # isort
+    "D",    # pydocstyle
+    "A",    # flake8-builtins
     "B",    # flake8-bugbear
     "C4",   # flake8-comprehensions
-    "SIM",  # flake8-simplify
     "ANN",  # flake8-annotations
+    "FBT",  # flake8-boolean-trap
+    "PYI",  # flake8-pyi
+    "SIM",  # flake8-simplify
     "RUF",  # ruff
     "UP",   # pyupgrade
 ]
-
+extend-select = ["D401","D404","D413"]
 ignore = [
-    "ANN401"
+    "D105",    # missing docstring in magic method
+    "ANN401",  # typing.Any disallowed
 ]
-
-
 unfixable = [
     "F401"  # disable fix for unused imports
 ]
+pydocstyle = { convention = "google" }
 
 [tool.ruff.lint.per-file-ignores]
 "__init__.py" = ["I002"]
+"!src/**.py" = ["D"]
+"!src/__init__.py" = ["D100"]
 
 [tool.ruff.lint.isort]
 required-imports = ["from __future__ import annotations"]
 extra-standard-library = ["typing_extensions"]
+known-third-party = ["fastapi", "pydantic", "syncwave"]

{syncwave-0.2.0 → syncwave-0.2.1}/src/syncwave/__init__.py

@@ -1,12 +1,15 @@
-__version__ = "0.2.0"
+"""Turn plain JSONs into live data stores, two-way synced with Python objects."""
 
+__version__ = "0.2.1"
 
-from .reactive import Reactive
+
+from .reactive import DeadReferenceError, Reactive
 from .sync_collection import SyncCollection, SyncDict, SyncList, SyncSet
 from .sync_model import SyncModel, is_sync_model_supported
 from .syncwave import Syncwave
 
 __all__ = [
+    "DeadReferenceError",
     "Reactive",
     "SyncCollection",
     "SyncDict",

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

@@ -11,6 +11,9 @@ from pydantic import TypeAdapter, ValidationError
 
 from .watcher import watcher
 
+__all__ = []
+
+
 PendingWrite = tuple[Any, TypeAdapter, Timer]
 
 
@@ -88,7 +91,7 @@ class _IO:
         self._atomic_write(path, self._serialize(init_value, ta))
         return init_value
 
-    def read_json(self, path: Path, ta: TypeAdapter = _any_ta) -> Any:
+    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:
@@ -97,10 +100,10 @@ class _IO:
                     return value
                 text = self._serialize(value, previous_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()
@@ -108,6 +111,20 @@ class _IO:
             self._pending_writes[path] = (value, ta, timer)
             timer.start()
 
+    def read_json(self, path: Path) -> str:
+        with self._lock:
+            if path in self._pending_writes:
+                value, ta, _ = self._pending_writes[path]
+                return self._serialize(value, 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:
+                _, _, timer = 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:
@@ -127,7 +144,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

syncwave-0.2.1/src/syncwave/reactive.py

@@ -0,0 +1,188 @@
+from __future__ import annotations
+
+from abc import ABCMeta, abstractmethod
+from dataclasses import dataclass
+from functools import wraps
+from threading import RLock
+from typing import Any, Callable, NoReturn, TypeVar, final
+from typing_extensions import ParamSpec
+
+__all__ = ["DeadReferenceError", "Reactive"]
+
+
+@dataclass(frozen=True)
+class StoreRef:
+    lock: RLock
+    on_change: Callable[[], None]
+
+
+@dataclass(frozen=True)
+class Context:
+    tp: type[Reactive]
+
+
+class ContextMap(dict[type["Reactive"], Context]): ...
+
+
+CtxSubCls = TypeVar("CtxSubCls", bound=Context)
+ReactiveSubCls = TypeVar("ReactiveSubCls", bound="Reactive")
+
+
+class Reactive(metaclass=ABCMeta):
+    """Base class shared by all reactive values in Syncwave.
+
+    All reactive types (`SyncDict`, `SyncList`, `SyncSet` and `SyncModel`) are
+    subclasses of `Reactive`. You will mainly encounter it for type checks:
+    `isinstance(value, Reactive)`.
+
+    A reactive object can become dead when the corresponding store entry is removed or
+    replaced. Once dead, `sync_live` returns `False` and any further operation raises
+    `DeadReferenceError`.
+
+    Example:
+    ```python
+    from syncwave import Reactive, SyncDict, Syncwave
+
+    syncwave = Syncwave()
+    sync_dict = syncwave.create_store(SyncDict[str, int], name="sync_dict")
+    print(isinstance(sync_dict, Reactive))  # True
+    print(issubclass(SyncDict, Reactive))  # True
+    ```
+
+    ---
+
+    Abstract: Usage Documentation
+        [Reactive](https://placeholder.dev/usage/syncwave/)
+
+    """
+
+    __syncwave_sref__: StoreRef
+    __syncwave_ctx__: Context
+    __syncwave_live__: bool
+
+    def __new__(cls, *args: Any, **kwargs: Any) -> NoReturn:  # noqa: D102
+        raise TypeError("Reactive types can never be instantiated directly.")
+
+    @final
+    @property
+    def sync_live(self) -> bool:
+        """Whether this reactive object is still connected to the store.
+
+        Returns `False` once the object has been removed or replaced in its parent
+        store, for example because a key was deleted from a `SyncDict`. After that, any
+        operation on the object raises `DeadReferenceError`.
+
+        Example:
+        ```python
+        from pydantic import BaseModel
+        from syncwave import Syncwave
+
+        syncwave = Syncwave()
+
+
+        @syncwave.register(name="customers")
+        class Customer(BaseModel):
+            name: str
+            age: int
+
+
+        customers = syncwave["customers"]
+        customers.append({"name": "Alice", "age": 30})
+        alice = customers[0]
+        print(alice.sync_live)  # True
+        del customers[0]
+        print(alice.sync_live)  # False
+        ```
+
+        ---
+
+        Abstract: Usage Documentation
+            [Reactive](https://placeholder.dev/usage/syncwave/)
+
+        """
+        return self.__syncwave_live__  # atomic, no need to lock
+
+    @abstractmethod
+    def __syncwave_init__(self, sref: StoreRef, ctx: CtxSubCls) -> None:
+        raise NotImplementedError
+
+    @abstractmethod
+    def __syncwave_kill__(self) -> None:
+        raise NotImplementedError
+
+    @abstractmethod
+    def __syncwave_update__(self, new: ReactiveSubCls) -> None:
+        raise NotImplementedError
+
+
+P = ParamSpec("P")
+R = TypeVar("R")
+
+
+def atomic(fn: Callable[P, R]) -> Callable[P, R]:
+    @wraps(fn)
+    def wrapper(self: Reactive, *args: P.args, **kwargs: P.kwargs) -> R:
+        with self.__syncwave_sref__.lock:
+            if not self.__syncwave_live__:
+                raise DeadReferenceError(reference=self)
+            return fn(self, *args, **kwargs)  # ty: ignore[invalid-argument-type]
+
+    return wrapper  # ty: ignore[invalid-return-type]
+
+
+def mut_atomic(fn: Callable[P, R]) -> Callable[P, None]:
+    @wraps(fn)
+    def wrapper(self: Reactive, *args: P.args, **kwargs: P.kwargs) -> None:
+        with self.__syncwave_sref__.lock:
+            if not self.__syncwave_live__:
+                raise DeadReferenceError(reference=self)
+            result = fn(self, *args, **kwargs)  # ty: ignore[invalid-argument-type]
+            if result is not None:
+                unreachable()
+            self.__syncwave_sref__.on_change()
+
+    return wrapper  # ty: ignore[invalid-return-type]
+
+
+class DeadReferenceError(RuntimeError):
+    """Raised when an operation is attempted on a dead reactive object.
+
+    A reactive object becomes dead when it is removed from the store, for example
+    by deleting a key from a `SyncDict` or by deleting the store entirely. Catching
+    this error is one way to check whether a reference is still valid, though
+    checking `sync_live` first is usually cleaner.
+
+    Example:
+    ```python
+    from pydantic import BaseModel
+    from syncwave import DeadReferenceError, Syncwave
+
+    syncwave = Syncwave()
+
+
+    @syncwave.register(name="customers")
+    class Customer(BaseModel):
+        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)
+    ```
+
+    """
+
+    def __init__(self, *, reference: Reactive) -> None:  # noqa: D107
+        message = f"Operation attempted on a dead reference: {reference!r}"
+        super().__init__(message)
+
+
+def unreachable() -> NoReturn:
+    raise RuntimeError("Internal Error")

{syncwave-0.2.0 → syncwave-0.2.1}/src/syncwave/sync_collection.py

@@ -34,12 +34,35 @@ from .reactive import (
     unreachable,
 )
 
+__all__ = ["SyncCollection", "SyncDict", "SyncList", "SyncSet"]
+
+
 KT = TypeVar("KT")
 VT = TypeVar("VT", bound=Union[Reactive, Any])
 
 
 @final
 class SyncCollection(Reactive):
+    """Virtual base class for Syncwave's reactive collection types.
+
+    The `SyncCollection` types are `SyncDict`, `SyncList`, and `SyncSet`.
+
+    `SyncCollection` itself cannot be instantiated or subclassed. Can be used for
+    `isinstance` and `issubclass` checks.
+
+    Example:
+    ```python
+    from syncwave import SyncCollection, SyncList, Syncwave
+
+    syncwave = Syncwave()
+    sync_list = syncwave.create_store(SyncList[int], name="sync_list")
+
+    print(isinstance(sync_list, SyncCollection))  # True
+    print(issubclass(SyncList, SyncCollection))  # True
+    ```
+
+    """
+
     def __init_subclass__(cls, /, **kwargs: Any) -> NoReturn:
         raise TypeError("SyncCollection cannot be subclassed.")
 
@@ -54,13 +77,45 @@ class SyncCollection(Reactive):
 
 
 @dataclass(frozen=True)
-class SyncDictCtx(Generic[KT, VT], Context):
+class SyncDictCtx(Context, Generic[KT, VT]):
     tp: type[SyncDict]
     inner_ctx: Context | ContextMap | None
     inner_type_adapter: TypeAdapter[VT]
 
 
 class SyncDict(MutableMapping[KT, VT], Reactive):
+    """A reactive dictionary.
+
+    `SyncDict` behaves like a regular `dict`. Assignments, updates, and deletions
+    trigger a write to the backing JSON file, and external changes to the file are
+    reflected in place.
+
+    References to reactive values are stable by key: a reference to `store["alice"]`
+    continues to represent whatever is stored under `"alice"` until that key is removed,
+    at which point `sync_live` is set to `False` and any further operation raises
+    `DeadReferenceError`.
+
+    Example:
+    ```python
+    from syncwave import SyncDict, Syncwave
+
+    syncwave = Syncwave()
+    sync_dict = syncwave.create_store(SyncDict[str, int], name="sync_dict")
+
+    sync_dict["a"] = 1
+    sync_dict["b"] = 2
+    sync_dict["c"] = 3
+    print(sync_dict)
+    print(list(sync_dict.items()))
+    ```
+
+    ---
+
+    Abstract: Usage Documentation
+        [SyncDict](https://placeholder.dev/usage/syncwave/)
+
+    """
+
     __syncwave_ctx__: SyncDictCtx[KT, VT]
     __data: dict[KT, VT]
 
@@ -221,13 +276,43 @@ class SyncDict(MutableMapping[KT, VT], Reactive):
 
 
 @dataclass(frozen=True)
-class SyncListCtx(Generic[VT], Context):
+class SyncListCtx(Context, Generic[VT]):
     tp: type[SyncList]
     inner_ctx: Context | ContextMap | None
     inner_type_adapter: TypeAdapter[VT]
 
 
 class SyncList(MutableSequence[VT], Reactive):
+    """A reactive list.
+
+    `SyncList` behaves like a regular `list`. Appending, replacing, inserting, and
+    deleting items trigger a write to the backing JSON file, and external changes to the
+    file are reflected in place.
+
+    When a `SyncList` holds reactive items, references are stable by position, not by
+    value. A reference to `store[0]` represents whatever is at index `0`. Inserting a
+    new element at the beginning shifts that reference to the new element, not to the
+    one that was there before.
+
+    Example:
+    ```python
+    from syncwave import SyncList, Syncwave
+
+    syncwave = Syncwave()
+    sync_list = syncwave.create_store(SyncList[int], name="sync_list")
+
+    sync_list.append(1)
+    sync_list.extend([2, 3])
+    print(sync_list)
+    ```
+
+    ---
+
+    Abstract: Usage Documentation
+        [SyncList](https://placeholder.dev/usage/syncwave/)
+
+    """
+
     __syncwave_ctx__: SyncListCtx[VT]
     __data: list[VT]
 
@@ -374,7 +459,7 @@ class SyncList(MutableSequence[VT], Reactive):
         return len(self.__data)
 
     @mut_atomic
-    def insert(self, index: SupportsIndex, value: VT) -> None:
+    def insert(self, index: SupportsIndex, value: VT) -> None:  # noqa: D102
         i = _get_index(index)
         inner_ctx = self.__syncwave_ctx__.inner_ctx
         new_item = self.__syncwave_ctx__.inner_type_adapter.validate_python(value)
@@ -426,13 +511,42 @@ def _get_index(index: Any) -> int:
 
 
 @dataclass(frozen=True)
-class SyncSetCtx(Generic[VT], Context):
+class SyncSetCtx(Context, Generic[VT]):
     tp: type[SyncSet]
     inner_ctx: None  # never holds reactive items
     inner_type_adapter: TypeAdapter[VT]
 
 
 class SyncSet(MutableSet[VT], Reactive):
+    """A reactive set.
+
+    `SyncSet` behaves like a regular `set`. Adding and discarding items trigger a write
+    to the backing JSON file, and external changes to the file are reflected in place.
+
+    `SyncSet` can only hold non-reactive, hashable values such as `str`, `int`, `UUID`,
+    etc. Reactive types like `SyncCollection` or `SyncModel` are mutable and therefore
+    not supported.
+
+    Example:
+    ```python
+    from syncwave import SyncSet, Syncwave
+
+    syncwave = Syncwave()
+    sync_set: SyncSet[int] = syncwave.create_store(SyncSet[int], name="sync_set")
+
+    sync_set.add(1)
+    sync_set.add(2)
+    sync_set.discard(2)
+    print(sync_set)
+    ```
+
+    ---
+
+    Abstract: Usage Documentation
+        [SyncSet](https://placeholder.dev/usage/syncwave/)
+
+    """
+
     # SyncSet cannot hold reactive items because a reactive item is mutable
     __syncwave_ctx__: SyncSetCtx[VT]
     __data: set[VT]
@@ -490,12 +604,12 @@ class SyncSet(MutableSet[VT], Reactive):
         return len(self.__data)
 
     @mut_atomic
-    def add(self, value: VT) -> None:
+    def add(self, value: VT) -> None:  # noqa: D102
         new_item = self.__syncwave_ctx__.inner_type_adapter.validate_python(value)
         self.__data.add(new_item)
 
     @mut_atomic
-    def discard(self, value: VT) -> None:
+    def discard(self, value: VT) -> None:  # noqa: D102
         if value in self.__data:
             self.__data.discard(value)
 

{syncwave-0.2.0 → syncwave-0.2.1}/src/syncwave/sync_model.py

@@ -38,8 +38,48 @@ if TYPE_CHECKING:
     #   3. classes decorated with `@pydantic.dataclasses.dataclass`.
     SMS = Union[BaseModel, RootModel, PydanticDataclass]
 
+__all__ = ["SyncModel", "is_sync_model_supported"]
+
 
 def is_sync_model_supported(cls: Any) -> TypeGuard[type[SMS]]:
+    """Return whether `cls` can be made into a `SyncModel`.
+
+    Supported classes are:
+
+    - subclasses of `pydantic.BaseModel`
+    - subclasses of `pydantic.RootModel`
+    - classes decorated with `pydantic.dataclasses.dataclass`
+
+    Standard-library dataclasses or plain Python classes are not supported.
+
+    Example:
+    ```python
+    from pydantic import BaseModel
+    from syncwave import is_sync_model_supported
+
+
+    class Customer(BaseModel):
+        name: str
+
+
+    is_sync_model_supported(Customer)  # True
+    is_sync_model_supported(dict)  # False
+    ```
+
+    ---
+
+    Abstract: Usage Documentation
+        [is_sync_model_supported](https://placeholder.dev/usage/syncwave/)
+
+    Args:
+        cls: Object to test.
+
+    Returns:
+        `True` if `cls` can be passed to [Syncwave.make_reactive](https://placeholder.dev/api/syncwave/#syncwave.Syncwave.make_reactive)
+            or used with [Syncwave.register](https://placeholder.dev/api/syncwave/#syncwave.Syncwave.register),
+            and False otherwise.
+
+    """
     if not isclass(cls):
         return False
     if issubclass(cls, SyncModel):
@@ -56,6 +96,46 @@ class SyncModelCtx(Context):
 
 
 class SyncModel(Reactive):
+    """Base class for reactive models.
+
+    Instances of `SyncModel` behave just like the original model: field access and
+    assignment work exactly the same way. The difference is that every field assignment
+    triggers a write to the backing JSON file, and external changes to the file are
+    reflected in the same object.
+
+    You will rarely interact with `SyncModel` directly. Instances appear when you access
+    reactive model values from a store, and `isinstance(value, SyncModel)` is the main
+    way to check for them.
+
+    Example:
+    ```python
+    from pydantic import BaseModel
+    from syncwave import SyncModel, Syncwave
+
+    syncwave = Syncwave()
+
+
+    @syncwave.register(name="customers")
+    class Customer(BaseModel):
+        name: str
+        age: int
+
+
+    customers = syncwave["customers"]
+    customers.append({"name": "Alice", "age": 30})
+    alice = customers[0]
+    isinstance(alice, SyncModel)  # True
+    alice.age = 31  # writes to customers.json immediately
+    print(alice)  # name='Alice' age=31
+    ```
+
+    ---
+
+    Abstract: Usage Documentation
+        [SyncModel](https://placeholder.dev/usage/syncwave/)
+
+    """
+
     __syncwave_ctx__: SyncModelCtx
     __syncwave_original_cls__: type[SMS]
 
@@ -220,7 +300,7 @@ class SyncModel(Reactive):
             o_setattr(self, f, n)
 
 
-def create_sync_model(cls: type[SMS], rename: bool | str = True) -> type[SyncModel]:
+def create_sync_model(cls: type[SMS], *, rename: bool | str = True) -> type[SyncModel]:
     cls_name = f"Sync{cls.__name__}" if rename is True else rename or cls.__name__
     return type(
         cls_name,