syncwave 0.1.1__tar.gz → 0.1.3__tar.gz

{syncwave-0.1.1 → syncwave-0.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: syncwave
-Version: 0.1.1
+Version: 0.1.3
 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.1.1 → syncwave-0.1.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "syncwave"
-version = "0.1.1"
+version = "0.1.3"
 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" }]
@@ -24,8 +24,12 @@ build-backend = "uv_build"
 
 [dependency-groups]
 dev = [
-    "ruff>=0.12.7",
+    "ruff>=0.12.9",
 ]
 
 [tool.ruff.lint]
-extend-select = ["E501"]
+select = ["E", "F"]
+
+unfixable = [
+    "F401"  # disable fix for unused imports
+]

{syncwave-0.1.1 → syncwave-0.1.3}/src/syncwave/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "0.1.0"
+__version__ = "0.1.3"
 
 
 from .syncwave import SyncStore, Syncwave

{syncwave-0.1.1 → syncwave-0.1.3}/src/syncwave/io.py

@@ -62,15 +62,13 @@ class _IO:
             timer.start()
 
     def _scheduled_write(self, path: Path, data_provider: DataProvider) -> None:
-        try:
-            self._atomic_write(path, data_provider())
-        finally:
-            with self._lock:
-                self._debounce_timers.pop(path, None)
-                self._pending_data_providers.pop(path, None)
+        with self._lock:
+            self._debounce_timers.pop(path, None)
+            self._pending_data_providers.pop(path, None)
+        self._atomic_write(path, data_provider())
 
     def _atomic_write(self, path: Path, data: JSONData) -> None:
-        fd, tmp_path = mkstemp(prefix=".tmp_", suffix=".json", dir=path.parent)
+        fd, tmp_path = mkstemp(prefix=watcher.TMP_FILE_PREFIX, dir=path.parent)
         try:
             with os.fdopen(fd, "w", encoding=self.ENCODING) as tmp_file:
                 json.dump(data, tmp_file, **self.DUMPS_CONFIG)
@@ -81,6 +79,7 @@ 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.1.1 → syncwave-0.1.3}/src/syncwave/syncwave.py

@@ -1,11 +1,11 @@
-import json
-import threading
 from collections.abc import Mapping
 from inspect import isclass
+from json import JSONDecodeError
 from pathlib import Path
-from typing import Any, Callable, Iterator, Optional, Type, Union, get_args
+from threading import RLock
+from typing import Any, Callable, Iterator, Optional, Type, Union, get_args, overload
 
-from pydantic import BaseModel, ValidationError
+from pydantic import BaseModel, ValidationError, create_model, model_validator
 
 from .io import io
 from .watcher import watcher
@@ -33,37 +33,44 @@ class SyncStore(Mapping[JSONKey, BaseModel]):
         self,
         syncwave: "Syncwave",
         cls: Type[BaseModel],
-        *,
+        /,
         name: Optional[str] = None,
-        key: str,
+        key: Optional[str] = None,
+        *,
         skip_key_validation: bool = False,
         file_name: Optional[str] = None,
         sub_dir: Optional[Union[Path, str]] = None,
         file_path: Optional[Union[Path, str]] = None,
+        new_cls_name: Optional[str] = None,
         # in_memory: bool = True,  # TODO: implement in_memory
     ) -> None:
         if not isinstance(syncwave, Syncwave):
-            raise ValueError("The syncwave argument must be an instance of Syncwave.")
+            raise TypeError("The first argument must be an instance of Syncwave.")
         if not (isclass(cls) and issubclass(cls, BaseModel)):
-            raise ValueError("Only subclasses of BaseModel can be used.")
+            raise TypeError("Only subclasses of Pydantic's BaseModel can be used.")
+        # `store.cls` is created with `create_model`, with `cls` as its only base class
+        # in other words, this checks that `cls` has not been registered already
+        if any(store.cls.__bases__[0] is cls for store in syncwave.values()):
+            raise ValueError(f"The class '{cls.__name__}' has already been registered.")
+        # `name` defaults to the lowercased class name if not provided
         if (name_ := name or cls.__name__.lower()) in syncwave:
-            raise ValueError(f"The name '{name_}' is already registered.")
-        if cls in [store.cls for store in syncwave.values()]:
-            raise ValueError(f"The class '{cls.__name__}' is already registered.")
-        if key not in cls.model_fields:
-            raise ValueError(f"'{cls.__name__}' does not have a field '{key}'.")
+            raise ValueError(f"The name '{name_}' has already been registered.")
+        if not cls.model_fields:
+            raise ValueError(f"Class '{cls.__name__}' has no fields defined.")
+        # `key` defaults to the first field in the model if not provided
+        if (key_ := key or next(iter(cls.model_fields))) not in cls.model_fields:
+            raise ValueError(f"'{cls.__name__}' does not have a field named '{key_}'.")
         if not skip_key_validation:
