module ipythonhelper.notebook_runner

Short summary

module pyquickhelper.ipythonhelper.notebook_runner

Modified version of runipy.notebook_runner.

source on GitHub

Classes

class	truncated documentation
NotebookError	Raised when the execution fails.
NotebookKernelError	Raised when wait_for_ready …
NotebookRunner	The kernel communicates with mime-types while the notebook uses short labels for different cell types. We’ll use this …

Static Methods

staticmethod	truncated documentation
get_cell_code	Returns the code of a cell.

Methods

method	truncated documentation
__add__	Merges two notebooks together, returns a new none.
__del__	We close the kernel.
__init__	constuctor
__len__	Returns the number of cells, it iterates on cells to get this information and does cache the information.
_cell_container	Returns a cells container, it may change according to the format.
_check_thumbnail_tuple	Checks types for a thumbnail.
_merge_images	Merges images defined by (buffer, format). The method uses PIL to merge images when possible.
_scale_image	Scales an image with the same aspect ratio centered in an image with a given max_width and max_height.
add_tag_slide	Tries to add tags for a slide show when they are too few.
cell_height	Approximates the height of a cell by its number of lines it contains.
cell_image	Returns the cell image or None if not found.
cell_metadata	Returns the cell metadata.
cell_type	Returns the cell type.
clean_code	Cleans the code before running it, the function comment out instruction such as show().
copy	Copies the notebook (just the content).
count_code_cells	Returns the number of code cells in the notebook.
create_picture_from	Creates a picture from text.
first_cell	Returns the first cell.
get_description	Gets summary and description of this notebook. We expect the first cell to contain a title and a description …
get_thumbnail	Processes the notebook and creates one picture based on the outputs to illustrate a notebook.
iter_cells	Iterates over the notebook cells.
iter_code_cells	Iterates over the notebook cells containing code.
merge_notebook	Appends notebook nb to this one.
run_cell	Runs a notebook cell and update the output of that cell in-place.
run_notebook	Runs all the cells of a notebook in order and update the outputs in-place. If skip_exceptions is set, …
shutdown_kernel	Shuts down kernel.
to_json	Converts the notebook into JSON.
to_python	Converts the notebook into python.

Documentation

Modified version of runipy.notebook_runner.

source on GitHub

exception pyquickhelper.ipythonhelper.notebook_runner.NotebookError

Bases: Exception

Raised when the execution fails.

source on GitHub

exception pyquickhelper.ipythonhelper.notebook_runner.NotebookKernelError

Bases: Exception

Raised when wait_for_ready fails.

source on GitHub

class pyquickhelper.ipythonhelper.notebook_runner.NotebookRunner(nb, profile_dir=None, working_dir=None, comment='', fLOG=<function noLOG>, theNotebook=None, code_init=None, kernel_name='python', log_level='30', extended_args=None, kernel=False, filename=None, replacements=None, detailed_log=None, startup_timeout=300)

Bases: object

The kernel communicates with mime-types while the notebook uses short labels for different cell types. We’ll use this to map from kernel types to notebook format types.

This classes executes a notebook end to end.

The class can use different kernels. The next links gives more information on how to create or test a kernel:

• jupyter_kernel_test

• simple_kernel

Do I need to shutdown the kernel after running a notebook?

If the class is instantiated with kernel=True, a kernel will be started. It must be shutdown otherwise the program might be waiting for it for ever. That is one of the reasons why the travis build does not complete. The build finished but cannot terminate until all kernels are shutdown.

source on GitHub

constuctor

Parameters

• nb – notebook as JSON

• profile_dir – profile directory

• working_dir – working directory

• comment – additional information added to error message

• theNotebook – if not None, populate the variable theNotebook with this value in the notebook

• code_init – to initialize the notebook with a python code as if it was a cell

• fLOG – logging function

• log_level – Choices: (0, 10, 20, 30=default, 40, 50, ‘DEBUG’, ‘INFO’, ‘WARN’, ‘ERROR’, ‘CRITICAL’)

