nbtoolbelt package

Submodules

nbtoolbelt.arguments module

Functions for command-line argument parsing

This software is made available under the terms of the MIT License.

class nbtoolbelt.arguments.ExtendAction(option_strings, dest, **kwargs)[source]

Bases: Action

Extend current list for option with parsed list.

Note

Assumption: Option is already present in namespace (from embedded config file read in __init__()).

class nbtoolbelt.arguments.LoadConfigFile(option_strings, dest, **kwargs)[source]

Bases: Action

Action to take when parsing a configuration file option.

class nbtoolbelt.arguments.LoadSourceFile(option_strings, dest, **kwargs)[source]

Bases: Action

Action to take when parsing a source file option.

class nbtoolbelt.arguments.NegatableAction(option_strings, dest, default=None, required=False, help=None)[source]

Bases: Action

Add the supplied positive options and negative versions as well. Inspired by nbshow.

class nbtoolbelt.arguments.TestAction(option_strings, dest, **kwargs)[source]

Bases: Action, Namespace

Action to test the action mechanism, by printing the parameter values received in constructor and call methods.

nbtoolbelt.arguments.join_csv(s: Iterable[str]) → str[source]

Join strings in list to comma-separated values. Inverse of split_csv.

Parameters:: s – list to join
Returns:: joined csv string

nbtoolbelt.arguments.quote_help(s: str) → str[source]: Double percent signs, and quote newlines. This is needed in help for argparse.

nbtoolbelt.arguments.split_csv(arg: str) → List[str][source]

Split comma-separated values into a list.

Parameters:: arg – argument to split
Returns:: list of separated valued

nbtoolbelt.cleaning module

Functions for cleaning

This software is made available under the terms of the MIT License.

nbtoolbelt.cleaning.clean_code_metadata(nb: NotebookNode, clean: List[str]) → None[source]

Clean metadata of code cells, by * removing collapsed and scrolled flags on code cells * removing ExecuteTime data on code cells

Note

Modifies: nb

Parameters:

nb – notebook to clean
clean – metadata keys to clean

nbtoolbelt.cleaning.clean_code_output(nb: NotebookNode) → None[source]

Clean all output cells and execution counts.

Note

Modifies: nb

Parameters:: nb – notebook to clean

nbtoolbelt.cleaning.clean_nb(nb: NotebookNode, args: Namespace) → Dict[source]

Clean fields and optionally output from notebook.

If args is not None, then the following arguments are used:

clean_notebook_metadata_fields (collection)
clean_cell_metadata_fields (collection)
clean_tags (collection)
clean_empty_cells (boolean)
clean_outputs (boolean)

Note

Modifies: nb

Parameters:

nb – notebook to clean
args – namespace with arguments (options)

Returns:

dictionary with statistics for removed elements

nbtoolbelt.cleaning.truncate_output_streams(nb: NotebookNode, args: Namespace) → None[source]

Limit the output cells to at most args.limit_output lines.

Parameters:

nb – notebook to limit
args – namespace with arguments (options)

nbtoolbelt.config module

Configuration file handling

This software is made available under the terms of the MIT License.

Configuration files use JSON to make it easier to move the Jupyter configuration file mechanism in the future.

There is a top-level entry for global options with the package name as key. Each tool has a tool-specific entry with key ‘nb’ + tool name; e.g. ‘nbrun’.

The top-level configuration is loaded first; typically it has options that apply to multiple tools. Then the tool-specific configuration is loaded on top of that (using dict update).

TODO: First the embedded configuration file is loaded (these are defaults).

TODO: Then a configuration file in the home directory is loaded, if present.

Finally configuration files mentioned on the command line are loaded. These are processed during argument parsing.

nbtoolbelt.config.config_path() → Path[source]

Return path to embedded config file.

Returns:: path to embedded config file

nbtoolbelt.config.load_config(tool: str = 'nbtoolbelt', verbose: bool = False) → Namespace[source]

Load configuration for tool.

Successively load configuration files (if present) in:

the package itself (see src/nbtoolbelt/data/CONFIG_FILE_NAME)
/etc/CONFIG_FILE_NAME
~/.CONFIG_FILE_NAME (a dot file in the home directory)

Note

Modifies: ns

Parameters:

tool – tool for which to load a configuration file (default: top-level)
verbose – whether to print some diagnostic info

