Configuration Files

nbtoolbelt can load options from a JSON configuration file: see Read Configuration File.

Such a configuration file holds one object in JSON (JavaScript Object Notation), with optional members for global options and options for each individual tool:

• nbtoolbelt: global options that apply to multiple tools

• nbvalidate: options for Notebook Validation

• nbheads: options for Notebook Heads

• nbdump: options for Notebook Dump

• nbstats: options for Notebook Statistics

• nbview: options for Notebook Viewing

• nbcat: options for Notebook Catenation

• nbclean: options for Notebook Cleaning

• nbrun: options for Notebook Execution

• nbsplit: options for Notebook Splitting

• nbpunch: options for Notebook Punching

The options for a tool are contained in a single object, with a member per option. The member name is the same as the long command-line option, in which dashes (’-’) have been replaced by underscores (’_’).

Whenever a configuration file is loaded,

1. the common options from that file are applied (with attribute "nbtoolbelt"),

2. those options are applied that concern the selected tool.

Thus, tool-specific options override common options in the same configuration file, but not the other way round.

Note

Note

• that JSON syntax is very strict;

• that nbtb config [tool] will report the configuration using Python syntax;

• that JSON booleans are spelled in all lower case: false and true;

• that JSON strings must be surrounded by double quotes ("...").

• that JSON does not allow trailing commas in arrays and objects;

• that JSON does not support any form of comments.

Errors when loading a configuration file will be sent to stderr, and execution is aborted immediately.

Example

Here is the embedded configuration file:

{
  "nbtoolbelt": {
    "notebooks": [],
    "verbose": false,
    "quiet": false,
    "assert": true,
    "validate": false,

    "run": false,
    "kernel_name": "",
    "run_path": "",
    "timeout": -1,
    "interrupt_on_timeout": true,
    "record_timing": true,
    "ipc": "",
    "allow_errors": true,
    "clean_before": false,
    "clean_after": false,
    "clean_after_metadata": [
    ],
    "streams_head": -1,
    "streams_truncate_message": "*** Output truncated ***",
    "append_cell": false,
    "appended_cell": "# Automatically added code cell: lists all global names defined by this notebook.\n%whos",

    "inplace": false,
    "write_files": true,
    "output_json": null,
    "debug": false
  },

  "nbvalidate": {

  },

  "nbhead": {
    "number": 5
  },

  "nbdump": {
    "dump_notebook_info": true,
    "dump_cell_info": true,
    "dump_sources": true,
    "dump_cell_types": [
      "markdown",
      "code",
      "raw"
    ],
    "dump_info_prefix": "=====",
    "dump_source_line_indent": 2,
    "dump_source_line_numbers": false,
    "dump_cell_spacing": 0
  },

  "nbstats": {
    "all_stats": false,
    "cell_types": true,
    "sources": false,
    "metadata": false,
    "tags": false,
    "attachments": false,
    "outputs": false,
    "streams": false,
    "errors": false,
    "execution": false,
    "extra": false
  },

  "nbview": {
    "browser": true,
    "template_file": "",
    "template": "classic",
    "wait_delete": false,
    "view_result_name": "-view"
  },

  "nbcat": {
    "cat_result_name": "-cat"
  },

  "nbrun": {
    "kernel_name": "",
    "run_path": "",
    "timeout": -1,
    "interrupt_on_timeout": true,
    "allow_errors": true,
    "record_timing": true,
    "clean_before": true,
    "clean_before_metadata": [
      "ExecuteTime",
      "execution"
    ],
    "clean_after": true,
    "clean_after_metadata": [
      "collapsed",
      "scrolled"
    ],
    "streams_head": -1,
    "append_cell": false,
    "run_result_name": "-run"
  },

  "nbclean": {
    "clean_notebook_metadata_fields": [],
    "clean_cell_metadata_fields": [],
    "clean_tags": [],
    "clean_empty_cells": false,
    "clean_outputs": false,
    "clean_result_name": "-clean"
  },

  "nbsplit": {
    "split_cell_types": [
      "markdown",
      "code",
      "raw"
    ],
    "split_markdown_result_name": "-markdown",
    "split_code_result_name": "-code",
    "split_raw_result_name": "-raw"
  },

  "nbpunch": {
    "tags": [
    ],
    "punched": true,
    "chads": false,
    "keep_marker_lines": true,
    "marker_regex": {
      "markdown": "#//.*_TODO",
      "code": "#//.*_TODO",
      "raw": "#//.*_TODO"
    },
    "marker_line_parsing_regex": {
      "markdown": "`#// (?P<transition>.*?)_TODO \\[(?P<label>.*?)\\] ?(?P<description>.*?)`",
      "code": "#// (?P<transition>.*?)_TODO \\[(?P<label>.*?)\\] ?(?P<description>.*)",
      "raw": "#// (?P<transition>.*?)_TODO \\[(?P<label>.*?)\\] ?(?P<description>.*)"
    },
    "marker_transitions": {
      "begin": "BEGIN",
      "end": "END"
    },
    "fill": false,
    "filling": {
      "markdown": "\n<div class='alert alert-warning' role='alert'>Replace this line by your text.</div>\n",
      "code": "\n# ===== =====> Replace this line by your code. <===== ===== #\n",
      "raw": "\n% ===== =====> Replace this line by your content. <===== =====\n"
    },
    "list": false,
    "allow_errors": false,
    "punch_source": "",
    "source_chads": {},
    "punch_punched_result_name": "-punched",
    "punch_chads_result_name": "-chads",
    "label_regex": ""
  }
}

Here is an example configuration file with one global option (for verbose mode) and options for running and punching. It can either be loaded through the command-line option --config nbtoolbelt.json or by putting it in your home directory as ~/.nbtoolbelt.json (note the dot, which makes it a hidden file).

{
  "nbtoolbelt": {
    "verbose": true
  },
  "nbrun": {
    "kernel_name": "python3",
    "timeout": 5,
    "allow_errors": false
  },
  "nbpunch": {
    "tags": [ "YourTurn" ]
  }
}