Metadata-Version: 2.4
Name: nbimgextract
Version: 0.3.0
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Programming Language :: Rust
License-File: LICENSE
Summary: A command-line tool for extracting images from Jupyter Notebooks.
Home-Page: https://github.com/felixgwilliams/nbimgextract
Requires-Python: >=3.8
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Homepage, https://github.com/felixgwilliams/nbimgextract
Project-URL: Source Code, https://github.com/felixgwilliams/nbimgextract

# nbimgextract

[![License:MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![PyPI - Version](https://img.shields.io/pypi/v/nbimgextract)](https://pypi.org/project/nbimgextract/)
[![codecov](https://codecov.io/gh/felixgwilliams/nbimgextract/graph/badge.svg?token=YC1FQQVRFM)](https://codecov.io/gh/felixgwilliams/nbimgextract)

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

## Usage

```text
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`.

```python
# 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](https://quarto.org/docs/authoring/figures.html#cross-references) 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`.

