ws_sync

ws-sync: WebSocket Sync

Minimal helpers for keeping Python objects and a browser in sync over a WebSocket connection. State changes are shipped as JSON Patches and there is a companion React hook.

Patterns

from pydantic import BaseModel, Field
from ws_sync import remote_action, remote_task, sync_all, Synced


class Notes(Synced, BaseModel):
    title: str = Field("My Notes", min_length=3, max_length=50)
    notes: list[str] = []

    @sync_all()
    def model_post_init(self, _):
        ...  # Sync is created here

    @remote_action
    async def rename(self, title: str = Field(min_length=3, max_length=50)):
        self.title = title
        await self.sync()

    @remote_task
    async def add(self, note: str):
        self.notes.append(note)
        await self.sync()

Synced is a thin mixin over BaseModel; it honours Pydantic configs and validates both the fields and any remote actions/tasks.

2. Classic class with annotations

from ws_sync import remote_action, sync_all
from ws_sync.sync import Sync


class Notes:
    sync: Sync  # type checking & validation via TypeAdapter
    title: str
    notes: list[str]

    @sync_all()
    def __init__(self):
        self.title = "My Notes"
        self.notes = []

    @remote_action
    async def rename(self, title: str):
        self.title = title
        await self.sync()

3. Manual sync without validation

from ws_sync.sync import Sync


class Notes:
    def __init__(self):
        self.title = "My Notes"
        self.notes = []
        self.sync = Sync.all(self, "NOTES")

Attributes are sent as-is with no type validation.

Remote actions & tasks

class Counter(Synced, BaseModel):
    value: int = 0

    @remote_action
    async def reset(self):
        self.value = 0
        await self.sync()

    @remote_task
    async def inc(self, by: int):
        self.value += by
        await self.sync()

@remote_action exposes a method for one-off calls. @remote_task spawns a concurrent task that can be cancelled. All parameters are validated using the type hints (Pydantic models, dataclasses, enums, etc.).

Frontend

The second parameter of useSynced is the initial state.

The returned notes object not only contains the state, but also the setters and syncers:

const Notes = () => {
  const notes = useSynced("NOTES", {
    title: "",
    notes: [],
  });

  return (
    <div>
      <input
        value={notes.title}
        onChange={(e) => notes.syncTitle(e.target.value)}
      />
      <ul>
        {notes.notes.map((note) => (
          <li>{note}</li>
        ))}
      </ul>
    </div>
  );
};

Server

Example using FastAPI:

from fastapi import FastAPI, WebSocket
from ws_sync import Session
from .notes import Notes

# FastAPI server
app = FastAPI()


# create a new session, in this case only 1 global session
with Session() as session:
    my_notes = Notes()
    my_session = session

@app.websocket("/ws")
async def websocket_endpoint(ws: WebSocket):
    await my_session.handle_connection(ws)

Concepts and Implementation

High-Level

Session: A session is a connection between a frontend and a backend, and it _persists across WebSocket reconnects_. This means that any interruption of the connection will not affect the backend state in any way, and all the self.sync() calls will be ignored. On reconnect, the frontend will automatically restore the latest state from the backend.

Sync: A sync operation will generate a new snapshot of the object state, calculate the difference to the previous state snapshot, and send a JSON Patch object to the frontend. The frontend will then apply the patch to its local state. This is done automatically on every self.sync() call. This way, only the changes are sent over the network, and the frontend state is always in sync with the backend state.

Low-Level

Events: The primitive of the protocol are events. An event is a JSON object with a simple {"type": "event_type", "data": any} format. All the operations done by the Sync object uses different events, including actions and tasks.

Validators and Schema Generation

Static

If you use the Synced object with pydantic BaseModels, you can get JSON schemas for the synced state, registered actions and tasks. This can then be used to generate frontend client types and codes.

class Notes(Synced, BaseModel):
    title: str = Field(min_length=3, max_length=50)
    content: dict[str, list[str]] = {}

    @remote_action
    async def set_title(self, title: str):
        self.title = title
        await self.sync()

Notes.ws_sync_json_schema()
 1"""
 2.. include:: ../README.md
 3"""
 4
 5__all__ = [  # noqa: RUF022
 6    # submodules
 7    "decorators",
 8    "session",
 9    # decorators
10    "sync",
11    "sync_all",
12    "sync_only",
13    "remote_action",
14    "remote_task",
15    "remote_task_cancel",
16    # classes
17    "Sync",
18    "Session",
19    "SessionState",
20    "Synced",
21    "SyncedAsCamelCase",
22    # globals
23    "session_context",
24    "get_user_session",
25    # sync key scoping
26    "sync_key_scope",
27    "get_current_sync_key_prefix",
28]
29
30from .decorators import (
31    remote_action,
32    remote_task,
33    remote_task_cancel,
34    sync,
35    sync_all,
36    sync_only,
37)
38from .id import get_user_session
39from .session import Session, SessionState, session_context
40from .sync import Sync, get_current_sync_key_prefix, sync_key_scope
41from .synced_model import Synced, SyncedAsCamelCase
def sync_all( key: str | None = None, *, include: dict[str, str | ellipsis] | list[str] | None = None, exclude: list[str] | None = None, toCamelCase: bool | None = None, send_on_init: bool = True, expose_running_tasks: bool = False, logger: logging.Logger | None = None):
263def sync_all(
264    key: str | None = None,
265    *,
266    include: dict[str, str | EllipsisType] | list[str] | None = None,
267    exclude: list[str] | None = None,
268    toCamelCase: bool | None = None,  # noqa: N803
269    send_on_init: bool = True,
270    expose_running_tasks: bool = False,
271    logger: Logger | None = None,
272):
273    """
274    Decorator for `__init__()`: Register all non-private attributes to be synced with the frontend.
275
276    Args:
277        key: unique key (matching the frontend key) to identify the object.
278             If None, defaults to the class name.
279        include: attribute names to sync, value being either ... or a string of the key of the attribute
280        exclude: list of attributes to exclude from syncing
281        toCamelCase: convert attribute names to camelCase
282        send_on_init: send the state on connection init
283        expose_running_tasks: expose the list in the synced state as `running_tasks` or `runningTasks`
284        logger: logger to use for logging
285    """
286    return sync(
287        key=key,
288        sync_all=True,
289        include=include,
290        exclude=exclude or [],
291        toCamelCase=toCamelCase,
292        send_on_init=send_on_init,
293        expose_running_tasks=expose_running_tasks,
294        logger=logger,
295    )

Decorator for __init__(): Register all non-private attributes to be synced with the frontend.

Arguments:
  • key: unique key (matching the frontend key) to identify the object. If None, defaults to the class name.
  • include: attribute names to sync, value being either ... or a string of the key of the attribute
  • exclude: list of attributes to exclude from syncing
  • toCamelCase: convert attribute names to camelCase
  • send_on_init: send the state on connection init
  • expose_running_tasks: expose the list in the synced state as running_tasks or runningTasks
  • logger: logger to use for logging
def sync_only( _key: str | None = None, *, _toCamelCase: bool | None = None, _send_on_init: bool = True, _expose_running_tasks: bool = False, _logger: logging.Logger | None = None, **sync_attributes: str | ellipsis):
298def sync_only(
299    _key: str | None = None,
300    *,
301    _toCamelCase: bool | None = None,  # noqa: N803
302    _send_on_init: bool = True,
303    _expose_running_tasks: bool = False,
304    _logger: Logger | None = None,
305    **sync_attributes: str | EllipsisType,
306):
307    """
308    Decorator for `__init__()`: Register only the keyword-specified attributes to be synced with the frontend.
309
310    Args:
311        _key: unique key (matching the frontend key) to identify the object.
312              If None, defaults to the class name.
313        _toCamelCase: convert attribute names to camelCase
314        _send_on_init: send the state on connection init
315        _expose_running_tasks: expose the list in the synced state as `running_tasks` or `runningTasks`
316        _logger: logger to use for logging
317        **sync_attributes: attribute names to sync, value being the key of the attribute
318    """
319    return sync(
320        key=_key,
321        sync_all=False,
322        include=sync_attributes,
323        exclude=[],
324        toCamelCase=_toCamelCase,
325        send_on_init=_send_on_init,
326        expose_running_tasks=_expose_running_tasks,
327        logger=_logger,
328    )

Decorator for __init__(): Register only the keyword-specified attributes to be synced with the frontend.

Arguments:
  • _key: unique key (matching the frontend key) to identify the object. If None, defaults to the class name.
  • _toCamelCase: convert attribute names to camelCase
  • _send_on_init: send the state on connection init
  • _expose_running_tasks: expose the list in the synced state as running_tasks or runningTasks
  • _logger: logger to use for logging
  • **sync_attributes: attribute names to sync, value being the key of the attribute
def remote_action(key: Union[str, NoneType, F] = None) -> Union[F, Callable[[F], F]]:
339def remote_action[F: Callable](key: str | None | F = None) -> F | Callable[[F], F]:
340    """
341    Decorator for methods: Expose the method as an action to the frontend.
342
343    An action is a "synchronous" method that blocks the backend logic until it completes.
344    Of course, the method should be `async` to allow for non-blocking concurrency with other parallel sessions of the server.
345
346    Args:
347        key: unique key (matching the frontend key) to identify the action.
348             If None, defaults to the method name.
349    """
350
351    def decorator(func: F) -> F:
352        action_key = key if isinstance(key, str) else func.__name__
353        func.remote_action = action_key  # type: ignore
354        return func
355
356    if callable(key):  # @remote_action without parentheses
357        func = key  # key is actually the function
358        return decorator(func)
359    # @remote_action(...) was used
360    decorator.forgot_to_call = True  # type: ignore[reportFunctionMemberAccess]
361    return decorator

Decorator for methods: Expose the method as an action to the frontend.

An action is a "synchronous" method that blocks the backend logic until it completes. Of course, the method should be async to allow for non-blocking concurrency with other parallel sessions of the server.

Arguments:
  • key: unique key (matching the frontend key) to identify the action. If None, defaults to the method name.
def remote_task(key: Union[str, NoneType, F] = None) -> Union[F, Callable[[F], F]]:
390def remote_task[F: Callable](key: str | None | F = None) -> F | Callable[[F], F]:
391    """
392    Decorator for methods: Expose the method as a long-running task to the frontend.
393
394    A task is a "non-blocking" method that runs concurrently with the backend logic.
395    The frontend can cancel the task at any time, so you should also implement a `@remote_task_cancel` method to cancel the task.
396
397    Args:
398        key: unique key (matching the frontend key) to identify the task.
399             If None, defaults to the method name.
400    """
401
402    def decorator(func: F) -> F:
403        task_key = key if isinstance(key, str) else func.__name__
404        func.remote_task = task_key  # type: ignore
405        func.cancel = remote_task_cancel(task_key)  # type: ignore # syntactic sugar
406        return func
407
408    if callable(key):  # @remote_task without parentheses
409        func = key  # key is actually the function
410        return decorator(func)
411    # @remote_task(...) was used
412    decorator.forgot_to_call = True  # type: ignore[reportFunctionMemberAccess]
413    return decorator

Decorator for methods: Expose the method as a long-running task to the frontend.

A task is a "non-blocking" method that runs concurrently with the backend logic. The frontend can cancel the task at any time, so you should also implement a @remote_task_cancel method to cancel the task.

Arguments:
  • key: unique key (matching the frontend key) to identify the task. If None, defaults to the method name.
def remote_task_cancel(key: str) -> Callable[[F], F]:
435def remote_task_cancel[F: Callable](key: str) -> Callable[[F], F]:
436    """
437    Decorator for methods: Expose the method as a task-canceller to the frontend.
438
439    A task-canceller is a method that cancels a running task.
440    The method `f` decorated with `@remote_task` has a corresponding cancel decorator `@f.cancel`:
441    ```python
442    @remote_task("MY_TASK")
443    async def my_task(self): ...
444
445    @my_task.cancel
446    async def cancel_my_task(self): ...
447    ```
448
449    Args:
450        key: unique key (matching the frontend key) to identify the task
451    """
452
453    def decorator(func: F) -> F:
454        func.remote_task_cancel = key  # type: ignore
455        return func
456
457    decorator.forgot_to_call = True  # type: ignore[reportFunctionMemberAccess]
458    return decorator

Decorator for methods: Expose the method as a task-canceller to the frontend.

A task-canceller is a method that cancels a running task. The method f decorated with @remote_task has a corresponding cancel decorator @f.cancel:

@remote_task("MY_TASK")
async def my_task(self): ...

@my_task.cancel
async def cancel_my_task(self): ...
Arguments:
  • key: unique key (matching the frontend key) to identify the task
class Sync:
 188class Sync:
 189    """
 190    Register an object's attributes to this class to sync them with the frontend.
 191    """
 192
 193    @classmethod
 194    def all(
 195        cls,
 196        obj: object,
 197        key: str,
 198        *,
 199        include: dict[str, str | EllipsisType] | list[str] | None = None,
 200        exclude: list[str] | None = None,
 201        toCamelCase: bool | None = None,  # noqa: N803
 202        send_on_init: bool = True,
 203        expose_running_tasks: bool = False,
 204        logger: Logger | None = None,
 205        actions: Mapping[str, Callable[..., Any]] | None = None,
 206        tasks: Mapping[str, Callable[..., Awaitable[Any]]] | None = None,
 207        task_cancels: Mapping[str, Callable[..., Awaitable[Any]]] | None = None,
 208    ) -> "Sync":
 209        return cls(
 210            obj=obj,
 211            key=key,
 212            sync_all=True,
 213            include=include,
 214            exclude=exclude or [],
 215            toCamelCase=toCamelCase,
 216            send_on_init=send_on_init,
 217            expose_running_tasks=expose_running_tasks,
 218            logger=logger,
 219            actions=actions,
 220            tasks=tasks,
 221            task_cancels=task_cancels,
 222        )
 223
 224    @classmethod
 225    def only(
 226        cls,
 227        _obj: object,
 228        _key: str,
 229        *,
 230        _toCamelCase: bool | None = None,  # noqa: N803
 231        _send_on_init: bool = True,
 232        _expose_running_tasks: bool = False,
 233        _logger: Logger | None = None,
 234        _actions: Mapping[str, Callable[..., Any]] | None = None,
 235        _tasks: Mapping[str, Callable[..., Awaitable[Any]]] | None = None,
 236        _task_cancels: Mapping[str, Callable[..., Awaitable[Any]]] | None = None,
 237        **sync_attributes: str | EllipsisType,
 238    ) -> "Sync":
 239        return cls(
 240            obj=_obj,
 241            key=_key,
 242            sync_all=False,
 243            include=sync_attributes,
 244            exclude=[],
 245            toCamelCase=_toCamelCase,
 246            send_on_init=_send_on_init,
 247            expose_running_tasks=_expose_running_tasks,
 248            logger=_logger,
 249            actions=_actions,
 250            tasks=_tasks,
 251            task_cancels=_task_cancels,
 252        )
 253
 254    @staticmethod
 255    def resolve_attributes(
 256        obj_or_cls: object | type,
 257        *,
 258        include: dict[str, str | EllipsisType] | None = None,
 259        exclude: list[str] | None = None,
 260        sync_all: bool = False,
 261        casing_func: Callable[[str], str] | None = None,
 262    ) -> dict[str, str]:
 263        """
 264        Resolve which attributes to sync based on configuration.
 265
 266        Returns:
 267            Dict mapping attribute name to sync key (alias).
 268        """
 269        include = include or {}
 270        exclude = exclude or []
 271        sync_attributes: dict[str, str] = {}
 272
 273        is_class = isinstance(obj_or_cls, type)
 274        cls = obj_or_cls if is_class else type(obj_or_cls)
 275
 276        def casing(attr: str) -> str:
 277            return casing_func(attr) if casing_func else attr
 278
 279        # observe all non-private attributes
 280        if sync_all:
 281            if issubclass(cls, BaseModel):
 282                # Include regular fields
 283                for field in cls.model_fields:
 284                    if field in exclude:
 285                        continue
 286                    sync_attributes[field] = casing(field)
 287
 288                # Include computed fields
 289                for field in cls.model_computed_fields:
 290                    if field in exclude:
 291                        continue
 292                    sync_attributes[field] = casing(field)
 293            # For regular classes, we need an instance to check dir() reliably for instance attrs,
 294            # but we can check class attrs if we only have a class.
 295            # However, if we only have a class, we can't know instance attributes that are set in __init__.
 296            # So sync_all=True for plain classes really works best with an instance.
 297            # If we have a class, we can only guess based on annotations or class attributes.
 298            elif is_class:
 299                # Best effort for static analysis of plain classes
 300                # We can check type hints
 301                for attr_name in get_type_hints(cls):
 302                    if attr_name in exclude or attr_name.startswith("_"):
 303                        continue
 304                    sync_attributes[attr_name] = casing(attr_name)
 305            else:
 306                for attr_name in dir(obj_or_cls):
 307                    try:
 308                        attr = getattr(obj_or_cls, attr_name)
 309                    except AttributeError:
 310                        continue
 311                    if (
 312                        attr_name in exclude
 313                        or attr_name.startswith("_")
 314                        or callable(attr)
 315                        or isinstance(attr, Sync)
 316                    ):
 317                        continue
 318
 319                    sync_attributes[attr_name] = casing(attr_name)
 320
 321        # observe specific attributes
 322        for attr_name, sync_key in include.items():
 323            sync_attributes[attr_name] = (
 324                casing(attr_name) if sync_key is ... else cast(str, sync_key)
 325            )
 326
 327        return sync_attributes
 328
 329    def __init__(
 330        self,
 331        obj: object,
 332        key: str,
 333        *,
 334        sync_all: bool = False,
 335        include: dict[str, str | EllipsisType] | list[str] | None = None,
 336        exclude: list[str] | None = None,
 337        toCamelCase: bool | None = None,  # noqa: N803
 338        send_on_init: bool = True,
 339        expose_running_tasks: bool = False,
 340        logger: Logger | None = None,
 341        actions: Mapping[str, Callable[..., Any]] | None = None,
 342        tasks: Mapping[str, Callable[..., Awaitable[Any]]] | None = None,
 343        task_cancels: Mapping[str, Callable[..., Awaitable[Any]]] | None = None,
 344    ):
 345        """
 346        Register the attributes that should be synced with the frontend.
 347
 348        Args:
 349            obj: the object whose attributes should be synced
 350            key: unique key for this object
 351
 352            sync_all: whether to sync all non-private attributes
 353            include: attribute names to sync, value being either ...
 354                or a string of the key of the attribute
 355            exclude: list of attributes to exclude from syncing
 356
 357            toCamelCase: convert attribute names to camelCase. Must be ``None`` for
 358                Pydantic models, which should configure ``alias_generator``
 359            send_on_init: whether to send the state on connection init
 360            expose_running_tasks: whether to expose the running tasks to the frontend
 361            logger: logger to use for logging
 362
 363            actions: action handlers for each action type, each taking the data of the action as keyword arguments
 364            tasks: either a dict of task factories for each task type, each returning a coroutine to be used as a task, or a tuple of (task_start_handler, task_cancel_handler)
 365            task_cancels: a dict of task cancel handlers for each task type
 366
 367
 368        """
 369        self.obj = obj
 370        self.key = _apply_sync_key_prefix(key)
 371        self.send_on_init = send_on_init
 372        self.casing_func = (
 373            get_alias_function_for_class(type(self.obj))
 374            if isinstance(self.obj, BaseModel)
 375            else (to_camel if toCamelCase else None)
 376        )
 377        self.task_exposure = (
 378            self.casing("running_tasks") if expose_running_tasks else None
 379        )
 380        self.logger = logger
 381
 382        # Convert list[str] include to dict format
 383        if isinstance(include, list):
 384            include = dict.fromkeys(include, ...)
 385        include = include or {}
 386        exclude = exclude or []
 387
 388        # Validate that BaseModel objects don't use custom sync keys
 389        if isinstance(obj, BaseModel) and include:
 390            for attr_name, sync_key in include.items():
 391                assert sync_key is ..., (
 392                    f"Custom sync key '{sync_key}' for attribute '{attr_name}' is not allowed for Pydantic models. Use pydantic's alias_generator in model_config instead."
 393                )
 394
 395        self.session = session_context.get()
 396        assert self.session, "No session set, use the session.session_context variable!"
 397
 398        # ========== Create Action Validators (cached) ========== #
 399        actions = dict(actions or {}) | find_remote_actions(type(self.obj))
 400        self.action_validators: dict[str, TypeAdapter[Any]] = (
 401            self.build_action_validators(
 402                target_cls=type(self.obj),
 403                actions=actions,
 404                param_alias_generator=self.casing_func,
 405            )
 406        )
 407        # Create action handler after validators are ready
 408        self.actions = self._create_action_handler(obj, actions)
 409
 410        # ========== Create Task Validators (cached) ========== #
 411        tasks = dict(tasks or {}) | find_remote_tasks(type(self.obj))
 412        task_cancels = dict(task_cancels or {}) | find_remote_task_cancellers(
 413            type(self.obj)
 414        )
 415        self.task_validators: dict[str, TypeAdapter[Any]] = self.build_task_validators(
 416            target_cls=type(self.obj),
 417            tasks=tasks,
 418            param_alias_generator=self.casing_func,
 419        )
 420        self.tasks, self.task_cancels = self._create_task_handlers(
 421            obj, tasks, task_cancels
 422        )
 423
 424        # store running tasks
 425        self.running_tasks: dict[str, asyncio.Task[Any]] = {}
 426
 427        # ========== Find attributes to sync ========== #
 428        self.sync_attributes: dict[str, str] = {}
 429
 430        # observe all non-private attributes
 431        if sync_all:
 432            if isinstance(obj, BaseModel):
 433                # Include regular fields
 434                for field in type(obj).model_fields:
 435                    if field in exclude:
 436                        continue
 437                    self.sync_attributes[field] = self.casing(field)
 438
 439                # Include computed fields
 440                for field in type(obj).model_computed_fields:
 441                    if field in exclude:
 442                        continue
 443                    self.sync_attributes[field] = self.casing(field)
 444            else:
 445                for attr_name in dir(obj):
 446                    try:
 447                        attr = getattr(obj, attr_name)
 448                    except AttributeError:
 449                        continue
 450                    if (
 451                        attr_name in exclude
 452                        or attr_name.startswith("_")
 453                        or callable(attr)
 454                        or isinstance(attr, Sync)
 455                    ):
 456                        continue
 457
 458                    self.sync_attributes[attr_name] = self.casing(attr_name)
 459
 460        # observe specific attributes
 461        for attr_name, sync_key in include.items():
 462            self.sync_attributes[attr_name] = (
 463                self.casing(attr_name) if sync_key is ... else sync_key
 464            )
 465
 466        # create reverse-lookup for patching
 467        self.key_to_attr: dict[str, str] = {
 468            key: attr for attr, key in self.sync_attributes.items()
 469        }
 470
 471        # ========== Debugging ========== #
 472        if self.logger:
 473            self.logger.debug("%s: Syncing %s", self.key, self.sync_attributes)
 474            self.logger.debug("%s: Actions %s", self.key, actions)
 475            self.logger.debug("%s: Tasks %s", self.key, tasks)
 476            self.logger.debug("%s: Task Cancels %s", self.key, task_cancels)
 477
 478        assert include.keys().isdisjoint(exclude), "Attribute in both include & exclude"
 479        assert all(a in dir(obj) for a in self.sync_attributes), "Attribute not found"
 480        assert all(e in dir(obj) for e in exclude), "Excluded attribute not found"
 481        # assert (
 482        #     len(self.sync_attributes) + expose_running_tasks > 0
 483        # ), "No attributes to sync"
 484
 485        # ========== Field Type Adapters (cached) ========== #
 486        self.type_adapters: dict[str, TypeAdapter[Any]] = self.build_field_validators(
 487            type(obj), field_whitelist=self.sync_attributes.keys()
 488        )
 489
 490        # ========== State Management ========== #
 491        # the snapshot is the exact state that the frontend has, for patching
 492        self.state_snapshot: dict[str, Any] = self._snapshot()
 493        self._last_sync: float | None = None  # timestamp of last sync
 494
 495        # ========== Weak Reference Cleanup State ========== #
 496        self._closed = False
 497        self._init_wrapper: Callable[..., Any] | None = None
 498        self._registered_handlers: dict[str, Callable[..., Any]] = {}
 499        self._weak_self_ref: weakref.ref[Sync] | None = None
 500        self._register_event_handlers()
 501
 502    # ========== High-Level: Sync and Actions ========== #
 503    async def sync(self, if_since_last: float | None = None):
 504        """
 505        Sync all registered attributes.
 506
 507        Args:
 508            if_since_last: only sync if the last sync was before this many seconds
 509        """
 510        if not self.session.is_connected:
 511            return
 512        t = time()
 513        if if_since_last and self._last_sync and t - self._last_sync < if_since_last:
 514            return
 515
 516        # calculate patch
 517        prev = self.state_snapshot
 518        self.state_snapshot = self._snapshot()
 519        patch = jsonpatch.make_patch(prev, self.state_snapshot).patch
 520
 521        if len(patch) > 0:
 522            await self.session.send(patch_event(self.key), patch)
 523            self._last_sync = t
 524
 525    async def __call__(
 526        self,
 527        if_since_last: float | None = None,
 528        toast: str | None = None,
 529        type: ToastType = "default",  # noqa: A002
 530    ):
 531        """
 532        Sync all registered attributes.
 533
 534        Args:
 535            if_since_last: only sync if the last sync was before this many seconds
 536            toast: toast message to send after syncing
 537            type: toast type
 538        """
 539        await self.sync(if_since_last=if_since_last)
 540        if toast:
 541            await self.toast(toast, type=type)
 542
 543    async def send_action(self, action: dict[str, Any]):
 544        """
 545        Send an action to the frontend.
 546        """
 547        await self.session.send(action_event(self.key), action)
 548
 549    async def send_binary(self, metadata: dict[str, Any], data: bytes):
 550        """
 551        Send binary data to the frontend, along with metadata.
 552
 553        This is a subset of an action, but with bytes data always included.
 554        """
 555        await self.session.send_binary(action_event(self.key), metadata, data)
 556
 557    async def toast(
 558        self,
 559        *messages,
 560        type: ToastType = "default",  # noqa: A002
 561        logger: Logger | None = None,
 562    ) -> str:
 563        """
 564        Send a toast message to the frontend.
 565
 566        Returns the sent message content, so that you can easily return or print it.
 567        """
 568        messages = " ".join(str(message) for message in messages)
 569
 570        if lg := (logger or self.logger):
 571            match type:
 572                case "default":
 573                    lg.debug(messages)
 574                case "message" | "info" | "success":
 575                    lg.info(messages)
 576                case "warning":
 577                    lg.warning(messages)
 578                case "error":
 579                    lg.error(messages)
 580                case _:
 581                    lg.debug(messages)
 582
 583        await self.session.send(toast_event(), {"type": type, "message": messages})
 584        return messages
 585
 586    async def download(self, filename: str, binary: bytes) -> None:
 587        """
 588        Send a file to the frontend for download.
 589        """
 590        data = base64.b64encode(binary).decode("utf-8")
 591        await self.session.send(download_event(), {"filename": filename, "data": data})
 592
 593    def observe(self, obj: object, **sync_attributes: str | EllipsisType) -> None:
 594        """
 595        Observe additional attributes, useful for when you're extending/subclassing an already Synced object, or when you want to observe multiple objects.
 596        """
 597        # TODO: append, deregister, re-register
 598
 599    # ========== Low-Level: State Management ========== #
 600    def _snapshot(self) -> dict[str, Any]:
 601        result = {}
 602
 603        if isinstance(self.obj, BaseModel):
 604            # TODO: maybe always explicitly serialize using TypeAdapters like below, since the model maybe be configured for other serialization use cases?
 605            result = self.obj.model_dump(
 606                mode="json",
 607                include=set(self.sync_attributes.keys()),
 608                warnings=False,
 609            )
 610        else:
 611            for attr, key in self.sync_attributes.items():
 612                value = getattr(self.obj, attr)
 613                if attr in self.type_adapters:
 614                    # Use TypeAdapter to serialize with warnings disabled
 615                    result[key] = self.type_adapters[attr].dump_python(
 616                        value, mode="json", warnings=False
 617                    )
 618                else:
 619                    result[key] = deepcopy(value)
 620
 621        if self.task_exposure:
 622            result[self.task_exposure] = list(self.running_tasks.keys())
 623
 624        return result
 625
 626    # ========== Low-Level: Register Event Callbacks ========== #
 627    def _register_event_handlers(self):
 628        """
 629        Register event handlers with the session using weak references.
 630
 631        This allows the Sync object (and its target object) to be garbage collected
 632        when no longer referenced, automatically cleaning up the handlers.
 633        """
 634        # Capture values needed for cleanup callback (avoid capturing 'self')
 635        session = self.session
 636        key = self.key
 637        send_on_init = self.send_on_init
 638
 639        # Create weak reference to self for use in wrappers
 640        weak_self: weakref.ref[Sync] = weakref.ref(self)
 641
 642        # Factory to create async wrappers that check if Sync is still alive
 643        def make_method_wrapper(method_name: str):
 644            async def wrapper(data: Any = None) -> None:
 645                sync = weak_self()
 646                if sync is None:
 647                    return  # Sync was garbage collected
 648                method = getattr(sync, method_name)
 649                if data is not None:
 650                    await method(data)
 651                else:
 652                    await method()
 653
 654            return wrapper
 655
 656        # Create wrappers for the core state handlers
 657        send_state_wrapper = make_method_wrapper("_send_state")
 658        set_state_wrapper = make_method_wrapper("_set_state")
 659        patch_state_wrapper = make_method_wrapper("_patch_state")
 660
 661        # Create wrappers for action/task handlers if they exist
 662        actions_wrapper = None
 663        if self.actions:
 664            original_actions = self.actions
 665
 666            async def _actions_wrapper(data: Any):
 667                sync = weak_self()
 668                if sync is None:
 669                    return
 670                await original_actions(data)
 671
 672            actions_wrapper = _actions_wrapper
 673
 674        tasks_wrapper = None
 675        if self.tasks:
 676            original_tasks = self.tasks
 677
 678            async def _tasks_wrapper(data: Any):
 679                sync = weak_self()
 680                if sync is None:
 681                    return
 682                await original_tasks(data)
 683
 684            tasks_wrapper = _tasks_wrapper
 685
 686        task_cancels_wrapper = None
 687        if self.task_cancels:
 688            original_task_cancels = self.task_cancels
 689
 690            async def _task_cancels_wrapper(data: Any):
 691                sync = weak_self()
 692                if sync is None:
 693                    return
 694                await original_task_cancels(data)
 695
 696            task_cancels_wrapper = _task_cancels_wrapper
 697
 698        # Register handlers with session
 699        session.register_event(get_event(key), send_state_wrapper)
 700        session.register_event(set_event(key), set_state_wrapper)
 701        session.register_event(patch_event(key), patch_state_wrapper)
 702
 703        if send_on_init:
 704            session.register_init(send_state_wrapper)
 705
 706        if actions_wrapper:
 707            session.register_event(action_event(key), actions_wrapper)
 708
 709        if tasks_wrapper:
 710            session.register_event(task_start_event(key), tasks_wrapper)
 711
 712        if task_cancels_wrapper:
 713            session.register_event(task_cancel_event(key), task_cancels_wrapper)
 714
 715        # Store wrapper references for cleanup - we need to check identity before removing
 716        # to avoid removing handlers that were overwritten by a newer Sync with same key
 717        registered_handlers: dict[str, Callable[..., Any]] = {
 718            get_event(key): send_state_wrapper,
 719            set_event(key): set_state_wrapper,
 720            patch_event(key): patch_state_wrapper,
 721        }
 722        if actions_wrapper:
 723            registered_handlers[action_event(key)] = actions_wrapper
 724        if tasks_wrapper:
 725            registered_handlers[task_start_event(key)] = tasks_wrapper
 726        if task_cancels_wrapper:
 727            registered_handlers[task_cancel_event(key)] = task_cancels_wrapper
 728
 729        init_wrapper_to_remove = send_state_wrapper if send_on_init else None
 730
 731        # Create cleanup callback that runs when Sync is garbage collected
 732        # This callback must NOT capture 'self' - only the variables above
 733        def _weak_cleanup_callback(_dead_ref: weakref.ref[Sync]):
 734            # Handle mock sessions gracefully (used in tests)
 735            if not hasattr(session, "event_handlers"):
 736                return
 737
 738            # Only deregister handlers if they're still ours (not overwritten by newer Sync)
 739            for event_key, our_handler in registered_handlers.items():
 740                current_handler = session.event_handlers.get(event_key)
 741                if current_handler is our_handler:
 742                    session.deregister_event(event_key)
 743
 744            # Remove from init_handlers list if applicable
 745            if init_wrapper_to_remove is not None:
 746                with suppress(ValueError):
 747                    session.init_handlers.remove(init_wrapper_to_remove)
 748
 749        # Store the weak reference with cleanup callback
 750        # This ref must be stored to prevent immediate GC of the ref object itself
 751        self._weak_self_ref = weakref.ref(self, _weak_cleanup_callback)
 752
 753        # Store references for manual deregistration via close()
 754        self._init_wrapper = init_wrapper_to_remove
 755        self._registered_handlers = registered_handlers
 756        self._closed = False
 757
 758    def _deregister(self):
 759        """
 760        Remove all event handlers from the session.
 761
 762        This is called automatically when the Sync is garbage collected,
 763        but can also be called manually via close() for immediate cleanup.
 764        """
 765        if self._closed:
 766            return
 767        self._closed = True
 768
 769        # Only deregister handlers if they're still ours (not overwritten by newer Sync)
 770        for event_key, our_handler in self._registered_handlers.items():
 771            current_handler = self.session.event_handlers.get(event_key)
 772            if current_handler is our_handler:
 773                self.session.deregister_event(event_key)
 774
 775        # Remove from init_handlers list if applicable
 776        if self._init_wrapper is not None:
 777            with suppress(ValueError):
 778                self.session.init_handlers.remove(self._init_wrapper)
 779
 780    def close(self):
 781        """
 782        Explicitly close this Sync and deregister all handlers.
 783
 784        Call this when you're done with a Sync object to immediately release
 785        resources. If not called, cleanup happens automatically when the
 786        Sync is garbage collected.
 787
 788        This is idempotent - calling it multiple times is safe.
 789        """
 790        self._deregister()
 791
 792    async def _send_state(self, _: Any = None):
 793        self.state_snapshot = self._snapshot()
 794        await self.session.send(set_event(self.key), self.state_snapshot)
 795
 796    async def _set_state(self, new_state: dict[str, Any]):
 797        for key, val in new_state.items():
 798            if key == self.task_exposure:
 799                continue
 800
 801            attr_name = self.key_to_attr[key]
 802            value = deepcopy(val)
 803
 804            # if isinstance(self.obj, BaseModel):
 805            #     value = validate_model_field(type(self.obj), attr_name, value)
 806            if attr_name in self.type_adapters:
 807                value = self.type_adapters[attr_name].validate_python(value)
 808
 809            try:
 810                setattr(self.obj, attr_name, value)
 811            except AttributeError:
 812                # Check if this is a computed field without setter - if so, skip silently
 813                if (
 814                    isinstance(self.obj, BaseModel)
 815                    and attr_name in type(self.obj).model_computed_fields
 816                ):
 817                    computed_field = type(self.obj).model_computed_fields[attr_name]
 818                    if computed_field.wrapped_property.fset is None:
 819                        # Read-only computed field - skip setting, it will be recalculated
 820                        continue
 821
 822                # For other readonly attributes, skip setting
 823                # Don't assert value equality because dependent properties may have changed
 824                # when other attributes were set earlier in this loop
 825
 826        self.state_snapshot = new_state  # update latest snapshot
 827
 828    async def _patch_state(self, patch: list[dict[str, Any]]):
 829        # Apply patch to the snapshot first to update state tracking
 830        self.state_snapshot = jsonpatch.apply_patch(
 831            self.state_snapshot, patch, in_place=True
 832        )
 833
 834        # Extract the keys that were actually modified by the patch
 835        modified_keys = set()
 836        for patch_op in patch:
 837            path = patch_op["path"]
 838            if path.startswith("/"):
 839                # Extract the top-level key from the path
 840                key = path.split("/")[1]
 841                if key in self.key_to_attr:
 842                    modified_keys.add(key)
 843
 844        # Only set attributes that were actually modified by the patch
 845        for key in modified_keys:
 846            if key == self.task_exposure:
 847                continue
 848
 849            attr_name = self.key_to_attr[key]
 850            value = deepcopy(self.state_snapshot[key])
 851
 852            # if isinstance(self.obj, BaseModel):
 853            #     value = validate_model_field(type(self.obj), attr_name, value)
 854            if attr_name in self.type_adapters:
 855                value = self.type_adapters[attr_name].validate_python(value)
 856
 857            try:
 858                setattr(self.obj, attr_name, value)
 859            except AttributeError:
 860                # Check if this is a computed field without setter - if so, skip silently
 861                if (
 862                    isinstance(self.obj, BaseModel)
 863                    and attr_name in type(self.obj).model_computed_fields
 864                ):
 865                    computed_field = type(self.obj).model_computed_fields[attr_name]
 866                    if computed_field.wrapped_property.fset is None:
 867                        # Read-only computed field - skip setting, it will be recalculated
 868                        continue
 869
 870                # For other readonly attributes, skip setting
 871                # Don't assert value equality because dependent properties may have changed
 872                # when other attributes were set earlier in this loop
 873
 874    def _create_action_handler(
 875        self,
 876        obj: object,
 877        handlers: Mapping[str, Callable[..., Any]],
 878    ) -> Callable[[dict[str, Any]], Awaitable[None]]:
 879        # Use weakrefs to avoid preventing GC of self and obj
 880        weak_self: weakref.ref[Sync] = weakref.ref(self)
 881        weak_obj: weakref.ref[object] = weakref.ref(obj)
 882
 883        async def _handle_action(action: dict):
 884            sync = weak_self()
 885            target = weak_obj()
 886            if sync is None or target is None:
 887                return  # Already garbage collected
 888
 889            action_type = action.pop("type")
 890            if handler := handlers.get(action_type):
 891                # Validate action parameters, including converting to python
 892                if validator := sync.action_validators.get(action_type):
 893                    validated = validator.validate_python(action)
 894                    if isinstance(validated, BaseModel):
 895                        # Extract native Python objects (BaseModel/dataclass/etc.)
 896                        kwargs = {
 897                            name: getattr(validated, name)
 898                            for name in type(validated).model_fields
 899                        }
 900                    else:
 901                        kwargs = validated  # already a dict-like structure
 902                else:
 903                    kwargs = action
 904
 905                # Call the underlying action handler
 906                if getattr(handler, "__self__", None) is None:
 907                    await nonblock_call(
 908                        handler, target, **kwargs
 909                    )  # handler is unbound to an instance
 910                else:
 911                    await nonblock_call(
 912                        handler, **kwargs
 913                    )  # handler is bound to an instance
 914            else:
 915                warnings.warn(f"No handler for action {action_type}", stacklevel=1)
 916
 917        return _handle_action
 918
 919    def _create_task_handlers(
 920        self,
 921        obj: object,
 922        factories: Mapping[str, Callable[..., Awaitable[Any]]],
 923        on_cancel: Mapping[str, Callable[..., Awaitable[Any]]] | None,
 924    ) -> tuple[
 925        Callable[[dict[str, Any]], Awaitable[None]],
 926        Callable[[dict[str, Any]], Awaitable[None]],
 927    ]:
 928        # Use weakrefs to avoid preventing GC of self and obj
 929        weak_self: weakref.ref[Sync] = weakref.ref(self)
 930        weak_obj: weakref.ref[object] = weakref.ref(obj)
 931
 932        async def _run_and_pop(task: Awaitable, task_type: str):
 933            sync = weak_self()
 934            try:
 935                await task
 936            except asyncio.CancelledError:
 937                if sync and sync.logger:
 938                    sync.logger.info("Task %s cancelled", task_type)
 939                if on_cancel and task_type in on_cancel:
 940                    await on_cancel[task_type]()
 941                raise
 942            finally:
 943                if sync:
 944                    sync.running_tasks.pop(task_type, None)
 945                    if sync.task_exposure:
 946                        await sync.sync()
 947
 948        async def _create_task(task_args: dict):
 949            sync = weak_self()
 950            target = weak_obj()
 951            if sync is None or target is None:
 952                return  # Already garbage collected
 953
 954            task_type = task_args.pop("type")
 955            if factory := factories.get(task_type):
 956                if task_type in sync.running_tasks:
 957                    if sync.logger:
 958                        sync.logger.warning("Task %s already running", task_type)
 959                    return
 960
 961                if validator := sync.task_validators.get(task_type):
 962                    validated = validator.validate_python(task_args)
 963                    if isinstance(validated, BaseModel):
 964                        # Extract native Python objects (BaseModel/dataclass/etc.)
 965                        kwargs = {
 966                            name: getattr(validated, name)
 967                            for name in type(validated).model_fields
 968                        }
 969                    else:
 970                        kwargs = validated  # already a dict-like structure
 971                else:
 972                    kwargs = task_args
 973
 974                # Create the task
 975                if getattr(factory, "__self__", None) is None:
 976                    todo = nonblock_call(
 977                        factory, target, **kwargs
 978                    )  # factory is unbound to an instance
 979                else:
 980                    todo = nonblock_call(
 981                        factory, **kwargs
 982                    )  # factory is bound to an instance
 983
 984                task = asyncio.create_task(_run_and_pop(todo, task_type))
 985                sync.running_tasks[task_type] = task
 986                if sync.task_exposure:
 987                    await sync.sync()
 988            else:
 989                warnings.warn(f"No factory for task {task_type}", stacklevel=1)
 990
 991        async def _cancel_task(task_args: dict):
 992            sync = weak_self()
 993            if sync is None:
 994                return  # Already garbage collected
 995
 996            task_type = task_args.pop("type")
 997            if running_task := sync.running_tasks.get(task_type):
 998                running_task.cancel()
 999            elif sync.logger:
1000                sync.logger.warning("Task %s not running", task_type)
1001
1002        return _create_task, _cancel_task
1003
1004    # ========== Utils ========== #
1005    def casing(self, attr: str) -> str:
1006        return self.casing_func(attr) if self.casing_func else attr
1007
1008    # ========== Static validator builders with caching ========== #
1009    _field_validators_cache: dict[type, dict[str, TypeAdapter[Any]]] = {}
1010    """{class: {field: TypeAdapter}}; Dynamically registered fields may be added at runtime"""
1011    _action_validators_cache: dict[type, dict[str, TypeAdapter[Any]]] = {}
1012    """{class: {action_key: TypeAdapter}}; Dynamically registered actions may be added at runtime"""
1013    _task_validators_cache: dict[type, dict[str, TypeAdapter[Any]]] = {}
1014    """{class: {task_key: TypeAdapter}}; Dynamically registered tasks may be added at runtime"""
1015
1016    @staticmethod
1017    def build_kwargs_model(
1018        target_cls: type,
1019        model_name: str,
1020        func: Callable[..., Any],
1021        alias_generator: Callable[[str], str] | AliasGenerator | None,
1022    ) -> type[BaseModel]:
1023        """
1024        Build a Pydantic model to validate the kwargs of a function.
1025        """
1026        sig = signature(func)
1027        fields: dict[str, tuple[Any, Any]] = {}
1028        for idx, (param_name, param) in enumerate(sig.parameters.items()):
1029            if idx == 0 and param_name == "self":
1030                continue
1031            if param.kind in (Parameter.VAR_POSITIONAL, Parameter.VAR_KEYWORD):
1032                continue
1033            annotation = (
1034                param.annotation if param.annotation is not Parameter.empty else Any
1035            )
1036            default = param.default if param.default is not Parameter.empty else ...
1037            fields[param_name] = (annotation, default)
1038
1039        cfg = ConfigDict(
1040            alias_generator=alias_generator,
1041            validate_by_name=True,  # Python -> Python (TODO: when?)
1042            validate_by_alias=True,  # JSON -> Python
1043        )
1044        model = create_model(
1045            model_name,
1046            __config__=cfg,
1047            __module__=target_cls.__module__,
1048            **cast("dict[str, Any]", fields),
1049        )
1050        return model
1051
1052    @staticmethod
1053    def build_field_validators(
1054        target_cls: type,
1055        *,
1056        field_whitelist: Iterable[str] | None = None,
1057        use_cache: bool = True,
1058    ) -> dict[str, TypeAdapter[Any]]:
1059        """
1060        Build a dictionary of field validators for a given class.
1061
1062        Args:
1063            target_cls: The class to build validators for.
1064            field_whitelist: A list of field names to include in the validators. If None, all fields are included.
1065            use_cache: Whether to use the cache.
1066        """
1067        if use_cache and target_cls in Sync._field_validators_cache:
1068            return Sync._field_validators_cache[target_cls]
1069
1070        validators: dict[str, TypeAdapter[Any]] = {}
1071        if issubclass(target_cls, BaseModel):
1072            for name, field in target_cls.model_fields.items():
1073                validators[name] = TypeAdapter(field.annotation)
1074            for name, field in target_cls.model_computed_fields.items():
1075                validators[name] = TypeAdapter(field.return_type)
1076
1077        else:
1078            type_hints = get_type_hints(target_cls)
1079            if field_whitelist is not None:
1080                type_hints = {
1081                    field: annotation
1082                    for field in field_whitelist
1083                    if (annotation := type_hints.get(field))
1084                }
1085            for name, annotation in type_hints.items():
1086                try:
1087                    validators[name] = TypeAdapter(annotation)
1088                except PydanticSchemaGenerationError:
1089                    logger.exception("Error building validator for %s", name)
1090
1091        if use_cache:
1092            Sync._field_validators_cache[target_cls] = validators
1093        return validators
1094
1095    @staticmethod
1096    def build_action_validators(
1097        target_cls: type,
1098        *,
1099        actions: dict[str, Callable[..., Any]] | None = None,
1100        schema_title_generator: SchemaTitleGenerator = default_action_title_generator,
1101        param_alias_generator: Callable[[str], str] | AliasGenerator | None = None,
1102        use_cache: bool = True,
1103    ) -> dict[str, TypeAdapter[Any]]:
1104        """
1105        Build a dictionary of action validators for a given class.
1106
1107        Args:
1108            target_cls: The class whose actions to build validators for.
1109            actions: A dictionary of action names to functions. If None, all actions are included.
1110            schema_title_generator: A function to set the JSON schema title for each action.
1111            param_alias_generator: A function to set the JSON schema alias for the action *parameter names*.
1112            use_cache: Whether to use the cache for the validator objects.
1113        """
1114        if param_alias_generator is None:
1115            param_alias_generator = get_alias_function_for_class(target_cls)
1116
1117        validators: dict[str, TypeAdapter[Any]] = {}
1118
1119        cache_key = target_cls
1120        if use_cache and cache_key in Sync._action_validators_cache:
1121            validators = Sync._action_validators_cache[cache_key]
1122
1123        actions = actions or find_remote_actions(target_cls)
1124        for key, func in actions.items():
1125            if key in validators:
1126                continue
1127
1128            model = Sync.build_kwargs_model(
1129                target_cls=target_cls,
1130                model_name=schema_title_generator(
1131                    class_name=target_cls.__name__, key=key
1132                ),
1133                func=func,
1134                alias_generator=param_alias_generator,
1135            )
1136            validators[key] = TypeAdapter(model)
1137
1138        if use_cache:
1139            Sync._action_validators_cache[cache_key] = validators
1140        return validators
1141
1142    @staticmethod
1143    def build_task_validators(
1144        target_cls: type,
1145        *,
1146        tasks: dict[str, Callable[..., Any]] | None = None,
1147        schema_title_generator: SchemaTitleGenerator = default_task_title_generator,
1148        param_alias_generator: Callable[[str], str] | AliasGenerator | None = None,
1149        use_cache: bool = True,
1150    ) -> dict[str, TypeAdapter[Any]]:
1151        """
1152        Build a dictionary of task validators for a given class.
1153
1154        Args:
1155            target_cls: The class whose tasks to build validators for.
1156            tasks: A dictionary of task names to functions. If None, all tasks are included.
1157            schema_title_generator: A function to set the JSON schema title for each task.
1158            param_alias_generator: A function to set the JSON schema alias for the task *parameter names*.
1159            use_cache: Whether to use the cache for the validator objects.
1160        """
1161        if param_alias_generator is None:
1162            param_alias_generator = get_alias_function_for_class(target_cls)
1163
1164        validators: dict[str, TypeAdapter[Any]] = {}
1165
1166        cache_key = target_cls
1167        if use_cache and cache_key in Sync._task_validators_cache:
1168            validators = Sync._task_validators_cache[cache_key]
1169
1170        tasks = tasks or find_remote_tasks(target_cls)
1171        for key, func in tasks.items():
1172            if key in validators:
1173                continue
1174
1175            model = Sync.build_kwargs_model(
1176                target_cls=target_cls,
1177                model_name=schema_title_generator(
1178                    class_name=target_cls.__name__, key=key
1179                ),
1180                func=func,
1181                alias_generator=param_alias_generator,
1182            )
1183            validators[key] = TypeAdapter(model)
1184
1185        if use_cache:
1186            Sync._task_validators_cache[cache_key] = validators
1187        return validators

Register an object's attributes to this class to sync them with the frontend.

Sync( obj: object, key: str, *, sync_all: bool = False, include: dict[str, str | ellipsis] | list[str] | None = None, exclude: list[str] | None = None, toCamelCase: bool | None = None, send_on_init: bool = True, expose_running_tasks: bool = False, logger: logging.Logger | None = None, actions: Mapping[str, Callable[..., typing.Any]] | None = None, tasks: Mapping[str, Callable[..., Awaitable[typing.Any]]] | None = None, task_cancels: Mapping[str, Callable[..., Awaitable[typing.Any]]] | None = None)
329    def __init__(
330        self,
331        obj: object,
332        key: str,
333        *,
334        sync_all: bool = False,
335        include: dict[str, str | EllipsisType] | list[str] | None = None,
336        exclude: list[str] | None = None,
337        toCamelCase: bool | None = None,  # noqa: N803
338        send_on_init: bool = True,
339        expose_running_tasks: bool = False,
340        logger: Logger | None = None,
341        actions: Mapping[str, Callable[..., Any]] | None = None,
342        tasks: Mapping[str, Callable[..., Awaitable[Any]]] | None = None,
343        task_cancels: Mapping[str, Callable[..., Awaitable[Any]]] | None = None,
344    ):
345        """
346        Register the attributes that should be synced with the frontend.
347
348        Args:
349            obj: the object whose attributes should be synced
350            key: unique key for this object
351
352            sync_all: whether to sync all non-private attributes
353            include: attribute names to sync, value being either ...
354                or a string of the key of the attribute
355            exclude: list of attributes to exclude from syncing
356
357            toCamelCase: convert attribute names to camelCase. Must be ``None`` for
358                Pydantic models, which should configure ``alias_generator``
359            send_on_init: whether to send the state on connection init
360            expose_running_tasks: whether to expose the running tasks to the frontend
361            logger: logger to use for logging
362
363            actions: action handlers for each action type, each taking the data of the action as keyword arguments
364            tasks: either a dict of task factories for each task type, each returning a coroutine to be used as a task, or a tuple of (task_start_handler, task_cancel_handler)
365            task_cancels: a dict of task cancel handlers for each task type
366
367
368        """
369        self.obj = obj
370        self.key = _apply_sync_key_prefix(key)
371        self.send_on_init = send_on_init
372        self.casing_func = (
373            get_alias_function_for_class(type(self.obj))
374            if isinstance(self.obj, BaseModel)
375            else (to_camel if toCamelCase else None)
376        )
377        self.task_exposure = (
378            self.casing("running_tasks") if expose_running_tasks else None
379        )
380        self.logger = logger
381
382        # Convert list[str] include to dict format
383        if isinstance(include, list):
384            include = dict.fromkeys(include, ...)
385        include = include or {}
386        exclude = exclude or []
387
388        # Validate that BaseModel objects don't use custom sync keys
389        if isinstance(obj, BaseModel) and include:
390            for attr_name, sync_key in include.items():
391                assert sync_key is ..., (
392                    f"Custom sync key '{sync_key}' for attribute '{attr_name}' is not allowed for Pydantic models. Use pydantic's alias_generator in model_config instead."
393                )
394
395        self.session = session_context.get()
396        assert self.session, "No session set, use the session.session_context variable!"
397
398        # ========== Create Action Validators (cached) ========== #
399        actions = dict(actions or {}) | find_remote_actions(type(self.obj))
400        self.action_validators: dict[str, TypeAdapter[Any]] = (
401            self.build_action_validators(
402                target_cls=type(self.obj),
403                actions=actions,
404                param_alias_generator=self.casing_func,
405            )
406        )
407        # Create action handler after validators are ready
408        self.actions = self._create_action_handler(obj, actions)
409
410        # ========== Create Task Validators (cached) ========== #
411        tasks = dict(tasks or {}) | find_remote_tasks(type(self.obj))
412        task_cancels = dict(task_cancels or {}) | find_remote_task_cancellers(
413            type(self.obj)
414        )
415        self.task_validators: dict[str, TypeAdapter[Any]] = self.build_task_validators(
416            target_cls=type(self.obj),
417            tasks=tasks,
418            param_alias_generator=self.casing_func,
419        )
420        self.tasks, self.task_cancels = self._create_task_handlers(
421            obj, tasks, task_cancels
422        )
423
424        # store running tasks
425        self.running_tasks: dict[str, asyncio.Task[Any]] = {}
426
427        # ========== Find attributes to sync ========== #
428        self.sync_attributes: dict[str, str] = {}
429
430        # observe all non-private attributes
431        if sync_all:
432            if isinstance(obj, BaseModel):
433                # Include regular fields
434                for field in type(obj).model_fields:
435                    if field in exclude:
436                        continue
437                    self.sync_attributes[field] = self.casing(field)
438
439                # Include computed fields
440                for field in type(obj).model_computed_fields:
441                    if field in exclude:
442                        continue
443                    self.sync_attributes[field] = self.casing(field)
444            else:
445                for attr_name in dir(obj):
446                    try:
447                        attr = getattr(obj, attr_name)
448                    except AttributeError:
449                        continue
450                    if (
451                        attr_name in exclude
452                        or attr_name.startswith("_")
453                        or callable(attr)
454                        or isinstance(attr, Sync)
455                    ):
456                        continue
457
458                    self.sync_attributes[attr_name] = self.casing(attr_name)
459
460        # observe specific attributes
461        for attr_name, sync_key in include.items():
462            self.sync_attributes[attr_name] = (
463                self.casing(attr_name) if sync_key is ... else sync_key
464            )
465
466        # create reverse-lookup for patching
467        self.key_to_attr: dict[str, str] = {
468            key: attr for attr, key in self.sync_attributes.items()
469        }
470
471        # ========== Debugging ========== #
472        if self.logger:
473            self.logger.debug("%s: Syncing %s", self.key, self.sync_attributes)
474            self.logger.debug("%s: Actions %s", self.key, actions)
475            self.logger.debug("%s: Tasks %s", self.key, tasks)
476            self.logger.debug("%s: Task Cancels %s", self.key, task_cancels)
477
478        assert include.keys().isdisjoint(exclude), "Attribute in both include & exclude"
479        assert all(a in dir(obj) for a in self.sync_attributes), "Attribute not found"
480        assert all(e in dir(obj) for e in exclude), "Excluded attribute not found"
481        # assert (
482        #     len(self.sync_attributes) + expose_running_tasks > 0
483        # ), "No attributes to sync"
484
485        # ========== Field Type Adapters (cached) ========== #
486        self.type_adapters: dict[str, TypeAdapter[Any]] = self.build_field_validators(
487            type(obj), field_whitelist=self.sync_attributes.keys()
488        )
489
490        # ========== State Management ========== #
491        # the snapshot is the exact state that the frontend has, for patching
492        self.state_snapshot: dict[str, Any] = self._snapshot()
493        self._last_sync: float | None = None  # timestamp of last sync
494
495        # ========== Weak Reference Cleanup State ========== #
496        self._closed = False
497        self._init_wrapper: Callable[..., Any] | None = None
498        self._registered_handlers: dict[str, Callable[..., Any]] = {}
499        self._weak_self_ref: weakref.ref[Sync] | None = None
500        self._register_event_handlers()

Register the attributes that should be synced with the frontend.

Arguments:
  • obj: the object whose attributes should be synced
  • key: unique key for this object
  • sync_all: whether to sync all non-private attributes
  • include: attribute names to sync, value being either ... or a string of the key of the attribute
  • exclude: list of attributes to exclude from syncing
  • toCamelCase: convert attribute names to camelCase. Must be None for Pydantic models, which should configure alias_generator
  • send_on_init: whether to send the state on connection init
  • expose_running_tasks: whether to expose the running tasks to the frontend
  • logger: logger to use for logging
  • actions: action handlers for each action type, each taking the data of the action as keyword arguments
  • tasks: either a dict of task factories for each task type, each returning a coroutine to be used as a task, or a tuple of (task_start_handler, task_cancel_handler)
  • task_cancels: a dict of task cancel handlers for each task type
@classmethod
def all( cls, obj: object, key: str, *, include: dict[str, str | ellipsis] | list[str] | None = None, exclude: list[str] | None = None, toCamelCase: bool | None = None, send_on_init: bool = True, expose_running_tasks: bool = False, logger: logging.Logger | None = None, actions: Mapping[str, Callable[..., typing.Any]] | None = None, tasks: Mapping[str, Callable[..., Awaitable[typing.Any]]] | None = None, task_cancels: Mapping[str, Callable[..., Awaitable[typing.Any]]] | None = None) -> Sync:
193    @classmethod
194    def all(
195        cls,
196        obj: object,
197        key: str,
198        *,
199        include: dict[str, str | EllipsisType] | list[str] | None = None,
200        exclude: list[str] | None = None,
201        toCamelCase: bool | None = None,  # noqa: N803
202        send_on_init: bool = True,
203        expose_running_tasks: bool = False,
204        logger: Logger | None = None,
205        actions: Mapping[str, Callable[..., Any]] | None = None,
206        tasks: Mapping[str, Callable[..., Awaitable[Any]]] | None = None,
207        task_cancels: Mapping[str, Callable[..., Awaitable[Any]]] | None = None,
208    ) -> "Sync":
209        return cls(
210            obj=obj,
211            key=key,
212            sync_all=True,
213            include=include,
214            exclude=exclude or [],
215            toCamelCase=toCamelCase,
216            send_on_init=send_on_init,
217            expose_running_tasks=expose_running_tasks,
218            logger=logger,
219            actions=actions,
220            tasks=tasks,
221            task_cancels=task_cancels,
222        )
@classmethod
def only( cls, _obj: object, _key: str, *, _toCamelCase: bool | None = None, _send_on_init: bool = True, _expose_running_tasks: bool = False, _logger: logging.Logger | None = None, _actions: Mapping[str, Callable[..., typing.Any]] | None = None, _tasks: Mapping[str, Callable[..., Awaitable[typing.Any]]] | None = None, _task_cancels: Mapping[str, Callable[..., Awaitable[typing.Any]]] | None = None, **sync_attributes: str | ellipsis) -> Sync:
224    @classmethod
225    def only(
226        cls,
227        _obj: object,
228        _key: str,
229        *,
230        _toCamelCase: bool | None = None,  # noqa: N803
231        _send_on_init: bool = True,
232        _expose_running_tasks: bool = False,
233        _logger: Logger | None = None,
234        _actions: Mapping[str, Callable[..., Any]] | None = None,
235        _tasks: Mapping[str, Callable[..., Awaitable[Any]]] | None = None,
236        _task_cancels: Mapping[str, Callable[..., Awaitable[Any]]] | None = None,
237        **sync_attributes: str | EllipsisType,
238    ) -> "Sync":
239        return cls(
240            obj=_obj,
241            key=_key,
242            sync_all=False,
243            include=sync_attributes,
244            exclude=[],
245            toCamelCase=_toCamelCase,
246            send_on_init=_send_on_init,
247            expose_running_tasks=_expose_running_tasks,
248            logger=_logger,
249            actions=_actions,
250            tasks=_tasks,
251            task_cancels=_task_cancels,
252        )
@staticmethod
def resolve_attributes( obj_or_cls: object | type, *, include: dict[str, str | ellipsis] | None = None, exclude: list[str] | None = None, sync_all: bool = False, casing_func: Callable[[str], str] | None = None) -> dict[str, str]:
254    @staticmethod
255    def resolve_attributes(
256        obj_or_cls: object | type,
257        *,
258        include: dict[str, str | EllipsisType] | None = None,
259        exclude: list[str] | None = None,
260        sync_all: bool = False,
261        casing_func: Callable[[str], str] | None = None,
262    ) -> dict[str, str]:
263        """
264        Resolve which attributes to sync based on configuration.
265
266        Returns:
267            Dict mapping attribute name to sync key (alias).
268        """
269        include = include or {}
270        exclude = exclude or []
271        sync_attributes: dict[str, str] = {}
272
273        is_class = isinstance(obj_or_cls, type)
274        cls = obj_or_cls if is_class else type(obj_or_cls)
275
276        def casing(attr: str) -> str:
277            return casing_func(attr) if casing_func else attr
278
279        # observe all non-private attributes
280        if sync_all:
281            if issubclass(cls, BaseModel):
282                # Include regular fields
283                for field in cls.model_fields:
284                    if field in exclude:
285                        continue
286                    sync_attributes[field] = casing(field)
287
288                # Include computed fields
289                for field in cls.model_computed_fields:
290                    if field in exclude:
291                        continue
292                    sync_attributes[field] = casing(field)
293            # For regular classes, we need an instance to check dir() reliably for instance attrs,
294            # but we can check class attrs if we only have a class.
295            # However, if we only have a class, we can't know instance attributes that are set in __init__.
296            # So sync_all=True for plain classes really works best with an instance.
297            # If we have a class, we can only guess based on annotations or class attributes.
298            elif is_class:
299                # Best effort for static analysis of plain classes
300                # We can check type hints
301                for attr_name in get_type_hints(cls):
302                    if attr_name in exclude or attr_name.startswith("_"):
303                        continue
304                    sync_attributes[attr_name] = casing(attr_name)
305            else:
306                for attr_name in dir(obj_or_cls):
307                    try:
308                        attr = getattr(obj_or_cls, attr_name)
309                    except AttributeError:
310                        continue
311                    if (
312                        attr_name in exclude
313                        or attr_name.startswith("_")
314                        or callable(attr)
315                        or isinstance(attr, Sync)
316                    ):
317                        continue
318
319                    sync_attributes[attr_name] = casing(attr_name)
320
321        # observe specific attributes
322        for attr_name, sync_key in include.items():
323            sync_attributes[attr_name] = (
324                casing(attr_name) if sync_key is ... else cast(str, sync_key)
325            )
326
327        return sync_attributes

Resolve which attributes to sync based on configuration.

Returns:

Dict mapping attribute name to sync key (alias).

obj
key
send_on_init
casing_func
task_exposure
logger
session
action_validators: dict[str, pydantic.type_adapter.TypeAdapter[typing.Any]]
actions
task_validators: dict[str, pydantic.type_adapter.TypeAdapter[typing.Any]]
running_tasks: dict[str, _asyncio.Task[typing.Any]]
sync_attributes: dict[str, str]
key_to_attr: dict[str, str]
type_adapters: dict[str, pydantic.type_adapter.TypeAdapter[typing.Any]]
state_snapshot: dict[str, typing.Any]
async def sync(self, if_since_last: float | None = None):
503    async def sync(self, if_since_last: float | None = None):
504        """
505        Sync all registered attributes.
506
507        Args:
508            if_since_last: only sync if the last sync was before this many seconds
509        """
510        if not self.session.is_connected:
511            return
512        t = time()
513        if if_since_last and self._last_sync and t - self._last_sync < if_since_last:
514            return
515
516        # calculate patch
517        prev = self.state_snapshot
518        self.state_snapshot = self._snapshot()
519        patch = jsonpatch.make_patch(prev, self.state_snapshot).patch
520
521        if len(patch) > 0:
522            await self.session.send(patch_event(self.key), patch)
523            self._last_sync = t

Sync all registered attributes.

Arguments:
  • if_since_last: only sync if the last sync was before this many seconds
async def send_action(self, action: dict[str, typing.Any]):
543    async def send_action(self, action: dict[str, Any]):
544        """
545        Send an action to the frontend.
546        """
547        await self.session.send(action_event(self.key), action)

Send an action to the frontend.

async def send_binary(self, metadata: dict[str, typing.Any], data: bytes):
549    async def send_binary(self, metadata: dict[str, Any], data: bytes):
550        """
551        Send binary data to the frontend, along with metadata.
552
553        This is a subset of an action, but with bytes data always included.
554        """
555        await self.session.send_binary(action_event(self.key), metadata, data)

Send binary data to the frontend, along with metadata.

This is a subset of an action, but with bytes data always included.

async def toast( self, *messages, type: Literal['default', 'message', 'info', 'success', 'warning', 'error'] = 'default', logger: logging.Logger | None = None) -> str:
557    async def toast(
558        self,
559        *messages,
560        type: ToastType = "default",  # noqa: A002
561        logger: Logger | None = None,
562    ) -> str:
563        """
564        Send a toast message to the frontend.
565
566        Returns the sent message content, so that you can easily return or print it.
567        """
568        messages = " ".join(str(message) for message in messages)
569
570        if lg := (logger or self.logger):
571            match type:
572                case "default":
573                    lg.debug(messages)
574                case "message" | "info" | "success":
575                    lg.info(messages)
576                case "warning":
577                    lg.warning(messages)
578                case "error":
579                    lg.error(messages)
580                case _:
581                    lg.debug(messages)
582
583        await self.session.send(toast_event(), {"type": type, "message": messages})
584        return messages

Send a toast message to the frontend.

Returns the sent message content, so that you can easily return or print it.

async def download(self, filename: str, binary: bytes) -> None:
586    async def download(self, filename: str, binary: bytes) -> None:
587        """
588        Send a file to the frontend for download.
589        """
590        data = base64.b64encode(binary).decode("utf-8")
591        await self.session.send(download_event(), {"filename": filename, "data": data})

Send a file to the frontend for download.

def observe(self, obj: object, **sync_attributes: str | ellipsis) -> None:
593    def observe(self, obj: object, **sync_attributes: str | EllipsisType) -> None:
594        """
595        Observe additional attributes, useful for when you're extending/subclassing an already Synced object, or when you want to observe multiple objects.
596        """
597        # TODO: append, deregister, re-register

Observe additional attributes, useful for when you're extending/subclassing an already Synced object, or when you want to observe multiple objects.

def close(self):
780    def close(self):
781        """
782        Explicitly close this Sync and deregister all handlers.
783
784        Call this when you're done with a Sync object to immediately release
785        resources. If not called, cleanup happens automatically when the
786        Sync is garbage collected.
787
788        This is idempotent - calling it multiple times is safe.
789        """
790        self._deregister()

Explicitly close this Sync and deregister all handlers.

Call this when you're done with a Sync object to immediately release resources. If not called, cleanup happens automatically when the Sync is garbage collected.

This is idempotent - calling it multiple times is safe.

def casing(self, attr: str) -> str:
1005    def casing(self, attr: str) -> str:
1006        return self.casing_func(attr) if self.casing_func else attr
@staticmethod
def build_kwargs_model( target_cls: type, model_name: str, func: Callable[..., typing.Any], alias_generator: Callable[[str], str] | pydantic.aliases.AliasGenerator | None) -> type[pydantic.main.BaseModel]:
1016    @staticmethod
1017    def build_kwargs_model(
1018        target_cls: type,
1019        model_name: str,
1020        func: Callable[..., Any],
1021        alias_generator: Callable[[str], str] | AliasGenerator | None,
1022    ) -> type[BaseModel]:
1023        """
1024        Build a Pydantic model to validate the kwargs of a function.
1025        """
1026        sig = signature(func)
1027        fields: dict[str, tuple[Any, Any]] = {}
1028        for idx, (param_name, param) in enumerate(sig.parameters.items()):
1029            if idx == 0 and param_name == "self":
1030                continue
1031            if param.kind in (Parameter.VAR_POSITIONAL, Parameter.VAR_KEYWORD):
1032                continue
1033            annotation = (
1034                param.annotation if param.annotation is not Parameter.empty else Any
1035            )
1036            default = param.default if param.default is not Parameter.empty else ...
1037            fields[param_name] = (annotation, default)
1038
1039        cfg = ConfigDict(
1040            alias_generator=alias_generator,
1041            validate_by_name=True,  # Python -> Python (TODO: when?)
1042            validate_by_alias=True,  # JSON -> Python
1043        )
1044        model = create_model(
1045            model_name,
1046            __config__=cfg,
1047            __module__=target_cls.__module__,
1048            **cast("dict[str, Any]", fields),
1049        )
1050        return model

Build a Pydantic model to validate the kwargs of a function.

@staticmethod
def build_field_validators( target_cls: type, *, field_whitelist: Iterable[str] | None = None, use_cache: bool = True) -> dict[str, pydantic.type_adapter.TypeAdapter[typing.Any]]:
1052    @staticmethod
1053    def build_field_validators(
1054        target_cls: type,
1055        *,
1056        field_whitelist: Iterable[str] | None = None,
1057        use_cache: bool = True,
1058    ) -> dict[str, TypeAdapter[Any]]:
1059        """
1060        Build a dictionary of field validators for a given class.
1061
1062        Args:
1063            target_cls: The class to build validators for.
1064            field_whitelist: A list of field names to include in the validators. If None, all fields are included.
1065            use_cache: Whether to use the cache.
1066        """
1067        if use_cache and target_cls in Sync._field_validators_cache:
1068            return Sync._field_validators_cache[target_cls]
1069
1070        validators: dict[str, TypeAdapter[Any]] = {}
1071        if issubclass(target_cls, BaseModel):
1072            for name, field in target_cls.model_fields.items():
1073                validators[name] = TypeAdapter(field.annotation)
1074            for name, field in target_cls.model_computed_fields.items():
1075                validators[name] = TypeAdapter(field.return_type)
1076
1077        else:
1078            type_hints = get_type_hints(target_cls)
1079            if field_whitelist is not None:
1080                type_hints = {
1081                    field: annotation
1082                    for field in field_whitelist
1083                    if (annotation := type_hints.get(field))
1084                }
1085            for name, annotation in type_hints.items():
1086                try:
1087                    validators[name] = TypeAdapter(annotation)
1088                except PydanticSchemaGenerationError:
1089                    logger.exception("Error building validator for %s", name)
1090
1091        if use_cache:
1092            Sync._field_validators_cache[target_cls] = validators
1093        return validators

Build a dictionary of field validators for a given class.

Arguments:
  • target_cls: The class to build validators for.
  • field_whitelist: A list of field names to include in the validators. If None, all fields are included.
  • use_cache: Whether to use the cache.
@staticmethod
def build_action_validators( target_cls: type, *, actions: dict[str, Callable[..., typing.Any]] | None = None, schema_title_generator: ws_sync.sync.SchemaTitleGenerator = <function <lambda>>, param_alias_generator: Callable[[str], str] | pydantic.aliases.AliasGenerator | None = None, use_cache: bool = True) -> dict[str, pydantic.type_adapter.TypeAdapter[typing.Any]]:
1095    @staticmethod
1096    def build_action_validators(
1097        target_cls: type,
1098        *,
1099        actions: dict[str, Callable[..., Any]] | None = None,
1100        schema_title_generator: SchemaTitleGenerator = default_action_title_generator,
1101        param_alias_generator: Callable[[str], str] | AliasGenerator | None = None,
1102        use_cache: bool = True,
1103    ) -> dict[str, TypeAdapter[Any]]:
1104        """
1105        Build a dictionary of action validators for a given class.
1106
1107        Args:
1108            target_cls: The class whose actions to build validators for.
1109            actions: A dictionary of action names to functions. If None, all actions are included.
1110            schema_title_generator: A function to set the JSON schema title for each action.
1111            param_alias_generator: A function to set the JSON schema alias for the action *parameter names*.
1112            use_cache: Whether to use the cache for the validator objects.
1113        """
1114        if param_alias_generator is None:
1115            param_alias_generator = get_alias_function_for_class(target_cls)
1116
1117        validators: dict[str, TypeAdapter[Any]] = {}
1118
1119        cache_key = target_cls
1120        if use_cache and cache_key in Sync._action_validators_cache:
1121            validators = Sync._action_validators_cache[cache_key]
1122
1123        actions = actions or find_remote_actions(target_cls)
1124        for key, func in actions.items():
1125            if key in validators:
1126                continue
1127
1128            model = Sync.build_kwargs_model(
1129                target_cls=target_cls,
1130                model_name=schema_title_generator(
1131                    class_name=target_cls.__name__, key=key
1132                ),
1133                func=func,
1134                alias_generator=param_alias_generator,
1135            )
1136            validators[key] = TypeAdapter(model)
1137
1138        if use_cache:
1139            Sync._action_validators_cache[cache_key] = validators
1140        return validators

Build a dictionary of action validators for a given class.

Arguments:
  • target_cls: The class whose actions to build validators for.
  • actions: A dictionary of action names to functions. If None, all actions are included.
  • schema_title_generator: A function to set the JSON schema title for each action.
  • param_alias_generator: A function to set the JSON schema alias for the action parameter names.
  • use_cache: Whether to use the cache for the validator objects.
@staticmethod
def build_task_validators( target_cls: type, *, tasks: dict[str, Callable[..., typing.Any]] | None = None, schema_title_generator: ws_sync.sync.SchemaTitleGenerator = <function <lambda>>, param_alias_generator: Callable[[str], str] | pydantic.aliases.AliasGenerator | None = None, use_cache: bool = True) -> dict[str, pydantic.type_adapter.TypeAdapter[typing.Any]]:
1142    @staticmethod
1143    def build_task_validators(
1144        target_cls: type,
1145        *,
1146        tasks: dict[str, Callable[..., Any]] | None = None,
1147        schema_title_generator: SchemaTitleGenerator = default_task_title_generator,
1148        param_alias_generator: Callable[[str], str] | AliasGenerator | None = None,
1149        use_cache: bool = True,
1150    ) -> dict[str, TypeAdapter[Any]]:
1151        """
1152        Build a dictionary of task validators for a given class.
1153
1154        Args:
1155            target_cls: The class whose tasks to build validators for.
1156            tasks: A dictionary of task names to functions. If None, all tasks are included.
1157            schema_title_generator: A function to set the JSON schema title for each task.
1158            param_alias_generator: A function to set the JSON schema alias for the task *parameter names*.
1159            use_cache: Whether to use the cache for the validator objects.
1160        """
1161        if param_alias_generator is None:
1162            param_alias_generator = get_alias_function_for_class(target_cls)
1163
1164        validators: dict[str, TypeAdapter[Any]] = {}
1165
1166        cache_key = target_cls
1167        if use_cache and cache_key in Sync._task_validators_cache:
1168            validators = Sync._task_validators_cache[cache_key]
1169
1170        tasks = tasks or find_remote_tasks(target_cls)
1171        for key, func in tasks.items():
1172            if key in validators:
1173                continue
1174
1175            model = Sync.build_kwargs_model(
1176                target_cls=target_cls,
1177                model_name=schema_title_generator(
1178                    class_name=target_cls.__name__, key=key
1179                ),
1180                func=func,
1181                alias_generator=param_alias_generator,
1182            )
1183            validators[key] = TypeAdapter(model)
1184
1185        if use_cache:
1186            Sync._task_validators_cache[cache_key] = validators
1187        return validators

Build a dictionary of task validators for a given class.

Arguments:
  • target_cls: The class whose tasks to build validators for.
  • tasks: A dictionary of task names to functions. If None, all tasks are included.
  • schema_title_generator: A function to set the JSON schema title for each task.
  • param_alias_generator: A function to set the JSON schema alias for the task parameter names.
  • use_cache: Whether to use the cache for the validator objects.
class Session:
 23class Session:
 24    """
 25    A session is a persistent connection with the other.
 26
 27    This is a counter-part to the SessionManager in the frontend.
 28    There should be one instance of this class per user session, even across reconnects of the websocket. This means the states that belong to the user session should be subscribed to the events of this class.
 29    It defines a simple state-syncing protocol between the frontend and the backend, every event being of type {type: str, data: any}.
 30    """
 31
 32    def __init__(self, logger: Logger | None = logger):
 33        self.ws = None
 34        self.ws_lock = Lock()  # when multiple clients try to connect at the same time, we need to ensure that only one connection is established
 35        self.event_handlers: dict[str, Callable[..., Any]] = {}  # triggered on event
 36        self.init_handlers: list[
 37            Callable[..., Any]
 38        ] = []  # triggered on connection init
 39        self.logger = logger
 40        self.state: SessionState | None = None
 41        """user-assigned state associated with the session"""
 42        self._tokens: list[Token[Session]] = []
 43
 44    @property
 45    def is_connected(self) -> bool:
 46        return self.ws is not None
 47
 48    # ===== Low-Level: Register Event Callbacks =====#
 49    def register_event(self, event: str, callback: Callable[..., Any]):
 50        if event in self.event_handlers and self.logger:
 51            self.logger.warning("Event %s already has a subscriber.", event)
 52        self.event_handlers[event] = callback
 53
 54    def deregister_event(self, event: str):
 55        if event not in self.event_handlers:
 56            if self.logger:
 57                self.logger.warning("Event %s has no subscriber.", event)
 58            return
 59        del self.event_handlers[event]
 60
 61    def register_init(self, callback: Callable[..., Any]):
 62        self.init_handlers.append(callback)
 63
 64    # ===== Low-Level: Networking =====#
 65    async def new_connection(self, ws: WebSocket):
 66        """
 67        Set the new ws connection while possibly gracefully disconnecting the old one.
 68        """
 69        async with self.ws_lock:
 70            if self.ws is not None:
 71                if self.logger:
 72                    self.logger.warning(
 73                        "Overwriting existing websocket %s with %s",
 74                        self.ws.client,
 75                        ws.client,
 76                    )
 77                await self.disconnect()
 78            self.ws = ws
 79
 80        if self.ws.application_state == WebSocketState.CONNECTING:
 81            await self.ws.accept()
 82
 83        await self.init()
 84
 85    async def disconnect(
 86        self,
 87        message: str = "Seems like you're logged in somewhere else. If this is a mistake, please refresh the page.",
 88        ws: WebSocket | None = None,
 89    ):
 90        """
 91        Disconnect the websocket connection after sending a message.
 92        """
 93        # TODO: not sure why I made the ws argument, but I will keep it for now.
 94        if ws:
 95            self.ws = ws
 96        if self.ws is None:
 97            return
 98        await self.send("_DISCONNECT", message)
 99        assert self.ws is not None
100        with suppress(Exception):
101            await self.ws.close()
102        self.ws = None
103
104    async def init(self):
105        for handler in self.init_handlers:
106            await nonblock_call(handler)
107
108    async def send(self, event: str, data: Any):
109        if self.ws is None:
110            return
111        try:
112            await self.ws.send_json({"type": event, "data": data})
113        except Exception:
114            if self.logger:
115                self.logger.exception("Error sending event %s", event)
116
117    async def send_binary(self, event: str, metadata: dict[str, Any], data: bytes):
118        if self.ws is None:
119            return
120        try:
121            await self.ws.send_json(
122                {"type": "_BIN_META", "data": {"type": event, "metadata": metadata}}
123            )
124            await self.ws.send_bytes(data)
125        except Exception:
126            if self.logger:
127                self.logger.exception("Error sending binary event %s", event)
128
129    async def handle_connection(self, ws: WebSocket | None = None):
130        """
131        Handler that blocks until the websocket is disconnected. It takes care of accepting the websocket connection, and dispatching events to the appropriate handlers. If the ws argument is provided, it will be used as the websocket connection, otherwise it will use the existing connection.
132
133        Args:
134            ws: The websocket connection to use. If None, it will use the existing connection.
135        """
136        if ws:
137            await self.new_connection(ws)
138
139        assert self.ws is not None
140
141        with self:  # provide the session context
142            try:
143                if self.state:
144                    await self.state.on_connect()
145            except Exception:
146                if self.logger:
147                    self.logger.exception("Error while calling state.on_connect")
148
149            try:
150                while self.ws.application_state == WebSocketState.CONNECTED:
151                    full_data = await self.ws.receive_json()
152                    event = full_data.get("type")
153                    data = full_data.get("data")
154
155                    if event == "_BIN_META":
156                        # unwrap and construct the original event
157                        event = data.get("type")
158                        metadata = data.get("metadata")
159                        bindata = await self.ws.receive_bytes()
160                        data = {"data": bindata, **metadata}
161
162                    if handler := self.event_handlers.get(event):
163                        await nonblock_call(handler, data)
164                    elif self.logger:
165                        self.logger.warning(
166                            "Received event %s but no subscriber was found.", event
167                        )
168            except WebSocketDisconnect:
169                if self.logger:
170                    self.logger.info("Websocket disconnected")
171            except Exception:
172                if self.logger:
173                    self.logger.exception("Error while handling connection")
174            finally:
175                try:
176                    if self.state:
177                        await self.state.on_disconnect()
178                except Exception:
179                    if self.logger:
180                        self.logger.exception("Error while calling state.on_disconnect")
181                with suppress(Exception):
182                    ws = self.ws
183                    self.ws = None
184                    if ws is not None:
185                        await ws.close()
186
187    # ===== High-Level: Context Manager =====#
188    def __enter__(self) -> Self:
189        token = session_context.set(self)
190        self._tokens.append(token)
191        return self
192
193    def __exit__(
194        self,
195        exc_type: type[BaseException] | None,
196        exc_value: BaseException | None,
197        traceback: object,
198    ):
199        if self._tokens:
200            token = self._tokens.pop()
201            session_context.reset(token)

A session is a persistent connection with the other.

This is a counter-part to the SessionManager in the frontend. There should be one instance of this class per user session, even across reconnects of the websocket. This means the states that belong to the user session should be subscribed to the events of this class. It defines a simple state-syncing protocol between the frontend and the backend, every event being of type {type: str, data: any}.

Session(logger: logging.Logger | None = <Logger ws_sync.session (WARNING)>)
32    def __init__(self, logger: Logger | None = logger):
33        self.ws = None
34        self.ws_lock = Lock()  # when multiple clients try to connect at the same time, we need to ensure that only one connection is established
35        self.event_handlers: dict[str, Callable[..., Any]] = {}  # triggered on event
36        self.init_handlers: list[
37            Callable[..., Any]
38        ] = []  # triggered on connection init
39        self.logger = logger
40        self.state: SessionState | None = None
41        """user-assigned state associated with the session"""
42        self._tokens: list[Token[Session]] = []
ws
ws_lock
event_handlers: dict[str, Callable[..., typing.Any]]
init_handlers: list[Callable[..., typing.Any]]
logger
state: SessionState | None

user-assigned state associated with the session

