Jupyter Y-document

3.4.0 · active · verified Sun Apr 12

jupyter-ydoc provides document structures for collaborative editing in Jupyter environments, leveraging the Ypy library. It enables real-time synchronization of Jupyter notebooks and other file types using Yjs CRDTs. The library is actively maintained by the Jupyter project, with frequent patch and minor releases.

Warnings

breaking Starting with version 3.3.0, `jupyter-ydoc` requires Python 3.10 or newer. Installations on older Python versions will fail.
Fix: Upgrade your Python environment to 3.10 or later.
gotcha Older versions of `jupyter-ydoc` (prior to 3.3.3) had issues handling multi-byte Unicode characters in files, potentially leading to data corruption or incorrect display.
Fix: Upgrade to `jupyter-ydoc` version 3.3.3 or higher to ensure correct handling of all Unicode characters.
gotcha Several bugs in versions prior to 3.3.4 could lead to cell duplication, incorrect reloading, or inconsistent states during collaborative editing of notebooks.
Fix: It is highly recommended to upgrade to `jupyter-ydoc` version 3.3.4 or later to benefit from critical bug fixes related to document synchronization and integrity.
gotcha Version 3.4.0 introduced asynchronous `get` and `set` methods for documents. While existing synchronous methods remain, developers building new integrations or optimizing performance might need to adapt to the new async patterns.
Fix: Consult the official documentation for `jupyter-ydoc` version 3.4.0 to understand the new `async_get` and `async_set` methods and their usage in asynchronous contexts.

Install

pip install jupyter-ydoc Install stable version

Imports

YDoc
```
from jupyter_ydoc import YDoc
```
YFile
```
from jupyter_ydoc import YFile
```
YNotebook
```
from jupyter_ydoc import YNotebook
```

Quickstart

This quickstart demonstrates how to initialize a YDoc, wrap it with YNotebook, set content from a standard Jupyter notebook dictionary, retrieve the content, and programmatically add a new cell to the Y-document structure.

import json
from jupyter_ydoc import YDoc, YNotebook

# 1. Initialize a YDoc (the core Yjs document)
ydoc = YDoc()

# 2. Create a YNotebook wrapper for the YDoc
# This initializes the YDoc with an empty notebook structure if it's new.
ynotebook = YNotebook(ydoc)

# 3. Set content from a standard Jupyter notebook dictionary
notebook_content = {
    "cells": [
        {"cell_type": "code", "source": "print('Hello from jupyter-ydoc!')", "metadata": {}},
        {"cell_type": "markdown", "source": "## Getting Started", "metadata": {}}
    ],
    "metadata": {
        "kernelspec": {"display_name": "Python 3", "language": "python", "name": "python3"},
        "language_info": {"codemirror_mode": {"name": "ipython", "version": 3}}
    },
    "nbformat": 4,
    "nbformat_minor": 5
}
ynotebook.set(notebook_content)
print("Notebook content set successfully.")

# 4. Retrieve content as a standard Jupyter notebook dictionary
retrieved_content = ynotebook.get()
print("\nRetrieved notebook content:")
print(json.dumps(retrieved_content, indent=2))

# 5. Manipulate the notebook content (e.g., add a new cell)
ynotebook.append_cell({"cell_type": "code", "source": "x = 10\ny = 20\nx + y", "metadata": {}})
print("\nAdded a new code cell.")

# 6. Get the updated content
updated_content = ynotebook.get()
print("\nUpdated notebook content after adding cell:")
print(json.dumps(updated_content, indent=2))

view raw JSON →