Pycrdt WebSocket Connector

Common errors

• ModuleNotFoundError: No module named 'pycrdt_websocket'

  cause Attempting to import from the old package name `pycrdt_websocket` after upgrading to version 0.16.0 or newer.
  fix Update your import statements to use `from pycrdt.websocket import ...`.

• AttributeError: module 'pycrdt.websocket' has no attribute 'YStore'

  cause `YStore` was moved to the `pycrdt-store` package in version 0.16.0, and is no longer directly available from `pycrdt.websocket`.
  fix Install `pycrdt-store` (`pip install pycrdt-store`) and change your import to `from pycrdt_store import YStore`.

• TypeError: object Room can't be used in 'await' expression

  cause You are attempting to use an `async` function call (like `room.connect()`) without the `await` keyword, or calling it outside an `async` context.
  fix Ensure that `room.connect()` (and similar `async` methods) are called with `await` inside an `async def` function, and that the top-level call is handled by `asyncio.run()`.

Warnings

• breaking The top-level package name for imports changed from `pycrdt_websocket` to `pycrdt.websocket` starting from version 0.16.0. This requires updating all import statements.
  Fix: Replace `from pycrdt_websocket import ...` with `from pycrdt.websocket import ...`.
• breaking The `YStore` class, which manages persistence for Y-CRDT documents, was extracted into a separate package `pycrdt-store` starting from version 0.16.0. If you were using or subclassing `YStore` directly, you now need to import it from `pycrdt_store`.
  Fix: Install `pycrdt-store` (`pip install pycrdt-store`) and update imports from `from pycrdt.websocket import YStore` to `from pycrdt_store import YStore`.
• gotcha Pycrdt-websocket is built on `asyncio` and requires `await` for all network operations (e.g., `server.start()`, `room.connect()`). Forgetting `await` will lead to silent failures or incorrect behavior.
  Fix: Ensure all calls to asynchronous methods are prefixed with `await` and run within an `async` function, typically managed by `asyncio.run()`.
• gotcha Compatibility with `pycrdt` versions is crucial. Always check the release notes for `pycrdt-websocket` to ensure you are using a compatible `pycrdt` version, as internal API changes in `pycrdt` can break `pycrdt-websocket` functionality.
  Fix: Refer to the `pycrdt-websocket` project's `pyproject.toml` or `setup.py` for the exact `pycrdt` version range requirement, and upgrade/downgrade `pycrdt` accordingly (e.g., `pip install pycrdt>=0.9.0,<0.11.0`).

Install

• pip install pycrdt-websocket Install latest version

Imports

• WebSocketServer
  wrong:

  from pycrdt_websocket import WebSocketServer

  correct:

  from pycrdt.websocket import WebSocketServer

  Package name changed from `pycrdt_websocket` to `pycrdt.websocket` in v0.16.0.
• YDocRoom
  wrong:

  from pycrdt_websocket import YDocRoom

  correct:

  from pycrdt.websocket import YDocRoom

  Package name changed from `pycrdt_websocket` to `pycrdt.websocket` in v0.16.0.
• YStore
  wrong:

  from pycrdt.websocket import YStore

  correct:

  from pycrdt_store import YStore

  The YStore class was extracted into the `pycrdt-store` package starting from v0.16.0.

Quickstart

This quickstart demonstrates a basic pycrdt-websocket setup with a server and a client. The server initializes a YDoc and listens for connections, while the client connects to synchronize its own YDoc. It shows how text changes are synchronized in real-time.

import asyncio
from pycrdt import YDoc, YText
from pycrdt.websocket import WebSocketServer, YDocRoom

async def server_main():
    # Initialize a Y-CRDT document for the server
    ydoc = YDoc()
    with ydoc.transaction():
        text = ydoc.get_text('my_text')
        text += 'Hello from server!'

    # Create a WebSocket server that manages rooms
    server = WebSocketServer(ydoc, 'ws://127.0.0.1:1234')
    print("Server starting on ws://127.0.0.1:1234")
    await server.start()
    await asyncio.sleep(5) # Keep server running for a bit
    await server.stop()
    print("Server stopped")

async def client_main():
    await asyncio.sleep(1) # Give server a moment to start
    print("Client connecting...")
    # Connect to the server with a YDocRoom
    client_ydoc = YDoc()
    room = YDocRoom(client_ydoc, 'ws://127.0.0.1:1234')
    await room.connect()

    # Access the shared text
    shared_text = client_ydoc.get_text('my_text')
    print(f"Client received: '{shared_text}'")

    with client_ydoc.transaction():
        shared_text.append(' And client!')
    print(f"Client sent: '{shared_text}'")

    await asyncio.sleep(1) # Allow changes to propagate
    await room.disconnect()
    print("Client disconnected")

async def main():
    server_task = asyncio.create_task(server_main())
    client_task = asyncio.create_task(client_main())
    await asyncio.gather(server_task, client_task)

if __name__ == '__main__':
    asyncio.run(main())