Returns:

updated ns

nbtoolbelt.config.load_config_file(tool: str = 'nbtoolbelt', ns: Optional[Namespace] = None, file_path: Union[str, Path] = PosixPath('/home/docs/checkouts/readthedocs.org/user_builds/nbtoolbelt/envs/latest/lib/python3.10/site-packages/nbtoolbelt/data/nbtoolbelt.json'), verbose: bool = False) → Namespace[source]

Load configuration for tool from file and return update namespace. Silently ignores file if it does not exist.

Note

Modifies: ns

Parameters:

tool – tool for which to load a configuration file
ns – namespace to load configuration into
file_path – file path to load configuration from
verbose – whether to print some diagnostic info

Returns:

updated ns

nbtoolbelt.counting module

Functions for counting elements in Jupyter notebooks

This software is made available under the terms of the MIT License.

nbtoolbelt.counting.CELL_STATISTICS = ('cell_types', 'sources', 'cell_metadata', 'cell_attachments', 'code_execution', 'code_outputs', 'cell_extra'): Fields used in the dictionary returned by nb_cell_stats().

nbtoolbelt.counting.PAIRING_TOKEN = ' : ': character sequence to combine key pairs

nbtoolbelt.counting.clean_dict(d: Dict[str, Any]) → Dict[str, Any][source]

Remove key-nan pairs and convert non-nan np types to native Python.

Parameters:: d – dict to clean
Returns:: cleaned dict

nbtoolbelt.counting.count_source(source: str) → Tuple[int, int, int][source]

Count number of non-blank lines, words, and non-whitespace characters.

Parameters:: source – string to count
Returns:: number of non-blank lines, words, and non-whitespace characters

nbtoolbelt.counting.extract_aggregate(d: ~typing.Dict[str, ~typing.Dict[str, ~typing.Any]], attr: str = 'total', convert: ~typing.Callable[[~typing.Any], ~typing.Any] = <class 'int'>) → Dict[str, Any][source]: Extract converted values for given attribute from nested dictionary.

nbtoolbelt.counting.flatten_mapping(mapping: Mapping[str, Any]) → Dict[str, Any][source]

Return recursively flattened mapping as dict.

Parameters:: mapping – object to flatten
Returns:: flattened mapping

nbtoolbelt.counting.is_key_pair(key: str) → bool[source]

Return whether key is paired, that is, result of pair_key.

Parameters:: key – key to test
Returns:: whether key is result of pair_key()

nbtoolbelt.counting.nb_cell_stats(nb: NotebookNode, args: Optional[Namespace] = None) → Dict[str, Dict[str, int]][source]

Count occurrences of various elements in notebook cells.

If args is not None, then the following boolean arguments are used (if present; absent is interpreted as False):

sources
metadata
tags
code
streams
errors

If args is None, then all statistics are gathered.

Parameters:

nb – notebook to inspect
args – namespace with arguments; if None, count everything

Returns:

dictionary of dictionaries with counts per section; each section has its own key; see CELL_STATISTICS

nbtoolbelt.counting.nb_code_execution_stats(nb: NotebookNode) → Dict[source]

Count number of (executed) code cells and errors in notebook.

Parameters:: nb – notebook to inspect
Returns:: dictionary with ‘code cells’: number of code cells, ‘executed’: number of executed cells, ‘with errors’: number of execution errors

nbtoolbelt.counting.nb_extra_fields(nb: NotebookNode) → Dict[str, int][source]

Extract extra global fields in notebook.

Parameters:: nb – notebook to inspect
Returns:: list of extra fields (not set, because that is not JSON serializable)

nbtoolbelt.counting.nb_metadata(nb: NotebookNode) → Dict[str, Any][source]

Summarize notebook global metadata.

Parameters:: nb – notebook to inspect
Returns:: dictionary with format, kernel, and language info

nbtoolbelt.counting.nb_other_metadata(nb: NotebookNode) → Dict[str, int][source]

Extract other global metadata fields in notebook.

Parameters:: nb – notebook to inspect
Returns:: set of global metadata fields other than required

nbtoolbelt.counting.pair_keys(key1: str, key2: str) → str[source]

Pair two strings into one string, where key2 may also have been paired.

Parameters:

key1 – first key
key2 – second key

Returns:

paired key

