Feat/ws url (#41)

* chore: add proxy method

* makefile

* lint

* fix: stop

* stop: revert

Author: echarles

Makefile

@@ -28,6 +28,9 @@ build:
 clean: ## clean
 	git clean -fdx
 
+jupyter-server: ## jupyter-server
+	jupyter server --port 8888 --ServerApp.port_retries 0 --IdentityProvider.token MY_TOKEN --ServerApp.root_dir ./dev
+
 jupyterlab: ## jupyterlab
 	jupyter lab --port 8888 --ServerApp.port_retries 0 --IdentityProvider.token MY_TOKEN --ServerApp.root_dir ./dev
 

README.md

@@ -29,7 +29,7 @@ pip uninstall -y pycrdt datalayer_pycrdt
 pip install datalayer_pycrdt
 ```
 
-## Usage
+## Usage with Jupyter
 
 1. Ensure you have the needed packages in your environment to run the example here after.
 
@@ -125,7 +125,7 @@ with KernelClient(server_url="http://localhost:8888", token="MY_TOKEN") as kerne
 
 > [!NOTE]
 >
-> Instead of using the clients as context manager, you can call the `start()` and `stop()` methods.
+> Instead of using the nbmodel clients as context manager, you can call the `start()` and `stop()` methods.
 
 ```py
 from jupyter_nbmodel_client import NbModelClient, get_jupyter_notebook_websocket_url
@@ -150,21 +150,27 @@ finally:
     kernel.stop()
 ```
 
-> [!NOTE]
->
-> To connect to Datalayer collaborative room, you can use the helper function `get_datalayer_websocket_url`:
+## Usage with Datalayer
+
+To connect to a [Datalayer collaborative room](https://docs.datalayer.app/platform#notebook-editor), you can use the helper function `get_datalayer_notebook_websocket_url`:
+
+- The `server` is `https://prod1.datalayer.run` for the Datalayer production SaaS.
+- The `room_id` is the id of your notebook shown in the URL browser bar.
+- The `token` is the assigned token for the notebook.
+
+All those details can be retrieved from a Notebook sidebar on the Datalayer SaaS.
 
 ```py
-from jupyter_nbmodel_client import NbModelClient, get_datalayer_websocket_url
+from jupyter_nbmodel_client import NbModelClient, get_datalayer_notebook_websocket_url
 
-ws_url = get_datalayer_websocket_url(
+ws_url = get_datalayer_notebook_websocket_url(
     server_url=server,
     room_id=room_id,
     token=token
 )
 
 async with NbModelClient(ws_url) as notebook:
-    notebook.add_code_cell(CODE)
+    notebook.add_code_cell("1+1")
 ```
 
 ## Uninstall
@@ -177,7 +183,7 @@ pip uninstall jupyter_nbmodel_client
 
 ## Data Models
 
-The following json schema describe the data model used in cells and notebook metadata to communicate between user clients and an Jupyter AI Agent.
+The following json schema describes the data model used in cells and notebook metadata to communicate between user clients and an Jupyter AI Agent.
 
 For that, you will need the [Jupyter AI Agents](https://github.com/datalayer/jupyter-ai-agents) extension installed.
 

jupyter_nbmodel_client/__init__.py

@@ -9,7 +9,11 @@
 from jupyter_nbmodel_client._version import VERSION as __version__  # noqa: N811
 from jupyter_nbmodel_client.agent import AIMessageType, BaseNbAgent
 from jupyter_nbmodel_client.client import NbModelClient
-from jupyter_nbmodel_client.helpers import get_datalayer_websocket_url, get_jupyter_notebook_websocket_url
+from jupyter_nbmodel_client.helpers import (
+    get_notebook_websocket_url,
+    get_datalayer_notebook_websocket_url,
+    get_jupyter_notebook_websocket_url,
+)
 from jupyter_nbmodel_client.model import KernelClient, NotebookModel
 
 
@@ -21,6 +25,7 @@
     "NotebookModel",
     "NotebookNode",
     "__version__",
-    "get_datalayer_websocket_url",
+    "get_notebook_websocket_url",
+    "get_datalayer_notebook_websocket_url",
     "get_jupyter_notebook_websocket_url",
 ]

jupyter_nbmodel_client/_version.py

@@ -2,4 +2,4 @@
 #
 # BSD 3-Clause License
 
-VERSION = "0.13.0"
+VERSION = "0.13.4"

jupyter_nbmodel_client/agent.py

@@ -2,7 +2,7 @@
 #
 # BSD 3-Clause License
 
-"""This module provides a base class agent to interact with collaborative Jupyter notebook."""
+"""This module provides a base class AI agent to interact with collaborative Jupyter notebook."""
 
 from __future__ import annotations
 
@@ -106,7 +106,7 @@ class BaseNbAgent(NbModelClient):
     """
 
     user_agent: str = f"Datalayer-BaseNbAgent/{VERSION}"
-    """User agent used to identify the client type in the awareness state."""
+    """User agent used to identify the nbmodel client type in the awareness state."""
 
     def __init__(
         self,

jupyter_nbmodel_client/client.py

@@ -129,11 +129,11 @@ class NbModelClient(NotebookModel):
     #
     # Document changes callback is only placing event in a queue as it is a blocking operation.
     #
-    # When using the client as a context manager or the start/stop methods, the `run` method will be
+    # When using the nbmodel client as a context manager or the start/stop methods, the `run` method will be
     # executed in a task.
 
     user_agent: str = f"Datalayer-NbModelClient/{VERSION}"
-    """User agent used to identify the client type in the awareness state."""
+    """User agent used to identify the nbmodel client type in the awareness state."""
 
     def __init__(
         self,
@@ -190,7 +190,8 @@ async def __aexit__(self, exc_type, exc_value, exc_tb) -> None:
         await self.stop()
 
     async def run(self) -> None:
-        """Run the client."""
+        """Run the nbmodel client."""
+        self._log.info("Starting the nbmodel client…")
         if self.__is_running:
             raise RuntimeError("NbModelClient is already connected.")
 
@@ -253,7 +254,7 @@ async def run(self) -> None:
             # Wait forever and prevent the forwarder to be cancelled to avoid losing changes
             await asyncio.gather(awareness_ping, listener, asyncio.shield(sender))
         finally:
-            self._log.info("Stop the client…")
+            self._log.info("Stopping the nbmodel client…")
 
             # Stop listening to incoming messages
             if listener.cancel():
@@ -300,7 +301,7 @@ async def run(self) -> None:
     def get_local_client_id(self) -> int:
         """Get the local client ID.
 
-        This is the identifier of the client communicated to all peers.
+        This is the identifier of the nbmodel client communicated to all peers.
 
         Returns:
             The local client ID.
@@ -338,7 +339,7 @@ def set_local_state_field(self, key: str, value: Any) -> None:
         cast(Awareness, self._doc.awareness).set_local_state_field(key, value)
 
     async def start(self) -> None:
-        """Start the client."""
+        """Start the nbmodel client."""
         if self.__run is not None:
             raise RuntimeError("The client is already connected.")
 
@@ -358,9 +359,15 @@ def callback(_: asyncio.Task) -> None:
             self._log.warning("Document %s not yet synced.", self._path)
 
     async def stop(self) -> None:
-        """Stop and reset the client."""
-        if self.__run is not None and self.__run.cancel():
-            await asyncio.wait([self.__run])
+        """Stop and reset the nbmodel client."""
+        if self.__run is not None:
+            if self.__run.cancel():
+                # TODO without timeout, stop() sometimes hangs indefinitely.
+                # try:
+                #     await asyncio.wait_for(self.__run, timeout=1.0)
+                # except TimeoutError:
+                #     self._log.warning('Timeout with stopping the nbmodel client "%s".', self._path)
+                await asyncio.wait([self.__run])
 
     async def wait_until_synced(self) -> None:
         """Wait until the model is synced."""

jupyter_nbmodel_client/helpers.py

@@ -11,6 +11,37 @@
 from jupyter_nbmodel_client.utils import fetch, url_path_join
 
 
+def get_notebook_websocket_url(
+    server_url: str,
+    path: str,
+    provider: "jupyter" | "datalayer" = "jupyter",
+    token: str | None = None,
+    timeout: float = REQUEST_TIMEOUT,
+    log: logging.Logger | None = None,
+) -> str:
+    """Get the websocket endpoint to connect to a collaborative Jupyter notebook.
+
+    Args:
+        server_url: Jupyter Server URL
+        provider: jupyter or datalayer
+        path: Notebook path relative to the server root directory
+        token: [optional] Jupyter Server authentication token; default None
+        timeout: [optional] Request timeout in seconds; default to environment variable REQUEST_TIMEOUT
+        log: [optional] Custom logger; default local logger
+
+    Returns:
+        The websocket endpoint
+    """
+    if provider == "jupyter":
+        return get_jupyter_notebook_websocket_url(
+            server_url, path, token, timeout, log
+        )
+    elif provider == "datalayer":
+        return get_datalayer_notebook_websocket_url(
+            server_url, path, token, timeout, log
+        )
+
+
 def get_jupyter_notebook_websocket_url(
     server_url: str,
     path: str,
@@ -31,7 +62,7 @@ def get_jupyter_notebook_websocket_url(
         The websocket endpoint
     """
     (log or DEFAULT_LOGGER).debug("Request the session ID from the Jupyter server.")
-    # Fetch a session ID
+    # Fetch a session ID.
     response = fetch(
         url_path_join(server_url, "/api/collaboration/session", quote(path)),
         token,
@@ -54,7 +85,7 @@ def get_jupyter_notebook_websocket_url(
     return room_url
 
 
-def get_datalayer_websocket_url(
+def get_datalayer_notebook_websocket_url(
     server_url: str,
     room_id: str,
     token: str | None = None,