Handle Yjs awareness on the widget comm by gjmooney · Pull Request #40 · QuantStack/ypywidgets

gjmooney · 2026-04-02T16:18:47Z

This PR wires up pycrdt Awareness, so the kernel can consume YMessageType.AWARENESS frames.

CommProvider creates an Awareness(ydoc) alongside sync/update handling. Inbound messages whose first byte is YMessageType.AWARENESS are decoded with read_message and applied with apply_awareness_update.

CommWidget exposes awareness, plus on_awareness_change / unobserve_awareness as thin wrappers over Awareness.observe / unobserve for notebooks and library code.

martinRenou · 2026-04-03T07:44:11Z

Maybe pin pytest=8 for now so that the CI passes

davidbrochart · 2026-04-03T07:57:42Z

I think it requires rethinking the async fixtures, I can look at it.

davidbrochart · 2026-04-04T12:31:52Z

Thanks @gjmooney. We'll need a test for the new functionality.

davidbrochart

I think that there is too much mocking in the tests, in the end they don't test much.
Could you try and test more with less mocking?

src/ypywidgets/comm.py

tests/conftest.py

davidbrochart · 2026-04-07T12:00:26Z

tests/test_comm_awareness.py

+
+    def send(self, *, buffers=None, **kwargs):
+        if buffers:
+            self.sent.append(bytes(memoryview(buffers[0])))


What is it used for?

It was used in the CommProvider __init__ when CommProvider got instantiated with the DummyComm

davidbrochart · 2026-04-07T12:17:21Z

tests/test_comm_awareness.py

+    payload = awareness.encode_awareness_update([awareness.client_id])
+    frame = create_awareness_message(payload)
+
+    assert frame[0] == YMessageType.AWARENESS
+
+    provider._receive({"buffers": [frame]})


The test passes without this code, so I'm wondering what this test checks?

davidbrochart · 2026-04-07T15:54:59Z

I think that there is too much mocking in the tests, in the end they don't test much. Could you try and test more with less mocking?

@gjmooney Don't worry if you cannot reach full coverage. I'm fine with no test and explicit # pragma: nocover in the code. In the end it's an optional feature that should not break existing code.

davidbrochart · 2026-04-08T14:16:28Z

There is something I don't understand: your CommWidget will receive and apply awareness updates, but how are you going to set the awareness and send the updates from the kernel?

martinRenou · 2026-04-08T15:09:29Z

but how are you going to set the awareness and send the updates from the kernel?

For now setting the awareness from the kernel has not been evoked on our side. I wonder if that is something we want to do?

davidbrochart · 2026-04-08T15:24:12Z

Isn't test_remote_manager_applies_awareness_messages doing just that? I suggest to remove it then.

davidbrochart · 2026-04-10T07:28:50Z

tests/conftest.py

        self.remote_widget: Widget | None = None
        self.local_widget_created = Event()
        self.remote_widget_created = Event()
+        self._remote_awareness: Awareness | None = None


If you're not supporting the kernel setting the awareness, no need to test it?

Suggested change

self._remote_awareness: Awareness | None = None

davidbrochart · 2026-04-10T07:29:49Z

tests/test_comm_awareness.py

+pytestmark = pytest.mark.anyio
+
+
+async def test_comm_provider_applies_awareness_frame(synced_widgets, context):


Suggested change

async def test_comm_provider_applies_awareness_frame(synced_widgets, context):

async def test_comm_provider_applies_awareness_message(synced_widgets, context):

davidbrochart · 2026-04-10T07:30:08Z

tests/test_comm_awareness.py

+        remote_awareness = Awareness(Doc())
+        remote_awareness.set_local_state({"role": "remote"})
+        payload = remote_awareness.encode_awareness_update([remote_awareness.client_id])
+        frame = create_awareness_message(payload)


Suggested change

frame = create_awareness_message(payload)

message = create_awareness_message(payload)

davidbrochart · 2026-04-10T07:33:18Z

tests/test_comm_awareness.py

+async def test_comm_widget_exposes_provider_awareness(synced_widgets, context):
+    async with context:
+        widget = await synced_widgets.get_local_widget()
+        assert widget.awareness is widget._comm_provider.awareness


You just need a CommWidget?

Suggested change

async def test_comm_widget_exposes_provider_awareness(synced_widgets, context):

async with context:

widget = await synced_widgets.get_local_widget()

assert widget.awareness is widget._comm_provider.awareness

async def test_comm_widget_exposes_provider_awareness():

widget = CommWidget()

