{"id":4330,"library":"y-py","title":"y-py: Python bindings for Y-CRDT","description":"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.","status":"active","version":"0.6.2","language":"python","source_language":"en","source_url":"https://github.com/y-crdt/ypy","tags":["CRDT","real-time","collaboration","data synchronization","Rust binding"],"install":[{"cmd":"pip install y-py","lang":"bash","label":"PyPI"}],"dependencies":[],"imports":[{"note":"The common and recommended pattern is to import the library as 'Y' and access classes/functions through it.","wrong":"from y_py import YDoc","symbol":"YDoc","correct":"import y_py as Y; doc = Y.YDoc()"}],"quickstart":{"code":"import y_py as Y\n\nd1 = Y.YDoc()\ntext = d1.get_text('test')\n\nwith d1.begin_transaction() as txn:\n    text.extend(txn, \"hello world!\")\n\nd2 = Y.YDoc()\nstate_vector = Y.encode_state_vector(d2)\ndiff = Y.encode_state_as_update(d1, state_vector)\nY.apply_update(d2, diff)\n\nvalue = str(d2.get_text('test'))\nassert value == \"hello world!\"\nprint(f\"Synchronized text: {value}\")","lang":"python","description":"This example demonstrates how to create a YDoc, modify its content within a transaction, and synchronize changes between two document instances."},"warnings":[{"fix":"Refer to the latest official documentation and release notes for API changes when upgrading.","message":"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.","severity":"breaking","affected_versions":"<1.0.0"},{"fix":"Upgrade to `y-py` 0.6.2 or later for Python 3.12 compatibility.","message":"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.","severity":"gotcha","affected_versions":"<0.6.2"},{"fix":"Always wrap modifications to shared types within a `with doc.begin_transaction() as txn:` block.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Update method calls to `Y.apply_update()` and verify other API changes against the latest documentation.","message":"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.","severity":"breaking","affected_versions":"<0.5.5"}],"env_vars":null,"search_vec":"'0.6.2':77 '1.0':69 'api':64 'bind':5,19,53,86 'built':29 'chang':65 'collabor':82 'communic':47 'crdt':9,23,52,78 'cross':45 'cross-domain':44 'current':61,73 'data':26,83 'distribut':25 'domain':46 'enabl':33 'expect':66 'experiment':62 'high':16 'high-perform':15 'librari':28 'like':54 'perform':17 'process':42 'project':59 'py':3,12 'python':4,18 'real':36,80 'real-tim':35,79 'releas':71 'rust':31,85 'seamless':34 'stabl':70,74 'state':40 'synchron':38,84 'time':37,81 'type':27 'version':75 'wasm':57 'y':2,8,11,22,51,56 'y-crdt':7,21,50 'y-pi':1,10 'y-wasm':55","created_at":"2026-04-12T03:50:46.075133+00:00","updated_at":"2026-04-17T14:23:14.701676+00:00","problems":[{"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.","cause":"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.","error":"error: `cargo` exited with an error: No such file or directory (os error 2)"},{"fix":"Access the string content using `str(y_text_obj)` or `y_text_obj.to_json()`.","cause":"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.","error":"AttributeError: 'YText' object has no attribute 'value'"},{"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')`).","cause":"Operations that modify shared Y-types (like `YText`, `YMap`, `YArray`) must be performed within a transaction block.","error":"RuntimeError: Expected transaction"},{"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`.","cause":"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.","error":"ERROR: Failed building wheel for y-py"},{"fix":"Change the import statement from `import ypy` to `import y_py`.","cause":"The library was imported using an incorrect module name. The PyPI package is 'y-py', but the importable module is 'y_py'.","error":"ModuleNotFoundError: No module named 'ypy'"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.6.2","cli_name":"","cli_version":null,"type":"library","homepage":"https://yrs.dev","github":"https://github.com/y-crdt/ypy","docs":null,"changelog":null,"pypi":"https://pypi.org/project/y-py/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["serialization","database","ai-ml"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-29","next_check":"2026-07-28","install_tag":null}}