Skip to main content
Python Software Foundation 20th Year Anniversary Fundraiser  Donate today!

Automatically export Jupyter notebooks to various file formats (.py, .html, and more) on save.

Project description

nbautoexport

Docs Status PyPI conda-forge tests codecov

Making it easier to code review Jupyter notebooks, one script at a time.

nbautoexport automatically exports Jupyter notebooks to various file formats (.py, .html, and more) upon save while using Jupyter. One great use case is to automatically have script versions of your notebooks to facilitate code review commenting.

Installation

First, you will need to install nbautoexport. This should be installed in the same environment you are running Jupyter Notebook or Jupyter Lab from. nbautoexport is available either from PyPI via pip or from conda-forge via conda.

pip install nbautoexport
conda install nbautoexport --channel conda-forge

Then, to register nbautoexport to run automatically while using Jupyter Notebook or Jupyter Lab, run:

nbautoexport install

If you already have a Jupyter server running, you will need to restart it for this to take effect.

Simple usage

Let's say you have a project and keep your notebooks in a notebooks/ subdirectory.

To configure that directory for automatic exporting, run the following command:

nbautoexport configure notebooks

This will create a configuration file notebooks/.nbautoexport.

If you've set up nbautoexport to work with Jupyter (using the install command as detailed in the previous section), then any time you save a notebook in Jupyter, a hook will run that checks whether there is a .nbautoexport configuration file in the same directory as the notebook. If so, it will use the settings specified in that file to export your notebook. By default, it will generate a script version of your notebook named after the notebook (with the .py extension) and saved in the directory notebooks/script.

If everything is working, your notebooks directory should end up with files like the below example:

notebooks
├──0.1-ejm-data-exploration.ipynb
├──0.2-ejm-feature-creation.ipynb
└── script
    └── 0.1-ejm-data-exploration.py
    └── 0.2-ejm-feature-creation.py

Configuring export options

The default .nbautoexport configuration file looks like this:

{
  "export_formats": [
    "script"
  ],
  "organize_by": "extension"
}

Upon save, this will lead to notebooks being exported to scripts which saved to the notebooks/script directory.

notebooks
├──0.1-ejm-data-exploration.ipynb
├──0.2-ejm-feature-creation.ipynb
└── script
    └── 0.1-ejm-data-exploration.py
    └── 0.2-ejm-feature-creation.py

An alternative way to organize exported files is to create a directory for each notebook. This can be handy for matching both the notebook and subdirectory when tab-completing and then globbing with * after the part that completed.

nbautoexport configure notebooks --organize-by notebook
notebooks
├── 0.1-ejm-data-exploration
│   └── 0.1-ejm-data-exploration.py
├── 0.2-ejm-feature-creation
│   └── 0.2-ejm-feature-creation.py
├──0.1-ejm-data-exploration.ipynb
└──0.2-ejm-feature-creation.ipynb

If you do not like the settings you selected, you can always change them by either 1) re-running the nbautoexport command with new arguments and the --overwrite flag, or 2) manually editing the .nbautoexport file.

You can also specify as many export formats as you'd like. We support most of the export formats available from nbconvert, such as html, md, and pdf. To specify formats, use the --export-format for each format you want to include.

Advanced example

nbautoexport configure sprint_one_notebooks -f script -f html --organize-by extension

Upon save, this creates .py and .html versions of the Jupyter notebooks in sprint_one_notebooks folder and results in the following organization:

notebooks
├──0.1-ejm-data-exploration.ipynb
├──0.2-ejm-feature-creation.ipynb
├── script
│   └── 0.1-ejm-data-exploration.py
│   └── 0.1-ejm-features-creation.py
└── html
    └── 0.1-ejm-data-exploration.html
    └── 0.1-ejm-features-creation.html

More functionality

The nbautoexport CLI has two additional commands:

  • export is for ad hoc exporting of a notebook or directory of notebooks
  • clean (EXPERIMENTAL) will delete files in a directory that are not generated by the current .nbautoexport configuration

Use the --help flag to see the documentation.

Command-line help

nbautoexport --help
Usage: nbautoexport [OPTIONS] COMMAND [ARGS]...

  Automatically export Jupyter notebooks to various file formats (.py,
  .html, and more) upon save. One great use case is to automatically have
  script versions of your notebooks to facilitate code review commenting.

  To set up, first use the 'install' command to register nbautoexport with
  Jupyter. If you already have a Jupyter server running, you will need to
  restart it.

  Next, you will need to use the 'configure' command to create a
  .nbautoexport configuration file in the same directory as the notebooks
  you want to have export automatically.

  Once nbautoexport is installed with the first step, exporting will run
  automatically when saving a notebook in Jupyter for any notebook where
  there is a .nbautoexport configuration file in the same directory.

Options:
  --version             Show nbautoexport version.
  --install-completion  Install completion for the current shell.
  --show-completion     Show completion for the current shell, to copy it or
                        customize the installation.

  --help                Show this message and exit.

Commands:
  clean      (EXPERIMENTAL) Remove subfolders/files not matching...
  configure  Create a .nbautoexport configuration file in a directory.
  export     Manually export notebook or directory of notebooks.
  install    Register nbautoexport post-save hook with Jupyter.

This repository was initially created using Cookiecutter with audreyr/cookiecutter-pypackage.

History

0.3.1 (2021-03-10)

  • Remove extraneous dependency on jupyter_contrib_nbextensions. Add traitlets, notebook, jupyter_core, and nbformat as explicit dependencies; previously they were treated as transitive dependencies even though they are actually direct dependencies. #68

0.3.0 (2021-02-18)

  • Explicitly set all input and output file encodings to UTF-8, which fixes a bug with HTML exports on Windows with nbconvert v6.0. This version removes the version ceiling on <6.
    • This is not expected to cause any backwards compatibility issues. However, in the very unlikely instance that your jupyter_notebook_config.py file or your nbautoexport.json config file is Windows-1252-encoded and contains non-ASCII characters, you will need to convert them to UTF-8. (#57, #61)

0.2.1 (2020-09-18)

  • nbconvert released version 6, which may break HTML exports on Windows. Pinning to nbconvert<6 until we can address #57.

0.2.0 (2020-09-04)

  • Add option to specify glob-style patterns to exclude files from deletion when using clean. See documentation for more details. (#46, #54)

0.1.1 (2020-08-06)

  • Fixes missing requirements.txt bug when installing from source distribution. (#50, #52)

0.1.0 (2020-08-05)

  • First release on PyPI.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for nbautoexport, version 0.3.1
Filename, size File type Python version Upload date Hashes
Filename, size nbautoexport-0.3.1-py3-none-any.whl (16.9 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size nbautoexport-0.3.1.tar.gz (57.2 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page