nbtoolbelt.counting.unflatten_dict(d: Dict[str, Any]) → Dict[str, Any][source]

Return recursively unflattened dictionary, that is, flatten_mapping(result) == d.

Parameters:: d – dictionary to unflatten
Returns:: unflattened version of d

nbtoolbelt.counting.unpair_key(key: str) → Tuple[str, str][source]

Unpair key into key1, key2 such that key1 is not a pair, and pair_keys(key1, key2) == key.

Note

Assumption: is_key_pair(key)

Parameters:: key – key to split
Returns:: key1, key2 where pair_keys(key1, key2) == key

nbtoolbelt.inline_attachments module

NbConvert Preprocessor to inline attachments

This software is made available under the terms of the MIT License.

Parts of this code are reworked from the rendernb checklet for Momotor <momotor.org>.

class nbtoolbelt.inline_attachments.InlineAttachmentsPreprocessor(**kwargs: Any)[source]

Bases: Preprocessor

To embed cell attachments inside the cell’s source.

ACCEPTABLE_TYPES = ('image/png', 'image/jpeg', 'image/gif', 'image/webp', 'image/bmp')

preprocess_cell(cell: NotebookNode, resources: Dict[str, Any], index: int) → Tuple[NotebookNode, Dict[str, Any]][source]

Take a Jupyter Notebook cell and inline all attachments as data.

Note

Modifies: cell

Parameters:

cell – cell for which to inline attachments
resources – global resources
index – cell index in notebook

Returns:

modified cell, updated resources

nbtoolbelt.nbcatapp module

Main for nbcat

This software is made available under the terms of the MIT License.

class nbtoolbelt.nbcatapp.CatTool[source]

Bases: Tool

Catenate notebooks.

process_collected_data()[source]

Process outputs collected from all processed notebooks.

Hook method to be overridden in concrete tools. Overriding method must call super() at begin.

process_nb(nb: NotebookNode, nb_path: Path) → Sequence[Tuple[NotebookNode, Path]][source]

Collect cells of notebook nb.

Parameters:

nb – notebook to catenate
nb_path – path to nb

Returns:

catenation when called on last notebook

nbtoolbelt.nbcatapp.main(cli_args: Optional[List[str]] = None) → int[source]

nbtoolbelt.nbcleanapp module

Main for nbclean

This software is made available under the terms of the MIT License.

class nbtoolbelt.nbcleanapp.CleanTool[source]

Bases: Tool

Clean each notebook.

check_and_adjust_arguments()[source]

Do tool-specific checks and adjustments of parsed arguments.

Hook method to be overridden in concrete tools.

config_tool_args_parsing(group: _ArgumentGroup) → None[source]

Add argument configurations that are tool specific to the given argument group.

Hook method to be overridden in concrete tools.

Parameters:: group – argument group to add into

print_tool_args() → None[source]

Print tool-specific arguments; used especially in verbose mode. Indent the lines by 2 spaces.

Hook method to be overridden in concrete tools.

process_nb(nb: NotebookNode, nb_path: Path) → Sequence[Tuple[NotebookNode, Path]][source]

Clean notebook nb.

Note

Modifies: nb

Parameters:

nb – notebook to clean
nb_path – path to nb

Returns:

sequence of resulting (notebook, notebook-path) pairs

nbtoolbelt.nbcleanapp.main(cli_args: Optional[List[str]] = None) → int[source]

nbtoolbelt.nbdumpapp module

Tool nbdump; dump cell sources of notebooks

This software is made available under the terms of the MIT License.

class nbtoolbelt.nbdumpapp.DumpTool[source]

Bases: Tool

Show all source lines of each notebook.

check_and_adjust_arguments() → None[source]

Do tool-specific checks and adjustments of parsed arguments.

Hook method to be overridden in concrete tools.

config_tool_args_parsing(group: _ArgumentGroup) → None[source]

Add argument configurations that are tool specific to the given argument group.

Hook method to be overridden in concrete tools.

Parameters:: group – argument group to add into

print_tool_args() → None[source]

Print tool-specific arguments; used especially in verbose mode. Indent the lines by 2 spaces.

Hook method to be overridden in concrete tools.

process_nb(nb: NotebookNode, nb_path: Path) → Sequence[Tuple[NotebookNode, Path]][source]

Dump cell sources of notebook.

Parameters:

