Previously it was hard to step through the code whenever messages were
coming in live from a kernel due to the asynchronous nature of
handling process output in Emacs.
* jupyter-base.el (jupyter-read-connection): New function.
* jupyter-kernel-process-manager.el
(jupyter-start-kernel) [jupyter-command-kernel]: Use it.
but first...
* jupyter-base.el: ...idle-received-p -> idle-p for jupyter-request objects
* jupyter-client.el: ...then, do it.
* test/jupyter-test.el: Do it.
It is replaced with `jupyter-map-mime-bundle` which is a function.
* jupyter-base.el (jupyter-loop-over-mime): Remove.
(jupyter-map-mime-bundle): New function. Update call sites of the
removed function, with calls to this function.
(jupyter-normalize-data): Return a mime bundle, a property list with
:data and :metadata keys. Update all callers.
* jupyter-mime.el (jupyter-insert): Updated to take into account the
previously mentioned changes.
* jupyter-org-client.el (jupyter-org-result): Ditto.
* test/jupyter-test.el (jupyter-loop-over-mime): Rename to
`jupyter-map-mime-bundle` and update the test to consider it.
Converting to lowercase was done arbitrarily. So that one could write
`(jupyter-lang wolfram-language)` instead of
`(jupyter-lang Wolfram-Language)`.
fixes#241
* CHANGELOG.org: Add note.
* README.org: Update relevant sections.
* jupyter-base.el (jupyter-canonicalize-language-string): Do it.
* ob-jupyter.el (org-babel-jupyter-aliases-from-kernelspecs):
* README.org: Add notes on behavior when a kernel's language name has spaces
and uppercase characters.
* jupyter-base.el (jupyter-canonicalize-language-string): New function.
* jupyter-client.el (jupyter-kernel-info): Use it.
* jupyter-kernelspec.el (jupyter-available-kernelspecs): Use it.
* ob-jupyter.el (org-babel-jupyter-aliases-from-kernelspecs): Use it.
* test/jupyter-test.el (jupyter-canonicalize-language-string): New test.
* jupyter-base.el: Don't add `jupyter-server-mode--unset-client-soon` to
`server-switch-hook` at toplevel
(jupyter-server-mode-set-client): Add `jupyter-server-mode--unset-client-soon`
to `server-switch-hook` if necessary.
* jupyter-client.el: (jupyter--run-callbacks): Use `when-let`.
(jupyter--set-callback): Remove.
(jupyter--add-callback): Use `add-function`.
* jupyter-ioloop.el (jupyter-ioloop-add-arg-type): Use `setf` along with `alist-get`.
(jupyter-ioloop--replace-args): Use `pcase`.
(jupyter-ioloop--event-dispatcher): Extract out event cases into variable `user-events`.
(jupyter-ioloop--body): New function.
(jupyter-ioloop--function): Use it.
* jupyter-kernel-process-manager.el
(jupyter--kernel-died-process-sentinel)
(jupyter-stop-channels): Use `when-let`.
* jupyter-org-client.el (jupyter-org-interaction-mode): Use `cl-callf2?`.
* jupyter-server.el: Add TODO.
* jupyter-tramp.el: Remove unused function declaration.
Having the `jupyter-comm-layer` abstraction means we do not need to do so.
* jupyter-base.el (zmq): Un-require.
(jupyter-socket-types): Move to `jupyter-channels.el`.
(jupyter-session): Don't mention zmq in doc string.
(jupyter-available-local-ports, jupyter-make-ssh-tunnel): New functions.
(jupyter-tunnel-connection): Use them.
* jupyter-channel-ioloop-comm.el: New file.
* jupyter-channels.el (jupyter-messages): Un-require.
(jupyter-comm-layer, zmq): New requires.
(jupyter-socket-types): Moved from `jupyter-base.el`.
(jupyter-send, jupyter-recv):
Implementations for `jupyter-session` moved from `jupyter-messages.el`.
(jupyter-sync-channel-comm): `jupyter-comm-layer` implementation for
`jupyter-sync-channel` objects moved from `jupyter-comm-layer.el`.
* jupyter-comm-layer.el (jupyter-channel-ioloop): Un-require.
(jupyter-sync-channel-comm): Move implementation to `jupyter-channels.el`.
(jupyter-ioloop-comm): Move implementation to new file `jupyter-ioloop-comm.el`.
(jupyter-channel-ioloop-comm):
Move implementation to new file `jupyter-channel-ioloop-comm.el`.
* jupyter-ioloop-comm.el: New file.
* jupyter-ioloop.el (zmq): Require.
* jupyter-kernel-manager.el
(jupyter-make-client): Ensure `jupyter-channel-ioloop-comm` is required.
* jupyter-messages.el (jupyter-send)
(jupyter-recv): Moved to `jupyter-channels.el`
* jupyter-repl.el
(jupyter-connect-repl): Ensure `jupyter-channel-ioloop-comm` is required.
* test/jupyter-test.el (jupyter-available-local-ports): New test.
* test/test-helper.el (jupyter-channel-ioloop-comm): New require.
Fixes#137
* jupyter-base.el (jupyter-kernelspec): Un-require.
(jupyter-command, jupyter-locate-python)
(jupyter-runtime-directory): Move to new file `jupyter-env.el`
(jupyter-include-other-output, jupyter-iopub-message-hook)
(jupyter-shell-message-hook)
(jupyter-stdin-message-hook): Move to `jupyter-client.el`
(jupyter-sha256, jupyter-hmac-sha256):
(jupytern-new-uuid): Move to `jupyter-messages.el`. Add declaration of
`jupyter-new-uuid` to account for its removal.
(jupyter-create-connection-info)
(jupyter-write-connection-file): Move to `jupyter-kernel-manager.el`
(jupyter-connect-endpoint, jupyter-connect-channel): Move to `jupyter-channels.el`
* jupyter-channels.el: Accept moved functions.
* jupyter-client.el: Accept moved variables.
* jupyter-kernel-manager.el: Accept moved functions.
(jupyter-env, jupyter-kernelspec): New requires.
* jupyter-kernelspec (jupyter-env): New require.
(jupyter-command): Remove declaration.
(jupyter-read-plist-from-string): New declaration.
* jupyter-messages.el: Accept moved functions.
(hmac-def, json): New requires.
* jupyter-org-extensions.el (jupyter-kernelspec): New require.
* jupyter-repl.el (jupyter-kernelspec): New require.
* jupyter-env.el: New file.
* ob-jupyter.el (jupyter-env, jupyter-kernelspec): New requires.
* test/jupyter-test.el (jupyter-env): New require.
Speeds up the line count test associated with
`jupyter-eval-short-result-max-lines` by an order of magnitude for somewhat
large strings. The byte compiled versions are not that different.
Since `jupyter-current-client` is a buffer local variable, its value inside the
display buffer is always `nil` when we usually want it to take on the value it
has before this macro is called.
If method arguments are not named it gives rise to errors like
`Args out of range: "", 0`
that originate in `help-function-arglist` when calling `describe-function` on
those methods.
This refactor implements a new class hierarchy to manage the lifetime of a
Jupyter kernel. The first node in this hierarchy is the
`jupyter-kernel-lifetime` class which defines a set of methods to manage the
lifetime of a kernel. An object that inherits from `jupyter-kernel-lifetime` is
stating that it has an association with a kernel and can be used to manage the
lifetime of the associated kernel.
The `jupyter-meta-kernel` class inherits from `jupyter-kernel-lifetime` and
mainly defines a `spec` slot used to hold the `kernelspec` from which a command
can be constructed to start a kernel and a `session` slot used to hold the
`jupyter-session` object that clients can use to establish communication with a
kernel once its live. Concrete classes that actually launch kernels are
intended to inherit from this class and use its slots.
`jupyter-kernel-process` manages the lifetime of a kernel started as a process
using the function `start-file-process`, `jupyter-command-kernel` calls the
`jupyter kernel` shell command to start a kernel, finally `jupyter-spec-kernel`
uses the `spec` slot to construct a shell command to start a kernel.
A `jupyter-kernel-manager` now consists of a `kernel` slot that holds a
`jupyter-meta-kernel` and a `control-channel` slot and inherits from
`jupyter-kernel-lifetime`. The `jupyter-kernel-lifetime` methods of the manager
just defer to those of `kernel` while also taking into account the
`control-channel`.
* jupyter-base.el (jupyter-write-connection-file): New function.
* jupyter-channel-ioloop.el
(jupyter-channel-ioloop-add-start-channel-event): Remove `sleep-for` call.
The startup message is not so important anymore.
* jupyter-client.el (jupyter-wait-until-startup: New function.
* jupyter-kernel-manager.el (jupyter-kernel-lifetime)
(jupyter-kernel, jupyter-kernel-process, jupyter-command-kernel)
(jupyter-spec-kernel): New classes.
(jupyter-kernel-manager): Inherit from jupyter-kernel-lifetime only and
implement its methods.
(jupyter-kernel-manager--cleanup, jupyter-kernel-managers)
(jupyter-delete-all-kernels, jupyter--kernel-sentinel)
(jupyter--start-kernel): Remove and remove related, their functionality has
been generalized in the new classes.
(jupyter-interrupt-kernel, jupyter-shutdown-kernel)
(jupyter-start-channels, jupyter-start-kernel, jupyter-kernel-alive-p)
(jupyter-kill-kernel): Refactor and implement to use the new class hierarchy.
* test/jupyter-test.el: Refactor tests to account for changes.
(jupyter-write-connect-file, jupyter-command-kernel): New tests.
* jupyter-kernelspec.el (jupyter-guess-kernelspec): New function.
The previous mechanism to communicate with a kernel was too low level from the
perspective of a client. The client interfaced directly with the subprocess
abstraction, `jupyter-ioloop`, and had to handle all "events" that occurred in
the `jupyter-ioloop`, e.g. when a channel was started or stopped. But in
reality such events should not be the concern of a client.
A client should only care about events that are directly related to kernel
messages and not events related to the implementation details of *how*
communication occurs.
This commit abstracts out the way in which a client communicates with its
kernel by introducing a new `jupyter-comm-layer` class. The
`jupyter-comm-layer` class takes care of managing the communication channel
between a kernel and its clients as well as sending events to all registered
clients. This way, clients operate solely at the level of events on the
communication layer. All a client does is register itself to receive events on
the communication layer and send events on the layer.
* jupyter-base.el (jupyter-session-endpoints): New function.
* jupyter-client.el (jupyter-kernel-client): Remove ioloop and channels slots.
Add kcomm slot.
(initialize-instance): Unconditionally stop channels.
(jupyter-initialize-connection): Change into a method call.
Call `jupyter-initialize-connection` on the `kcomm` slot.
(jupyter-with-client-buffer): Remove stale comment.
(jupyter-send): Call `jupyter-send` on the `kcomm` slot.
(jupyter-ioloop-handler): Remove all method definitions, replace `sent` and
`message` methods with their `jupyter-event-handler` equivalents.
(jupyter-hb-pause, jupyter-hb-unpause, jupyter-hb-beating):
(jupyter-channel-alive-p, jupyter-start-channel, jupyter-stop-channel):
(jupyter-start-channels, jupyter-stop-channels):
Replace with calls to their equivalents using the `kcomm` slot.
* jupyter-comm-layer.el: New file.
* jupyter-kernel-manager (jupyter-make-client): Set a client's `kcomm` slot to
`jupyter-channel-ioloop-comm`.
* jupyter-messages.el (jupyter-decode-message): Use `list` directly. There
seemed to be issues when using the new `jupyter-sync-channel-comm` due to
using quoted lists.
* test/jupyter-test.el: Add `jupyter-comm-layer` test. Update other tests.
* test/test-helper.el: Add `jupyter-comm-layer` mock objects. Update
`jupyter-echo-client`.
This also removes the use of `shell-command-to-string`, replacing it directly
with `process-file`. `shell-command-to-string` uses `shell-file-name` directly
which may not work properly when `default-directory` is a remote directory as
the remote directory may have a different shell than the local one. See #75.
For this case, no tunnels actually need to be created since docker can expose
ports using the -p flag to `docker run`. This is assumed here. A complete
example to start a kernel in a docker container using one of the official
Jupyter docker images is below:
docker pull jupyter/base-notebook
docker run --name test -it --rm -p 56406-56410:56406-56410 \
jupyter/base-notebook start.sh jupyter-kernel \
--ip=0.0.0.0 \
--KernelManager.control_port=56406 \
--KernelManager.hb_port=56407 \
--KernelManager.iopub_port=56408 \
--KernelManager.shell_port=56409 \
--KernelManager.stdin_port=56410
`accept-process-output` will return when any output has been read from a
process (after it has been handled by the process filter function) which is
usually the time when we want to check on the wait condition so there is no
need to have such a low time resolution.
