jupyter-server-ydoc

2.3.0 · active · verified Sun Apr 12

jupyter-server-ydoc is a Jupyter Server extension that integrates collaborative shared models into Jupyter environments, enabling real-time co-editing of notebooks and files. It leverages Yjs for document synchronization. The current Python package version is 2.3.0, and it is part of the larger Jupyter Collaboration project, which sees frequent updates and aims for close integration with JupyterLab and Jupyter Server.

Warnings

gotcha The extension must be explicitly enabled for Jupyter Server. While `jupyter lab --collaborative` can enable it temporarily, for persistent use or headless servers, use `jupyter server extension enable jupyter_server_ydoc`.
Fix: Run `jupyter server extension enable jupyter_server_ydoc` once to persistently enable it. Then launch JupyterLab normally, or with `jupyter lab --collaborative` for explicit collaboration mode.
breaking jupyter-server-ydoc has strict version dependencies on `jupyterlab-server` and `jupyter-ydoc`. Incompatible versions can lead to server startup failures or non-functional collaboration.
Fix: Always check the `requires_dist` section on PyPI or the `pyproject.toml` in the GitHub repository for the exact compatible version ranges of its dependencies. Update all related Jupyter components together if possible.
gotcha Collaboration relies on WebSocket communication. Ensure that firewalls, proxies, or Docker container network configurations do not block WebSocket connections to the Jupyter Server.
Fix: Verify network settings allow WebSocket traffic on the Jupyter Server port. For Docker, ensure ports are exposed correctly. For cloud deployments, check security groups and load balancer settings.
breaking This library requires Python 3.10 or newer.
Fix: Upgrade your Python environment to 3.10 or later. Using an older Python version will lead to installation failure.

Install

pip install jupyter-server-ydoc Install jupyter-server-ydoc

Imports

YDocExtension
```
from jupyter_server_ydoc.extension import YDocExtension
```
This is the Python class representing the server extension. End-users typically interact with it via `jupyter server extension enable` rather than direct import.

Quickstart

This quickstart verifies the installation of `jupyter-server-ydoc` and checks if it's discoverable by the Jupyter Server extension manager. It then provides command-line instructions for enabling the extension and starting JupyterLab with collaborative features.

import subprocess
import sys

try:
    # Verify that jupyter-server-ydoc is installed
    import jupyter_server_ydoc
    print("jupyter-server-ydoc is installed.")

    # Programmatically check if the extension is discoverable by Jupyter Server
    from jupyter_server.extension.manager import ExtensionManager
    from jupyter_server.serverapp import ServerApp
    from traitlets.config import Config

    class DummyServerApp(ServerApp):
        log_level = 0 # Suppress verbose logging
        def initialize(self, argv=None):
            super().initialize(argv)
            if not hasattr(self, 'config'):
                self.config = Config()

    app = DummyServerApp()
    manager = ExtensionManager(serverapp=app)
    extension_name = "jupyter_server_ydoc"

    if extension_name in manager.available_extensions:
        print(f"Extension '{extension_name}' is discoverable by Jupyter Server.")
        print("To enable collaborative features:")
        print(f"1. Run in your terminal: `jupyter server extension enable {extension_name}`")
        print("2. Start JupyterLab with collaboration enabled: `jupyter lab --collaborative`")
        print("3. Share the JupyterLab URL with others for real-time collaboration.")
    else:
        print(f"Error: Extension '{extension_name}' not found by Jupyter Server ExtensionManager.")
        print("Please ensure `jupyter-server-ydoc` is installed and the environment is correct.")

except ImportError:
    print("Error: jupyter-server-ydoc is not installed.")
    print("Please install it using: `pip install jupyter-server-ydoc`")
except Exception as e:
    print(f"An unexpected error occurred: {e}")

view raw JSON →