nbimgextract 0.3.0

A command-line tool for extracting images from Jupyter Notebooks.

nbimgextract

nbimgextract is a command-line tool for extracting images from Jupyter Notebooks.

Usage

Usage: nbimgextract [OPTIONS] <FILE>

Arguments:
  <FILE>  path to ipynb file from which to extract files

Options:
  -o, --output-path <OUTPUT_PATH>  output directory for images
  -t, --tag-prefix <TAG_PREFIX>    Prefix for cell tags to create the file name
  -q, --quiet                      Disable output of written files
  -Q, --print-filenames            Output written files to terminal [default]
      --dry-run                    Do not write any files
      --write-files                Write image files [default]
  -h, --help                       Print help
  -V, --version                    Print version

Non Empty Dir Actions:
      --error      Raise an error when the target directory is not empty [default]
      --clear-dir  If target dir is not empty, delete it
      --proceed    Ignore non-empty target dir

Output File Names

By default, the names of the image files extracted from a notebook are based on the ordinal number of the cell, zero-padded to the width of the cell count: for example, the image from the third cell of a 13-cell notebook is named img-03.

However, you can also specify the desired file names within the notebook in a few ways.

1. Comment in the cell code
2. Cell tag

If a cell has a valid comment and a valid tag, the comment has priority. If a cell produces multiple images/plots, these will be numbered: name-1, name-2, and so on. If two cells would produce the same file name, the later one gets a numeric suffix; images never silently overwrite each other.

Labels must be plain file names: a label containing a path separator or .. is ignored with a warning, and files are always written inside the output directory.

Comment

nbimagextract allows you to specify the desired image filename via a comment in the cell's code. To be detected, the comment must begin with label: — after the # and an optional | — followed by the desired filename. Both # label: name and Quarto's #| label: name forms work; comments that merely contain the word, such as # xlabel: time, do not set the name. Any whitespace around the filename will be trimmed.

The comment must appear in the cell's leading comment block: the comment lines at the very top of the cell, before the first code or blank line. A label: comment further down the cell is ignored.

For example, the plot produced by the cell with the following code will be saved as sin-plot.

# label: sin-plot
x = np.linspace(0, 2 * np.pi, 100)
y = np.sin(x)
plt.plot(x, y)

This closely follows the convention Quarto uses for applying labels to plots for the purposes of cross referencing, with the | after the # made optional.

Cell Tags

You can use cell tags to specify the file name for the image generated by that cell. The tag should start with img and anything after that prefix will be used in the file name. You can override this prefix with the --tag-prefix option. Any spaces, hyphens or underscores immediately following the prefix will be ignored. That is to say, if the tag is img-my-chart, the resulting file names will be called my-chart.