jupynium.nvim

Jupynium synchronizes your Neovim buffer with a Jupyter Notebook using Selenium browser automation. A Jupynium server receives events from Neovim and applies them to the Jupyter Notebook frontend.

Key characteristics:

• One-way sync: It synchronizes from Neovim to the Notebook. It does not sync from Notebook to Neovim, so you should only modify code within Neovim.
• No kernel extensions required: Because it interacts via the frontend, you can use it with remote Jupyter instances, university-hosted notebooks, or non-Python kernels like R.

Jupynium is split into two primary components to ensure compatibility across different Neovim environments (including remote Neovim). This decoupling allows the CLI to function independently of the Neovim plugin.

1. Python CLI (src/): The core engine. It manages the Selenium browser and handles the synchronization/control logic. It can be operated without the Neovim plugin installed.
2. Lua Files (src/jupynium/lua/): Part of the CLI package. These define the Lua functions and Neovim commands that the Python CLI uses via RPC to interact with Neovim (e.g., starting/stopping sync, executing cells).
3. Neovim Plugin (lua/): The user-facing interface. It handles file extension detection, provides text objects, manages UI effects (like dimming non-focused cells), and provides commands like :JupyniumStartAndAttachToServer to trigger the CLI.

Jupynium follows the Jupytext percent format. Files must be named *.ju.py (or match the jupynium_file_pattern in your setup) to be detected.

Cell Types

• Code Cell: Defined by the separator # %%.
• Markdown Cell: Defined by # %% [md] or # %% [markdown].
  • In Python, wrap content in a multi-line string:

    # %% [md]
    """
    # Heading
    Content
    """

  • In other languages (like R), comment every line.

Magic Commands

• # %time is converted to %time in the notebook.
• To comment out a magic command, use double comments: ## %time.

# %% [md]
"""
# This is a markdown heading
This is markdown content
"""

You can use Jupynium without the Neovim plugin by using the command-line tool. This is useful for attaching to a remote Neovim instance.

1. Install Jupynium: pip3 install jupynium
2. Identify Neovim socket: In Neovim, run :echo v:servername.
3. Run Jupynium:
   • To attach to a specific socket: jupynium --nvim_listen_addr /tmp/your_socket_path
   • Alternatively, start Neovim with a listen address: nvim --listen localhost:18898 notebook.ju.py and then run jupynium --nvim_listen_addr localhost:18898.

Jupynium will open Firefox with Selenium, defaulting to http://localhost:8888/nbclassic.

Follow these steps to start a session:

1. Open a file with the .ju.py extension (e.g., myfile.ju.py).
2. Run :JupyniumStartAndAttachToServer. This opens Firefox with the Jupyter Notebook.
3. Run :JupyniumStartSync. This creates an Untitled.ipynb file in the browser.
4. Create a code cell in Neovim by typing # %%.
5. Execute cells using the default keybinding <space>x.

Install Jupynium using your preferred Neovim plugin manager. It is recommended to install the required Python dependencies using the build step provided by the manager.

Note: You may want to install nvim-notify and dressing.nvim for a better UI experience.

-- Using lazy.nvim
{
  "kiyoon/jupynium.nvim",
  build = "pip3 install --user .",
},
"rcarriga/nvim-notify",   -- optional
"stevearc/dressing.nvim", -- optional

After connecting to the server, you must manually start the sync process. Syncing is one-way (from Neovim to the browser); avoid making changes directly in the browser.

Syncing commands

• :JupyniumStartSync: Syncs the current buffer to a new notebook (defaults to Untitled.ipynb).
• :JupyniumStartSync filename: Syncs the buffer to a specific name (filename.ipynb).
• :JupyniumStartSync <tab_index>: Syncs the current Jupynium file to an existing notebook tab (e.g., :JupyniumStartSync 2 for the 2nd tab).
• :JupyniumStopSync: Stops the synchronization.

Managing files

• :JupyniumDownloadIpynb [filename]: Saves a copy of the current notebook as an .ipynb file.
• :JupyniumAutoDownloadIpynbToggle: Toggles automatic downloading of the .ipynb file.

:JupyniumStartSync [filename / tab_index]

Jupynium uses the Jupytext percent format. You primarily interact with .ju.py files rather than .ipynb files directly. The contents are synced to the browser notebook in real-time.

For new notebooks

Create a local file named <filename>.ju.py.

For existing .ipynb notebooks

Option 1: Command Line Use the included ipynb2jupytext tool:

ipynb2jupytext [-h] [--stdout] [--code_only] file.ipynb [file.ju.py]

Option 2: Via Neovim (requires active server connection)

1. Open the .ipynb file in your web browser (after connecting to the server).
2. In a new Neovim buffer, run :JupyniumLoadFromIpynbTab to convert the notebook contents to Jupynium format.
3. Save the buffer as <filename>.ju.py.

For local Neovim usage, open your .ju.py file and run the following command to start the notebook server and attach Neovim to it:

• :JupyniumStartAndAttachToServer [notebook_URL]
• :JupyniumStartAndAttachToServerInTerminal [notebook_URL] (useful for debugging)
• :JupyniumAttachToServer [notebook_URL] (if the server is already running)

Use require("jupynium").setup({...}) to configure the plugin.

Important Configuration Notes:

• Notebook 7 Compatibility: Jupynium does not support Notebook 7 yet. To use the classic (Notebook 6) interface, set default_notebook_URL = "localhost:8888/nbclassic" and ensure nbclassic is installed via pip (pip install nbclassic).
• Conda Users: If using Conda, you must change python_host to use the conda run command pattern.
• Python Host: Defaults to vim.g.python3_host_prog or python3.

require("jupynium").setup({
  python_host = vim.g.python3_host_prog or "python3",
  default_notebook_URL = "localhost:8888/nbclassic",
  jupyter_command = "jupyter",
  auto_download_ipynb = true,
  auto_close_tab = true,
  jupynium_file_pattern = { "*.ju.*" },
  -- ... other options
})

If the specified --notebook_URL is localhost and no server is running, Jupynium will attempt to start one using the command provided in --jupyter_command.

Note for Conda users: When using conda run, ensure you include the space before the dash in the command string to handle argument escaping correctly.

jupynium --jupyter_command conda run ' --no-capture-output' -n base jupyter