• kernel_name – kernel name, it can be None

• extended_args – others arguments to pass to the command line (‘–KernelManager.autorestar=True’ for example), see Jupyter Notebook Arguments for a full list

• kernel – kernel is True by default, the notebook can be run, if False, the notebook can be read but not run

• filename – to add the notebook file if there is one in error messages

• replacements – replacements to make in every cell before running it, dictionary { string: string }

• detailed_log – to log detailed information when executing the notebook, this should be a function with the same signature as print or None

• startup_timeout –

  wait for this long for the kernel to be ready, see wait_for_ready

Changed in version 1.8: Parameter startup_timeout was added.

source on GitHub

__add__(nb)

Merges two notebooks together, returns a new none.

Parameters

nb – notebook

Returns

new notebook

source on GitHub

__del__()

We close the kernel.

source on GitHub

__init__(nb, profile_dir=None, working_dir=None, comment='', fLOG=<function noLOG>, theNotebook=None, code_init=None, kernel_name='python', log_level='30', extended_args=None, kernel=False, filename=None, replacements=None, detailed_log=None, startup_timeout=300)

constuctor

Parameters

• nb – notebook as JSON

• profile_dir – profile directory

• working_dir – working directory

• comment – additional information added to error message

• theNotebook – if not None, populate the variable theNotebook with this value in the notebook

• code_init – to initialize the notebook with a python code as if it was a cell

• fLOG – logging function

• log_level – Choices: (0, 10, 20, 30=default, 40, 50, ‘DEBUG’, ‘INFO’, ‘WARN’, ‘ERROR’, ‘CRITICAL’)

• kernel_name – kernel name, it can be None

• extended_args – others arguments to pass to the command line (‘–KernelManager.autorestar=True’ for example), see Jupyter Notebook Arguments for a full list

• kernel – kernel is True by default, the notebook can be run, if False, the notebook can be read but not run

• filename – to add the notebook file if there is one in error messages

• replacements – replacements to make in every cell before running it, dictionary { string: string }

• detailed_log – to log detailed information when executing the notebook, this should be a function with the same signature as print or None

• startup_timeout –

  wait for this long for the kernel to be ready, see wait_for_ready

Changed in version 1.8: Parameter startup_timeout was added.

source on GitHub

__len__()

Returns the number of cells, it iterates on cells to get this information and does cache the information.

Returns

int

source on GitHub

_cell_container()

Returns a cells container, it may change according to the format.

Returns

cell container

source on GitHub

_check_thumbnail_tuple(b)

Checks types for a thumbnail.

Parameters

b – tuple image, format

Returns

b

The function raises an exception if the type is incorrect.

source on GitHub

_merge_images(results)

Merges images defined by (buffer, format). The method uses PIL to merge images when possible.

Returns

[ (image, format) ]

source on GitHub

_scale_image(in_bytes, format=None, max_width=200, max_height=200)

Scales an image with the same aspect ratio centered in an image with a given max_width and max_height.

Parameters

• in_bytes – image as bytes

• format – indication of the format (can be empty)

• max_width – maximum size of the thumbnail

• max_height – maximum size of the thumbnail

Returns

Image (PIL)

source on GitHub

add_tag_slide(max_nb_cell=4, max_nb_line=25)

Tries to add tags for a slide show when they are too few.

Parameters

• max_nb_cell – maximum number of cells within a slide

• max_nb_line – maximum number of lines within a slide

Returns

