y-py: Python bindings for Y-CRDT

0.6.2 · active · verified Sat Apr 11

y-py is a high-performance Python binding for Y-CRDT, a distributed data type library built in Rust. It enables seamless real-time synchronization of state between processes and cross-domain communication with other Y-CRDT bindings like Y-Wasm. The project is currently experimental, with API changes expected before a 1.0 stable release. The current stable version is 0.6.2.

Warnings

breaking The `y-py` library is currently experimental, and its API is subject to change without strict backward compatibility guarantees before a 1.0 stable release. Users should anticipate potential breaking changes with minor version updates.
Fix: Refer to the latest official documentation and release notes for API changes when upgrading.
gotcha Initial support for Python 3.12 was introduced in `y-py` version 0.6.2. Users running earlier versions of `y-py` with Python 3.12 may encounter compatibility issues.
Fix: Upgrade to `y-py` 0.6.2 or later for Python 3.12 compatibility.
gotcha All modifications to `YDoc` shared types (e.g., `YText`, `YMap`, `YArray`) must occur within a transaction context initiated by `doc.begin_transaction()`. Attempting to modify shared types outside a transaction or initiating multiple concurrent transactions on the same document will raise an exception.
Fix: Always wrap modifications to shared types within a `with doc.begin_transaction() as txn:` block.
breaking Prior to version 0.5.5, some update application methods might have had different names (e.g., `applyV1`). The current public API uses `Y.apply_update()` for applying document updates. Code using older method names will break with modern `y-py` versions.
Fix: Update method calls to `Y.apply_update()` and verify other API changes against the latest documentation.

Install

pip install y-py PyPI

Imports

YDoc
```
import y_py as Y; doc = Y.YDoc()
```
The common and recommended pattern is to import the library as 'Y' and access classes/functions through it.

Quickstart

This example demonstrates how to create a YDoc, modify its content within a transaction, and synchronize changes between two document instances.

import y_py as Y

d1 = Y.YDoc()
text = d1.get_text('test')

with d1.begin_transaction() as txn:
    text.extend(txn, "hello world!")

d2 = Y.YDoc()
state_vector = Y.encode_state_vector(d2)
diff = Y.encode_state_as_update(d1, state_vector)
Y.apply_update(d2, diff)

value = str(d2.get_text('test'))
assert value == "hello world!"
print(f"Synchronized text: {value}")

view raw JSON →