The Jupytext Menu is back!

A few weeks back, jupytext==1.16.0 went out. That release included multiple amazing contributions by Mahendra Paipuri, this post will go over the new features, and thank Mahendra for his great work.

As we will see below, Mahendra restored the Jupytext Menu, made the extension fully compatible with JupyterLab 4 and Jupyter Notebook 7, and added the option to create Text Notebooks directly from the launcher.

What is Jupytext

Jupytext is a Python package that lets you save Jupyter Notebooks as text notebooks. Multiple formats are supported, and the notebooks can be saved either as Markdown documents with a .md extension, or as scripts with e.g. a .py extension (assuming you use Python - otherwise multiple languages are supported).

A .py notebook in the percent format looks like this:

# %% [markdown]
# This is a markdown cell

# %%
def f(x):
  return 3*x+1


# %%
[f(i) for i in range(6)]

To open a text notebook as a notebook in Jupyter, right-click on the document and select “Notebook” (you can also change the default viewer to “Jupytext Notebook” if you wish: see below the section about the settings)

Right click to open a text notebook with the Notebook editor

Text notebooks are conveniently edited and executed in Jupyter as notebooks:

A Text Notebook in JupyterLab

You can also edit them with your favorite text editor. You will get the changes back in Jupyter by re-opening or by reloading the document: click e.g. on reload Python file from disk in the File menu.

Text notebooks only contain the notebook inputs. For that reason they use much less disk space than .ipynb notebooks. They are also better suited for version control as they only contain the content that was actually typed by the user. But even more useful are paired notebooks: text notebooks paired with an .ipynb notebook where the notebook outputs are preserved. When a paired notebook is saved, Jupytext writes the notebook to both files. When the notebook is read or reloaded in Jupyter, the notebook inputs are loaded from the most recent file, meaning that any edits on the text notebook will be reflected in Jupyter (and propagated to the .ipynb file the next time it is saved).

The Jupytext Menu is back!

One of the most frequent operation when using Jupytext is to pair an .ipynb notebook with a text notebook in the format of your choice.

In earlier versions of Jupytext, pairing a notebook had to be done through the command palette.

In Jupytext v1.16, thanks to Mahendra’s work on the front-end extension, you can directly use the Jupytext Menu for this. And the menu is available for both JupyterLab 4 and Jupyter Notebook 7!

If you are new to Jupytext, we recommend that you pair your .ipynb notebooks with either a percent script or with a MyST Markdown file. The former format works well if you want to save and edit your notebook as a script, while the latter is well suited for writing documentation.

Once you have paired the notebook with a Jupytext format, save your notebook, and the paired files will be created or updated.

The Jupytext Menu

Creating new text notebooks

For some notebooks you might decide that you don’t need to save the outputs at all. In that case you can work with an (unpaired) text notebook.

To create a text notebook you can use the New Text Notebook sub-menu under File:

Create Text Notebooks directly from the menu

If, later on, you decide that you want to preserve the notebook outputs in a paired .ipynb notebooks, you will just have to pair the document to an .ipynb notebook using the Jupytext Menu documented at the previous paragraph.

Text Notebooks in the launcher

In Jupytext v1.16, thanks to Mahendra’s work on the front end, text notebooks are also available in a Jupytext section in the Jupyter launcher:

Text Notebooks are also available in the launcher

Jupytext Settings in JupyterLab

Since there are many possible formats for text notebooks, we have decided to expose only the most common ones, by default, in the launcher and in the New Text Notebook menu.

You can include more formats in the menu and in the launcher by changing the Jupytext settings in the Settings Editor (in the Settings menu):

The Jupytext Menu/Launcher settings

You might also want to open certain text documents as notebooks with a single click. You can achieve this by setting the default viewer for those documents to “Jupytext Notebook”. For instance, if you want to open .py and .md files as notebooks with a single click, you can configure the default viewers like this:

Changing the default viewers to open Text Notebooks with a single click

Alternatively, you can also list and set the default viewers with the jupytext-config utility (which was developed recently by Thierry Parmentelat), using e.g.

jupytext-config set-default-viewer python markdown

to set “Jupytext Notebook” as the default viewer for both Python and Markdown files.

Pairing notebooks globally

The pairing commands provided through the Jupytext Menu and commands act on individual notebooks, by settings a jupytext.formats metadata in the notebook.

It is also possible to pair all the notebooks within a certain folder using a jupytext.toml configuration file - see Jupytext's documentation. Please note that:

1. The local metadata in the notebook takes precedence over the global configuration, and
2. Jupyter is aware of the global jupytext.toml file and will pair the notebooks accordingly, however the Jupytext Menu is not aware of the global configuration, so the paired formats selected through the global configuration will not be checked in the menu.

Installing Jupytext v1.16

The front end extension for JupyterLab shipped with Jupytext v1.16 requires JupyterLab 4, and/or Jupyter Notebook 7. Please upgrade Jupyter accordingly. Then, install Jupytext with

pip install 'jupytext>=1.16.0'

or

conda install 'jupytext>=1.16.0' -c conda-forge

and restart your Jupyter server with e.g. jupyter lab.

Acknowledgments

I would like to thank Mahendra Paipuri for his impressive work. I am pretty sure that the Jupytext Menu, and the option to create new text notebooks, will be much appreciated by Jupytext users!

While users will mostly notice Mahendra’s work on the front end extension, it was actually not his only contribution to this release! Mahendra also thoroughly revisited the packaging of Jupytext, and helped us transition the project to the src layout, and our old setup.py to an up-to-date pyproject.toml configuration that uses hatch to build Jupytext.

I also want to thank Cristian Le for his precious advice regarding the layout refactoring, and for helping us to tackle the CI reorganization. Thierry Parmentelat, who had previously ported the front-end extension to JupyterLab 4, contributed much testing and feedback on this new version of the front-end extension.

It is always a pleasure for me to maintain Jupytext, an amazing adventure that started five years ago already. However, I can get busy at times (Jupytext comes in addition to my day job, one cat, two bikes, three kids), so I am really thankful for receiving such contributions, especially when they are of such a great quality!