syncwave 0.1.2__tar.gz → 0.1.4__tar.gz

{syncwave-0.1.2 → syncwave-0.1.4}/PKG-INFO

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

@@ -1,6 +1,6 @@
 [project]
 name = "syncwave"
-version = "0.1.2"
+version = "0.1.4"
 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" }]
@@ -28,8 +28,24 @@ dev = [
 ]
 
 [tool.ruff.lint]
-select = ["E", "F"]
+select = [
+    "E",  # pycodestyle errors
+    "F",  # pyflakes
+    "I",  # isort
+    "B",  # flake8-bugbear
+    "C4",  # flake8-comprehensions
+    "SIM",  # flake8-simplify
+    "ANN",  # flake8-annotations
+    "RUF",  # ruff
+    "UP",  # pyupgrade
+]
 
 unfixable = [
     "F401"  # disable fix for unused imports
 ]
+
+[tool.ruff.lint.per-file-ignores]
+"__init__.py" = ["I002"]
+
+[tool.ruff.lint.isort]
+required-imports = ["from __future__ import annotations"]

{syncwave-0.1.2 → syncwave-0.1.4}/src/syncwave/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "0.1.2"
+__version__ = "0.1.4"
 
 
 from .syncwave import SyncStore, Syncwave

{syncwave-0.1.2 → syncwave-0.1.4}/src/syncwave/io.py

@@ -1,9 +1,12 @@
+from __future__ import annotations
+
+import contextlib
 import json
 import os
 from pathlib import Path
 from tempfile import mkstemp
 from threading import Lock, Timer
-from typing import Any, Callable
+from typing import Any, Callable, Final
 
 from .watcher import watcher
 
@@ -12,10 +15,10 @@ DataProvider = Callable[[], JSONData]
 
 
 class _IO:
-    ENCODING = "utf-8"
-    DEFAULT_JSON_CONTENT = {}
-    DUMPS_CONFIG = {"indent": 2, "ensure_ascii": False}
-    DEBOUNCE_WINDOW = 0.05
+    ENCODING: Final[str] = "utf-8"
+    DEFAULT_JSON_CONTENT: Final[JSONData] = {}
+    DUMPS_CONFIG: Final[dict[str, Any]] = {"indent": 2, "ensure_ascii": False}
+    DEBOUNCE_WINDOW: Final[float] = 0.05
 
     def __init__(self) -> None:
         self._lock = Lock()
@@ -37,7 +40,7 @@ class _IO:
             with path.open(encoding=self.ENCODING) as f:
                 json.load(f)
         except json.JSONDecodeError as e:
-            raise IOError(f"File '{path}' exists but is not a valid JSON file.") from e
+            raise OSError(f"File '{path}' exists but is not a valid JSON file.") from e
 
     def read_json(self, path: Path) -> JSONData:
         with self._lock:
@@ -79,15 +82,14 @@ 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
-            try:
+            with contextlib.suppress(OSError):
                 os.remove(tmp_path)
-            except OSError:
-                pass
             # Raise a clear error message including context
-            raise IOError(
+            raise OSError(
                 f"Failed to write JSON to '{path}'. "
                 f"Temporary file '{tmp_path}' removed. Original error: {e}"
             ) from e

{syncwave-0.1.2 → syncwave-0.1.4}/src/syncwave/syncwave.py

@@ -1,11 +1,13 @@
-from collections.abc import Mapping
+from __future__ import annotations
+
+from collections.abc import Iterator, Mapping
 from inspect import isclass
 from json import JSONDecodeError
 from pathlib import Path
 from threading import RLock
-from typing import Any, Callable, Iterator, Optional, Type, Union, get_args
+from typing import Any, Callable, 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
@@ -14,7 +16,7 @@ from .watcher import watcher
 JSONKey = Union[str, int, float, bool, None]
 
 
-def _validate_key_type(cls: Type[BaseModel], key: str) -> None:
+def _validate_key_type(cls: type[BaseModel], key: str) -> None:
     # This will work if the key field is a basic type (str, int, float, bool, or None),
     # but will fail for more complex types (Union[str, int], Optional[str], etc.).
     # In that case skip the validation.
@@ -31,39 +33,46 @@ def _validate_key_type(cls: Type[BaseModel], key: str) -> None:
 class SyncStore(Mapping[JSONKey, BaseModel]):
     def __init__(
         self,
-        syncwave: "Syncwave",
-        cls: Type[BaseModel],
+        syncwave: Syncwave,
+        cls: type[BaseModel],
+        /,
+        name: str | None = None,
+        key: str | None = None,
         *,
-        name: Optional[str] = None,
-        key: str,
         skip_key_validation: bool = False,
-        file_name: Optional[str] = None,
-        sub_dir: Optional[Union[Path, str]] = None,
-        file_path: Optional[Union[Path, str]] = None,
+        file_name: str | None = None,
+        sub_dir: Path | str | None = None,
+        file_path: Path | str | None = None,
+        new_cls_name: str | None = 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 = RLock()
-        self._patch_cls()
         io.init_json_file(self.path)
         self.load()
         watcher.watch(self.path, self.load)
@@ -75,7 +84,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 +100,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:
@@ -119,8 +125,8 @@ class SyncStore(Mapping[JSONKey, BaseModel]):
     def _get_path(
         self,
         file_name: str,
-        sub_dir: Union[Path, str, None],
-        file_path: Union[Path, str, None],
+        sub_dir: Path | str | None,
+        file_path: Path | str | None,
     ) -> Path:
         if file_path:
             return Path(file_path).resolve()
@@ -129,45 +135,57 @@ 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)},
+        )
+
+        # preserve original methods
+        original_setattr = cls.__setattr__
+        original_delattr = cls.__delattr__
 
-        def __setattr__(model_instance: BaseModel, attr: str, value: Any) -> None:
+        def __setattr__(self_model: BaseModel, attr: str, value: Any) -> None:  # noqa: ANN401
             # 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]):
-    def __init__(self, data_dir: Union[str, Path]) -> None:
+    def __init__(self, data_dir: str | Path) -> None:
         self.data_dir = Path(data_dir).resolve()
         self._swd: dict[str, SyncStore] = {}  # actual mapping, swd = SyncWaveDict
 
@@ -196,19 +214,33 @@ class Syncwave(Mapping[str, SyncStore]):
     def stop(self) -> None:
         watcher.stop()
 
+    @overload
+    def register(
+        self,
+        *,
+        name: str | None = None,
+        key: str | None = None,
+        skip_key_validation: bool = False,
+        file_name: str | None = None,
+        sub_dir: Path | str | None = None,
+        file_path: Path | str | None = None,
+    ) -> Callable[[type[BaseModel]], type[BaseModel]]: ...
+
     def register(
         self,
+        _cls: type[BaseModel] | None = None,
+        /,
         *,
-        name: Optional[str] = None,
-        key: str,
+        name: str | None = None,
+        key: str | None = 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,
+        file_name: str | None = None,
+        sub_dir: Path | str | None = None,
+        file_path: Path | str | None = None,
         # in_memory: bool = True,  # TODO: implement in_memory
-    ) -> Callable[[Type[BaseModel]], Type[BaseModel]]:
-        def decorator(cls: Type[BaseModel]) -> Type[BaseModel]:
-            SyncStore(
+    ) -> type[BaseModel] | Callable[[type[BaseModel]], type[BaseModel]]:
+        def decorator(cls: type[BaseModel]) -> type[BaseModel]:
+            store = SyncStore(
                 self,
                 cls,
                 name=name,
@@ -217,7 +249,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.2 → syncwave-0.1.4}/src/syncwave/watcher.py

@@ -1,7 +1,9 @@
+from __future__ import annotations
+
 from pathlib import Path
 from threading import Lock, Timer
 from time import monotonic, sleep
-from typing import Callable
+from typing import Callable, Final
 
 from watchdog.events import (
     DirDeletedEvent,
@@ -18,7 +20,7 @@ Callback = Callable[[], None]
 
 
 class _Watcher:
-    TMP_FILE_PREFIX = ".tmp_"
+    TMP_FILE_PREFIX: Final[str] = ".tmp_"
 
     def __init__(self) -> None:
         self._lock = Lock()
@@ -96,8 +98,8 @@ class _Watcher:
 
 
 class _EventHandler(FileSystemEventHandler):
-    DEBOUNCE_WINDOW = 0.05
-    SELF_WRITE_WINDOW = 0.5
+    DEBOUNCE_WINDOW: Final[float] = 0.05
+    SELF_WRITE_WINDOW: Final[float] = 0.5
 
     def __init__(self, watcher: _Watcher) -> None:
         self._watcher = watcher
@@ -121,9 +123,7 @@ class _EventHandler(FileSystemEventHandler):
     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
+        return ts is not None and monotonic() - ts < self.SELF_WRITE_WINDOW
 
     def dispatch(self, event: FileSystemEvent) -> None:
         if event.is_directory: