PyCRDT

https://github.com/y-crdt/pycrdt
Admin
pycrdt provides Conflict-free Replicated Data Types (CRDTs) in Python, built upon the Yrs library...
Tokens:3,398
Snippets:28
Trust Score:6.4
License:MIT
Update:1 year ago
Show doc for...
Tokens:
Raw
### Install pycrdt with pip

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

This command installs the `pycrdt` library using the `pip` package manager. It's the simplest way to get `pycrdt` for general use.

```bash
pip install pycrdt
```

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

### Set up pycrdt development environment with micromamba

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

These commands create and activate a dedicated `micromamba` environment named `pycrdt-dev`. It then installs essential development tools like `pip` and the Rust compiler, which are required for building `pycrdt`'s Rust extension.

```bash
micromamba create -n pycrdt-dev
micromamba activate pycrdt-dev
micromamba install -c conda-forge pip rust
```

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

### Install pycrdt with micromamba

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

This command installs the `pycrdt` library into the currently active `conda-forge` environment. It ensures `pycrdt` and its dependencies are managed by `micromamba`.

```bash
micromamba install -c conda-forge pycrdt
```

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

### Clone pycrdt repository for development

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

These commands clone the `pycrdt` Git repository from GitHub and then change the current directory into the newly cloned `pycrdt` project folder. This is the first step for setting up a development environment.

```bash
git clone https://github.com/y-crdt/pycrdt.git
cd pycrdt
```

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

### Install pycrdt in editable development mode

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

This command installs the `pycrdt` project in editable mode (`-e`). This means that changes made to the Python source code will be immediately reflected without needing to reinstall the package. It also triggers the initial build of the Rust extension using `maturin`.

```bash
pip install -e .
```

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

### Observe Document-Level Changes and Get Updates in pycrdt

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

Explains how to observe changes made to an entire pycrdt document, primarily for synchronization with remote documents. It shows how to register a callback for TransactionEvent to extract binary updates for transmission over a network.

```Python
from pycrdt import TransactionEvent

def handle_doc_changes(event: TransactionEvent):
    update: bytes = event.update
    # send binary update on the wire

doc.observe(handle_doc_changes)
```

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

### Rebuild pycrdt Rust extension during development

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

First, `pip install maturin` ensures the `maturin` tool is available. Then, `maturin develop` rebuilds the Rust extension for `pycrdt`. This step is necessary only when changes are made to the Rust code, allowing developers to quickly test their modifications.

```bash
pip install maturin
maturin develop
```

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

### Create and activate a micromamba environment

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

These commands create a new `conda-forge` environment named `my_env` and then activate it. This isolates `pycrdt` and its dependencies from other Python projects.

```bash
micromamba create -n my_env
micromamba activate my_env
```

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

### Manage Asynchronous Transactions with pycrdt

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

Illustrates how to use pycrdt.Doc in an asynchronous environment. It shows how new_transaction() can be used with an async context manager, yielding to the event loop until a transaction is acquired, suitable for async frameworks like AnyIO.

```Python
from anyio import create_task_group, run
from pycrdt import Doc

doc = Doc()

async def create_new_transaction():
    async with doc.new_transaction(timeout=3):
        ...

async def main():
    async with create_task_group() as tg:
        tg.start_soon(create_new_transaction)
        tg.start_soon(create_new_transaction)

run(main)
```

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

### Insert Pycrdt Shared Types into a Document

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

After initialization, shared data types must be inserted into a `Doc` object to become useful. This example shows how to create a `Doc` instance and assign the previously initialized `Text`, `Array`, and `Map` objects as root types, making them part of the collaborative document.

```py
from pycrdt import Doc

doc = Doc()
doc["text0"] = text0
doc["array0"] = array0
doc["map0"] = map0
```

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

### Apply Binary Updates to Remote pycrdt Documents

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

Illustrates how to apply received binary updates to a remote pycrdt document. This is typically used on the receiving end of a synchronization channel to merge changes from another document.

```Python
# receive binary update from e.g. a WebSocket
update: bytes

remote_doc.apply_update(update)
```

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

### Synchronize Pycrdt Documents Using Updates

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

This snippet demonstrates the synchronization mechanism in Pycrdt. Changes to a `Doc` generate binary updates that can be transmitted to a remote machine. The remote document then applies this update to achieve eventual consistency, retrieving the root types by their assigned names.

```py
update = doc.get_update()

# the (binary) update could travel on the wire to a remote machine:

remote_doc = Doc()
remote_doc.apply_update(update)

remote_doc["text0"] = text0 = Text()
remote_doc["array0"] = array0 = Array()
remote_doc["map0"] = map0 = Map()
```

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

### Nest Non-blocking Pycrdt Transactions

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

Pycrdt supports nesting transactions, where all changes occur within the outermost transaction. This example demonstrates multiple nested `doc.transaction()` context managers. All modifications made within `t1` and `t2` are ultimately part of the `t0` transaction.

```py
with doc.transaction() as t0:
    text0 += ", World!"
    with doc.transaction() as t1:
        array0.append("bar")
        with doc.transaction() as t2:
            map0["key1"] = "value1"
```

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

### Iterate Over Document Events Asynchronously in pycrdt

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

Shows how to handle document-level events asynchronously by iterating over them using an async context manager and async for loop, similar to shared data events, to process and send binary updates.

```Python
async def main():
    async with doc.events() as events:
        async for event in events:
            update: bytes = event.update
            # send binary update on the wire
```

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

### Manage Concurrent Transactions with Multithreading in pycrdt

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

Demonstrates how to use pycrdt.Doc with multithreading to acquire transactions using a blocking context manager. It shows how multiple threads can attempt to acquire a transaction, with an optional timeout, ensuring thread-safe access to the document.

```Python
from threading import Thread
from pycrdt import Doc

doc = Doc(allow_multithreading=True)

def create_new_transaction():
    with doc.new_transaction(timeout=3):
        ...

t0 = Thread(target=create_new_transaction)
t1 = Thread(target=create_new_transaction)
t0.start()
t1.start()
t0.join()
t1.join()
```

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

### Implement Undo/Redo Functionality with pycrdt UndoManager

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

Demonstrates how to use UndoManager to enable undo and redo operations on changes made to shared types within a pycrdt document. It shows initializing the manager, expanding its scope to specific shared types, and performing undo/redo actions.

```Python
from pycrdt import Doc, Text, UndoManager

doc = Doc()

text = doc.get("text", type=Text)
text += "Hello"

undo_manager = UndoManager(doc=doc)
undo_manager.expand_scope(text)

text += ", World!"
print(str(text))
# prints: "Hello, World!"

undo_manager.undo()
print(str(text))
# prints: "Hello"

undo_manager.redo()
print(str(text))
# prints: "Hello, World!"
```

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

### Using TypedMap and TypedDoc for Key-Specific Type Annotations

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

Illustrates the use of `TypedMap` and `TypedDoc` for defining specific types for individual keys, rather than a uniform type for all values. This allows for more granular type control, where each field can have its own distinct type, and shows how type checkers will flag assignments or access to non-existent keys that violate these definitions.

```python
from pycrdt import Array, Text, TypedDoc, TypedMap

class MyMap(TypedMap):
    name: str
    toggle: bool
    nested: Array[bool]

class MyDoc(TypedDoc):
    map0: MyMap
    array0: Array[int]
    text0: Text

doc = MyDoc()

doc.map0.name = "foo"
doc.map0.toggle = False
doc.map0.toggle = 3  # error: Incompatible types in assignment (expression has type "int", variable has type "bool")  [assignment]
doc.array0 = Array([1, 2, 3])
doc.map0.nested = Array([4])  # error: List item 0 has incompatible type "int"; expected "bool"  [list-item]
doc.map0.nested = Array([False, True])
v0: str = doc.map0.name
v1: str = doc.map0.toggle  # error: Incompatible types in assignment (expression has type "bool", variable has type "str")  [assignment]
v2: bool = doc.map0.toggle
doc.map0.wrong_key0  # error: "MyMap" has no attribute "wrong_key0"  [attr-defined]
```

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

### Perform Operations on Pycrdt Shared Types

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

This snippet illustrates common operations on Pycrdt shared data types after they have been inserted into a `Doc`. It demonstrates appending to a `Text` object, adding an element to an `Array`, and setting a new key-value pair in a `Map`, similar to their Python built-in counterparts.

```py
text0 += ", World!"
array0.append("bar")
map0["key1"] = "value1"
```

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

### Iterate Over Shared Data Events Asynchronously in pycrdt

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

Demonstrates an asynchronous approach to handling shared data events. Instead of registering a callback, it shows how to iterate over events using an async context manager and async for loop, suitable for asynchronous environments.

```Python
async def main():
    async with text0.events() as events:
        async for event in events:
            # process the event
```

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

### Nest Pycrdt Shared Data Types within Others

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

Pycrdt's `Array` and `Map` types can hold other shared data types, allowing for complex nested structures. This example shows how to create new `Map` and `Array` instances and then append the `Map` to an existing `Array` and assign the `Array` as a value in an existing `Map`.

