PyCrdt WebSocket

https://github.com/y-crdt/pycrdt-websocket
Admin
Pycrdt-websocket is a Python library for building WebSocket servers and clients that connect and...
Tokens:2,373
Snippets:15
Trust Score:6.4
License:MIT
Update:1 year ago
Show doc for...
Tokens:
Raw
### Install Node.js Dependencies for Integration Tests

Source: https://github.com/y-crdt/pycrdt-websocket/blob/main/docs/contributing.md

Navigates into the `tests/` directory to install required Node.js packages via `npm`, which are essential for running the integration tests. After installation, the command returns to the root directory, completing the test environment setup.

```bash
cd tests/
npm install
cd ..
```

--------------------------------

### Build and Serve Project Documentation

Source: https://github.com/y-crdt/pycrdt-websocket/blob/main/docs/contributing.md

Generates the project documentation using MkDocs and starts a local web server to preview it. The documentation becomes accessible at `http://127.0.0.1:8000`, enabling developers to review changes in real-time.

```bash
mkdocs serve
```

--------------------------------

### Install pycrdt-websocket with pip

Source: https://github.com/y-crdt/pycrdt-websocket/blob/main/docs/install.md

This command installs the `pycrdt-websocket` library from the Python Package Index (PyPI) using the `pip` package manager. It's the standard way to install Python packages.

```console
pip install pycrdt-websocket
```

--------------------------------

### Initialize and Configure Development Environment with Pixi

Source: https://github.com/y-crdt/pycrdt-websocket/blob/main/docs/contributing.md

Sets up the development environment using Pixi, installing `pip` and `nodejs` as project dependencies and activating the project shell. This prepares the system for further development tasks by ensuring all necessary tools are available.

```bash
pixi init
pixi add pip nodejs
pixi shell
```

--------------------------------

### Install pycrdt-websocket with micromamba

Source: https://github.com/y-crdt/pycrdt-websocket/blob/main/docs/install.md

This command installs the `pycrdt-websocket` library from the `conda-forge` channel using the `micromamba` package manager. `micromamba` is a lightweight, fast, and robust alternative to `conda` for managing environments and packages.

```console
micromamba install -c conda-forge pycrdt-websocket
```

--------------------------------

### Install Python Project in Editable Mode

Source: https://github.com/y-crdt/pycrdt-websocket/blob/main/docs/contributing.md

Installs the `pycrdt-websocket` project in editable mode, including optional dependencies for testing and documentation generation. This configuration allows for direct code modifications to be reflected without requiring a reinstallation, streamlining the development process.

```bash
pip install -e ".[test,docs]"
```

--------------------------------

### Setting up Pycrdt-websocket Server with Hypercorn ASGI

Source: https://github.com/y-crdt/pycrdt-websocket/blob/main/docs/usage/server.md

This Python example demonstrates how to initialize and run a `pycrdt-websocket` server using `Hypercorn` as an ASGI server. It configures the server to bind to a specific address and port, enabling real-time communication for `Doc` objects over WebSockets.

```python
import asyncio
from hypercorn import Config
from hypercorn.asyncio import serve
from pycrdt_websocket import ASGIServer, WebsocketServer

websocket_server = WebsocketServer()
app = ASGIServer(websocket_server)

async def main():
    websocket_server = WebsocketServer()
    app = ASGIServer(websocket_server)
    config = Config()
    config.bind = ["localhost:1234"]
    async with websocket_server:
        await serve(app, config, mode="asgi")

asyncio.run(main())
```

--------------------------------

### Install PyCRDT WebSocket Library

Source: https://github.com/y-crdt/pycrdt-websocket/blob/main/docs/index.md

Instructions to install the `pycrdt-websocket` library using pip, the Python package installer.

```bash
pip install pycrdt-websocket
```

--------------------------------

### Run PyCRDT WebSocket Server in Python

Source: https://github.com/y-crdt/pycrdt-websocket/blob/main/docs/index.md

Example Python script to initialize and start the `YCRDTWebsocketServer` for real-time collaborative editing. It binds to a specified host and port and uses `asyncio` to keep the server running asynchronously.

```python
import asyncio
from pycrdt_websocket import YCRDTWebsocketServer

async def main():
    server = YCRDTWebsocketServer(host="0.0.0.0", port=8000)
    await server.start()
    print(f"Server started on ws://0.0.0.0:8000")
    # Keep the server running
    await asyncio.Future()

if __name__ == "__main__":
    asyncio.run(main())
```

--------------------------------

### Connect pycrdt Doc to WebSocket with httpx-ws

Source: https://github.com/y-crdt/pycrdt-websocket/blob/main/docs/usage/client.md

This asynchronous Python example demonstrates how to connect a `pycrdt.Doc` instance to a WebSocket server using `pycrdt-websocket` and `httpx-ws`. It initializes a `Doc` and `Map`, then establishes a persistent WebSocket connection to synchronize changes, such as setting a key-value pair in the map.