-            _validate_key_type(cls, key)
+            _validate_key_type(cls, key_)
 
         self.syncwave = syncwave
-        self.cls = cls
+        self.cls = self._patch_cls(cls, new_cls_name or f"Syncwave{cls.__name__}")
         self.name = name_
-        self.key = key
+        self.key = key_
         self.path = self._get_path(file_name or name_, sub_dir, file_path)
 
         self._ssd: dict[JSONKey, BaseModel] = {}  # actual mapping, ssd = SyncStoreDict
-        self._lock = threading.RLock()
-        self._patch_cls()
+        self._lock = RLock()
         io.init_json_file(self.path)
         self.load()
         watcher.watch(self.path, self.load)
@@ -75,7 +82,7 @@ class SyncStore(Mapping[JSONKey, BaseModel]):
 
     def __iter__(self) -> Iterator[JSONKey]:
         with self._lock:
-            # first, convert to a list so the iterator is over a frozen object
+            # first convert to a list so the iterator is over a frozen object
             return iter(list(self._ssd))
 
     def __len__(self) -> int:
@@ -91,10 +98,7 @@ class SyncStore(Mapping[JSONKey, BaseModel]):
 
     def to_dict(self) -> dict[JSONKey, dict[str, Any]]:
         with self._lock:
-            return {
-                key: model_instance.model_dump()
-                for key, model_instance in self._ssd.items()
-            }
+            return {key: instance.model_dump() for key, instance in self._ssd.items()}
 
     def delete(self, key: JSONKey) -> None:
         with self._lock:
@@ -111,9 +115,9 @@ class SyncStore(Mapping[JSONKey, BaseModel]):
                 # no JSONDecodeError or ValidationError at this point, safe to clear
                 self._ssd.clear()
                 self._ssd.update(tmp_ssd)
-        except (json.JSONDecodeError, ValidationError):
-            return
-        else:
+        except (FileNotFoundError, JSONDecodeError, ValidationError):
+            pass
+        finally:
             io.write_json(self.path, self.to_dict)
 
     def _get_path(
@@ -129,41 +133,53 @@ class SyncStore(Mapping[JSONKey, BaseModel]):
             return (self.syncwave.data_dir / sub_dir / file_name).resolve()
         return (self.syncwave.data_dir / file_name).resolve()
 
-    def _patch_cls(self) -> None:
-        # preserve original methods
-        original_init = self.cls.__init__
-        original_setattr = self.cls.__setattr__
-        original_delattr = self.cls.__delattr__
-
-        def __init__(model_instance: BaseModel, *args: Any, **kwargs: Any) -> None:
-            original_init(model_instance, *args, **kwargs)
-            key_value = getattr(model_instance, self.key)
+    def _patch_cls(self, cls: Type[BaseModel], new_cls_name: str) -> Type[BaseModel]:
+        # This is a validator that acts as a post-initialization hook.
+        # Using a validator instead of `__init__` ensures every instance is tracked.
+        # Libraries such as FastAPI may create instances indirectly with methods like
+        # `validate_python` or `model_validate` and `__init__` may never be called.
+        def init(self_model: BaseModel) -> BaseModel:
+            key_value = getattr(self_model, self.key)
             with self._lock:
-                self._ssd[key_value] = model_instance
+                if key_value in self._ssd and self._ssd[key_value] == self_model:
+                    return self_model  # no changes, no need to write
+                self._ssd[key_value] = self_model
             io.write_json(self.path, self.to_dict)
+            return self_model
+
+        new_cls = create_model(
+            new_cls_name,
+            __base__=cls,
+            __validators__={"__syncwave_init__": model_validator(mode="after")(init)},
+        )
 
-        def __setattr__(model_instance: BaseModel, attr: str, value: Any) -> None:
+        # preserve original methods
+        original_setattr = cls.__setattr__
+        original_delattr = cls.__delattr__
+
+        def __setattr__(self_model: BaseModel, attr: str, value: Any) -> None:
             # TODO check for edge cases
-            old_value = getattr(model_instance, attr)
-            original_setattr(model_instance, attr, value)
+            old_value = getattr(self_model, attr)
+            original_setattr(self_model, attr, value)
             with self._lock:
                 if attr == self.key:
                     del self._ssd[old_value]
-                    self._ssd[value] = model_instance
+                    self._ssd[value] = self_model
             io.write_json(self.path, self.to_dict)
 
-        def __delattr__(model_instance: BaseModel, attr: str) -> None:
-            old_value = getattr(model_instance, attr)
-            original_delattr(model_instance, attr)
+        def __delattr__(self_model: BaseModel, attr: str) -> None:
+            old_value = getattr(self_model, attr)
+            original_delattr(self_model, attr)
             with self._lock:
                 if attr == self.key:
                     del self._ssd[old_value]
             io.write_json(self.path, self.to_dict)
 
-        # override original methods
-        self.cls.__init__ = __init__
-        self.cls.__setattr__ = __setattr__
-        self.cls.__delattr__ = __delattr__
+        # assign the new methods
+        new_cls.__setattr__ = __setattr__
+        new_cls.__delattr__ = __delattr__
+
+        return new_cls
 
 
 class Syncwave(Mapping[str, SyncStore]):
@@ -196,19 +212,33 @@ class Syncwave(Mapping[str, SyncStore]):
     def stop(self) -> None:
         watcher.stop()
 
+    @overload
+    def register(
+        self,
+        *,
+        name: Optional[str] = None,
+        key: Optional[str] = None,
+        skip_key_validation: bool = False,
+        file_name: Optional[str] = None,
+        sub_dir: Optional[Union[Path, str]] = None,
+        file_path: Optional[Union[Path, str]] = None,
+    ) -> Callable[[Type[BaseModel]], Type[BaseModel]]: ...
+
     def register(
         self,
+        _cls: Optional[Type[BaseModel]] = None,
+        /,
         *,
         name: Optional[str] = None,
-        key: str,
+        key: Optional[str] = None,
         skip_key_validation: bool = False,
         file_name: Optional[str] = None,
         sub_dir: Optional[Union[Path, str]] = None,
         file_path: Optional[Union[Path, str]] = None,
         # in_memory: bool = True,  # TODO: implement in_memory
-    ) -> Callable[[Type[BaseModel]], Type[BaseModel]]:
+    ) -> Union[Type[BaseModel], Callable[[Type[BaseModel]], Type[BaseModel]]]:
         def decorator(cls: Type[BaseModel]) -> Type[BaseModel]:
-            SyncStore(
+            store = SyncStore(
                 self,
                 cls,
                 name=name,
@@ -217,7 +247,12 @@ class Syncwave(Mapping[str, SyncStore]):
                 file_name=file_name,
                 sub_dir=sub_dir,
                 file_path=file_path,
+                new_cls_name=cls.__name__,
             )
-            return cls
+            return store.cls
 
-        return decorator
+        if _cls is None:
+            # called with parenthesis: @syncwave.register(...)
+            return decorator
+        # called without parenthesis: @syncwave.register
+        return decorator(_cls)

syncwave-0.1.3/src/syncwave/watcher.py

@@ -0,0 +1,177 @@
+from pathlib import Path
+from threading import Lock, Timer
+from time import monotonic, sleep
+from typing import Callable
+
+from watchdog.events import (
+    DirDeletedEvent,
+    DirMovedEvent,
+    FileSystemEvent,
+    FileSystemEventHandler,
+)
+from watchdog.observers import Observer
+from watchdog.observers.api import ObservedWatch
+
+DirPath = Path
+FilePath = Path
+Callback = Callable[[], None]
+
+
+class _Watcher:
+    TMP_FILE_PREFIX = ".tmp_"
+
+    def __init__(self) -> None:
+        self._lock = Lock()
+        # dir_path -> (watch object, set of file_paths)
+        self._watched_dirs: dict[DirPath, tuple[ObservedWatch, set[FilePath]]] = {}
+
+        self._observer = Observer()
+        self._event_handler = _EventHandler(self)
+        self._observer.start()
+
+    def watch(self, file_path: FilePath, callback: Callback) -> None:
+        if not file_path.is_file():
+            raise ValueError(f"Path '{file_path}' is not a file.")
+
+        dir_path = file_path.parent
+        with self._lock:
+            # if the directory is already being watched, just add the file to the set
+            if dir_path in self._watched_dirs:
+                _, watched_files = self._watched_dirs[dir_path]
+                watched_files.add(file_path)
+            # otherwise, schedule the directory and create the set of watched files
+            else:
+                self._watched_dirs[dir_path] = (
+                    self._observer.schedule(self._event_handler, str(dir_path)),
+                    {file_path},
+                )
+        # set or reset the callback in all cases
+        self._event_handler.set_callback(file_path, callback)
+
+    def unwatch(self, file_path: FilePath) -> None:
+        # remove the callback
+        self._event_handler.unset_callback(file_path)
+
+        dir_path = file_path.parent
+        with self._lock:
+            # if the directory is not being watched, do nothing
+            if dir_path not in self._watched_dirs:
+                return
+
+            # if the file is in the set, remove it
+            watch, watched_files = self._watched_dirs[dir_path]
+            if file_path in watched_files:
+                watched_files.remove(file_path)
+
+            # if the set is empty, unschedule the directory
+            if not watched_files:
+                self._observer.unschedule(watch)
+                del self._watched_dirs[dir_path]
+
+    def mark_self_write(self, file_path: FilePath) -> None:
+        self._event_handler.mark_self_write(file_path)
+
+    def get_watched_dirs(self) -> dict[DirPath, set[FilePath]]:
+        with self._lock:
+            return {
+                dir_path: watched_files.copy()
+                for dir_path, (_, watched_files) in self._watched_dirs.items()
+            }
+
+    def restore_watched_dir(self, dir_path: DirPath) -> None:
+        with self._lock:
+            if dir_path not in self._watched_dirs:
+                return
+            dir_path.mkdir(parents=True, exist_ok=True)
+            watch, watched_files = self._watched_dirs[dir_path]
+            self._observer.unschedule(watch)
+            self._watched_dirs[dir_path] = (
+                self._observer.schedule(self._event_handler, str(dir_path)),
+                watched_files,
+            )
+
+    def stop(self) -> None:
+        self._observer.stop()
+        self._observer.join()
+
+
+class _EventHandler(FileSystemEventHandler):
+    DEBOUNCE_WINDOW = 0.05
+    SELF_WRITE_WINDOW = 0.5
+
+    def __init__(self, watcher: _Watcher) -> None:
+        self._watcher = watcher
+        self._lock = Lock()
+        self._callbacks: dict[FilePath, Callback] = {}
+        self._debounce_timers: dict[FilePath, Timer] = {}
+        self._self_writes_ts: dict[FilePath, float] = {}
+
+    def set_callback(self, file_path: FilePath, callback: Callback) -> None:
+        with self._lock:
+            self._callbacks[file_path] = callback
+
+    def unset_callback(self, file_path: FilePath) -> None:
+        with self._lock:
+            self._callbacks.pop(file_path, None)
+
+    def mark_self_write(self, file_path: FilePath) -> None:
+        with self._lock:
+            self._self_writes_ts[file_path] = monotonic()
+
+    def _is_self_write(self, file_path: FilePath) -> bool:
+        # not protected by the lock because it's only called internally
+        ts = self._self_writes_ts.get(file_path)
+        if ts is not None and monotonic() - ts < self.SELF_WRITE_WINDOW:
+            return True
+        return False
+
+    def dispatch(self, event: FileSystemEvent) -> None:
+        if event.is_directory:
+            if not isinstance(event, (DirDeletedEvent, DirMovedEvent)):
+                return
+            watched_dirs = self._watcher.get_watched_dirs()
+            for dir_path in self._paths_from_event(event):
+                if dir_path in watched_dirs:
+                    self._on_dir_deleted(dir_path, watched_dirs[dir_path])
+        else:
+            for file_path in self._paths_from_event(event):
+                self._on_file_modified(file_path)
+
+    def _on_dir_deleted(self, dir_path: DirPath, watched_files: set[FilePath]) -> None:
+        sleep(self.DEBOUNCE_WINDOW)  # low-tech debounce
+        self._watcher.restore_watched_dir(dir_path)
+        for file_path in watched_files:
+            self._on_file_modified(file_path)
+
+    def _on_file_modified(self, file_path: FilePath) -> None:
+        with self._lock:
+            if file_path not in self._callbacks or self._is_self_write(file_path):
+                return
+
+            if file_path in self._debounce_timers:
+                self._debounce_timers[file_path].cancel()
+
+            timer = Timer(
+                self.DEBOUNCE_WINDOW,
+                self._scheduled_callback,
+                args=(file_path, self._callbacks[file_path]),
+            )
+            self._debounce_timers[file_path] = timer
+            timer.start()
+
+    def _scheduled_callback(self, file_path: FilePath, callback: Callback) -> None:
+        with self._lock:
+            self._debounce_timers.pop(file_path, None)
+        callback()
+
+    def _paths_from_event(self, event: FileSystemEvent) -> list[Path]:
+        paths = []
+        if self._watcher.TMP_FILE_PREFIX not in event.src_path:
+            paths.append(Path(event.src_path).resolve())
+        dest_path = getattr(event, "dest_path", "")
+        if dest_path and self._watcher.TMP_FILE_PREFIX not in dest_path:
+            paths.append(Path(dest_path).resolve())
+        return paths
+
+
+watcher = _Watcher()

syncwave-0.1.1/src/syncwave/watcher.py

@@ -1,139 +0,0 @@
-from pathlib import Path
-from threading import Lock, Timer
-from time import monotonic
-from typing import Callable, Union
-
-from watchdog.events import (
-    DirModifiedEvent,
-    FileModifiedEvent,
-    FileSystemEvent,
-    FileSystemEventHandler,
-)
-from watchdog.observers import Observer
-from watchdog.observers.api import ObservedWatch
-
-DirPath = Path
-FilePath = Path
-Callback = Callable[[], None]
-
-
-class _Watcher:
-    SELF_WRITE_WINDOW = 0.5
-
-    def __init__(self) -> None:
-        self._lock = Lock()
-        # mapping dir_path -> (watch object, set of file_paths)
-        self._watched_dirs: dict[DirPath, tuple[ObservedWatch, set[FilePath]]] = {}
-        self._self_writes_ts: dict[FilePath, float] = {}
-        self._callbacks: dict[FilePath, Callback] = {}
-
-        self._observer = Observer()
-        self._event_handler = _EventHandler(self)
-        self._observer.start()
-
-    def stop(self) -> None:
-        self._observer.stop()
-        self._observer.join()
-
-    def watch(self, file_path: FilePath, callback: Callback) -> None:
-        dir_path = file_path.parent
-
-        if not file_path.is_file():
-            raise ValueError(f"Path {file_path} is not a file.")
-
-        with self._lock:
-            # if the directory is already being watched...
-            if dir_path in self._watched_dirs:
-                _, watched_files = self._watched_dirs[dir_path]
-
-                # ...but the file is not in the set, add it
-                if file_path not in watched_files:
-                    watched_files.add(file_path)
-
-                # and in any case, update the callback before returning
-                self._callbacks[file_path] = callback
-                return
-
-            # otherwise, schedule the directory and register the callback
-            self._watched_dirs[dir_path] = (
-                self._observer.schedule(self._event_handler, str(dir_path)),
-                {file_path},
-            )
-            self._callbacks[file_path] = callback
-
-    def unwatch(self, file_path: FilePath) -> None:
-        dir_path = file_path.parent
-
-        with self._lock:
-            # remove the callback
-            self._callbacks.pop(file_path, None)
-
-            # if the directory is not being watched, do nothing
-            if dir_path not in self._watched_dirs:
-                return
-
-            watch, watched_files = self._watched_dirs[dir_path]
-
-            # if the file is in the set, remove it
-            if file_path in watched_files:
-                watched_files.remove(file_path)
-
-            # if the set is empty, unschedule the directory
-            if not watched_files:
-                self._observer.unschedule(watch)
-                del self._watched_dirs[dir_path]
-
-    def mark_self_write(self, file_path: FilePath) -> None:
-        with self._lock:
-            self._self_writes_ts[file_path] = monotonic()
-
-    def _is_self_write(self, file_path: FilePath) -> bool:
-        with self._lock:
-            ts = self._self_writes_ts.get(file_path)
-            if ts is not None and monotonic() - ts < self.SELF_WRITE_WINDOW:
-                return True
-        return False
-
-
-class _EventHandler(FileSystemEventHandler):
-    DEBOUNCE_WINDOW = 0.05
-
-    def __init__(self, watcher: _Watcher) -> None:
-        self.lock = Lock()
-        self.watcher = watcher
-        self.debounce_timers: dict[FileSystemEvent, Timer] = {}
-
-    def on_modified(self, event: Union[FileModifiedEvent, DirModifiedEvent]) -> None:
-        if event.is_directory or isinstance(event, DirModifiedEvent):
-            return
-
-        file_path = Path(event.src_path).resolve()
-
-        if self.watcher._is_self_write(file_path):
-            return
-
-        callback = self.watcher._callbacks.get(file_path)
-        if callback is None:
-            return
-
-        with self.lock:
-            if event in self.debounce_timers:
-                self.debounce_timers[event].cancel()
-
-            timer = Timer(
-                self.DEBOUNCE_WINDOW,
-                self.schedule_callback,
-                args=(event, callback),
-            )
-            self.debounce_timers[event] = timer
-            timer.start()
-
-    def schedule_callback(self, event: FileSystemEvent, callback: Callback) -> None:
-        try:
-            callback()
-        finally:
-            with self.lock:
-                self.debounce_timers.pop(event, None)
-
-
-watcher = _Watcher()