nb – notebook to dump
nb_path – notebook’s path

Returns:

empty result

nbtoolbelt.nbdumpapp.main(cli_args: Optional[List[str]] = None) → int[source]

nbtoolbelt.nbheadapp module

Tool nbhead; shows head of notebooks

This software is made available under the terms of the MIT License.

This tool also illustrates how to extend class Tool, to define a new concrete tool.

class nbtoolbelt.nbheadapp.HeadTool[source]

Bases: Tool

Show the first n (default 5) source lines of the first cell of each notebook. If n is negative, show the last n source lines of the last cell.

It overrides:

config_tool_args_parsing() to configure parser for tool-specific arguments
print_tool_args() to print tool-specific arguments (used in verbose mode)
process_nb() to process one notebook

config_tool_args_parsing(group: _ArgumentGroup) → None[source]

Add argument configurations that are tool specific to the given argument group.

Hook method to be overridden in concrete tools.

Parameters:: group – argument group to add into

print_tool_args() → None[source]

Print tool-specific arguments; used especially in verbose mode. Indent the lines by 2 spaces.

Hook method to be overridden in concrete tools.

process_nb(nb: NotebookNode, nb_path: Path) → Sequence[Tuple[NotebookNode, Path]][source]

Show head of notebook.

Parameters:

nb – notebook to show head of
nb_path – notebook’s path

Returns:

empty result

nbtoolbelt.nbheadapp.main(cli_args: Optional[List[str]] = None) → int[source]

nbtoolbelt.nbpunchapp module

Tool nbpunch

This software is made available under the terms of the MIT License.

class nbtoolbelt.nbpunchapp.PunchTool[source]

Bases: Tool

Punch notebooks, optionally filling holes with material coming from other notebooks, writing the results to new notebooks.

check_and_adjust_arguments()[source]

Do tool-specific checks and adjustments of parsed arguments.

Hook method to be overridden in concrete tools.

config_tool_args_parsing(group: _ArgumentGroup) → None[source]

Add argument configurations that are tool specific to the given argument group.

Hook method to be overridden in concrete tools.

Parameters:: group – argument group to add into

print_tool_args() → None[source]

Print tool-specific arguments; used especially in verbose mode. Indent the lines by 2 spaces.

Hook method to be overridden in concrete tools.

process_nb(nb: NotebookNode, nb_path: Path) → Sequence[Tuple[NotebookNode, Path]][source]

Punch notebook nb.

Note

Modifies: nb

Parameters:

nb – notebook to punch
nb_path – path to nb

Returns:

sequence of resulting (notebook, notebook-path) pairs

nbtoolbelt.nbpunchapp.main(cli_args: Optional[List[str]] = None) → int[source]

nbtoolbelt.nbrunapp module

Main for nbrun

This software is made available under the terms of the MIT License.

class nbtoolbelt.nbrunapp.RunTool[source]

Bases: Tool

Run each notebook, with optional pre-/post-cleaning, and return results.

config_tool_args_parsing(group: _ArgumentGroup) → None[source]

Add argument configurations that are tool specific to the given argument group.

Hook method to be overridden in concrete tools.

Parameters:: group – argument group to add into

print_tool_args() → None[source]

Print tool-specific arguments; used especially in verbose mode. Indent the lines by 2 spaces.

Hook method to be overridden in concrete tools.

process_nb(nb: NotebookNode, nb_path: Path) → Sequence[Tuple[NotebookNode, Path]][source]

Run notebook nb.

Note

Modifies: nb

Parameters:

nb – notebook to run
nb_path – path to nb

Returns:

resulting (notebook, notebook-path) pair

nbtoolbelt.nbrunapp.main(cli_args: Optional[List[str]] = None) → int[source]

nbtoolbelt.nbsplitapp module

Main for nbsplit

This software is made available under the terms of the MIT License.

class nbtoolbelt.nbsplitapp.SplitTool[source]

Bases: Tool

Split each notebook.

check_and_adjust_arguments() → None[source]

Do tool-specific checks and adjustments of parsed arguments.

Hook method to be overridden in concrete tools.

config_tool_args_parsing(group: _ArgumentGroup) → None[source]

Add argument configurations that are tool specific to the given argument group.

Hook method to be overridden in concrete tools.

Parameters:: group – argument group to add into

print_tool_args() → None[source]