list of modified cells { #slide: (kind, reason, cell) }

source on GitHub

cell_height(cell)

Approximates the height of a cell by its number of lines it contains.

Parameters

cell – cell

Returns

number of cell

source on GitHub

cell_image(cell, image_from_text=False)

Returns the cell image or None if not found.

Parameters

• cell – cell to examine

• image_from_text – produce an image even if it is not one

Returns

None for no image or a list of tuple (image as bytes, extension) for each output of the cell

source on GitHub

cell_metadata(cell)

Returns the cell metadata.

Parameters

cell – cell

Returns

metadata

source on GitHub

cell_type(cell)

Returns the cell type.

Parameters

cell – from iter_cells

Returns

type

source on GitHub

clean_code(code)

Cleans the code before running it, the function comment out instruction such as show().

Parameters

code – code (string)

Returns

cleaned code

source on GitHub

copy()

Copies the notebook (just the content).

Returns

instance of NotebookRunner

source on GitHub

count_code_cells()

Returns the number of code cells in the notebook.

source on GitHub

create_picture_from(text, format, asbytes=True, context=None)

Creates a picture from text.

Parameters

• text – the text

• format – text, json, …

• context – (str) indication on the content of text (error, …)

• asbytes – results as bytes or as an image

Returns

tuple (picture, format) or PIL.Image (if asbytes is False)

The picture will be bytes, the format png, bmp… The size of the picture will depend on the text. The longer, the bigger. The method relies on matplotlib and then convert the image into a PIL image.

HTML could be rendered with QWebPage from PyQt (not implemented).

source on GitHub

first_cell()

Returns the first cell.

source on GitHub

static get_cell_code(cell)

Returns the code of a cell.

Parameters

cell – a cell or a string

Returns

boolean (=iscell), string

source on GitHub

get_description()

Gets summary and description of this notebook. We expect the first cell to contain a title and a description of its content.

Returns

header, description

source on GitHub

get_thumbnail(max_width=200, max_height=200, use_default=False)

Processes the notebook and creates one picture based on the outputs to illustrate a notebook.

Parameters

• max_width – maximum size of the thumbnail

• max_height – maximum size of the thumbnail

• use_default – force using a default image even if an even is present

Returns

string (SVG) or Image (PIL)

source on GitHub

iter_cells()

Iterates over the notebook cells.

source on GitHub

iter_code_cells()

Iterates over the notebook cells containing code.

source on GitHub

merge_notebook(nb)

Appends notebook nb to this one.

Parameters

nb – notebook or list of notebook (NotebookRunner)

Returns

number of added cells

How to merge notebook?

The following code merges two notebooks into the first one and stores the result unto a file.

from pyquickhelper.ipythonhelper import read_nb
nb1 = read_nb("<file1>", kernel=False)
nb2 = read_nb("<file2>", kernel=False)
nb1.merge_notebook(nb2)
nb1.to_json(outfile)

source on GitHub

run_cell(index_cell, cell, clean_function=None)

Runs a notebook cell and update the output of that cell in-place.

Parameters

• index_cell – index of the cell

• cell – cell to execute

• clean_function – cleaning function to apply to the code before running it

Returns

output of the cell

source on GitHub

run_notebook(skip_exceptions=False, progress_callback=None, additional_path=None, valid=None, clean_function=None, context=None)

Runs all the cells of a notebook in order and update the outputs in-place.

If skip_exceptions is set, then if exceptions occur in a cell, the subsequent cells are run (by default, the notebook execution stops).

Parameters

• skip_exceptions – skip exception

• progress_callback – call back function

• additional_path – additional paths (as a list or None if none)

• valid – if not None, valid is a function which returns whether or not the cell should be executed or not, if the function returns None, the execution of the notebooks and skip the execution of the other cells

• clean_function – function which cleans a cell’s code before executing it (None for None)

Returns

dictionary with statistics

The function adds the local variable theNotebook with the absolute file name of the notebook. Function valid can return None to stop the execution of the notebook before this cell.

source on GitHub

shutdown_kernel()

Shuts down kernel.

source on GitHub

to_json(filename=None, encoding='utf8')

Converts the notebook into JSON.

Parameters

• filename – filename or stream

• encoding – encoding

Returns

Json string if filename is None, None otherwise

source on GitHub

to_python()

Converts the notebook into python.

Returns

string

source on GitHub