Preprocessors Reference#

This library provides a collection of useful Preprocessors for nbconvert:

MetaDataListInjector#

class common_nb_preprocessors.metadata_injector.MetaDataListInjectorPreprocessor#

Parse all code cells and append the matched magic comments with the prefix to the metadata_group list. These strings must be on their own line and only contain the prefix, a string from strings (i.e., the magic comment) and whitespace characters.

__init__(**kwargs)#

Public constructor

configConfig

Configuration file structure

**kw

Additional keyword arguments passed to parent

Return type

None

metadata_group: str#

Metadata group to which the matched magic comment will be appended to if it doesn’t already exist. Default is tags.

prefix: str#

The prefix that indicates the possible start of a magic comment line. Should be comment character of the language. By default #.

preprocess_cell(cell, resource, _index)#

Inject metadata to code-cell if match is found

Parameters

  • cell (nbformat.notebooknode.NotebookNode) –

  • resource (Optional[Dict]) –

  • _index (int) –

Return type

Tuple[nbformat.notebooknode.NotebookNode, Optional[Dict]]

remove_line: bool#

By default remove the matching line in the code-cell.

strings: List[str]#

List of strings (magic comments) that define the text that will be matched and injected into the selected metadata group.

from nbformat.v4 import new_notebook, new_code_cell
from common_nb_preprocessors.metadata_injector import (
    MetaDataListInjectorPreprocessor,
    MetaDataMapInjectorPreprocessor,
)

nb = new_notebook()
nb.cells.append(new_code_cell("# remove-output\nimport os"))
pprint(nb)

{
│   'nbformat': 4,
│   'nbformat_minor': 5,
│   'metadata': {},
│   'cells': [
│   │   {
│   │   │   'id': '7464561a',
│   │   │   'cell_type': 'code',
│   │   │   'metadata': {},
│   │   │   'execution_count': None,
│   │   │   'source': '# remove-output\nimport os',
│   │   │   'outputs': []
│   │   }
│   ]
}

nb, _ = MetaDataListInjectorPreprocessor(
    prefix="#",
    remove_line=True,
    metadata_group="tags",
    strings=["remove-output"],
).preprocess(nb, None)
assert nb.cells[0]["source"] == "import os"
assert nb.cells[0]["metadata"]["tags"] == ["remove-output"]
pprint(nb)

{
│   'nbformat': 4,
│   'nbformat_minor': 5,
│   'metadata': {},
│   'cells': [
│   │   {
│   │   │   'id': '7464561a',
│   │   │   'cell_type': 'code',
│   │   │   'metadata': {
│   │   │   │   'tags': [
│   │   │   │   │   'remove-output'
│   │   │   │   ]
│   │   │   },
│   │   │   'execution_count': None,
│   │   │   'source': 'import os',
│   │   │   'outputs': []
│   │   }
│   ]
}

MetaDataMapInjector#

class common_nb_preprocessors.metadata_injector.MetaDataMapInjectorPreprocessor#

Parse all code cells and add the matched key-value pairs with the prefix to the metadata_group dictionary. The key-value pairs are generated by searching for each key of keys followed by delimiter and the value.

__init__(**kwargs)#

Public constructor

configConfig

Configuration file structure

**kw

Additional keyword arguments passed to parent

Return type

None

allow_nested_keys: bool#

Allow defining nested key access for nested setting of metadata group. Access next level with (hardcoded)

delimiter: str#

Delimiter that separates the key from the value.

keys: List[str]#

List of keys that will be used as a key for the metadata_group dictionary entry and is followed by the delimiter and value.

metadata_group: str#

Metadata group into which the matched key-value pairs will be written.

prefix: str#

The prefix that indicates the possible start of a magic comment line. Should be comment character of the language.

preprocess_cell(cell, resource, _index)#

Inject metadata dict entry to code-cell if match is found

Parameters

  • cell (nbformat.notebooknode.NotebookNode) –

  • resource (Optional[Dict]) –

  • _index (int) –

Return type

Tuple[nbformat.notebooknode.NotebookNode, Optional[Dict]]

remove_line: bool#

By default remove the matching line in the code-cell.

value_to_yaml: bool#

Parse the value as yaml syntax before writing it as a dictionary. Default is False.

from nbformat.v4 import new_notebook, new_code_cell
from common_nb_preprocessors.metadata_injector import MetaDataListInjectorPreprocessor

nb = new_notebook()
nb.cells.append(new_code_cell("# remove-output = true\nimport os"))
pprint(nb)

{
│   'nbformat': 4,
│   'nbformat_minor': 5,
│   'metadata': {},
│   'cells': [
│   │   {
│   │   │   'id': '6586ca36',
│   │   │   'cell_type': 'code',
│   │   │   'metadata': {},
│   │   │   'execution_count': None,
│   │   │   'source': '# remove-output = true\nimport os',
│   │   │   'outputs': []
│   │   }
│   ]
}

nb, _ = MetaDataMapInjectorPreprocessor(
    prefix="#",
    remove_line=True,
    metadata_group="mystnb",
    keys=["remove-output"],
    delimiter="=",
).preprocess(nb, None)
assert nb.cells[0]["source"] == "import os"
assert nb.cells[0]["metadata"]["mystnb"] == {"remove-output": "true"}
pprint(nb)

{
│   'nbformat': 4,
│   'nbformat_minor': 5,
│   'metadata': {},
│   'cells': [
│   │   {
│   │   │   'id': '6586ca36',
│   │   │   'cell_type': 'code',
│   │   │   'metadata': {
│   │   │   │   'mystnb': {
│   │   │   │   │   'remove-output': 'true'
│   │   │   │   }
│   │   │   },
│   │   │   'execution_count': None,
│   │   │   'source': 'import os',
│   │   │   'outputs': []
│   │   }
│   ]
}