Print tool-specific arguments; used especially in verbose mode. Indent the lines by 2 spaces.

Hook method to be overridden in concrete tools.

process_nb(nb: NotebookNode, nb_path: Path) → Sequence[Tuple[NotebookNode, Path]][source]

Split notebook nb into markdown, code, and raw cells.

Note

Modifies: nb

Side effect: writes new notebook files

Parameters:

nb – notebook to split
nb_path – path to nb

Returns:

sequence of resulting (notebook, notebook-path) pairs

nbtoolbelt.nbsplitapp.main(cli_args: Optional[List[str]] = None) → int[source]

nbtoolbelt.nbstatsapp module

Main for nbstats

This software is made available under the terms of the MIT License.

Summarize Jupyter notebooks on the command line.

class nbtoolbelt.nbstatsapp.StatsTool[source]

Bases: Tool

Collect and show a statistical summary of each notebook. Also compute some statistics over all notebooks.

check_and_adjust_arguments()[source]

Do tool-specific checks and adjustments of parsed arguments.

Hook method to be overridden in concrete tools.

config_tool_args_parsing(group: _ArgumentGroup) → None[source]

Add argument configurations that are tool specific to the given argument group.

Hook method to be overridden in concrete tools.

Parameters:: group – argument group to add into

process_collected_data()[source]

Process outputs collected from all processed notebooks.

Hook method to be overridden in concrete tools. Overriding method must call super() at begin.

process_nb(nb: NotebookNode, nb_path: Path) → Sequence[Tuple[NotebookNode, Path]][source]

Collect and present statistics about notebook nb.

Parameters:

nb – notebook to count
nb_path – path to nb

Returns:

sequence of resulting (notebook, notebook-path) pairs

nbtoolbelt.nbstatsapp.main(cli_args: Optional[List[str]] = None) → int[source]

nbtoolbelt.nbvalidateapp module

Tool nbvalidate

This software is made available under the terms of the MIT License.

class nbtoolbelt.nbvalidateapp.ValidateTool[source]

Bases: Tool

Validate each notebook, and report the validation results.

config_tool_args_parsing(group: _ArgumentGroup) → None[source]

Add argument configurations that are tool specific to the given argument group.

Hook method to be overridden in concrete tools.

Parameters:: group – argument group to add into

print_tool_args() → None[source]

Print tool-specific arguments; used especially in verbose mode. Indent the lines by 2 spaces.

Hook method to be overridden in concrete tools.

process_nb(nb: NotebookNode, nb_path: Path) → Sequence[Tuple[NotebookNode, Path]][source]

Validate notebook nb.

Parameters:

nb – notebook to validate
nb_path – path to nb

Returns:

empty result

nbtoolbelt.nbvalidateapp.main(cli_args: Optional[List[str]] = None) → int[source]

nbtoolbelt.nbviewapp module

Tool nbview

This software is made available under the terms of the MIT License.

class nbtoolbelt.nbviewapp.ViewTool[source]

Bases: Tool

Show notebooks in the browser, with embedded MathJax and attachments rendered.

check_and_adjust_arguments()[source]

Do tool-specific checks and adjustments of parsed arguments.

Hook method to be overridden in concrete tools.

config_tool_args_parsing(group: _ArgumentGroup) → None[source]

Add argument configurations that are tool specific to the given argument group.

Hook method to be overridden in concrete tools.

Parameters:: group – argument group to add into

print_tool_args() → None[source]

Print tool-specific arguments; used especially in verbose mode. Indent the lines by 2 spaces.

Hook method to be overridden in concrete tools.

process_collected_data()[source]

Process outputs collected from all processed notebooks.

Hook method to be overridden in concrete tools. Overriding method must call super() at begin.

process_nb(nb: NotebookNode, nb_path: Path) → Sequence[Tuple[NotebookNode, Path]][source]

View notebook. That is, convert it to html, and open it in the default browser.

Note

Side effect: Creates html file

Parameters:

nb – notebook to show head of
nb_path – notebook’s path

Returns:

empty

nbtoolbelt.nbviewapp.main(cli_args: Optional[List[str]] = None) → int[source]

nbtoolbelt.notebook_io module

Functions for notebook reading and writing

This software is made available under the terms of the MIT License.

nbtoolbelt.notebook_io.cell_lines(cell: NotebookNode) → List[str][source]