```py
map1 = Map({"baz": 1})
array1 = Array([5, 6, 7])

array0.append(map1)
map0["key2"] = array1
```

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

### Unregister Shared Data Event Callbacks in pycrdt

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

Shows how to unregister a previously registered callback for shared data events using the unobserve() method and the subscription ID obtained during the initial observation.

```Python
text0.unobserve(text0_subscription_id)
```

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

### Initialize Pycrdt Shared Data Types

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

This snippet demonstrates how to initialize the core Pycrdt shared data types: `Text`, `Array`, and `Map`. These types are similar to Python's built-in `str`, `list`, and `dict` respectively, serving as placeholders before insertion into a shared document.

```py
from pycrdt import Text, Array, Map

text0 = Text("Hello")
array0 = Array([0, "foo"])
map0 = Map({"key0": "value0"})
```

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

### Group Changes with Non-blocking Pycrdt Transactions

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

Pycrdt transactions allow grouping multiple changes atomically. This snippet shows how to use `doc.transaction()` as a context manager for a non-blocking transaction. All changes within the `with` block are treated as a single, simultaneous operation.

```py
with doc.transaction():
    text0 += ", World!"
    array0.append("bar")
    map0["key1"] = "value1"
```

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

### Observe Top-Level Shared Data Changes in pycrdt

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

Explains how to register a callback to observe changes to shared data types like Text. It shows how to define a handler function for TextEvent and subscribe to changes using observe(), returning a subscription ID for later unregistration.

```Python
from pycrdt import TextEvent

def handle_changes(event: TextEvent):
    # process the event
    ...

text0_subscription_id = text0.observe(handle_changes)
```

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

### Type Annotating Doc and Array for Uniform Types

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

Demonstrates how to use type annotations with `Doc` and `Array` to enforce uniform types across their contents. This snippet shows how attempting to append an incompatible type or retrieve a root type with a different annotation will result in static type errors, ensuring type consistency.

```python
from pycrdt import Array, Doc

doc = Doc[Array[int]]()
array0 = doc.get("array0", type=Array[int])
array0.append(0)
array0.append("foo")  # error: Argument 1 to "append" of "Array" has incompatible type "str"; expected "int"
array1 = doc.get("array1", type=Array[str])  # error: Argument "type" to "get" of "Doc" has incompatible type "type[pycrdt._array.Array[Any]]"; expected "type[pycrdt._array.Array[int]]"
```

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

### Accessing Underlying Map/Doc from Typed Containers

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

Explains that `TypedMap` and `TypedDoc` are not direct subclasses of `Map` and `Doc`, but rather encapsulate them. This snippet demonstrates how to access the underlying untyped `Map` or `Doc` instance from a `TypedMap` or `TypedDoc` using the special `_` property, allowing for operations that might bypass strict type checking if needed.

```python
from pycrdt import Doc, Map

untyped_doc: Doc = doc._
untyped_map: Map = doc.map0._
```

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

### Observe Deeply Nested Shared Data Changes in pycrdt

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

Describes how to observe changes deeply nested within container data types like Array and Map using observe_deep(). It highlights the difference from observe() by notifying for changes within nested structures and requiring a callback that accepts a list of events.

```Python
from pycrdt import ArrayEvent

def handle_deep_changes(events: list[ArrayEvent]):
    # process the events
    ...

array0_subscription_id = array0.observe_deep(handle_deep_changes)
```

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

### pycrdt Module API Members Overview

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

This section lists all public classes, events, and functions directly exposed by the `pycrdt` module. It provides an overview of the main components available for building collaborative applications with Y-CRDTs in Python.

```APIDOC
Module: pycrdt
  Members:
    - BaseType
    - Array
    - ArrayEvent
    - Awareness
    - Channel
    - Decoder
    - Doc
    - Encoder
    - Map
    - MapEvent
    - NewTransaction
    - Provider
    - ReadTransaction
    - StackItem
    - Subscription
    - SubdocsEvent
    - Text
    - TextEvent
    - Transaction
    - TransactionEvent
    - TypedArray
    - TypedDoc
    - TypedMap
    - UndoManager
    - XmlElement
    - XmlFragment
    - XmlText
    - XmlChildrenView
    - XmlAttributesView
    - YMessageType
    - YSyncMessageType
    - create_awareness_message
    - create_sync_message
    - create_update_message
    - handle_sync_message
    - get_state
    - get_update
    - merge_updates
    - read_message
    - write_message
    - write_var_uint
```
Tokens:
Raw