Skip to main content

macros for Jupyter Notebooks

Project description

JPConvert

JPConvert is a preprocessor for Jupyter Notebooks. It may be used to split up Jupyter Notebooks based on macros, automatically set options, embed images and remove unnecessary metadata.

Quick Start

Install JPConvert:

pip install jpconvert

Imagine two code cells inside your notebook:

#jp-solution
a = a + 1
#jp-practice
a = ...

If you call JPConvert with the --practice option, the first cell is removed and the second cell is kept:

a = ...

If you call JPConvert with the --solution option, the first cell is kept and the second cell is removed:

a = a + 1

Setup

The preferred way to use JPConvert is in a virtual environment:

python -m venv venv
source venv/bin/activate

Use pip to download and install JPConvert. JPConvert requires requests and python-magic to embed images via HTTP. Both packages are installed automatically by pip.

pip install jpconvert

Run JPConvert as a Python module:

python -m jpconvert <input> [<output>] [<options>]

Usage Guide

Macros and Output Types

JPConvert provides several macros to mark cells for a specific task. Only code cells with the macro matching the output options are kept.

cli option description
--practice / -p keep cells containing #jp-practice
--teaching / -t keep cells containing #jp-teaching
--solution / -s keep cells containing #jp-solution

Multiple macros can be used per cell. Macros themselves are removed from the code cells.

Instead of # you can also use --. The macros without any prefix can also be added as tags to individual cells.

It is also possible to remove any cells without macros. Add --remove-without-macros to the command line parameters to activate this behavior.

Empty Cells, Empty Lines, Trailing Spaces

JPConvert automatically removes

  1. trailing spaces from lines,
  2. empty lines from the end of cells and
  3. empty cells.

This behavior can be disabled using the command line parameters

  1. --no-strip-lines,
  2. --keep-trailing and
  3. --keep-empty.

Readonly and Undeletable

JPConvert automatically adds readonly and undeletable flags to any cells that do not contain #jp-practice. If you want to protect the latter from writing as well, add #jp-readonly or use #jp-practice-ro. Users may undo these changes, but at least they cannot accidentally delete or modify cells.

To disable this behavior, the command line parameters --no-force-readonly and --no-set-undeletable can be used.

Table of Contents

A table of contents is automatically inserted into all cells that contain the macro #jp-toc. The entries are automatically generated from headlines (lines starting with one or multiple #) in markdown cells. Each entry consists of the title and a reference that leads directly to the anchor tag of the heading.

Up to two conditionals can be added to control the table's depth. It uses the level of the heading (number of #) for filtering. The following example shows how to create a table of contents from level 2 to 5.

#jp-toc>=2<6

Embedding Images

Images can be embedded in markdown cells via the Jupyter user interface. JPConvert automatically embeds linked files from both local disk and HTTP(S) sources, which simplifies notebook editing. Supported file types are png, jpg and svg.

JPConvert also embeds files that are displayed using HTML tags. These provide the ability to scale graphics as desired, while in markdown the size is determined only by the resolution.

Add the command line parameter --no-embed-images to disable this behavior.

Stripping Output

execution_count is set to None and output is set to an empty array for each individual code cell. (Which is basically the functionality of nbstripout.)

Add the command line parameter --keep-output to disable this behavior.

Project details


Download files

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

Source Distribution

jpconvert-0.3.16.tar.gz (13.2 kB view details)

Uploaded Source

Built Distribution

jpconvert-0.3.16-py3-none-any.whl (15.5 kB view details)

Uploaded Python 3

File details

Details for the file jpconvert-0.3.16.tar.gz.

File metadata

  • Download URL: jpconvert-0.3.16.tar.gz
  • Upload date:
  • Size: 13.2 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/4.0.2 CPython/3.10.6

File hashes

Hashes for jpconvert-0.3.16.tar.gz
Algorithm Hash digest
SHA256 36751a0d1e3c1571bfdff05c5cd6ff718f3a777b2be378c7cf51204d294ac456
MD5 fc003150e897cc3f56899b9f22a4cd39
BLAKE2b-256 71dc0db156129a23e81c1b97b926a23670aefdc23a92734888ed8fcaf72ad0b9

See more details on using hashes here.

File details

Details for the file jpconvert-0.3.16-py3-none-any.whl.

File metadata

  • Download URL: jpconvert-0.3.16-py3-none-any.whl
  • Upload date:
  • Size: 15.5 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/4.0.2 CPython/3.10.6

File hashes

Hashes for jpconvert-0.3.16-py3-none-any.whl
Algorithm Hash digest
SHA256 0744849cdbdd80cdc528a74069aa86e2d2e1e8e993663de94b9bb54a2ca03dc4
MD5 5767b66ae3e1bff8807a39f2f942bd54
BLAKE2b-256 cc5c78f786d6f546fb4b3076d2941d662c454008f360bd9e5c364c5ea2637688

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page