🔙 Backport Support talking to Colab from the JKC #34

echarles · 2026-01-16T14:29:42Z

Fixes #35

… (experiment)

Changes to support talking to Colab from the JKC

Copilot

Pull request overview

This pull request adds support for the Jupyter Kernel Client to communicate with Google Colab by introducing a new JSON-based WebSocket subprotocol alongside the existing v1 binary protocol.

Changes:

Introduced JupyterSubprotocol enum to specify communication protocols (DEFAULT, V1, JSON)
Added JSON serialization/deserialization functions for Colab compatibility
Enhanced KernelWebSocketClient and WSSession to support multiple subprotocols
Modified KernelHttpManager to accept and forward custom headers
Added dependency-groups configuration for uv package manager
Updated test dependencies and added Makefile test target

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 14 comments.

Show a summary per file

File	Description
pyproject.toml	Added dependency-groups for uv, specified new test dependencies, and added test target configuration
jupyter_kernel_client/wsclient.py	Introduced JupyterSubprotocol enum, added subprotocol parameter to WSSession and KernelWebSocketClient, implemented protocol-specific message serialization logic
jupyter_kernel_client/utils.py	Added JSON serialization/deserialization functions for Colab support
jupyter_kernel_client/manager.py	Added headers parameter support and updated User-Agent string
jupyter_kernel_client/client.py	Added null check for manager in stop method
jupyter_kernel_client/init.py	Exported JupyterSubprotocol enum
Makefile	Added test target for running pytest

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-01-16T14:36:38Z

jupyter_kernel_client/manager.py

+    headers = {
+        "Accept": "application/json",
+        "Content-Type": "application/json",
+        "User-Agent": "Jupyter Kernel Client"


The User-Agent header value was changed from "Jupyter kernels CLI" to "Jupyter Kernel Client". While this change is likely intentional to better reflect the library's name, it represents a breaking change that could impact server-side analytics, logging, or behavior that depends on the User-Agent string.

Suggested change

"User-Agent": "Jupyter Kernel Client"

"User-Agent": "Jupyter kernels CLI"

Copilot · 2026-01-16T14:36:39Z

pyproject.toml

+[dependency-groups]
+dev = [
+    {include-group = "test"}
+]
+test = [
+    "ipykernel>=6.31.0",
+    "jupyter-server>=2.17.0",
+    "numpy>=2.0.2",
+    "pandas>=2.3.3",
+    "pytest>=8.4.2",
+    "pytest-asyncio>=1.2.0",
+    "pytest-cov>=7.0.0",
+    "pytest-timeout>=2.4.0",
+]


The dependency-groups section duplicates and conflicts with the existing project.optional-dependencies.test section. The dependency-groups.test has different version constraints (e.g., ipykernel>=6.31.0 vs ipykernel without version, jupyter-server>=2.17.0 vs jupyter_server>=2.10,<3). This duplication can cause confusion about which dependencies to use and may lead to inconsistent test environments. Consider consolidating these or clarifying which should be used.

Copilot · 2026-01-16T14:36:39Z

jupyter_kernel_client/wsclient.py

+
+

There are extra blank lines here. Line 480 appears to be unnecessary trailing whitespace, and line 481 adds an extra blank line. This violates code style conventions and may cause linting issues.

Suggested change

Copilot · 2026-01-16T14:36:39Z

jupyter_kernel_client/wsclient.py

+    token_param: String | None
+        The name of the token parameter to use.


The docstring comment on line 474 incorrectly states "String | None" for the token_param type. However, there is no token_param parameter in the init method signature. This documentation appears to be erroneous or incomplete.

Suggested change

token_param: String | None

The name of the token parameter to use.

Copilot · 2026-01-16T14:36:39Z

jupyter_kernel_client/utils.py

+
+def deserialize_msg_from_ws_json(ws_msg):
+    """Deserialize as JSON (for Colab)."""
+    return json.loads(ws_msg.encode('utf-8'))


The deserialize_msg_from_ws_json function is calling encode on a parameter that is already bytes. According to the _on_message signature in wsclient.py (line 1247), the message parameter is already of type bytes. Calling encode on bytes will raise an AttributeError. The function should either accept a string and encode it, or accept bytes and decode it directly.

Suggested change

return json.loads(ws_msg.encode('utf-8'))

# `ws_msg` may be either `str` or `bytes` depending on the WebSocket client.

# If it's bytes, decode it to text before passing to json.loads.

if isinstance(ws_msg, bytes):

text = ws_msg.decode("utf-8")

else:

text = ws_msg

return json.loads(text)

Copilot · 2026-01-16T14:36:41Z

jupyter_kernel_client/wsclient.py

+class JupyterSubprotocol(Enum):
+    """JupyterSubprotocol specifies which subprotocol the KernelWebSocketClient should specifically
+    request when interacting with the Jupyter server.
+    """
+
+    # Use the default subprotocol
+    # https://jupyter-server.readthedocs.io/en/latest/developers/websocket-protocols.html#default-websocket-protocol
+    DEFAULT = 0
+
+    # Use the v1.kernel.websocket.jupyter.org protocol
+    # https://jupyter-server.readthedocs.io/en/latest/developers/websocket-protocols.html#v1-kernel-websocket-jupyter-org-protocol
+    V1 = 1
+
+    # JSON is specifically for Colab (until we modify this library to actually have support for DEFAULT)
+    JSON = 2


The new JupyterSubprotocol enum and JSON subprotocol support lack test coverage. Given that the repository has comprehensive test coverage for other kernel client functionality, the new subprotocol behavior (especially the JSON serialization path for Colab) should be tested to ensure correctness.

Copilot · 2026-01-16T14:36:41Z

jupyter_kernel_client/wsclient.py

                header=header,
                metadata=metadata,
            )
