PyViz Comms

Warnings

• breaking For JupyterLab versions older than 3.0, the `@pyviz/jupyterlab_pyviz` extension needed to be installed manually using `jupyter labextension install @pyviz/jupyterlab_pyviz`. `pyviz-comms` version 3.x is specifically designed for JupyterLab 3.x and 4.x, where the extension is automatically bundled with the Python package.
  Fix: Upgrade JupyterLab to version 3.0 or higher. If unable to upgrade, use an older `pyviz-comms` version compatible with your JupyterLab or manually install the `jupyterlab_pyviz` extension.
• gotcha The project was formerly known as 'PyViz', which can cause confusion with the broader 'PyViz.org' community project that catalogs all Python visualization tools. `pyviz-comms` is now firmly part of the 'HoloViz' ecosystem.
  Fix: Refer to the official HoloViz documentation (holoviz.org) for information and usage patterns, and understand that `pyviz-comms` is a component within the HoloViz suite.
• gotcha pyviz-comms provides a low-level communication primitive. Most users of the HoloViz ecosystem will interact with this functionality indirectly through higher-level libraries like Panel, HoloViews, or Bokeh, rather than directly using `pyviz_comms.Comm`. Direct usage often requires detailed knowledge of both Python and JavaScript comms.
  Fix: Consider using higher-level HoloViz libraries like Panel (panel.holoviz.org) or HoloViews (holoviews.org) for most visualization and dashboarding needs, as they abstract away the complexities of direct comms management.

Install

• pip install pyviz-comms Latest version

Imports

• Comm

  from pyviz_comms import Comm

  This is the main class for establishing bidirectional communication.
• IPyComm

  from ipykernel.comm import Comm as IPyComm

  pyviz_comms internally uses `ipykernel.comm.Comm` and exposes it as `pyviz_comms.Comm`. Direct import of `IPyComm` from `pyviz_comms` is not the intended public API, though `Comm` itself wraps it.

Quickstart

This quickstart demonstrates how to establish a basic bidirectional communication channel using `pyviz_comms.Comm` within a Jupyter environment. It sets up a Python-side message handler and sends an initial message. For full interactivity, a corresponding JavaScript snippet must be executed in a Jupyter frontend cell to register the client-side comm and handle messages from Python, as well as send messages back. This example illustrates the low-level nature of `pyviz-comms`; higher-level libraries like Panel abstract much of this complexity.

from pyviz_comms import Comm
from IPython.display import display, Javascript

def python_message_handler(msg):
    print(f"Python received: {msg['content']['data']}")

# Create a new comm target
comm_id = 'my_pyviz_comm_example'
comm = Comm(target_name=comm_id, data={})
comm.on_msg(python_message_handler)

# Send a message from Python to the frontend
comm.send(data={'status': 'hello from python!'})

# To make this truly bidirectional, a JavaScript counterpart is needed in the Jupyter frontend.
# Run the following JavaScript in a separate Jupyter cell:
#
# %%javascript
# if (window.PyViz == undefined) { window.PyViz = {}; }
# if (window.PyViz.comms == undefined) { window.PyViz.comms = {}; }
#
# Jupyter.notebook.kernel.comm_manager.register_target('my_pyviz_comm_example', function(comm) {
#     window.PyViz.comms[comm.comm_id] = comm;
#     comm.on_msg(function(msg) {
#         console.log("JS received:", msg.content.data);
#         comm.send({'response': 'hello from JS!'});
#     });
#     comm.send({'ready': true});
#     console.log("JS comm 'my_pyviz_comm_example' registered and ready.");
# });

# After running the JS, you could send another message from Python:
# comm.send(data={'action': 'update_chart'})