WIP Add docs for interacting with kernels #3765
Conversation
|
I stuffed the comms documentation under 'User Documentation' because there was nowhere else for it, and you can't make a section for a single document. But now that we've got two, we should look at separating this more technically focused documentation from the pages that explain how to use the notebook. |
|
Good idea. I was having a difficult time trying to figure out where to put this, and finally decided next to comms docs was the best place. |
|
|
||
| TODO If the channel is missing in a message to the notebook server, it is assumed to be the ``shell`` channel. | ||
|
|
||
| Do we want to explicitly document and rely on this behavior, or just make this an undocumented nicety?) |
There was a problem hiding this comment.
In the spec, I think we can say that the channel key is required, since we are in undocumented-behavior territory right now.
|
|
||
| TODO | ||
|
|
||
| should we say that the session value of these is the same as the "session_id" in the kernel connection URL, and corresponds (maybe?) to the session id on the server connecting the filename to the kernel. |
There was a problem hiding this comment.
should we say that the session value of these is the same as the "session_id" in the kernel connection URL
We could do this, but I'm not sure we should commit to it. I think it's mostly an accident that it happens to be this way. We may come up with a better way to signal that a message came 'from the notebook server' than using the client's own session_id in the future. We could mention it as a current implementation detail, though.
corresponds (maybe?) to the session id on the server connecting the filename to the kernel.
It definitely doesn't. session_id is the per-client-connection id used in message headers, not related to the kernel:document mapping.
| The first frame part is the message serialized to JSON and encoded as UTF-8. The rest of the frame parts are the binary buffers associated with the message. | ||
|
|
||
| .. note:: | ||
| Should we explicitly say how we are serializing dates? |
There was a problem hiding this comment.
Since the message is already JSON, it's part of the message spec that dates are ISO8601 strings. At the binary serialization level, everything is JSONable, so just number,str,list,dict. Date handling would be occurring at the library level, e.g. ipywidgets/ipykernel, but not in the message spec.
I think we do already have a note that dates are ISO8601 in the kernel messaging doc
|
|
||
| TODO | ||
|
|
||
| Document the session URL parameter used in kernel connections. Is that created every time we request a kernel with a post request? Is it tied to just creating new sessions with the session rest api? No newline at end of file |
There was a problem hiding this comment.
Yes, we should document it. sessions_id is associated with each specific client. It's entirely unrelated to the session rest API. The session_id here is the message protocol header.session field, which is used on replies and iopub to identify the original sender of the message. The main important use of this session_id is setting zmq.IDENTITY on reconnects to ensure that replies intended for this client still arrive there after reconnects. It's also used to build messages created in the notebook server for this client, but I'm not sure we should commit to or rely on that yet.
|
This is a nearly 4 years PR. Are the proposed changes still applicable? |
Yes, very much so. jupyter/jupyter_client#388 was merged long ago, and this PR has documentation that was taken out of the docs there and put here as a more fitting place (for example, the kernel restarting messages on the websocket). |
However, looking at the documentation in the main branch, for notebook 7, I think this content belongs in the jupyter server docs now, where the websocket connection is actually handled. |
We also document things about kernel message buffering, rate limiting, etc. This migrates jupyter/notebook#3765 to the Jupyter Server repo, where the kernel message additions now happen.
|
I opened up a PR in Jupyter Server: jupyter-server/jupyter_server#869 |
|
Thank you @jasongrout |
4 participants
This fills in the gaps for how interacting with a kernel through the notebook is different than interacting with a kernel directly.
CC @minrk