is_connected: bool
44    @property
45    def is_connected(self) -> bool:
46        return self.ws is not None
def register_event(self, event: str, callback: Callable[..., typing.Any]):
49    def register_event(self, event: str, callback: Callable[..., Any]):
50        if event in self.event_handlers and self.logger:
51            self.logger.warning("Event %s already has a subscriber.", event)
52        self.event_handlers[event] = callback
def deregister_event(self, event: str):
54    def deregister_event(self, event: str):
55        if event not in self.event_handlers:
56            if self.logger:
57                self.logger.warning("Event %s has no subscriber.", event)
58            return
59        del self.event_handlers[event]
def register_init(self, callback: Callable[..., typing.Any]):
61    def register_init(self, callback: Callable[..., Any]):
62        self.init_handlers.append(callback)
async def new_connection(self, ws: starlette.websockets.WebSocket):
65    async def new_connection(self, ws: WebSocket):
66        """
67        Set the new ws connection while possibly gracefully disconnecting the old one.
68        """
69        async with self.ws_lock:
70            if self.ws is not None:
71                if self.logger:
72                    self.logger.warning(
73                        "Overwriting existing websocket %s with %s",
74                        self.ws.client,
75                        ws.client,
76                    )
77                await self.disconnect()
78            self.ws = ws
79
80        if self.ws.application_state == WebSocketState.CONNECTING:
81            await self.ws.accept()
82
83        await self.init()

Set the new ws connection while possibly gracefully disconnecting the old one.

async def disconnect( self, message: str = "Seems like you're logged in somewhere else. If this is a mistake, please refresh the page.", ws: starlette.websockets.WebSocket | None = None):
 85    async def disconnect(
 86        self,
 87        message: str = "Seems like you're logged in somewhere else. If this is a mistake, please refresh the page.",
 88        ws: WebSocket | None = None,
 89    ):
 90        """
 91        Disconnect the websocket connection after sending a message.
 92        """
 93        # TODO: not sure why I made the ws argument, but I will keep it for now.
 94        if ws:
 95            self.ws = ws
 96        if self.ws is None:
 97            return
 98        await self.send("_DISCONNECT", message)
 99        assert self.ws is not None
100        with suppress(Exception):
101            await self.ws.close()
102        self.ws = None

Disconnect the websocket connection after sending a message.

async def init(self):
104    async def init(self):
105        for handler in self.init_handlers:
106            await nonblock_call(handler)
async def send(self, event: str, data: Any):
108    async def send(self, event: str, data: Any):
109        if self.ws is None:
110            return
111        try:
112            await self.ws.send_json({"type": event, "data": data})
113        except Exception:
114            if self.logger:
115                self.logger.exception("Error sending event %s", event)
async def send_binary(self, event: str, metadata: dict[str, typing.Any], data: bytes):
117    async def send_binary(self, event: str, metadata: dict[str, Any], data: bytes):
118        if self.ws is None:
119            return
120        try:
121            await self.ws.send_json(
122                {"type": "_BIN_META", "data": {"type": event, "metadata": metadata}}
123            )
124            await self.ws.send_bytes(data)
125        except Exception:
126            if self.logger:
127                self.logger.exception("Error sending binary event %s", event)
async def handle_connection(self, ws: starlette.websockets.WebSocket | None = None):
129    async def handle_connection(self, ws: WebSocket | None = None):
130        """
131        Handler that blocks until the websocket is disconnected. It takes care of accepting the websocket connection, and dispatching events to the appropriate handlers. If the ws argument is provided, it will be used as the websocket connection, otherwise it will use the existing connection.
132
133        Args:
134            ws: The websocket connection to use. If None, it will use the existing connection.
135        """
136        if ws:
137            await self.new_connection(ws)
138
139        assert self.ws is not None
140
141        with self:  # provide the session context
142            try:
143                if self.state:
144                    await self.state.on_connect()
145            except Exception:
146                if self.logger:
147                    self.logger.exception("Error while calling state.on_connect")
148
149            try:
150                while self.ws.application_state == WebSocketState.CONNECTED:
151                    full_data = await self.ws.receive_json()
152                    event = full_data.get("type")
153                    data = full_data.get("data")
154
155                    if event == "_BIN_META":
156                        # unwrap and construct the original event
157                        event = data.get("type")
158                        metadata = data.get("metadata")
159                        bindata = await self.ws.receive_bytes()
160                        data = {"data": bindata, **metadata}
161
162                    if handler := self.event_handlers.get(event):
163                        await nonblock_call(handler, data)
164                    elif self.logger:
165                        self.logger.warning(
166                            "Received event %s but no subscriber was found.", event
167                        )
168            except WebSocketDisconnect:
169                if self.logger:
170                    self.logger.info("Websocket disconnected")
171            except Exception:
172                if self.logger:
173                    self.logger.exception("Error while handling connection")
174            finally:
175                try:
176                    if self.state:
177                        await self.state.on_disconnect()
178                except Exception:
179                    if self.logger:
180                        self.logger.exception("Error while calling state.on_disconnect")
181                with suppress(Exception):
182                    ws = self.ws
183                    self.ws = None
184                    if ws is not None:
185                        await ws.close()

Handler that blocks until the websocket is disconnected. It takes care of accepting the websocket connection, and dispatching events to the appropriate handlers. If the ws argument is provided, it will be used as the websocket connection, otherwise it will use the existing connection.

Arguments:
  • ws: The websocket connection to use. If None, it will use the existing connection.
class SessionState:
204class SessionState:
205    """
206    Abstract base class for user-defined session state objects that can be associated with a Session object.
207    """
208
209    async def on_connect(self):
210        """Called after the websocket connection is established."""
211
212    async def on_disconnect(self):
213        """Called after the websocket connection is closed."""
214
215    async def on_terminate(self):
216        """Called when the session is forcefully terminated by the server."""

Abstract base class for user-defined session state objects that can be associated with a Session object.

async def on_connect(self):
209    async def on_connect(self):
210        """Called after the websocket connection is established."""

Called after the websocket connection is established.

async def on_disconnect(self):
212    async def on_disconnect(self):
213        """Called after the websocket connection is closed."""

Called after the websocket connection is closed.

async def on_terminate(self):
215    async def on_terminate(self):
216        """Called when the session is forcefully terminated by the server."""

Called when the session is forcefully terminated by the server.

class Synced:
 24class Synced:
 25    """
 26    A mixin class that provides a `sync` attribute in a way that is compatible with any pydantic BaseModel subclass.
 27
 28    Making a class inherit from Synced means its fields are meant to be synced! Do not overload its usage for other serialization use cases unless it's guaranteed to be a 100% overlap with the synced use case.
 29
 30    Example with BaseModel:
 31    ```python
 32    class SyncedUser(Synced, BaseModel):
 33        name: str
 34        contacts: dict[str, str]
 35
 36        def model_post_init(self, context):
 37            # create the sync object
 38            self.sync = Sync.all(self, key="USER")
 39
 40    u = SyncedUser(name="John", contacts={"email": "[email protected]", "phone": "+1234567890"})
 41    await u.sync()
 42    ```
 43
 44    Example with custom BaseModel:
 45    ```python
 46    class MyBaseModel(BaseModel):
 47        # custom configuration
 48        pass
 49
 50    class SyncedUser(Synced, MyBaseModel):
 51        name: str
 52        contacts: dict[str, str]
 53
 54        def model_post_init(self, context):
 55            self.sync = Sync.all(self, key="USER")
 56    ```
 57    """
 58
 59    model_config = ConfigDict(
 60        # make fields with default values required in the JSON schema when mode="serialization"
 61        json_schema_serialization_defaults_required=True,
 62    )
 63
 64    _sync: Sync = PrivateAttr()
 65
 66    @property
 67    def sync(self):
 68        return self._sync
 69
 70    @sync.setter
 71    def sync(self, value: Sync):
 72        self._sync = value
 73
 74    def model_post_init(self, context: Any, /):
 75        """
 76        Called after model initialization.
 77
 78        Empty by default - decorators will override this to call user's model_post_init
 79        then initialize Sync.
 80        """
 81
 82    # ===== Class-level validator creation ===== #
 83    def __init_subclass__(cls, *, is_abstract: bool = False, **kwargs):
 84        """
 85        Initialize the subclass with the sync_key.
 86
 87        Args:
 88            is_abstract: Whether your subclass is still abstract, i.e. not meant to be instantiated.
 89        """
 90        super().__init_subclass__(**kwargs)
 91        if not is_abstract:
 92            assert issubclass(cls, BaseModel), (
 93                f"{cls.__name__} must inherit from BaseModel"
 94            )
 95            registered_synced_models[cls.__name__] = cls
 96
 97    @classmethod
 98    def generate_validators(cls):
 99        cls.field_validators = Sync.build_field_validators(cls)
100        cls.action_validators = Sync.build_action_validators(cls)
101        cls.task_validators = Sync.build_task_validators(cls)
102
103    @classmethod
104    def ws_sync_json_schema(
105        cls,
106        *,
107        always_include_validation_schema: bool = False,
108        schema_generator: type[GenerateJsonSchema] = GenerateJsonSchema,
109        ref_template: str = "#/$defs/{model}",
110    ):
111        """Returns a JSON schema suitable for ws_sync, meaning the model (all of its fields) as serialization, its action and task inputs as validation."""
112        assert issubclass(cls, BaseModel), f"{cls.__name__} must inherit from BaseModel"
113
114        cls.generate_validators()
115
116        # action and task validation schema
117        validation = list(cls.action_validators.items()) + list(
118            cls.task_validators.items()
119        )
120        if always_include_validation_schema:
121            validation.append(
122                ("MODEL CREATE", TypeAdapter(cls))
123            )  # FIXME: this includes all fields, not just the ones that are synced!
124
125        # model state serialization schema
126        serialization_adapter = TypeAdapter(cls)
127
128        if sync_config := getattr(cls, "_sync_config", None):
129            from ws_sync.utils import get_alias_function_for_class  # noqa: PLC0415
130
131            # Resolve attributes using the static config
132            casing_func = get_alias_function_for_class(cls)
133            synced_attrs = Sync.resolve_attributes(
134                obj_or_cls=cls,
135                include=sync_config.get("include"),
136                exclude=sync_config.get("exclude"),
137                sync_all=sync_config.get("sync_all", False),
138                casing_func=casing_func,
139            )
140
141            # Create a custom adapter that only includes the synced fields
142            field_definitions = {}
143            for name, field_info in cls.model_fields.items():
144                if name in synced_attrs:
145                    field_definitions[name] = (field_info.annotation, field_info)
146
147            fields = {}
148            for attr_name in synced_attrs:
149                if attr_name in cls.model_fields:
150                    fields[attr_name] = (
151                        cls.model_fields[attr_name].annotation,
152                        cls.model_fields[attr_name],
153                    )
154                elif attr_name in cls.model_computed_fields:
155                    # Computed fields are trickier to add to create_model dynamically to appear as fields
156                    # For schema generation purposes, we can treat them as read-only fields
157                    fields[attr_name] = (
158                        cls.model_computed_fields[attr_name].return_type,
159                        ...,
160                    )
161
162            # Create a new model just for schema generation
163            schema_model = create_model(
164                f"{cls.__name__}", **fields, __config__=cls.model_config
165            )
166            serialization_adapter = TypeAdapter(schema_model)
167
168        serialization = [("MODEL STATE", serialization_adapter)]
169
170        # merge all schemas
171        schema_inputs: list = [
172            (sync_key, "validation", validator) for sync_key, validator in validation
173        ] + [
174            (sync_key, "serialization", serializer)
175            for sync_key, serializer in serialization
176        ]
177        schemas, definitions = TypeAdapter.json_schemas(
178            schema_inputs, schema_generator=schema_generator, ref_template=ref_template
179        )
180
181        # Attach helper schemas for the remote actions
182        action_keys: list[str] = list(cls.action_validators)
183
184        # TODO: if the sync key is known at static time, include the sync key. How to deal with dynamic sync keys? Maybe instead of sync key it should just be an ID?
185        # # helps the frontend to know the model sync key
186        # schemas[("MODEL SYNC KEY", "validation")] = {
187        #     "description": "The sync key of the model",
188        #     "type": "string",
189        #     "enum": [class sync key here],
190        #     "title": f"{cls.__name__}SyncKey",
191        # }
192
193        # helps the frontend to know the possible actions
194        schemas[("REMOTE ACTIONS KEYS", "validation")] = {
195            "description": "Lists all action keys as enum values",
196            "type": "string",
197            "enum": action_keys,
198            "title": f"{cls.__name__}ActionsKeys",
199        }
200        # helps the frontend to know the possible parameters for each action
201        schemas[("REMOTE ACTIONS PARAMS", "validation")] = {
202            "description": "Maps each action keys to its parameters",
203            "properties": {
204                actions: nullify_if_empty(schemas[(actions, "validation")], definitions)
205                for actions in action_keys
206            },
207            "required": action_keys,
208            "title": f"{cls.__name__}ActionsParams",
209            "type": "object",
210        }
211
212        task_keys: list[str] = list(cls.task_validators)
213        schemas[("REMOTE TASKS KEYS", "validation")] = {
214            "description": "Lists all task keys as enum values",
215            "type": "string",
216            "enum": task_keys,
217            "title": f"{cls.__name__}TasksKeys",
218        }
219        schemas[("REMOTE TASKS PARAMS", "validation")] = {
220            "description": "Maps each task key to its parameters",
221            "properties": {
222                task: nullify_if_empty(schemas[(task, "validation")], definitions)
223                for task in task_keys
224            },
225            "required": task_keys,
226            "title": f"{cls.__name__}TasksParams",
227            "type": "object",
228        }
229
230        return schemas, definitions
231
232    @classmethod
233    def attach_to_openapi(
234        cls,
235        openapi: dict,
236        *,
237        always_include_validation_schema: bool = False,
238        schema_generator: type[GenerateJsonSchema] = CustomGenerateJsonSchema,
239    ) -> dict:
240        openapi = deepcopy(openapi)
241
242        if "components" not in openapi:
243            openapi["components"] = {"schemas": {}}
244
245        schemas, definitions = cls.ws_sync_json_schema(
246            always_include_validation_schema=always_include_validation_schema,
247            schema_generator=schema_generator,
248            ref_template="#/components/schemas/{model}",
249        )
250        deps = definitions.pop("$defs", {})
251        # either the remaining schema is a schema, or a $ref to a schema in deps
252        for schema in schemas.values():
253            if "title" in schema:
254                # schema is a schema
255                openapi["components"]["schemas"].update(
256                    {
257                        schema["title"]: schema,
258                    }
259                )
260            else:
261                # schema is a $ref to a schema, so already contained in deps
262                pass
263        openapi["components"]["schemas"].update(deps)
264
265        return openapi

