pycrdt

Pycrdt provides several shared data types that behave similarly to Python built-ins but are designed for CRDT synchronization. To make them useful, they must be inserted into a Doc instance.

Supported types:

• Text: similar to str.
• Array: similar to list.
• Map: similar to dict.
• XmlFragment, XmlElement, XmlText: XML-based types.

Once inserted into a Doc, you can perform standard operations (like +=, .append(), or key assignment) which will generate binary updates that can be synchronized with remote documents.

from pycrdt import Doc, Text, Array, Map

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

# Insert into a document
doc = Doc()
doc["text0"] = text0
doc["array0"] = array0
doc["map0"] = map0

# Operate on them
text0 += ", World!"
array0.append("bar")
map0["key1"] = "value1"

To install pycrdt using micromamba and conda-forge, create and activate a new environment before installing the package.

micromamba create -n my_env
micromamba activate my_env
micromamba install pycrdt

To synchronize state between different machines, you can extract a binary encoded update from a Doc and apply it to a remote Doc. This ensures that concurrent changes eventually converge to the same state across all participants.

# On the local machine:
update = doc.get_update()
# Send 'update' (bytes) over the wire (e.g., WebSocket)

# On the remote machine:
remote_doc = Doc()
remote_doc.apply_update(update)

# Retrieve root types by the names they were inserted under
text0 = remote_doc["text0"]

To develop on pycrdt, clone the repository and set up a conda environment containing pip and the Rust compiler. Install the package in editable mode to include test and type groups.

Note: This process uses maturin to build the Rust extension.

If you modify only Python code, changes are reflected immediately. If you modify Rust code, you must re-build the extension using maturin develop without needing to reinstall the package.

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

# Setup environment
micromamba create -n pycrdt-dev
micromamba activate pycrdt-dev
micromamba install pip rust

# Install in editable mode
pip install -e . --group test --group types

# If Rust code changes, re-build the extension:
pip install maturin
maturin develop

You can install pycrdt directly from PyPI using pip.

pip install pycrdt

Use pytest to run the test suite in your development environment.

pytest -v

A TextEvent provides metadata about a change. Key properties include:

• transaction: The transaction that caused the event.
• target: The Text object that was modified.
• path: The path within the structure where the change occurred.
• delta: A list representing the change (insertions/deletions).

# Accessing properties on a TextEvent 'e'
txn = e.transaction
target = e.target
path = e.path
delta = e.delta

The Doc class is the central container for all CRDT types in pycrdt. You can create a new instance by providing optional configuration parameters.

Parameters:

• client_id (int, optional): A unique identifier for the client. Must be a valid u64 and cannot exceed $2^{53} - 1$ (to ensure compatibility with JavaScript numbers).
• skip_gc (bool, optional): Whether to skip garbage collection.
• guid (str, optional): A unique identifier for the document.

Note: If you do not provide these, default values will be used.

from pycrdt import Doc

# Create a doc with custom configuration
doc = Doc(client_id=12345, skip_gc=False, guid="my-unique-doc-id")

# Create a default doc
doc_default = Doc()