Notebook Parameters¶

nbexec parameters are defined in a plain dict and indicated by a comment or a tag.

Defining parameters with comment ‘nbexec: params’¶

You can indicate the parameter definition by adding a comment # nbexec: params to the top of a cell.

Example:

[1]:

# nbexec: params
foo = 1
bar = 1.5
{
    'foo': dict(type=int, desc='Foo', examples=['1', '0xf']),
    'bar': dict(type=float, desc='Bar', examples=['1.5', '2e-2'])
}

[1]:

{'bar': {'desc': 'Bar', 'examples': ['1.5', '2e-2'], 'type': float},
 'foo': {'desc': 'Foo', 'examples': ['1', '0xf'], 'type': int}}

Defining parameters with tag ‘params’¶

You can also indicate the parameter definition by ‘params’ tag. To use tags, first you need to enable the cell toolbar by selecting Menu -> View -> Cell Toolbar -> Tags. Then input ‘params’ to the text field and click ‘Add tag’.

Example:

Default Values¶

The variable assignments above the object {...} are default values which are used when the parameters are not spcified at runtime. They are also required to execute the notebook interactively in the Jupyter notebook web interface. You can also write them in another cell above the parameter definition cell.

Parameter Definition¶

Format¶

The parameter definition is a plain dict which has the following format:

{
    'param_name': {
        'type': <bool|int|float|str>,
        'desc': '<description>',
        'examples': ['<value>', ...]
    }, ...
}

type is required. desc and examples are optional.

The following three definitions are the same because they make the exact same output.

{'foo': {'type': int}}
{'foo': dict(type=int)}
dict(foo=dict(type=int))

Parameter Name¶

You can use any name valid as a variable name in Python except the following reserved names:

notebook
token
output_path
overwrite
jupyter_kernel
cell_timeout

Types¶

Following types are available:

bool
int
float
str

nbexec validates the runtime parameter values.

Type Validation¶

‘True’, ‘False’, ‘true’, ‘false’, ‘1’, and ‘0’ are valid as bool
The value which pass int(<value>) is valid as int
The value which pass float(<value>) is valid as float

Description¶

You can write the description of the parameter in desc option. It is displayed in the execution document.

Examples¶

You can write the examples of the parameter value in examples option. It is a list of strings. The list cannot contain other types even though the parameter requires bool, int or float. Example values are displayed in the execution document. The first example is used in command line examples.

Notice: The string type of example will be quoted by double quote(“), when create Example in the execution document, so remember to escape the special characters like ", $, !, etc.

How nbexec deals with it¶

Applying runtime parameters¶

When nbexec finds a params definition cell, it executes the cell normally and gets the output (as shown in the above Out[1]) as the parameters definition. Then nbexec appends the given runtime parameters after the original source. For example, if you send parameters as foo=2&bar=3.5 for the above example, nbexec overwrite the cell as below and execute it again.

[2]:

# nbexec: params
foo = 1
bar = 1.5
{
    'foo': dict(type=int, desc='Foo', examples=['1', '0xf']),
    'bar': dict(type=float, desc='Bar', examples=['1.5', '2e-2'])
}
foo = 2
bar = float(3.5)

Since nbexec the same cell again, the execution count is incremented by two. The above cell shows the input prompt as In [2] instead of In [1]. As a result, the executed notebook will not have In [1] cell when the execution finishes.

Generating the document¶

nbexec also reads the params definitions when it renders the execution document, but in this case, it directly gets the output string of the cell without executing it. For this reason, the params definition cell must be executed and have the output before opening the document.