A mixin class that provides a sync attribute in a way that is compatible with any pydantic BaseModel subclass.

Making a class inherit from Synced means its fields are meant to be synced! Do not overload its usage for other serialization use cases unless it's guaranteed to be a 100% overlap with the synced use case.

Example with BaseModel:

class SyncedUser(Synced, BaseModel):
    name: str
    contacts: dict[str, str]

    def model_post_init(self, context):
        # create the sync object
        self.sync = Sync.all(self, key="USER")

u = SyncedUser(name="John", contacts={"email": "[email protected]", "phone": "+1234567890"})
await u.sync()

Example with custom BaseModel:

class MyBaseModel(BaseModel):
    # custom configuration
    pass

class SyncedUser(Synced, MyBaseModel):
    name: str
    contacts: dict[str, str]

    def model_post_init(self, context):
        self.sync = Sync.all(self, key="USER")
model_config = {'json_schema_serialization_defaults_required': True}
sync
66    @property
67    def sync(self):
68        return self._sync
def model_post_init(self, context: Any, /):
74    def model_post_init(self, context: Any, /):
75        """
76        Called after model initialization.
77
78        Empty by default - decorators will override this to call user's model_post_init
79        then initialize Sync.
80        """

Called after model initialization.

Empty by default - decorators will override this to call user's model_post_init then initialize Sync.

@classmethod
def generate_validators(cls):
 97    @classmethod
 98    def generate_validators(cls):
 99        cls.field_validators = Sync.build_field_validators(cls)
100        cls.action_validators = Sync.build_action_validators(cls)
101        cls.task_validators = Sync.build_task_validators(cls)
@classmethod
def ws_sync_json_schema( cls, *, always_include_validation_schema: bool = False, schema_generator: type[pydantic.json_schema.GenerateJsonSchema] = <class 'pydantic.json_schema.GenerateJsonSchema'>, ref_template: str = '#/$defs/{model}'):
103    @classmethod
104    def ws_sync_json_schema(
105        cls,
106        *,
107        always_include_validation_schema: bool = False,
108        schema_generator: type[GenerateJsonSchema] = GenerateJsonSchema,
109        ref_template: str = "#/$defs/{model}",
110    ):
111        """Returns a JSON schema suitable for ws_sync, meaning the model (all of its fields) as serialization, its action and task inputs as validation."""
112        assert issubclass(cls, BaseModel), f"{cls.__name__} must inherit from BaseModel"
113
114        cls.generate_validators()
115
116        # action and task validation schema
117        validation = list(cls.action_validators.items()) + list(
118            cls.task_validators.items()
119        )
120        if always_include_validation_schema:
121            validation.append(
122                ("MODEL CREATE", TypeAdapter(cls))
123            )  # FIXME: this includes all fields, not just the ones that are synced!
124
125        # model state serialization schema
126        serialization_adapter = TypeAdapter(cls)
127
128        if sync_config := getattr(cls, "_sync_config", None):
129            from ws_sync.utils import get_alias_function_for_class  # noqa: PLC0415
130
131            # Resolve attributes using the static config
132            casing_func = get_alias_function_for_class(cls)
133            synced_attrs = Sync.resolve_attributes(
134                obj_or_cls=cls,
135                include=sync_config.get("include"),
136                exclude=sync_config.get("exclude"),
137                sync_all=sync_config.get("sync_all", False),
138                casing_func=casing_func,
139            )
140
141            # Create a custom adapter that only includes the synced fields
142            field_definitions = {}
143            for name, field_info in cls.model_fields.items():
144                if name in synced_attrs:
145                    field_definitions[name] = (field_info.annotation, field_info)
146
147            fields = {}
148            for attr_name in synced_attrs:
149                if attr_name in cls.model_fields:
150                    fields[attr_name] = (
151                        cls.model_fields[attr_name].annotation,
152                        cls.model_fields[attr_name],
153                    )
154                elif attr_name in cls.model_computed_fields:
155                    # Computed fields are trickier to add to create_model dynamically to appear as fields
156                    # For schema generation purposes, we can treat them as read-only fields
157                    fields[attr_name] = (
158                        cls.model_computed_fields[attr_name].return_type,
159                        ...,
160                    )
161
162            # Create a new model just for schema generation
163            schema_model = create_model(
164                f"{cls.__name__}", **fields, __config__=cls.model_config
165            )
166            serialization_adapter = TypeAdapter(schema_model)
167
168        serialization = [("MODEL STATE", serialization_adapter)]
169
170        # merge all schemas
171        schema_inputs: list = [
172            (sync_key, "validation", validator) for sync_key, validator in validation
173        ] + [
174            (sync_key, "serialization", serializer)
175            for sync_key, serializer in serialization
176        ]
177        schemas, definitions = TypeAdapter.json_schemas(
178            schema_inputs, schema_generator=schema_generator, ref_template=ref_template
179        )
180
181        # Attach helper schemas for the remote actions
182        action_keys: list[str] = list(cls.action_validators)
183
184        # TODO: if the sync key is known at static time, include the sync key. How to deal with dynamic sync keys? Maybe instead of sync key it should just be an ID?
185        # # helps the frontend to know the model sync key
186        # schemas[("MODEL SYNC KEY", "validation")] = {
187        #     "description": "The sync key of the model",
188        #     "type": "string",
189        #     "enum": [class sync key here],
190        #     "title": f"{cls.__name__}SyncKey",
191        # }
192
193        # helps the frontend to know the possible actions
194        schemas[("REMOTE ACTIONS KEYS", "validation")] = {
195            "description": "Lists all action keys as enum values",
196            "type": "string",
197            "enum": action_keys,
198            "title": f"{cls.__name__}ActionsKeys",
199        }
200        # helps the frontend to know the possible parameters for each action
201        schemas[("REMOTE ACTIONS PARAMS", "validation")] = {
202            "description": "Maps each action keys to its parameters",
203            "properties": {
204                actions: nullify_if_empty(schemas[(actions, "validation")], definitions)
205                for actions in action_keys
206            },
207            "required": action_keys,
208            "title": f"{cls.__name__}ActionsParams",
209            "type": "object",
210        }
211
212        task_keys: list[str] = list(cls.task_validators)
213        schemas[("REMOTE TASKS KEYS", "validation")] = {
214            "description": "Lists all task keys as enum values",
215            "type": "string",
216            "enum": task_keys,
217            "title": f"{cls.__name__}TasksKeys",
218        }
219        schemas[("REMOTE TASKS PARAMS", "validation")] = {
220            "description": "Maps each task key to its parameters",
221            "properties": {
222                task: nullify_if_empty(schemas[(task, "validation")], definitions)
223                for task in task_keys
224            },
225            "required": task_keys,
226            "title": f"{cls.__name__}TasksParams",
227            "type": "object",
228        }
229
230        return schemas, definitions

Returns a JSON schema suitable for ws_sync, meaning the model (all of its fields) as serialization, its action and task inputs as validation.

@classmethod
def attach_to_openapi( cls, openapi: dict, *, always_include_validation_schema: bool = False, schema_generator: type[pydantic.json_schema.GenerateJsonSchema] = <class 'ws_sync.utils.json_schema.CustomGenerateJsonSchema'>) -> dict:
232    @classmethod
233    def attach_to_openapi(
234        cls,
235        openapi: dict,
236        *,
237        always_include_validation_schema: bool = False,
238        schema_generator: type[GenerateJsonSchema] = CustomGenerateJsonSchema,
239    ) -> dict:
240        openapi = deepcopy(openapi)
241
242        if "components" not in openapi:
243            openapi["components"] = {"schemas": {}}
244
245        schemas, definitions = cls.ws_sync_json_schema(
246            always_include_validation_schema=always_include_validation_schema,
247            schema_generator=schema_generator,
248            ref_template="#/components/schemas/{model}",
249        )
250        deps = definitions.pop("$defs", {})
251        # either the remaining schema is a schema, or a $ref to a schema in deps
252        for schema in schemas.values():
253            if "title" in schema:
254                # schema is a schema
255                openapi["components"]["schemas"].update(
256                    {
257                        schema["title"]: schema,
258                    }
259                )
260            else:
261                # schema is a $ref to a schema, so already contained in deps
262                pass
263        openapi["components"]["schemas"].update(deps)
264
265        return openapi
class SyncedAsCamelCase(ws_sync.Synced):
268class SyncedAsCamelCase(Synced, is_abstract=True):
269    """Synced base that serializes fields using camelCase."""
270
271    model_config = Synced.model_config | ConfigDict(
272        alias_generator=AliasGenerator(serialization_alias=to_camel),
273        serialize_by_alias=True,
274    )
275
276    def __init_subclass__(cls, *, is_abstract: bool = False, **kwargs):
277        super().__init_subclass__(is_abstract=is_abstract, **kwargs)

Synced base that serializes fields using camelCase.

model_config = {'json_schema_serialization_defaults_required': True, 'alias_generator': AliasGenerator(alias=None, validation_alias=None, serialization_alias=<function to_camel>), 'serialize_by_alias': True}
session_context = <ContextVar name='session_context'>
async def get_user_session( ws: starlette.websockets.WebSocket) -> tuple[str, str] | tuple[None, None]:
17async def get_user_session(ws: WebSocket) -> tuple[str, str] | tuple[None, None]:
18    """
19    A primitive WS user+session identification protocol.
20
21    So that the `Session` state can persist across reconnections/tabs/etc., the client sends their user_id and session_id to the server.
22
23    Args:
24        ws: the websocket
25
26    Returns:
27        the user_id and session_id or None, None if the client sent invalid data
28    """
29    try:
30        await ws.send_json({"type": "_REQUEST_USER_SESSION"})
31        msg = await ws.receive_json()
32        if msg["type"] != "_USER_SESSION":
33            raise InvalidUserSessionMessageError(msg)  # noqa: TRY301
34        user = msg["data"]["user"]
35        session = msg["data"]["session"]
36
37        if not user or not session:
38            raise InvalidUserSessionError(msg)  # noqa: TRY301
39
40    except (InvalidUserSessionMessageError, InvalidUserSessionError):
41        with suppress(Exception):
42            await ws.close()
43        return None, None
44    else:
45        return user, session

A primitive WS user+session identification protocol.

So that the Session state can persist across reconnections/tabs/etc., the client sends their user_id and session_id to the server.

Arguments:
  • ws: the websocket
Returns:

the user_id and session_id or None, None if the client sent invalid data

class sync_key_scope:
47class sync_key_scope:  # noqa: N801
48    """
49    Context manager for scoping sync keys with a prefix.
50
51    All Sync objects created within this context will have their keys prefixed.
52    Supports nesting - nested scopes will create hierarchical prefixes with '/' separator.
53
54    Example:
55        ```python
56        with sync_key_scope("user123"):
57            obj1 = MyObject()  # key: "user123/MY_KEY"
58
59            with sync_key_scope("session456"):
60                obj2 = MyObject()  # key: "user123/session456/MY_KEY"
61        ```
62
63    Args:
64        prefix: The prefix to add. Empty strings and None are ignored (no prefix added).
65    """
66
67    def __init__(self, prefix: str | None):
68        self.prefix = prefix
69        self.token: Token[list[str] | None] | None = None
70
71    def __enter__(self) -> Self:
72        # Only add non-empty prefixes
73        if self.prefix:
74            # Get current stack (creates a copy to avoid mutation issues)
75            current_stack = _sync_key_prefix_stack.get()
76            current_stack = [] if current_stack is None else current_stack.copy()
77            current_stack.append(self.prefix)
78            self.token = _sync_key_prefix_stack.set(current_stack)
79        return self
80
81    def __exit__(
82        self,
83        exc_type: type[BaseException] | None,
84        exc_value: BaseException | None,
85        traceback: object,
86    ) -> None:
87        if self.token is not None:
88            _sync_key_prefix_stack.reset(self.token)
89            self.token = None

Context manager for scoping sync keys with a prefix.

All Sync objects created within this context will have their keys prefixed. Supports nesting - nested scopes will create hierarchical prefixes with '/' separator.

Example:
with sync_key_scope("user123"):
    obj1 = MyObject()  # key: "user123/MY_KEY"

    with sync_key_scope("session456"):
        obj2 = MyObject()  # key: "user123/session456/MY_KEY"
Arguments:
  • prefix: The prefix to add. Empty strings and None are ignored (no prefix added).
sync_key_scope(prefix: str | None)
67    def __init__(self, prefix: str | None):
68        self.prefix = prefix
69        self.token: Token[list[str] | None] | None = None
prefix
token: _contextvars.Token[list[str] | None] | None
def get_current_sync_key_prefix() -> str | None:
 92def get_current_sync_key_prefix() -> str | None:
 93    """
 94    Get the current sync key prefix from nested scopes.
 95
 96    Returns:
 97        The full hierarchical prefix string (e.g., "abc/nested/deep"),
 98        or None if no prefix scope is active.
 99
100    Example:
101        ```python
102        with sync_key_scope("abc"):
103            with sync_key_scope("nested"):
104                prefix = get_current_sync_key_prefix()  # "abc/nested"
105        ```
106    """
107    stack = _sync_key_prefix_stack.get()
108    if not stack:
109        return None
110    return "/".join(stack)

Get the current sync key prefix from nested scopes.

Returns:

The full hierarchical prefix string (e.g., "abc/nested/deep"), or None if no prefix scope is active.

Example:
with sync_key_scope("abc"):
    with sync_key_scope("nested"):
        prefix = get_current_sync_key_prefix()  # "abc/nested"