assert widget.awareness is widget._comm_provider.awareness

davidbrochart · 2026-04-10T07:35:27Z

tests/test_comm_awareness.py

+async def test_comm_widget_awareness_observe_and_unobserve(synced_widgets, context):
+    async with context:
+        widget = await synced_widgets.get_local_widget()
+
+        events: list[str] = []
+        sub_id = widget.awareness.observe(lambda topic, _: events.append(topic))
+
+        widget.awareness.set_local_state({"ping": 1})
+        assert events
+
+        widget.awareness.unobserve(sub_id)
+        events.clear()
+        widget.awareness.set_local_state({"ping": 2})
+        assert events == []


Same comment as above.

Suggested change

async def test_comm_widget_awareness_observe_and_unobserve(synced_widgets, context):

async with context:

widget = await synced_widgets.get_local_widget()

events: list[str] = []

sub_id = widget.awareness.observe(lambda topic, _: events.append(topic))

widget.awareness.set_local_state({"ping": 1})

assert events

widget.awareness.unobserve(sub_id)

events.clear()

widget.awareness.set_local_state({"ping": 2})

assert events == []

async def test_comm_widget_awareness_observe_and_unobserve():

widget = CommWidget()

events: list[str] = []

sub_id = widget.awareness.observe(lambda topic, _: events.append(topic))

widget.awareness.set_local_state({"ping": 1})

assert events

widget.awareness.unobserve(sub_id)

events.clear()

widget.awareness.set_local_state({"ping": 2})

assert not events

davidbrochart · 2026-04-10T07:36:35Z

tests/conftest.py

+                        case YMessageType.AWARENESS:  # pragma: nocover
+                            if self._remote_awareness is None:
+                                self._remote_awareness = Awareness(
+                                    self.remote_widget.ydoc  # pragma: no
+                                )
+                            payload = read_message(bytes(message[1:]))
+                            self._remote_awareness.apply_awareness_update(payload, None)


See above.

Suggested change

case YMessageType.AWARENESS: # pragma: nocover

if self._remote_awareness is None:

self._remote_awareness = Awareness(

self.remote_widget.ydoc # pragma: no

)

payload = read_message(bytes(message[1:]))

self._remote_awareness.apply_awareness_update(payload, None)

Support awareness over Comm

0c4c141

gjmooney mentioned this pull request Apr 2, 2026

Wire notebook GIS widget to shared Y doc awareness geojupyter/jupytergis#1246

Open

5 tasks

martinRenou added the enhancement New feature or request label Apr 3, 2026

davidbrochart force-pushed the support-awareness-comm branch from da62498 to 5e14812 Compare April 4, 2026 12:29

davidbrochart force-pushed the support-awareness-comm branch 2 times, most recently from 1a57b31 to b0c950a Compare April 5, 2026 18:23

Merge branch 'main' into support-awareness-comm

a295d55

davidbrochart force-pushed the support-awareness-comm branch from b0c950a to a295d55 Compare April 5, 2026 18:25

gjmooney added 3 commits April 7, 2026 12:09

Tests

065df6f

Lint

7964b05

Coverage

1cac496

gjmooney requested a review from davidbrochart April 7, 2026 11:05

davidbrochart reviewed Apr 7, 2026

View reviewed changes

Apply suggestions and update test

2d86227

gjmooney force-pushed the support-awareness-comm branch from de328d0 to 2d86227 Compare April 8, 2026 09:58

gjmooney force-pushed the support-awareness-comm branch 4 times, most recently from d101d6f to 062974a Compare April 9, 2026 17:02

Remove test

61782e4

gjmooney force-pushed the support-awareness-comm branch from 062974a to 61782e4 Compare April 9, 2026 17:04

davidbrochart reviewed Apr 10, 2026

View reviewed changes

		pytestmark = pytest.mark.anyio


		async def test_comm_provider_applies_awareness_frame(synced_widgets, context):

	frame = create_awareness_message(payload)
	message = create_awareness_message(payload)

Conversation

gjmooney commented Apr 2, 2026

Uh oh!

martinRenou commented Apr 3, 2026

Uh oh!

davidbrochart commented Apr 3, 2026

Uh oh!

davidbrochart commented Apr 4, 2026

Uh oh!

davidbrochart left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

davidbrochart commented Apr 7, 2026

Uh oh!

davidbrochart commented Apr 8, 2026

Uh oh!

martinRenou commented Apr 8, 2026

Uh oh!

davidbrochart commented Apr 8, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants