jupyter-tempvars 0.1.dev1

Jupyter notebook extension providing per-cell temporary variables

jupyter-tempvars: Convenient temporary variable management in Jupyter Notebook

Do you work in Jupyter Notebook?

Are your notebooks flaky sometimes, due to leftover/temporary variables?

jupyter-tempvars can help!

Namespace pollution with leftover/temporary variables is a common challenge of using Jupyter notebooks. It's a downside of the power provided by the shared global notebook namespace, for things like exploratory data analysis.

And, it can be a pretty big downside. It's quite annoying to work for hours to try to figure out what's wrong with a notebook, only to have it suddenly work properly when you restart Jupyter. It's also quite annoying to have a workbook that you thought was working correctly, suddely stop working once you restart. It can cause even bigger problems if you pass a notebook on to someone else, and then it doesn't work right for them even though it was working fine for you.

jupyter-tempvars is a Jupyter nbextension built on the tempvars Python package that helps minimize these kinds of problems. Simply decorate code cells with metadata tags matching a defined template, and then variables that fit the rules you define will be automatically treated as temporary variables. This means that:

1. Matching variables will be removed from the global namespace before each tagged cell is executed, ensuring that cell isn't contaminated by "dragged-in" variables, and

2. Matching variables will be removed from the global namespace after the cell has finished executing, ensuring that other code cells aren't contaminated by this cell, either.

Prerequisites

Python

I've been developing jupyter-tempvars using Python 3.9, but I believe any version of Python 3 that works with the underlying tempvars library (which should be all actively maintained versions, 3.7+) should work fine. It should work on any platform supported by Jupyter. (At some point soon here, I'll be figuring out a test suite to actually check across platforms and Pythons....)

Jupyter

jupyter-tempvars requires a full instance of Jupyter Notebook, including the Javascript frontend. So far, I've only tested it with vanilla Jupyter, but in theory I think it should work with JupyterHub, Jupyter in Anaconda, etc. I would be grateful for feedback from anyone who tries to use it in other contexts. I believe it should work with notebook versions 4.x and above. Note that jupyter-tempvars will NOT work with JupyterLab!

To get a basic Jupyter install just pip install jupyter.

jupyter-contrib-nbextensions

The community-developed jupyter-contrib-nbextensions package is not strictly required in order to use jupyter-tempvars, but it's highly recommended. If nothing else, the configurator plugin that adds a Nbextensions tab to the main Jupyter interface is really handy. See the install instructions here.

Installation

The first step is to install the overall jupyter-tempvars package. It's on PyPI, so just:

$ pip install jupyter-tempvars

From there, the jupyter_tempvars extension needs to be installed into the Jupyter environment itself. The juypter-tempvars project ships with a helper script to simplify the most common case, where the extension is installed into the user-scope extension registry:

$ jupyter-tempvars install

Now that the extension is installed, it needs to be activated, either in the Nbextensions Jupyter tab of the configurator:

(click for full size image)

or by running the helper script with the enable command:

$ jupyter-tempvars enable

Usage

As of v0.1, jupyter-tempvars supports two filters for identifying temporary variables, a 'starts with' filter and an 'ends with' filter. Both methods use the built-in Jupyter capability to attach metadata to each cell in a notebook. The first step to use jupyter-tempvars is to turn on the Tags metadata cell headers:

(list of instructions)

(GIF)

Then, for each cell you want jupyter-tempvars to handle temporary variables, add a tag with one of the following two formats:

• To treat all variables starting with a given prefix as temporary, use tempvars-start-{prefix}

• To treat all variables ending with a given suffix as temporary, use tempvars-end-{suffix}

So, for example, to

Right now, just cell tag metadata and starts/ends.

Advanced Variable Management via tempvars

jupyter-tempvars only exposes a subset of the functionality provided by the underlying tempvars Python package. If you need a more powerful temporary variable management tool, take a look at the full capabilities of tempvars.

jupyter-tempvars also requires the full Jupyter notebook frontend to function. If you want to manage temporary variables when using, e.g., nbclient or nbmake, you should look into using tempvars directly in your code, instead of jupyter-tempvars.

---

Available (soon) on PyPI.

Source on GitHub. Bug reports and feature requests are welcomed at the Issues page there.

Copyright (c) Brian Skinn 2022

License: The MIT License. See LICENSE.txt for full license terms.