Return list of source lines for given cell.

Parameters:: cell – cell whose source lines to return as list
Returns:: list of source lines in cell

nbtoolbelt.notebook_io.read_nb(nb_path: Path, args: Namespace) → Union[None, NotebookNode][source]

Read notebook from given path, and return it. Uses args.debug: in debug mode, a read error results in an exception, else it returns None.

Parameters:

nb_path – path to read from
args – to check debug mode

Returns:

notebook read from nb_path or None if reading failed and not args.debug

nbtoolbelt.notebook_io.write_nb(nb: NotebookNode, nb_path: Path, args: Namespace) → Union[None, bool][source]

Write given notebook to given path. Uses args.debug: in debug mode, a write error results in an exception, else it returns None.

Parameters:

nb – notebook to be written
nb_path – path to write to
args – to check debug mode

Returns:

nbtoolbelt.printing module

Functions for printing

This software is made available under the terms of the MIT License.

nbtoolbelt.printing.print_dict(d: Dict[str, Any], header: Optional[str] = None, width: int = 10) → None[source]

Print dictionary d with section header.

Parameters:

d – dictionary to print
header – header of the table
width – width of the left column

nbtoolbelt.printing.print_namespace(ns: Namespace, header: Optional[str] = None) → None[source]

Print namespace with header.

Parameters:

ns – namespace to print
header – header of the table

nbtoolbelt.printing.print_set(s: Set[str], header: Optional[str] = None, width: int = 10) → None[source]

Print set s with section header.

Parameters:

s – set to print
header – header of the table
width – width of the left column

nbtoolbelt.processing module

Common processing definitions

This software is made available under the terms of the MIT License.

nbtoolbelt.punching module

Functions for punching

This software is made available under the terms of the MIT License.

class nbtoolbelt.punching.ChadsNotebookProcessor(nb: NotebookNode, args: Namespace, name: str)[source]

Bases: PunchBaseProcessor

Create chads notebook.

self.nb_chads = result notebook under construction self.cell_chads = next cell under construction, with source as list of strings (to be compacted)

post_cell(cell: NotebookNode)[source]

post_nb()[source]

pre_cell(cell: NotebookNode)[source]

punch_begin_marker_line(cell: NotebookNode, line: str)[source]: Process begin marker line.

punch_end_marker_line(cell: NotebookNode, line: str)[source]: Process end marker line.

punch_inside_line(cell: NotebookNode, line: str)[source]: Process line inside hole.

class nbtoolbelt.punching.PunchBaseProcessor(nb: NotebookNode, args: Namespace, name: str)[source]

Bases: object

Base class for punch processors, using the Template Method pattern. The base class takes care of parsing the marking structure. The concrete subclasses provide semantics for marking structure.

Template methods:

punch_nb(): main entry point; calls punch_line() and hook methods * pre_cell(), * post_cell(), and * post_nb()
punch_line(): calls hook methods * punch_begin_marker_line(), * punch_end_marker_line(), * punch_inside_line(), and * punch_outside_line()

Concrete processors override the following hook methods:

__init__() to initialize; must call super() at begin
pre_cell()
punch_begin_marker_line()
punch_end_marker_line()
punch_inside_line()
punch_outside_line()
post_cell()
post_nb()

A concrete class is typically instantiated and used to process a notebook in one go:

ConcretePunchProcessor(args, nb, name).punch_nb()

handle_error(message: str, cell: NotebookNode, ignore: bool = True) → None[source]

Handle error with marker.

Parameters:

message – error message
cell – notebook cell with error
ignore – whether to ignore the marker line

parse_line(line: str, cell_type: str) → None[source]

Parse given line for given cell type, and decide whether it is a marker line. Set instance variable marker to dictionary with transition, label, and description. Sets it to None if the line is not a marker line. Sets marker['transition'] to None if invalid marker line.

Note

Modifies: self.marker

Parameters:

line – marker line
cell_type – type of cell containing marker line

post_cell(cell: NotebookNode) → None[source]

post_nb() → Any[source]

pre_cell(cell: NotebookNode) → None[source]

punch_begin_marker_line(cell: NotebookNode, line: str) → None[source]: Process begin marker line.

punch_end_marker_line(cell: NotebookNode, line: str) → None[source]: Process end marker line.

punch_inside_line(cell: NotebookNode, line: str) → None[source]: Process line inside hole.

punch_line(cell: NotebookNode, cell_index: int, line: str, line_index: int) → None[source]: Punch line.

punch_nb() → Any[source]: Template method; main entry point.

punch_outside_line(cell: NotebookNode, line: str) → None[source]: Process line outside hole.

class nbtoolbelt.punching.PunchedNotebookProcessor(nb: NotebookNode, args: Namespace, name: str)[source]

Bases: PunchBaseProcessor

Create punched notebook.

self.nb_punched = result notebook under construction self.cell_punched = next cell under construction self.source_chad = chad being inserted in current hole

post_cell(cell: NotebookNode)[source]

post_nb()[source]

pre_cell(cell: NotebookNode)[source]

punch_begin_marker_line(cell: NotebookNode, line: str)[source]: Process begin marker line.

punch_end_marker_line(cell: NotebookNode, line: str)[source]: Process end marker line.

punch_outside_line(cell: NotebookNode, line: str)[source]: Process line outside hole.

class nbtoolbelt.punching.SourceChadsProcessor(nb: NotebookNode, args: Namespace, name: str)[source]

Bases: PunchBaseProcessor

Create chads for later use as source. Result is delivered in args.source_chads, which is a dictionary that maps hole labels to hole content as list of cells.

self.source_chads = dictionary that maps label to list of cells self.cell_source_chads = next cell under construction, with source as list of strings (to be compacted)

post_cell(cell: NotebookNode)[source]

post_nb()[source]

pre_cell(cell: NotebookNode)[source]

punch_begin_marker_line(cell: NotebookNode, line: str)[source]: Process begin marker line.

punch_end_marker_line(cell: NotebookNode, line: str)[source]: Process end marker line.

punch_inside_line(cell: NotebookNode, line: str)[source]: Process line inside hole.

nbtoolbelt.punching.punch_via_tags(nb: NotebookNode, args: Namespace) → Tuple[Dict[str, int], NotebookNode, NotebookNode][source]

Punch notebook via tags approach.

Note

Modifies: nb

Parameters:

nb – notebook to punch
args – options

Returns:

punch counts, punched notebook, chads notebook

nbtoolbelt.rendering module

Functions for rendering

This software is made available under the terms of the MIT License.

Parts of this code are reworked from the rendernb checklet for Momotor <momotor.org>.

nbtoolbelt.rendering.render_nb(notebook: NotebookNode, args: Namespace) → Dict[str, Any][source]

Render notebook as html. Uses args.template as template name.

Parameters:

notebook – notebook to render
args – options

Returns:

html

nbtoolbelt.running module

Functions for running

This software is made available under the terms of the MIT License.

nbtoolbelt.running.ipc_kernel_manager_factory(ipc_path)[source]

nbtoolbelt.running.run_nb(nb: NotebookNode, args: Namespace) → None[source]

Run notebook.

Note

Modifies: nb

Parameters:

nb – notebook to run
args – arguments (options)

nbtoolbelt.toolbaseapp module

Base class for concrete tools

This software is made available under the terms of the MIT License.

class nbtoolbelt.toolbaseapp.Tool(name: str = 'nbbase', action: str = 'copy', description: str = 'Copy Jupyter notebooks.')[source]

Bases: object

Base class for concrete tools. It is in itself a functional tool that copies notebooks.

These methods are template methods:

main()
parse_args()
process_file()

Concrete tools inherit from Tool and override these (hook) methods:

__init__() MUST super() at begin, when overriding
config_tool_args_parsing() optional; to configure parser for tool-specific arguments
check_and_adjust_arguments() optional
print_tool_args() optional; to print tool-specific arguments (called only in verbose mode)
process_nb() compulsory; to process one notebook; MUST NOT CALL super()
process_collected_data() optional; MUST CALL super() at begin, when overriding

About the instance variables:

OUTPUT_HEADER = '::::::::::::::'

check_and_adjust_arguments()[source]

Do tool-specific checks and adjustments of parsed arguments.

Hook method to be overridden in concrete tools.

config_tool_args_parsing(group: _ArgumentGroup) → None[source]

Add argument configurations that are tool specific to the given argument group.

Hook method to be overridden in concrete tools.

Parameters:: group – argument group to add into

main(cli_args: Optional[List[str]] = None) → int[source]

Main entry point. Processes all files in args.notebooks, returning an exit code (0 = success).

Can set self._exit_code to signal abortion.

Parameters:: cli_args – list of command-line arguments (None when used as independent script)

parse_args(arguments: List[str]) → None[source]

Configure an argument parser and parse the command-line arguments, updating the namespace with the parsed arguments.

Note

Modifies: self._args

Parameters:: arguments – list of arguments on command line

parser_with_common_arguments() → ArgumentParser[source]

Create argument parser and add common arguments to it.

Returns:: the pre-configured parser

print_tool_args() → None[source]

Print tool-specific arguments; used especially in verbose mode. Indent the lines by 2 spaces.

Hook method to be overridden in concrete tools.

process_collected_data() → None[source]

Process outputs collected from all processed notebooks.

Hook method to be overridden in concrete tools. Overriding method must call super() at begin.

process_file(nb_path: Path) → None[source]

Process one file, given by its path.

Note

Modifies: self._aggregate

Parameters:: nb_path – path of file to process
Returns:: exit code

process_nb(nb: NotebookNode, nb_path: Path) → Sequence[Tuple[NotebookNode, Path]][source]

Process notebook nb.

Can update self._aggregate.

Hook method to be overridden in concrete tools. Overriding method must NOT call super().

Note

Modifies: nb, self._aggregate

Parameters:

nb – notebook to process
nb_path – path to nb

Returns:

sequence of resulting (notebook, notebook-path) pairs

tool_name() → str[source]

Get the tool’s name.

Returns:: the tool’s name

write_output() → None[source]: Write accumulated output to JSON.

nbtoolbelt.toolbaseapp.main(cli_args: Optional[List[str]] = None) → int[source]

nbtoolbelt.validating module

Functions for validating notebooks

This software is made available under the terms of the MIT License.

nbtoolbelt.validating.validate_nb(nb: NotebookNode, assertive: bool) → bool[source]

Validate notebook.

Parameters:

nb – notebook to validate
assertive – whether to raise an exception when invalid

Returns:

whether nb is valid

Module contents

Exported interface, when nbtoolbelt is imported as library

This software is made available under the terms of the MIT License.

nbtoolbelt.__version__: Version number, as string

nbtoolbelt.version_info: Version as tuple

nbtoolbelt.package_name: Name of the nbtoolbelt package

nbtoolbelt.CELL_STATISTICS: Tuple with the keys used in the dictionary returned by nb_cell_stats()

nbtoolbelt.nb_cell_stats(nb: NotebookNode, args: Optional[Namespace] = None) → Dict[str, Dict[str, int]][source]

Count occurrences of various elements in notebook cells.

If args is not None, then the following boolean arguments are used (if present; absent is interpreted as False):

sources
metadata
tags
code
streams
errors

If args is None, then all statistics are gathered.

Parameters:

nb – notebook to inspect
args – namespace with arguments; if None, count everything

Returns:

dictionary of dictionaries with counts per section; each section has its own key; see CELL_STATISTICS

nbtoolbelt.nb_extra_fields(nb: NotebookNode) → Dict[str, int][source]

Extract extra global fields in notebook.

Parameters:: nb – notebook to inspect
Returns:: list of extra fields (not set, because that is not JSON serializable)

nbtoolbelt.nb_metadata(nb: NotebookNode) → Dict[str, Any][source]

Summarize notebook global metadata.

Parameters:: nb – notebook to inspect
Returns:: dictionary with format, kernel, and language info

nbtoolbelt.nb_other_metadata(nb: NotebookNode) → Dict[str, int][source]

Extract other global metadata fields in notebook.

Parameters:: nb – notebook to inspect
Returns:: set of global metadata fields other than required

nbtoolbelt.print_dict(d: Dict[str, Any], header: Optional[str] = None, width: int = 10) → None[source]

Print dictionary d with section header.

Parameters:

d – dictionary to print
header – header of the table
width – width of the left column

nbtoolbelt.print_set(s: Set[str], header: Optional[str] = None, width: int = 10) → None[source]

Print set s with section header.

Parameters:

s – set to print
header – header of the table
width – width of the left column

nbtoolbelt.run_nb(nb: NotebookNode, args: Namespace) → None[source]

Run notebook.

Note

Modifies: nb

Parameters:

nb – notebook to run
args – arguments (options)