Jupyter Ascending for Emacs

The Jupyter Ascending package facilitates editing and executing code in a Jupyter Python notebook from an ordinary Python buffer in Emacs. It does this by providing Emacs commands which utilize the Jupytext and Jupyter Ascending command line tools for

• rendering .ipynb notebooks as standard Python source files,
• synchronizing the state of the 2 files, and
• executing code in the Jupyter notebook.

This allows users to work with Jupyter Python notebooks in the comfort of Emacs and make use of all the features they would normally have when editing Python code, such as code completion, linting, etc, as well as running the code with their systems Python interpreter.

Demo

Python usage

Markdown usage

Starting up a session

Features

• Synchronization: Editing and saving the Python buffer automatically updates the Jupyter notebook
• Cell execution commands: Run individual cells or the entire notebook
• Navigation tools: Jump between cells with simple commands
• Cell management: Create new cells and toggle between code and markdown types
• Enhanced markdown editing:
  • Edit markdown cells in dedicated markdown buffers (similar to Org mode’s special edit mode)
  • Automatic comment insertion when pressing return in markdown cells
• Setup utilities: Commands for starting Jupyter notebooks and creating synchronized file pairs

Installation

Jupyter Ascending is available on MELPA.

Prerequisites

The following dependencies must be installed first.

If you haven’t already installed Jupyter:

pip install notebook

Then install the Jupyter Ascending command line tool.

pip install jupyter_ascending &&
python3 -m jupyter nbextension    install jupyter_ascending --sys-prefix --py && \
python3 -m jupyter nbextension     enable jupyter_ascending --sys-prefix --py && \
python3 -m jupyter serverextension enable jupyter_ascending --sys-prefix --py

Installing Jupyter Ascending (the command line tool) should install jupytext, but if not, run pip install jupytext.

Configuration

Here’s a sample installation which

• provides keybindings for common commands in jupyter-ascending-mode and
• uses the minor mode when opening python files with the .sync suffix just before the file extension.

(use-package jupyter-ascending
  :ensure t
  :hook (python-mode . (lambda ()
                         (when (and buffer-file-name
                                    (string-match-p "\\.sync\\.py\\'" buffer-file-name))
                           (jupyter-ascending-mode 1))))
  :bind (:map jupyter-ascending-mode-map
              ("C-c C-k" . jupyter-ascending-execute-line)
              ("C-c C-a" . jupyter-ascending-execute-all)
              ("C-c C-n" . jupyter-ascending-next-cell)
              ("C-c C-p" . jupyter-ascending-previous-cell)
              ("C-c t" . jupyter-ascending-cycle-cell-type)
              ("C-c '" . jupyter-ascending-edit-markdown-cell)))

Usage

Create a notebook pair with M-x jupyter-ascending-create-notebook-pair RET example RET Or, equivalently python3 -m jupyter_ascending.scripts.make_pair --base example This creates synced files: example.sync.py and example.sync.ipynb

If you have an existing Jupyter notebook, create a python file from it: M-x jupyter-ascending-convert-notebook RET example.ipynb RET Or, equivalently, jupytext --to py:percent <file_name> and then add the .sync suffix to both files

Start Jupyter and open the notebook: With example.sync.py open, M-x jupyter-ascending-start-notebook Or, equivalently, python3 -m jupyter notebook example.sync.ipynb

Within your Python file, a line starting with # %% deliminates a new cell.

# %% [markdown]
# This is a markdown cell.
# Below is a code cell.

# %%
def g(x):
  return 3*x

When you edit and save the Python source file, you should see the Jupyter notebook running in your browser update straight away.

I recommend you create keybindings for all the following commands:

Command	Description
jupyter-ascending-execute-line	Execute cell at cursor
jupyter-ascending-execute-all	Execute all cells
jupyter-ascending-next-cell	Move to next cell or create new cell
jupyter-ascending-previous-cell	Move to previous cell
jupyter-ascending-edit-markdown-cell	Edit Markdown cell in dedicated buffer
jupyter-ascending-cycle-cell-type	Toggle between Markdown and code cells

Limitations

This package only works with Python notebooks because the Jupyter Ascending command line tool only supports Python notebooks. See here: imbue-ai/jupyter_ascending#25

Related Packages

• emacs-jupyter
• ein