{"id":4866,"library":"ypy-websocket","title":"Ypy WebSocket Connector","description":"ypy-websocket is a Python library providing WebSocket connectivity for Ypy, enabling real-time collaborative applications using Y-CRDTs. It offers components for building both standalone WebSocket servers and integrating with ASGI frameworks like FastAPI and Django Channels. The current version is 0.12.4, with a moderately active release cadence, often seeing minor updates and fixes within a few months.","status":"active","version":"0.12.4","language":"en","source_language":"en","source_url":"https://github.com/y-crdt/ypy-websocket","tags":["websocket","y-crdt","realtime","collaboration","asgi","django-channels"],"install":[{"cmd":"pip install ypy-websocket","lang":"bash","label":"Install ypy-websocket"}],"dependencies":[{"reason":"Asynchronous I/O framework, core dependency for server operations.","package":"anyio","optional":false},{"reason":"Backports type hints for Python < 3.8.","package":"typing_extensions","optional":true},{"reason":"ASGI server for running the YpyWebSocketServer.","package":"uvicorn","optional":true},{"reason":"Required for using ChannelsYpyConsumer.","package":"Django Channels","optional":true}],"imports":[{"note":"YDoc itself is from the core y-py library, not ypy-websocket directly.","wrong":"from ypy_websocket.yroom import YDoc","symbol":"YDoc","correct":"from y_py import YDoc"},{"symbol":"YpyWebSocketServer","correct":"from ypy_websocket.server import YpyWebSocketServer"},{"symbol":"YRoom","correct":"from ypy_websocket.yroom import YRoom"},{"symbol":"YStore","correct":"from ypy_websocket.ystore import YStore"},{"symbol":"YpyWebSocketRouter","correct":"from ypy_websocket.router import YpyWebSocketRouter"},{"symbol":"ChannelsYpyConsumer","correct":"from ypy_websocket.django_channels import ChannelsYpyConsumer"}],"quickstart":{"code":"import asyncio\nimport uvicorn\nfrom y_py import YDoc\nfrom ypy_websocket.server import YpyWebSocketServer\nfrom ypy_websocket.yroom import YRoom\nfrom ypy_websocket.ystore import YStore\n\nasync def main():\n    # Initialize a YDoc\n    ydoc = YDoc()\n    # Apply an initial update, e.g., create a text type\n    with ydoc.begin_transaction() as txn:\n        ydoc.get_text('my_text').insert(txn, 0, 'Hello Y-CRDT!')\n\n    # Create a YStore and YRoom to manage the YDoc\n    ystore = YStore()\n    yroom = YRoom(ydoc, ystore=ystore)\n    # The server will handle rooms implicitly; here we just show direct room creation\n\n    # Create the WebSocket server\n    # In a real app, 'get_room' would likely fetch a room based on path\n    async def get_room(path: str) -> YRoom:\n        if path == '/ws/doc':\n            return yroom\n        raise ValueError('Room not found')\n\n    websocket_server = YpyWebSocketServer(get_room=get_room)\n\n    # This part typically runs in a separate process (e.g., via `uvicorn`) \n    # but we demonstrate the ASGI app creation.\n    # For a quick runnable demo, we'll start it directly if possible (not ideal for actual deployment)\n    # To run this, you would typically save it as `app.py` and run `uvicorn app:websocket_server`\n    print(\"Ypy WebSocket server initialized. Connect to ws://127.0.0.1:8000/ws/doc\")\n    # A full quickstart would involve running uvicorn\n    # For a runnable quickstart here, we'll demonstrate just the setup.\n    # To make it runnable via `python your_script.py`, it would require more extensive setup:\n    # from uvicorn.config import Config\n    # from uvicorn.server import Server\n    # config = Config(websocket_server, host=\"0.0.0.0\", port=8000, ws=\"wsproto\")\n    # server = Server(config)\n    # await server.serve()\n\n    # For a simple runnable example that demonstrates the setup without blocking:\n    # In a real scenario, this would be exposed by an ASGI server like Uvicorn.\n    # Let's mock a client connection setup without actually serving.\n    print(\"To run the server, save the above 'websocket_server' variable as 'app.py' and execute:\")\n    print(\"`uvicorn app:websocket_server --host 127.0.0.1 --port 8000`\")\n    print(\"Then connect with a WebSocket client to `ws://127.0.0.1:8000/ws/doc`\")\n\nif __name__ == '__main__':\n    asyncio.run(main())\n","lang":"python","description":"This quickstart demonstrates how to set up a basic Ypy WebSocket server using `YpyWebSocketServer` to serve a `YDoc`. It initializes a YDoc, wraps it in a `YRoom`, and configures the server to expose this room at a specific path. For actual deployment, you would run the `websocket_server` ASGI application with an ASGI server like Uvicorn (e.g., `uvicorn your_module:websocket_server`)."},"warnings":[{"fix":"Review the official examples and ensure `YStore` and `YRoom` instances are correctly passed and managed by the `YpyWebSocketServer`'s `get_room` callable, rather than manually starting them.","message":"The initialization of `YStore` and `YRoom` was refactored in `v0.12.0`. The `YpyWebSocketServer` now implicitly manages rooms, and the explicit `start_room` and `start_store` methods might have changed how they are used or called.","severity":"breaking","affected_versions":">=0.12.0"},{"fix":"Ensure that `anyio` installed in your environment is strictly less than version 5. If `anyio` v5 is required by other parts of your application, you may encounter conflicts requiring careful dependency management or waiting for an `ypy-websocket` update that supports `anyio` v5.","message":"The library pins its `anyio` dependency to versions less than 5 (`anyio<5`). Installing `anyio` version 5 or higher directly may lead to dependency conflicts or unexpected behavior.","severity":"gotcha","affected_versions":">=0.12.2"},{"fix":"If you have custom async logic interacting deeply with the server internals, refactor it to align with `anyio`'s patterns. Standard usage through `YpyWebSocketServer` should largely be unaffected, but advanced use cases might need review.","message":"Versions `v0.9.0` and `v0.11.0` introduced significant internal changes by fully transitioning to `anyio` from `aiofiles` and other asyncio mechanisms. Custom server implementations or extensions that relied on specific `asyncio` or `aiofiles` patterns might require updates.","severity":"breaking","affected_versions":">=0.9.0, <0.12.0"},{"fix":"Always use `YRoom` to manage `YDoc` instances for WebSocket clients, and `YStore` for persistence if needed, ensuring they are correctly configured and passed to the `YpyWebSocketServer` or `YpyWebSocketRouter`.","message":"While `YDoc` is imported from `y_py`, `YRoom` and `YStore` are specific components of `ypy-websocket` that manage the lifecycle and persistence of `YDoc` instances in a WebSocket context. Misunderstanding this hierarchy can lead to incorrect state management.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}