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 toolsnbvalidate
: options for Notebook Validationnbheads
: options for Notebook Headsnbdump
: options for Notebook Dumpnbstats
: options for Notebook Statisticsnbview
: options for Notebook Viewingnbcat
: options for Notebook Catenationnbclean
: options for Notebook Cleaningnbrun
: options for Notebook Executionnbsplit
: options for Notebook Splittingnbpunch
: 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,
the common options from that file are applied (with attribute
"nbtoolbelt"
),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
andtrue
;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" ]
}
}