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
1. Pydantic model (recommended)
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
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_tasksorrunningTasks - logger: logger to use for logging
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_tasksorrunningTasks - _logger: logger to use for logging
- **sync_attributes: attribute names to sync, value being the key of the attribute
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.
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.
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
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.
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
Nonefor Pydantic models, which should configurealias_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
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 )
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 )
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).
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
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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}.
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]] = []
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.
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.
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)
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.
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.
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")
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.
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.
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
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.
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
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).
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"