+        msg['channel'] = channel


The 'channel' field is unconditionally added to msg for all subprotocols. This is necessary for the JSON subprotocol but may not be appropriate for the V1 subprotocol, where the channel is passed as a separate parameter to serialize_msg_to_ws_v1. Consider adding the channel field conditionally based on the subprotocol to avoid polluting the message dict unnecessarily.

Suggested change

msg['channel'] = channel

# Only include the channel in the message dict for JSON subprotocol,

# where the channel is expected to be part of the serialized message.

if self.subprotocol == JupyterSubprotocol.JSON:

msg["channel"] = channel

Copilot · 2026-01-16T14:36:41Z

jupyter_kernel_client/manager.py

 from __future__ import annotations

 import datetime
+import logging


Import of 'logging' is not used.

Suggested change

import logging

Copilot · 2026-01-16T14:36:41Z

jupyter_kernel_client/utils.py


 from datetime import datetime, timedelta, timezone, tzinfo
+import json
+import logging


Import of 'logging' is not used.

Suggested change

import logging

Copilot · 2026-01-16T14:36:42Z

jupyter_kernel_client/wsclient.py

 from __future__ import annotations

+
+import json


Import of 'json' is not used.

Suggested change

import json

Add support for listing kernels

…tocol (#3) * Add serializers and deserializers for Jupyter's default websocket protocol * Adds a default serializer/deserializer - Logic unabashedly swiped from https://github.com/jupyterlab/jupyterlab/blob/main/packages/services/src/kernel/serialize.ts#L216 * Sets default values for the protocol as DEFAULT since it's... the default * Adds simple testing for the serializers/deserializers * Fixes minor bug with the logger being angry about multiple channels being defined * didn't realize that was a required arg for * ugh from_bytes as well * in tests as well * address comments * fix uv.lock * fix uv.lock --------- Co-authored-by: Drake Aiman <drakeaiman@google.com>

echarles

LGTM

teeler and others added 10 commits December 12, 2025 16:34

Add support for Colab

e155fff

fix headers

89066e2

fix typo

9194e6e

a few more cleanups

841526b

put the right user agent back in, remove the old commented out header…

bbf47ba

… (experiment)

add a JSON protocol as a workaround

3c31bd4

some cleanups to fix tests

251e71e

make running tests a little easier

7f3258e

remove crufty print statements

d93ec59

Merge pull request #1 from teeler/mods

beb6355

Changes to support talking to Colab from the JKC

Copilot AI review requested due to automatic review settings January 16, 2026 14:29

Copilot started reviewing on behalf of echarles January 16, 2026 14:30 View session

echarles changed the title ~~PORT - Changes to support talking to Colab from the JKC~~ BACKPORT - Changes to support talking to Colab from the JKC Jan 16, 2026

Copilot AI reviewed Jan 16, 2026

View reviewed changes

echarles assigned eleonorecharles Jan 20, 2026

echarles added the enhancement New feature or request label Jan 20, 2026

echarles changed the title ~~BACKPORT - Changes to support talking to Colab from the JKC~~ 🔙 Backport Support talking to Colab from the JKC Jan 20, 2026

echarles assigned echarles and unassigned eleonorecharles Jan 23, 2026

teeler and others added 2 commits January 28, 2026 21:23

Support for listing kernels (#2)

57fda74

Add support for listing kernels

echarles commented Feb 4, 2026

View reviewed changes

echarles merged commit 786cdc3 into datalayer:main Feb 4, 2026
2 of 9 checks passed

	"User-Agent": "Jupyter Kernel Client"
	"User-Agent": "Jupyter kernels CLI"

		token_param: String \| None
		The name of the token parameter to use.

-    return json.loads(ws_msg.encode('utf-8'))
+    # `ws_msg` may be either `str` or `bytes` depending on the WebSocket client.
+    # If it's bytes, decode it to text before passing to json.loads.
+    if isinstance(ws_msg, bytes):
+        text = ws_msg.decode("utf-8")
+    else:
+        text = ws_msg
+    return json.loads(text)

-        msg['channel'] = channel
+        # Only include the channel in the message dict for JSON subprotocol,
+        # where the channel is expected to be part of the serialized message.
+        if self.subprotocol == JupyterSubprotocol.JSON:
+            msg["channel"] = channel

Uh oh!

🔙 Backport Support talking to Colab from the JKC #34

🔙 Backport Support talking to Colab from the JKC #34

Uh oh!

Conversation

echarles commented Jan 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Jan 16, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 16, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 16, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 16, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 16, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 16, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 16, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 16, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 16, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 16, 2026

Choose a reason for hiding this comment

Uh oh!

echarles left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

echarles commented Jan 16, 2026 •

edited

Loading