y-py

library0.6.2pypypi✓ verified 22d ago

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.

serialization database ai-ml

pip install y-py

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · Y-PY

y-py

serializationpythonv0.6.2

Install

1.6s avg

Import

10ms

Disk

23MB

Pass rate

4/ 10

Env Coverage4 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.6.2 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

glibc

py 3.10

✕ build_error

✓ 1.6s

py 3.11

✕ build_error

✓ 1.6s

py 3.12

✕ build_error

✓ 1.5s

py 3.13

✕ build_error

py 3.9

✕ build_error

✓ 1.9s

23MB installed

● package 23MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

YDoc

✓ import y_py as Y; doc = Y.YDoc()

✗ from y_py import YDoc

The common and recommended pattern is to import the library as 'Y' and access classes/functions through it.

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}")

Debug

Known issues

breakingThe `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.

affects: <1.0.0

gotchaInitial 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.

affects: <0.6.2

gotchaAll 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.

affects: All versions

breakingPrior 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.

affects: <0.5.5

Errors

Common errors & fixes

error: `cargo` exited with an error: No such file or directory (os error 2)

The Rust toolchain, specifically the `cargo` command, is not installed or not available in the system's PATH, which is required to build y-py from source.

fix

Install the Rust toolchain using `curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh` and ensure `cargo` is added to your system's PATH.

AttributeError: 'YText' object has no attribute 'value'

The `YText` object directly represents the shared text; its string value is accessed by converting it to a string or by using its `to_json()` method, not through a `.value` attribute.

fix

Access the string content using `str(y_text_obj)` or `y_text_obj.to_json()`.

RuntimeError: Expected transaction

Operations that modify shared Y-types (like `YText`, `YMap`, `YArray`) must be performed within a transaction block.

fix

Wrap all modification operations inside a `with ydoc.begin_transaction() as txn:` block, passing the `txn` object as the first argument to the modification method (e.g., `y_text.insert(txn, 0, 'hello')`).

ERROR: Failed building wheel for y-py

The Rust binding for y-py failed to compile during installation, often due to a missing or outdated Rust toolchain, or platform-specific build issues.

fix

Ensure Rust and Cargo are installed and up-to-date (`rustup update`), and check platform-specific requirements. Sometimes `pip install maturin` can help before `pip install y-py`.

ModuleNotFoundError: No module named 'ypy'

The library was imported using an incorrect module name. The PyPI package is 'y-py', but the importable module is 'y_py'.

fix

Change the import statement from `import ypy` to `import y_py`.

Upgrade

Version history

0.6.2latest on PyPI · released Oct 5, 2023

Audit

Dependencies

No dependency data recorded yet.

Agent activity

55 hits · last 30 days

node