Awesome

Molten

Molten is a fork of Magma, a plugin for running code interactively with the jupyter kernel. Molten provides an excellent repl-like experience, and an incredible notebook-like experience in neovim.

https://github.com/benlubas/molten-nvim/assets/56943754/17ae81c0-306f-4496-bce8-99286e7f21ed

Feature Highlights

• Send code to run asynchronously in the jupyter kernel
• See output below the code in real time, without flicker, as virtual text or in a floating window (or both)
• Renders images, plots, and LaTeX in neovim
• Take input from stdin with vim.ui.input
• Send code from multiple buffers to the same kernel
• Send code from the same buffer to multiple kernels
• Supports any language with a Jupyter Kernel (in theory, they haven't all been tested)
• Python virtual environment support
• Import and Export outputs to and from jupyter notebook files

Requirements

• NeoVim 9.4+
• Python 3.10+
• image.nvim is only required for the image.nvim image provider
• wezterm.nvim is only required for the wezterm image provider
• Required Python packages (can be installed in a venv. read more):
  • pynvim (for the Remote Plugin API)
  • jupyter_client (for interacting with Jupyter)
• Optional Python packages:
  • cairosvg (for displaying SVG images with transparency)
    • If you don't need transparency, image.nvim can render svg images perfectly fine
  • pnglatex (for displaying TeX formulas)
  • plotly and kaleido (for displaying Plotly figures)
  • pyperclip if you want to use molten_copy_output
  • nbformat for importing and exporting output to jupyter notebooks files
  • pillow for opening images with :MoltenImagePopup
  • requests and websocket-client for connecting to the Jupyter Server API via HTTP and WebSocket with :MoltenInit <Jupyter server URL>

You can run :checkhealth to see what you have installed.

Note: Optional python packages are only imported when they're used.

Quick-start

• For the impatient: Probably Too Quick Start Guide
• For everyone else: Not So Quick Start Guide
• Windows users also read this
• NixOS users can checkout this

Configuration information is located further down in this README.

To setup molten for editing Jupyter Notebook files, see Notebook Setup.

Usage

Start by initializing a kernel. This kernel will get a kernel_id which is most commonly just the name of the kernel. If you try to initialize two kernels with the same name, the second one will be named kernel_name_n where n is the total number of kernels that are already initialized.

You execute code by sending it to a kernel, specified by its kernel_id (this is handled automatically if there is only one option).

When you execute some code, it will create a cell. You can recognize a cell because it will be highlighted when your cursor is in it.

A cell is delimited using two extmarks (see :h api-extended-marks), so each cell will adjust when editing text within its boundaries.

When your cursor is in a cell (i.e., you have an active cell), a floating window may be shown below the cell, reporting output. This is the floating output window. (To see more about whether a window is shown or not, see :MoltenShowOutput and g:molten_auto_open_output). When you cursor is not in any cell, no cell is active. When your cursor leaves a cell, its floating output window will close.

Output may also be displayed as virtual text below a cell. Virtual text output will stay there until you re-run the cell or delete the cell.

Overlapping cells are not allowed. If you create an overlapping cell, the old cell will be deleted.

The output window has a header, containing the execution count and execution state (i.e., whether the cell is waiting to be run, running, has finished successfully or has finished with an error). Below the header, output is shown.

Jupyter provides a rich set of outputs. To see what we can currently handle, see Output Chunks.

Commands

These user commands are the main interface to the plugin. It is recommended to map most of them to keys, as explained in Keybindings.

Here is a list of the commands and their arguments. Args in [] are optional, args in "" are literal.

When the kernel argument is specified as optional the command behaves in the following way:

• if the kernel is specified, send the code to that kernel
• else if there is only one active kernel for the current buffer, send the code to that kernel
• else if there is more than one active kernel for the current buffer, prompt the user for the kernel

Some commands will prompt for a kernel when they require one, but no kernel is attached to the buffer. This is configurable with the molten_auto_init_behavior option.

Keybindings

The commands above should be mapped to keys for the best experience.

Pay attention to MoltenEvaluateVisual and MoltenEnterOutput, as they need to be run in...odd ways.

Minimum Suggested

vim.keymap.set("n", "<localleader>mi", ":MoltenInit<CR>",
    { silent = true, desc = "Initialize the plugin" })
vim.keymap.set("n", "<localleader>e", ":MoltenEvaluateOperator<CR>",
    { silent = true, desc = "run operator selection" })
vim.keymap.set("n", "<localleader>rl", ":MoltenEvaluateLine<CR>",
    { silent = true, desc = "evaluate line" })
vim.keymap.set("n", "<localleader>rr", ":MoltenReevaluateCell<CR>",
    { silent = true, desc = "re-evaluate cell" })
vim.keymap.set("v", "<localleader>r", ":<C-u>MoltenEvaluateVisual<CR>gv",
    { silent = true, desc = "evaluate visual selection" })

Other example mappings

vim.keymap.set("n", "<localleader>rd", ":MoltenDelete<CR>",
    { silent = true, desc = "molten delete cell" })
vim.keymap.set("n", "<localleader>oh", ":MoltenHideOutput<CR>",
    { silent = true, desc = "hide output" })
vim.keymap.set("n", "<localleader>os", ":noautocmd MoltenEnterOutput<CR>",
    { silent = true, desc = "show/enter output" })

Configuration

Configuration is done with variables. Below you'll find a table of all the potential configuration variable, their values, and a brief description.

the default value is wrapped in ()

Images

Molten has two image providers, image.nvim or wezterm:

• image.nvim requires the image.nvim plugin (and its dependencies). It renders images in neovim inline with other cell output. This creates a better experience, but it can be buggy with large numbers of images, and it does not work on Windows.

• wezterm requires the wezterm.nvim plugin (and the wezterm terminal emulator). It renders images in a wezterm split pane using wezterm's imgcat program. This method is significantly less buggy with large numbers of images and works on Windows, but it doesn't keep images next to the code they came from.

  • Cannot be used with g:molten_auto_open_output = true
  • Configurable with the g:molten_split_direction and g:molten_split_size options.
  • Currently, the wezterm image provider does not integrate with tmux. There are issues with allowing images to passing through tmux to wezterm. If you are using tmux, you will need to use the image.nvim image provider.

Status Line

Molten provides a few functions that you can use to see information in your status line. These are listed below:

require('molten.status').initialized() -- "Molten" or "" based on initialization information
require('molten.status').kernels() -- "kernel1 kernel2" list of kernels attached to buffer or ""
require('molten.status').all_kernels() -- same as kernels, but will show all kernels

The way these are used will vary based on status line plugin. So please refer to your status line plugin to figure out how to use them.

Highlights

You can change highlights like so:

-- see :h nvim_set_hl for what to put in place of ...
-- I would recommend using the `link` option to link the values to colors from your color scheme
vim.api.nvim_set_hl(0, "MoltenOutputBorder", { ... })

Here is a complete list of the highlight groups that Molten uses, and their default values

• MoltenOutputBorder = FloatBorder: default output window border
• MoltenOutputBorderFail = MoltenOutputBorder: border of a failed output window
• MoltenOutputBorderSuccess = MoltenOutputBorder: border of a successfully run output window
• MoltenOutputWin = NormalFloat: the innards of the output window
• MoltenOutputWinNC = MoltenOutputWin: a "Non-Current" output window
• MoltenOutputFooter = FloatFooter: the "x more lines" text
• MoltenCell = CursorLine: applied to code that makes up a cell
• MoltenVirtualText = Comment: output that is rendered as virtual text

Autocommands

We provide some User autocommands (see :help User) for further customization. They are:

• MoltenInitPre: runs right before MoltenInit initialization happens for a buffer
• MoltenInitPost: runs right after MoltenInit initialization happens for a buffer
• MoltenDeinitPre: runs right before MoltenDeinit de-initialization happens for a buffer
• MoltenDeinitPost: runs right after MoltenDeinit de-initialization happens for a buffer
• MoltenKernelReady: runs when a kernel is ready for the first time. data field has the kernel_id

Here is an example of attaching molten specific mappings to the buffer after initialization:

vim.api.nvim_create_autocmd("User", {
  pattern = "MoltenInitPost",
  callback = function()
    vim.keymap.set("v", "<localleader>r", ":<C-u>MoltenEvaluateVisual<CR>gv",
      { desc = "execute visual selection", buffer = true, silent = true })
    -- ... more mappings
  end,
})

Similarly, you could remove these mappings on MoltenDeinitPost

For MoltenKernelReady you can get the kernel id like this:

-- ...
  callback = function(e)
    print("Kernel id: " .. e.data.kernel_id)
  end
-- ...

Functions

Molten exposes some functionality through vim functions. These are mostly for plugin authors and people who want some custom behavior.

MoltenEvaluateRange(start_line, end_line, [start_col, end_col]) - evaluates the code between the given line numbers and column numbers.

• ranges are inclusive and the indexing 1 based
• columns are optional, when omitted the entire line is captured
• passing -1 for end_col will use the last col on the line
• passing 0 for all other positions will use the last line/col
• The values are used to create extmarks, and the strict option is set to false. See :h nvim_buf_set_extmark() and then options > strict. This means passing 10 when there are only 5 lines in the buffer does result in an error.

-- run lines 1 through 23 (inclusive):
vim.fn.MoltenEvaluateRange(1, 23)

-- run code starting with col 4 on line 1, and ending with the last col on line 3
vim.fn.MoltenEvaluateRange(1, 3, 4, -1)

Additionally, this function can take a kernel_id as the first argument. When a string is given as the first argument, it's assumed to be a kernel_id.

-- run lines 1 through 23 (inclusive) with the python3 kernel
vim.fn.MoltenEvaluateRange("python3", 1, 23)

-- run code starting with col 4 on line 1, and ending with col 20 on line 3 with the R kernel
vim.fn.MoltenEvaluateRange("ir", 1, 3, 4, 20)

When there are multiple kernels attached to the buffer, and this function is called without a kernel_id, the user will be prompted for a kernel with vim.ui.select

Because Molten is a remote plugin, options are loaded and cached at initialization. This avoids making an unnecessary number of RPC calls if we were to fetch configuration values every time we needed to use them. This comes with the trade-off of not being able to update config values on the fly... can you see where this is going.

This function lets you update a configuration value after initialization, and the new value will take effect immediately.

You can specify option names with or without the "molten" prefix.

-- these are the same!
vim.fn.MoltenUpdateOption("auto_open_output", true)
vim.fn.MoltenUpdateOption("molten_auto_open_output", true)

Return a list of the currently running kernels' IDs. Takes one argument, when true, returns only kernels running in the current buffer. Otherwise, returns all running kernel_ids.

vim.fn.MoltenRunningKernels(true) -- list buf local kernel ids
vim.fn.MoltenRunningKernels(false) -- list all kernel ids

Returns a list of kernel names that molten is aware of.

vim.fn.MoltenAvailableKernels()

Takes in a start line, and end line, and a kernel and creates a code cell in the current buffer associated with that kernel. Does not run the code or create/open an output window.

for compatibility reasons, if there is only one active kernel, you do not need to pass the kernel argument

-- Creates a cell from line 5 to line 10 associated with the python3 kernel
vim.fn.MoltenDefineCell(5, 10, 'python3')

Output Chunks

In the Jupyter protocol, most output-related messages provide a dictionary of mime-types which can be used to display the data. Theoretically, a text/plain field (i.e., plain text) is always present, so we (theoretically) always have that fallback.

Here is a list of the currently handled mime-types:

• text/plain: Plain text. Shown as text in the output window's buffer.
• image/*: Molten attempts to render any image mimetype by sending it to image.nvim. In theory, this means that Molten can handle any image format that image.nvim supports, though I've only tested common formats
  • Images are also viewable outside of the terminal with :MoltenImagePopup
• application/vnd.plotly.v1+json: A Plotly figure. Rendered into a PNG with Plotly + Kaleido
• text/latex: A LaTeX formula. Rendered into a PNG with pnglatex
• text/html: via the :MoltenOpenInBrowser command.

This already provides quite a bit of basic functionality, but if you find a use case for a mime-type that isn't currently supported, feel free to open an issue and/or PR!

Thanks

• @dccsillag and everyone who has contributed to magma-nvim
• @3rd and everyone who has contributed to image.nvim