```Python
import asyncio
from httpx_ws import aconnect_ws
from pycrdt import Doc, Map
from pycrdt_websocket import WebsocketProvider
from pycrdt_websocket.websocket import HttpxWebsocket

async def client():
    ydoc = Doc()
    ymap = ydoc.get("map", type=Map)
    room_name = "my-roomname"
    async with (
        aconnect_ws(f"http://localhost:1234/{room_name}") as websocket,
        WebsocketProvider(ydoc, HttpxWebsocket(websocket, room_name)),
    ):
        # Changes to remote ydoc are applied to local ydoc.
        # Changes to local ydoc are sent over the WebSocket and
        # broadcast to all clients.
        ymap["key"] = "value"

        await asyncio.Future()  # run forever

asyncio.run(client())
```

--------------------------------

### Connect to PyCRDT WebSocket Server with JavaScript

Source: https://github.com/y-crdt/pycrdt-websocket/blob/main/docs/index.md

JavaScript code demonstrating how to establish a WebSocket connection to the PyCRDT server from a web browser. It includes examples for sending updates, handling incoming messages, and managing connection events like open, close, and error.

```javascript
const ws = new WebSocket("ws://localhost:8000");

ws.onopen = () => {
    console.log("Connected to PyCRDT WebSocket server");
    // Send a Y-CRDT update (example)
    ws.send(new Uint8Array([1, 2, 3]));
};

ws.onmessage = (event) => {
    console.log("Received message:", event.data);
    // Process Y-CRDT updates
};

ws.onclose = () => {
    console.log("Disconnected from PyCRDT WebSocket server");
};

ws.onerror = (error) => {
    console.error("WebSocket error:", error);
};
```

--------------------------------

### Run Pytest Integration Tests

Source: https://github.com/y-crdt/pycrdt-websocket/blob/main/docs/contributing.md

Executes integration tests using Pytest. The `-v` flag provides verbose output for all tests. To run a specific test file, specify its path (e.g., `pytest tests/<filename>`). Useful options include `-rP` to print all standard output for passing tests and `-k <test-name>` to run a specific test function by name.

```bash
pytest -v
pytest tests/<filename>
```

--------------------------------

### PyCRDT WebSocket Server Configuration and Conceptual API

Source: https://github.com/y-crdt/pycrdt-websocket/blob/main/docs/index.md

Details the constructor parameters for the `YCRDTWebsocketServer` class, allowing customization of host, port, path, document name, and logging level. Also outlines conceptual HTTP API endpoints for checking server status and triggering document snapshots.

```APIDOC
YCRDTWebsocketServer(host: str = "0.0.0.0", port: int = 8000, path: str = "/", doc_name: str = "default_doc", log_level: str = "INFO")
  - host: The host address to bind the server to. Defaults to "0.0.0.0".
  - port: The port to listen on. Defaults to 8000.
  - path: The WebSocket path. Defaults to "/".
  - doc_name: The name of the Y-CRDT document to manage. Defaults to "default_doc".
  - log_level: Logging level for the server. Defaults to "INFO".

GET /status
  - Returns the current server status.
  - Response: {"status": "running", "connections": 5}

POST /document/{doc_id}/snapshot
  - Takes a snapshot of a specific document.
  - Parameters:
    - doc_id: (path) The ID of the document.
  - Request Body: None
  - Response: {"message": "Snapshot taken for doc_id"}
```

--------------------------------

### Pycrdt-websocket Architecture Diagram

Source: https://github.com/y-crdt/pycrdt-websocket/blob/main/README.md

This diagram illustrates the typical architecture of Pycrdt-websocket, showing how multiple clients connect to a central WebSocket server, collaborate within distinct 'rooms' for shared documents, and how these documents can be persisted to a store. It highlights the role of the WebSocket Provider in client-server communication.

```mermaid
flowchart TD
    classDef room1 fill:#f96
    classDef room2 fill:#bbf
    A[Client A<br>room-1]:::room1 <-->|WebSocket<br>Provider| server(WebSocket Server)
    B[Client B<br>room-1]:::room1 <-->|WebSocket<br>Provider| server
    C[Client C<br>room-2]:::room2 <-->|WebSocket<br>Provider| server
    D[Client D<br>room-2]:::room2 <-->|WebSocket<br>Provider| server
    server <--> room1((room-1<br>clients: A, B)):::room1
    server <--> room2((room-2<br>clients: C, D)):::room2
    A <-..-> room1
    B <-..-> room1
    C <-..-> room2
    D <-..-> room2
    room1 ---> store1[(Store)]
    room2 ---> store2[(Store)]
```

--------------------------------

### WebSocket Interface Definition for pycrdt-websocket

Source: https://github.com/y-crdt/pycrdt-websocket/blob/main/docs/usage/WebSocket_API.md

This code defines the `WebSocket` protocol class, specifying the asynchronous methods and properties that must be implemented by any WebSocket object used with `WebsocketProvider` and `WebsocketServer.serve`. It includes methods for sending and receiving byte messages, and an asynchronous iterator for consuming incoming messages until the connection is closed.

```python
class WebSocket:

    @property
    def path(self) -> str:
        # can be e.g. the URL path
        # or a room identifier
        return "my-roomname"

    def __aiter__(self):
        return self

    async def __anext__(self) -> bytes:
        # async iterator for receiving messages
        # until the connection is closed
        try:
            message = await self.recv()
        except Exception:
            raise StopAsyncIteration()

        return message

    async def send(self, message: bytes):
        # send message
        pass

    async def recv(self) -> bytes:
        # receive message
        return b""
```
Tokens:
Raw