Python API

The parsing of a notebook consists of a number of stages, with each stage separated into a separate module:

1. The configuration is set (from a file or CLI)

2. The parser is called with an input string and source

3. The parser reads the input string to a notebook node

4. The notebook is converted to a Markdown-It tokens syntax tree

5. The notebook code outputs are potentially updated, via execution or from a cache

6. The syntax tree is transformed to a docutils document AST (calling the renderer plugin)

7. The docutils document is processed by docutils/sphinx, to create the desired output format(s)

Configuration

class myst_nb.core.config.NbParserConfig(custom_formats: ~typing.Dict[str, ~typing.Tuple[str, dict, bool]] = <factory>, read_as_md: bool = False, metadata_key: str = 'mystnb', cell_metadata_key: str = 'mystnb', kernel_rgx_aliases: ~typing.Dict[str, str] = <factory>, eval_name_regex: str = '^[a-zA-Z_][a-zA-Z0-9_]*$', execution_mode: ~typing.Literal['off', 'force', 'auto', 'cache', 'inline'] = 'auto', execution_cache_path: str = '', execution_excludepatterns: ~typing.Sequence[str] = (), execution_timeout: int = 30, execution_in_temp: bool = False, execution_allow_errors: bool = False, execution_raise_on_error: bool = False, execution_show_tb: bool = False, merge_streams: bool = False, render_plugin: str = 'default', remove_code_source: bool = False, remove_code_outputs: bool = False, code_prompt_show: str = 'Show code cell {type}', code_prompt_hide: str = 'Hide code cell {type}', number_source_lines: bool = False, builder_name: str = 'html', mime_priority_overrides: ~typing.Sequence[~typing.Tuple[str, str, int | None]] = (), output_stderr: ~typing.Literal['show', 'remove', 'remove-warn', 'warn', 'error', 'severe'] = 'show', render_text_lexer: str = 'myst-ansi', render_error_lexer: str = 'ipythontb', render_image_options: ~typing.Dict[str, str] = <factory>, render_figure_options: ~typing.Dict[str, str] = <factory>, render_markdown_format: ~typing.Literal['commonmark', 'gfm', 'myst'] = 'commonmark', ipywidgets_js: ~typing.Dict[str, ~typing.Dict[str, str]] = <factory>, output_folder: str = 'build', append_css: bool = True, metadata_to_fm: bool = False)

Global configuration options for the MyST-NB parser.

Note: in the docutils/sphinx configuration, these option names are prepended with nb_

as_triple() → Iterable[Tuple[str, Any, Field]]

Yield triples of (name, value, field).

copy(**changes) → NbParserConfig

Return a copy of the configuration with optional changes applied.

get_cell_level_config(field_name: str, cell_metadata: Dict[str, Any], warning_callback: Callable[[str, MystNBWarnings], Any]) → Any

Get a configuration value at the cell level.

Takes the highest priority configuration from: cell > document > global > default

Parameters:

• field – the field name to get the value for

• cell_metadata – the metadata for the cell

• warning_callback – a callback to use to warn about issues (msg, subtype)

Raises:

KeyError – if the field is not found

Parsers

class myst_nb.docutils_.Parser(rfc2822=False, inliner=None)

Docutils parser for Jupyter Notebooks, containing MyST Markdown.

config_section = 'myst-nb parser'

The name of the config file section specific to this component (lowercase, no brackets). Override in subclasses.

parse(inputstring: str, document: document) → None

Parse source text.

Parameters:

• inputstring – The source string to parse

• document – The root docutils node to add AST elements to

settings_spec = ('MyST-NB options', None, (('Read as the MyST Markdown format (default: False)', ['--nb-read-as-md'], {'default': UNSET, 'dest': 'nb_read_as_md', 'metavar': '<boolean>', 'validator': <function validate_boolean>}), ("Notebook level metadata key for config overrides (default: (default: 'mystnb'))", ['--nb-metadata-key'], {'default': UNSET, 'dest': 'nb_metadata_key', 'metavar': '<str>'}), ("Cell level metadata key for config overrides (default: (default: 'mystnb'))", ['--nb-cell-metadata-key'], {'default': UNSET, 'dest': 'nb_cell_metadata_key', 'metavar': '<str>'}), ("Regex that matches permitted values of eval expressions (default: (default: '^[a-zA-Z_][a-zA-Z0-9_]*$'))", ['--nb-eval-name-regex'], {'default': UNSET, 'dest': 'nb_eval_name_regex', 'metavar': '<str>'}), ("Execution mode for notebooks (default: 'auto')", ['--nb-execution-mode'], {'choices': ('off', 'force', 'auto', 'cache', 'inline'), 'default': UNSET, 'dest': 'nb_execution_mode', 'metavar': "<'off'|'force'|'auto'|'cache'|'inline'>", 'type': 'choice'}), ("Path to folder for caching notebooks (default: <outdir>) (default: (default: ''))", ['--nb-execution-cache-path'], {'default': UNSET, 'dest': 'nb_execution_cache_path', 'metavar': '<str>'}), ('Execution timeout (seconds) (default: 30)', ['--nb-execution-timeout'], {'default': UNSET, 'dest': 'nb_execution_timeout', 'metavar': '<int>', 'validator': <function _validate_int>}), ('Use temporary folder for the execution current working directory (default: False)', ['--nb-execution-in-temp'], {'default': UNSET, 'dest': 'nb_execution_in_temp', 'metavar': '<boolean>', 'validator': <function validate_boolean>}), ('Allow errors during execution (default: False)', ['--nb-execution-allow-errors'], {'default': UNSET, 'dest': 'nb_execution_allow_errors', 'metavar': '<boolean>', 'validator': <function validate_boolean>}), ('Raise an exception on failed execution, rather than emitting a warning (default: False)', ['--nb-execution-raise-on-error'], {'default': UNSET, 'dest': 'nb_execution_raise_on_error', 'metavar': '<boolean>', 'validator': <function validate_boolean>}), ('Print traceback to stderr on execution error (default: False)', ['--nb-execution-show-tb'], {'default': UNSET, 'dest': 'nb_execution_show_tb', 'metavar': '<boolean>', 'validator': <function validate_boolean>}), ('Merge stdout/stderr execution output streams (default: False)', ['--nb-merge-streams'], {'default': UNSET, 'dest': 'nb_merge_streams', 'metavar': '<boolean>', 'validator': <function validate_boolean>}), ("The entry point for the execution output render class (in group `myst_nb.output_renderer`) (default: (default: 'default'))", ['--nb-render-plugin'], {'default': UNSET, 'dest': 'nb_render_plugin', 'metavar': '<str>'}), ('Remove code cell source (default: False)', ['--nb-remove-code-source'], {'default': UNSET, 'dest': 'nb_remove_code_source', 'metavar': '<boolean>', 'validator': <function validate_boolean>}), ('Remove code cell outputs (default: False)', ['--nb-remove-code-outputs'], {'default': UNSET, 'dest': 'nb_remove_code_outputs', 'metavar': '<boolean>', 'validator': <function validate_boolean>}), ("Prompt to expand hidden code cell {content|source|outputs} (default: (default: 'Show code cell {type}'))", ['--nb-code-prompt-show'], {'default': UNSET, 'dest': 'nb_code_prompt_show', 'metavar': '<str>'}), ("Prompt to collapse hidden code cell {content|source|outputs} (default: (default: 'Hide code cell {type}'))", ['--nb-code-prompt-hide'], {'default': UNSET, 'dest': 'nb_code_prompt_hide', 'metavar': '<str>'}), ('Number code cell source lines (default: False)', ['--nb-number-source-lines'], {'default': UNSET, 'dest': 'nb_number_source_lines', 'metavar': '<boolean>', 'validator': <function validate_boolean>}), ("Builder name, to select render priority for mime types (default: (default: 'html'))", ['--nb-builder-name'], {'default': UNSET, 'dest': 'nb_builder_name', 'metavar': '<str>'}), ("Behaviour for stderr output (default: 'show')", ['--nb-output-stderr'], {'choices': ('show', 'remove', 'remove-warn', 'warn', 'error', 'severe'), 'default': UNSET, 'dest': 'nb_output_stderr', 'metavar': "<'show'|'remove'|'remove-warn'|'warn'|'error'|'severe'>", 'type': 'choice'}), ("Pygments lexer applied to stdout/stderr and text/plain outputs (default: (default: 'myst-ansi'))", ['--nb-render-text-lexer'], {'default': UNSET, 'dest': 'nb_render_text_lexer', 'metavar': '<str>'}), ("Pygments lexer applied to error/traceback outputs (default: (default: 'ipythontb'))", ['--nb-render-error-lexer'], {'default': UNSET, 'dest': 'nb_render_error_lexer', 'metavar': '<str>'}), ("The format to use for text/markdown rendering (default: 'commonmark')", ['--nb-render-markdown-format'], {'choices': ('commonmark', 'gfm', 'myst'), 'default': UNSET, 'dest': 'nb_render_markdown_format', 'metavar': "<'commonmark'|'gfm'|'myst'>", 'type': 'choice'}), ("Folder for external outputs (like images), skipped if empty (default: (default: 'build'))", ['--nb-output-folder'], {'default': UNSET, 'dest': 'nb_output_folder', 'metavar': '<str>'}), ('Add default MyST-NB CSS to HTML outputs (default: True)', ['--nb-append-css'], {'default': UNSET, 'dest': 'nb_append_css', 'metavar': '<boolean>', 'validator': <function validate_boolean>}), ('Convert unhandled metadata to frontmatter (default: False)', ['--nb-metadata-to-fm'], {'default': UNSET, 'dest': 'nb_metadata_to_fm', 'metavar': '<boolean>', 'validator': <function validate_boolean>})), 'MyST options', None, (('Use strict CommonMark parser (default: False)', ['--myst-commonmark-only'], {'default': UNSET, 'dest': 'myst_commonmark_only', 'metavar': '<boolean>', 'validator': <function validate_boolean>}), ('Use strict Github Flavoured Markdown parser (default: False)', ['--myst-gfm-only'], {'default': UNSET, 'dest': 'myst_gfm_only', 'metavar': '<boolean>', 'validator': <function validate_boolean>}), ('Enable syntax extensions', ['--myst-enable-extensions'], {'default': UNSET, 'dest': 'myst_enable_extensions', 'metavar': '<comma-delimited>', 'validator': <function _validate_comma_separated_set>}), ('Disable Commonmark syntax elements', ['--myst-disable-syntax'], {'default': UNSET, 'dest': 'myst_disable_syntax', 'metavar': '<comma-delimited>', 'validator': <function validate_comma_separated_list>}), ('Parse all links as simple hyperlinks (default: False)', ['--myst-all-links-external'], {'default': UNSET, 'dest': 'myst_all_links_external', 'metavar': '<boolean>', 'validator': <function validate_boolean>}), ('Open all external links in a new tab (default: False)', ['--myst-links-external-new-tab'], {'default': UNSET, 'dest': 'myst_links_external_new_tab', 'metavar': '<boolean>', 'validator': <function validate_boolean>}), ('URI schemes that are converted to external links (default: http,https,mailto,ftp)', ['--myst-url-schemes'], {'default': UNSET, 'dest': 'myst_url_schemes', 'metavar': '<comma-delimited>|<yaml-dict>', 'validator': <function _validate_url_schemes>}), ('Interpret a code fence as a directive, for certain language names. This can be useful for fences like dot and mermaid, and interoperability with other Markdown renderers.', ['--myst-fence-as-directive'], {'default': UNSET, 'dest': 'myst_fence_as_directive', 'metavar': '<comma-delimited>', 'validator': <function _validate_comma_separated_set>}), ('Add line numbers to code blocks with these languages', ['--myst-number-code-blocks'], {'default': UNSET, 'dest': 'myst_number_code_blocks', 'metavar': '<comma-delimited>', 'validator': <function validate_comma_separated_list>}), ('Convert a `title` field in the front-matter to a H1 header (default: False)', ['--myst-title-to-header'], {'default': UNSET, 'dest': 'myst_title_to_header', 'metavar': '<boolean>', 'validator': <function validate_boolean>}), ('Heading level depth to assign HTML anchors (default: 0)', ['--myst-heading-anchors'], {'default': UNSET, 'dest': 'myst_heading_anchors', 'metavar': '<int>', 'validator': <function _validate_int>}), ("Function for creating heading anchors, or a python import path e.g. `my_package.my_module.my_function` (default: (default: 'None'))", ['--myst-heading-slug-func'], {'default': UNSET, 'dest': 'myst_heading_slug_func', 'metavar': '<str>'}), ('HTML meta tags', ['--myst-html-meta'], {'default': UNSET, 'dest': 'myst_html_meta', 'metavar': '<yaml-dict>', 'validator': <function _create_validate_yaml.<locals>._validate_yaml>}), ('Move all footnotes to the end of the document, and sort by reference order (default: True)', ['--myst-footnote-sort'], {'default': UNSET, 'dest': 'myst_footnote_sort', 'metavar': '<boolean>', 'validator': <function validate_boolean>}), ('Place a transition before sorted footnotes (default: True)', ['--myst-footnote-transition'], {'default': UNSET, 'dest': 'myst_footnote_transition', 'metavar': '<boolean>', 'validator': <function validate_boolean>}), ('For reading speed calculations (default: 200)', ['--myst-words-per-minute'], {'default': UNSET, 'dest': 'myst_words_per_minute', 'metavar': '<int>', 'validator': <function _validate_int>}), ('Substitutions mapping', ['--myst-substitutions'], {'default': UNSET, 'dest': 'myst_substitutions', 'metavar': '<yaml-dict>', 'validator': <function _create_validate_yaml.<locals>._validate_yaml>}), ('Recognise URLs without schema prefixes (default: True)', ['--myst-linkify-fuzzy-links'], {'default': UNSET, 'dest': 'myst_linkify_fuzzy_links', 'metavar': '<boolean>', 'validator': <function validate_boolean>}), ('Parse `$$...$$ (label)` (default: True)', ['--myst-dmath-allow-labels'], {'default': UNSET, 'dest': 'myst_dmath_allow_labels', 'metavar': '<boolean>', 'validator': <function validate_boolean>}), ('Allow initial/final spaces in `$ ... $` (default: True)', ['--myst-dmath-allow-space'], {'default': UNSET, 'dest': 'myst_dmath_allow_space', 'metavar': '<boolean>', 'validator': <function validate_boolean>}), ('Allow initial/final digits `1$ ...$2` (default: True)', ['--myst-dmath-allow-digits'], {'default': UNSET, 'dest': 'myst_dmath_allow_digits', 'metavar': '<boolean>', 'validator': <function validate_boolean>}), ('Parse inline `$$ ... $$` (default: False)', ['--myst-dmath-double-inline'], {'default': UNSET, 'dest': 'myst_dmath_double_inline', 'metavar': '<boolean>', 'validator': <function validate_boolean>}), ('Enable checkboxes (default: False)', ['--myst-enable-checkboxes'], {'default': UNSET, 'dest': 'myst_enable_checkboxes', 'metavar': '<boolean>', 'validator': <function validate_boolean>}), ('A list of warning types to suppress warning messages', ['--myst-suppress-warnings'], {'default': UNSET, 'dest': 'myst_suppress_warnings', 'metavar': '<comma-delimited>', 'validator': <function validate_comma_separated_list>}), ('Syntax highlight code blocks with pygments (default: True)', ['--myst-highlight-code-blocks'], {'default': UNSET, 'dest': 'myst_highlight_code_blocks', 'metavar': '<boolean>', 'validator': <function validate_boolean>}), ('Mapping of key to (url, inv file), for intra-project referencing', ['--myst-inventories'], {'default': UNSET, 'dest': 'myst_inventories', 'metavar': '<yaml-dict>', 'validator': <function _create_validate_yaml.<locals>._validate_yaml>})), 'Generic Parser Options', None, (('Disable directives that insert the contents of an external file; replaced with a "warning" system message.', ['--no-file-insertion'], {'action': 'store_false', 'default': 1, 'dest': 'file_insertion_enabled', 'validator': <function validate_boolean>}), ('Enable directives that insert the contents of an external file. (default)', ['--file-insertion-enabled'], {'action': 'store_true'}), ('Disable the "raw" directive; replaced with a "warning" system message.', ['--no-raw'], {'action': 'store_false', 'default': 1, 'dest': 'raw_enabled', 'validator': <function validate_boolean>}), ('Enable the "raw" directive. (default)', ['--raw-enabled'], {'action': 'store_true'}), ('Maximal number of characters in an input line. Default 10 000.', ['--line-length-limit'], {'default': 10000, 'metavar': '<length>', 'type': 'int', 'validator': <function validate_nonnegative_int>})), 'reStructuredText Parser Options', None, (('Recognize and link to standalone PEP references (like "PEP 258").', ['--pep-references'], {'action': 'store_true', 'validator': <function validate_boolean>}), ('Base URL for PEP references (default "https://peps.python.org/").', ['--pep-base-url'], {'default': 'https://peps.python.org/', 'metavar': '<URL>', 'validator': <function validate_url_trailing_slash>}), ('Template for PEP file part of URL. (default "pep-%04d")', ['--pep-file-url-template'], {'default': 'pep-%04d', 'metavar': '<URL>'}), ('Recognize and link to standalone RFC references (like "RFC 822").', ['--rfc-references'], {'action': 'store_true', 'validator': <function validate_boolean>}), ('Base URL for RFC references (default "https://tools.ietf.org/html/").', ['--rfc-base-url'], {'default': 'https://tools.ietf.org/html/', 'metavar': '<URL>', 'validator': <function validate_url_trailing_slash>}), ('Set number of spaces for tab expansion (default 8).', ['--tab-width'], {'default': 8, 'metavar': '<width>', 'type': 'int', 'validator': <function validate_nonnegative_int>}), ('Remove spaces before footnote references.', ['--trim-footnote-reference-space'], {'action': 'store_true', 'validator': <function validate_boolean>}), ('Leave spaces before footnote references.', ['--leave-footnote-reference-space'], {'action': 'store_false', 'dest': 'trim_footnote_reference_space'}), ('Token name set for parsing code with Pygments: one of "long", "short", or "none" (no parsing). Default is "long".', ['--syntax-highlight'], {'choices': ['long', 'short', 'none'], 'default': 'long', 'metavar': '<format>'}), ('Change straight quotation marks to typographic form: one of "yes", "no", "alt[ernative]" (default "no").', ['--smart-quotes'], {'default': False, 'metavar': '<yes/no/alt>', 'validator': <function validate_ternary>}), ('Characters to use as "smart quotes" for <language>. ', ['--smartquotes-locales'], {'action': 'append', 'metavar': '<language:quotes[,language:quotes,...]>', 'validator': <function validate_smartquotes_locales>}), ('Inline markup recognized at word boundaries only (adjacent to punctuation or whitespace). Force character-level inline markup recognition with "\\ " (backslash + space). Default.', ['--word-level-inline-markup'], {'action': 'store_false', 'dest': 'character_level_inline_markup'}), ('Inline markup recognized anywhere, regardless of surrounding characters. Backslash-escapes must be used to avoid unwanted markup recognition. Useful for East Asian languages. Experimental.', ['--character-level-inline-markup'], {'action': 'store_true', 'default': False, 'dest': 'character_level_inline_markup'})))

Runtime settings specification.

supported: tuple[str, ...] = ('mystnb', 'ipynb')

Aliases this parser supports.

class myst_nb.sphinx_.Parser

Sphinx parser for Jupyter Notebook formats, containing MyST Markdown.

config_section = 'myst-nb parser'

The name of the config file section specific to this component (lowercase, no brackets). Override in subclasses.

config_section_dependencies = ('parsers',)

A list of names of config file sections that are to be applied before config_section, in order (from general to specific). In other words, the settings in config_section are to be overlaid on top of the settings from these sections. The “general” section is assumed implicitly. Override in subclasses.

env: SphinxEnvType

The environment object

parse(inputstring: str, document: document) → None

Parse source text.

Parameters:

• inputstring – The source string to parse

• document – The root docutils node to add AST elements to

supported: tuple[str, ...] = ('myst-nb',)

Aliases this parser supports.

Read

class myst_nb.core.read.NbReader(read: Callable[[str], NotebookNode], md_config: MdParserConfig, read_fmt: dict | None = None)

A data class for reading a notebook format.

md_config: MdParserConfig

The configuration for parsing markdown cells.

read: Callable[[str], NotebookNode]

The function to read a notebook from a (utf8) string.

read_fmt: dict | None = None

The type of the reader, if known.

myst_nb.core.read.create_nb_reader(path: str, md_config: MdParserConfig, nb_config: NbParserConfig, content: None | str | Iterator[str]) → NbReader | None

Create a notebook reader, given a string, source path and configuration.

Note, we do not directly parse to a notebook, since jupyter-cache functionality requires the reader.

Parameters:

• path – Path to the input source being processed.

• nb_config – The configuration for parsing Notebooks.

• md_config – The default configuration for parsing Markown.

• content – The input string (optionally used to check for text-based notebooks)

Returns:

the notebook reader, and the (potentially modified) MdParserConfig, or None if the input cannot be read as a notebook.

myst_nb.core.read.is_myst_markdown_notebook(text: str | Iterator[str]) → bool

Check if the input is a MyST Markdown notebook.

This is identified by the presence of a top-matter section, containing either:

---
file_format: mystnb
---

or:

---
jupytext:
    text_representation:
        format_name: myst
---

Parameters:

text – The input text.

Returns:

True if the input is a markdown notebook.

myst_nb.core.read.read_myst_markdown_notebook(text, config: MdParserConfig | None = None, code_directive='{code-cell}', raw_directive='{raw-cell}', add_source_map=False, path: str | Path | None = None) → NotebookNode

Convert text written in the myst format to a notebook.

Parameters:

• text – the file text

• code_directive – the name of the directive to search for containing code cells

• raw_directive – the name of the directive to search for containing raw cells

• add_source_map – add a source_map key to the notebook metadata, which is a list of the starting source line number for each cell.

• path – path to notebook (required for :load:)

:raises MystMetadataParsingError if the metadata block is not valid JSON/YAML

NOTE: we assume here that all of these directives are at the top-level, i.e. not nested in other directives.

Execute

myst_nb.core.execute.create_client(notebook: NotebookNode, source: str, nb_config: NbParserConfig, logger: LoggerType, read_fmt: None | dict = None) → NotebookClientBase

Create a notebook execution client, to update its outputs.

This function may execute the notebook if necessary, to update its outputs, or populate from a cache.

Parameters:

• notebook – The notebook to update.

• source – Path to or description of the input source being processed.

• nb_config – The configuration for the notebook parser.

• logger – The logger to use.

• read_fmt – The format of the input source (to parse to jupyter cache)

Returns:

The updated notebook, and the (optional) execution metadata.

class myst_nb.core.execute.base.NotebookClientBase(notebook: NotebookNode, path: Path | None, nb_config: NbParserConfig, logger: DocutilsDocLogger | SphinxDocLogger, **kwargs: Any)

A base client for interacting with Jupyter notebooks.

This class is intended to be used as a context manager, and should only be entered once.

Subclasses should override the start_client and close_client methods.

cell_line(cell_index: int) → int

Get the source line number of a cell.

close_client(exc_type, exc_val, exc_tb)

Close the client.

code_cell_outputs(cell_index: int) → tuple[int | None, list[NotebookNode]]

Get the outputs of a cell.

Returns:

a tuple of the execution_count and the outputs

Raises:

IndexError – if the cell index is out of range

eval_variable(name: str) → list[NotebookNode]

Retrieve the value of a variable from the kernel.

Parameters:

name – the name of the variable, must match the regex [a-zA-Z][a-zA-Z0-9_]*

Returns:

code cell outputs

Raises:

• NotImplementedError – if the execution mode does not support this feature

• EvalNameError – if the variable name is invalid

property exec_metadata: ExecutionResult | None

Get the execution metadata.

finalise_client()

Finalise the client.

This is called before final rendering and should be used, for example, to finalise the widget state on the metadata.

property glue_data: dict[str, NotebookNode]

Get the glue data.

property logger: DocutilsDocLogger | SphinxDocLogger

Get the logger.

property nb_config: NbParserConfig

Get the notebook configuration.

property nb_metadata: dict[str, Any]

Get the notebook level metadata.

nb_source_code_lexer() → str | None

Get the lexer for the notebook source code.

property notebook: NotebookNode

Get the notebook.

property path: Path | None

Get the notebook path.

start_client()

Start the client.

class myst_nb.core.execute.direct.NotebookClientDirect(notebook: NotebookNode, path: Path | None, nb_config: NbParserConfig, logger: DocutilsDocLogger | SphinxDocLogger, **kwargs: Any)

A notebook client that executes the notebook directly, on entrance of the context.

class myst_nb.core.execute.cache.NotebookClientCache(notebook: NotebookNode, path: Path | None, nb_config: NbParserConfig, logger: DocutilsDocLogger | SphinxDocLogger, **kwargs: Any)

A notebook client that retrieves notebook outputs from the cache, or executes the notebook and adds them to the cache, on entrance of the context.

class myst_nb.core.execute.inline.NotebookClientInline(notebook: NotebookNode, path: Path | None, nb_config: NbParserConfig, logger: DocutilsDocLogger | SphinxDocLogger, **kwargs: Any)

A notebook client that executes the notebook inline, i.e. during the render.

This allows for the client to be called in-between code cell executions, in order to extract variable state.

exception myst_nb.core.execute.base.ExecutionError

An exception for failed execution and execution_raise_on_error is true.

exception myst_nb.core.execute.base.EvalNameError

An exception for if an evaluation variable name is invalid.

class myst_nb.core.execute.base.ExecutionResult

Result of executing a notebook.

error: str | None

error type if the notebook failed to execute

method: str

method used to execute the notebook

mtime: float

POSIX timestamp of the execution time

runtime: float | None

runtime in seconds

succeeded: bool

True if the notebook executed successfully

traceback: str | None

traceback if the notebook failed

Render plugin

class myst_nb.core.render.MimeData(mime_type: str, content: str | bytes, cell_metadata: dict[str, ~typing.Any] = <factory>, output_metadata: dict[str, ~typing.Any] = <factory>, cell_index: int | None = None, output_index: int | None = None, line: int | None = None)

Mime data from an execution output (display_data / execute_result)

e.g. notebook.cells[0].outputs[0].data[‘text/plain’] = “Hello, world!”

see: https://nbformat.readthedocs.io/en/5.1.3/format_description.html#display-data

cell_index: int | None = None

Index of the cell in the notebook

cell_metadata: dict[str, Any]

Cell level metadata of the output

content: str | bytes

Data value of the output.data

line: int | None = None

Source line of the cell

mime_type: str

Mime type key of the output.data

output_index: int | None = None

Index of the output in the cell

output_metadata: dict[str, Any]

Output level metadata of the output

property string: str

Get the content as a string.

class myst_nb.core.render.NbElementRenderer(renderer: DocutilsNbRenderer | SphinxNbRenderer, logger: LoggerType)

A class for rendering notebook elements.

add_js_file(key: str, uri: str | None, kwargs: dict[str, str]) → None

Register a JavaScript file to include in the HTML output of this document.

Parameters:

• key – the key to use for referencing the file

• uri – the URI to the file, or None and supply the file contents in kwargs[‘body’]

property config: NbParserConfig

The notebook parser config

property logger: DocutilsDocLogger | SphinxDocLogger

The logger for this renderer.

In extension to a standard logger, this logger also for line and subtype kwargs to the log methods.

render_error(output: NotebookNode, cell_metadata: dict[str, Any], cell_index: int, source_line: int) → list[Element]

Render a notebook error output.

https://nbformat.readthedocs.io/en/5.1.3/format_description.html#error

Parameters:

• output – the output node

• metadata – the cell level metadata

• cell_index – the index of the cell containing the output

• source_line – the line number of the cell in the source document

render_image(data: MimeData) → list[Element]

Render a notebook image mime data output.

render_image_inline(data: MimeData) → list[Element]

Render a notebook image mime data output.

render_javascript(data: MimeData) → list[Element]

Render a notebook application/javascript mime data output.

render_javascript_inline(data: MimeData) → list[Element]

Render a notebook application/javascript mime data output.

render_markdown(data: MimeData) → list[Element]

Render a notebook text/markdown mime data output.

render_markdown_inline(data: MimeData) → list[Element]

Render a notebook text/markdown mime data output.

render_mime_type(data: MimeData) → list[Element]

Render a notebook mime output, as a block level element.

render_mime_type_inline(data: MimeData) → list[Element]

Render a notebook mime output, as an inline level element.

render_nb_finalise(metadata: dict) → None

Finalise the render of the notebook metadata.

render_raw_cell(content: str, metadata: dict, cell_index: int, source_line: int) → list[Element]

Render a raw cell.

https://nbformat.readthedocs.io/en/5.1.3/format_description.html#raw-nbconvert-cells

Parameters:

• content – the raw cell content

• metadata – the cell level metadata

• cell_index – the index of the cell

• source_line – the line number of the cell in the source document

render_stderr(output: NotebookNode, cell_metadata: dict[str, Any], cell_index: int, source_line: int) → list[Element]

Render a notebook stderr output.

https://nbformat.readthedocs.io/en/5.1.3/format_description.html#stream-output

Parameters:

• output – the output node

• metadata – the cell level metadata

• cell_index – the index of the cell containing the output

• source_line – the line number of the cell in the source document

render_stdout(output: NotebookNode, cell_metadata: dict[str, Any], cell_index: int, source_line: int) → list[Element]

Render a notebook stdout output.

https://nbformat.readthedocs.io/en/5.1.3/format_description.html#stream-output

Parameters:

• output – the output node

• metadata – the cell level metadata

• cell_index – the index of the cell containing the output

• source_line – the line number of the cell in the source document

render_text_html(data: MimeData) → list[Element]

Render a notebook text/html mime data output.

render_text_html_inline(data: MimeData) → list[Element]

Render a notebook text/html mime data output.

render_text_latex(data: MimeData) → list[Element]

Render a notebook text/latex mime data output.

render_text_latex_inline(data: MimeData) → list[Element]

Render a notebook text/latex mime data output.

render_text_plain(data: MimeData) → list[Element]

Render a notebook text/plain mime data output.

render_text_plain_inline(data: MimeData) → list[Element]

Render a notebook text/plain mime data output.

render_unhandled(data: MimeData) → list[Element]

Render a notebook output of unknown mime type.

render_unhandled_inline(data: MimeData) → list[Element]

Render a notebook output of unknown mime type.

render_widget_view(data: MimeData) → list[Element]

Render a notebook application/vnd.jupyter.widget-view+json mime output.

render_widget_view_inline(data: MimeData) → list[Element]

Render a notebook application/vnd.jupyter.widget-view+json mime output.

property renderer: DocutilsNbRenderer | SphinxNbRenderer

The renderer this output renderer is associated with.

property source

The source of the notebook.

write_file(path: list[str], content: bytes, overwrite=False, exists_ok=False) → str

Write a file to the external output folder.

Parameters:

• path – the path to write the file to, relative to the output folder

• content – the content to write to the file

• overwrite – whether to overwrite an existing file

• exists_ok – whether to ignore an existing file if overwrite is False

Returns:

URI to use for referencing the file

class myst_nb.core.render.MimeRenderPlugin(*args, **kwargs)

Protocol for a mime renderer plugin.

static handle_mime(renderer: NbElementRenderer, data: MimeData, inline: bool) → None | list[Element]

A function that renders a mime type to docutils nodes, or returns None to reject.

mime_priority_overrides: ClassVar[Sequence[tuple[str, str, int | None]]] = ()

A list of (builder name, mime type, priority).

class myst_nb.core.render.ExampleMimeRenderPlugin(*args, **kwargs)

Example mime renderer for custommimetype.

static handle_mime(renderer: NbElementRenderer, data: MimeData, inline: int) → None | list[Element]

A function that renders a mime type to docutils nodes, or returns None to reject.

mime_priority_overrides: ClassVar[Sequence[tuple[str, str, int | None]]] = [('*', 'custommimetype', 1)]

A list of (builder name, mime type, priority).

Lexers

class myst_nb.core.lexers.AnsiColorLexer(*args, **kwds)

Bases: RegexLexer

Pygments lexer for text containing ANSI color codes.

Adapted from chriskuehl/pygments-ansi-color

aliases = ('myst-ansi',)

A list of short, unique identifiers that can be used to look up the lexer from a list, e.g., using get_lexer_by_name().

property current_token

flags = 24

Flags for compiling the regular expressions. Defaults to MULTILINE.

name = 'ANSI Color'

Full name of the lexer, in human-readable form

process(match)

Produce the next token and bit of text.

Interprets the ANSI code (which may be a color code or some other code), changing the lexer state and producing a new token. If it’s not a color code, we just strip it out and move on.

Some useful reference for ANSI codes:

• http://ascii-table.com/ansi-escape-sequences.php

reset_state()

tokens = {'root': [('\\x1b\\[([^\\x1b]*)', <function AnsiColorLexer.process>), ('[^\\x1b]+', ('Text',))]}

At all time there is a stack of states. Initially, the stack contains a single state ‘root’. The top of the stack is called “the current state”.

Dict of {'state': [(regex, tokentype, new_state), ...], ...}

new_state can be omitted to signify no state transition. If new_state is a string, it is pushed on the stack. This ensure the new current state is new_state. If new_state is a tuple of strings, all of those strings are pushed on the stack and the current state will be the last element of the list. new_state can also be combined('state1', 'state2', ...) to signify a new, anonymous state combined from the rules of two or more existing ones. Furthermore, it can be ‘#pop’ to signify going back one step in the state stack, or ‘#push’ to push the current state on the stack again. Note that if you push while in a combined state, the combined state itself is pushed, and not only the state in which the rule is defined.

The tuple can also be replaced with include('state'), in which case the rules from the state named by the string are included in the current one.

Loggers

class myst_nb.core.loggers.DocutilsDocLogger(document: document, type_name: str = 'mystnb')

Bases: LoggerAdapter

A logger which routes messages to the docutils document reporter.

The document path and message type are automatically included in the message, and line is allowed as a keyword argument. The standard sphinx logger keywords are allowed but ignored: subtype, color, once, nonl.

type.subtype are also appended to the end of messages.

KEYWORDS = ['type', 'subtype', 'location', 'nonl', 'color', 'once', 'line', 'parent']

process(msg, kwargs)

Process the logging message and keyword arguments passed in to a logging call to insert contextual information. You can either manipulate the message itself, the keyword args or both. Return the message and kwargs modified (or not) to suit your needs.

Normally, you’ll only need to override this one method in a LoggerAdapter subclass for your specific needs.

class myst_nb.core.loggers.SphinxDocLogger(document: document, type_name: str = 'mystnb')

Bases: LoggerAdapter

Wraps a Sphinx logger, which routes messages to the docutils document reporter.

The document path and message type are automatically included in the message, and line is allowed as a keyword argument, as well as the standard sphinx logger keywords: subtype, color, once, nonl.

As per the sphinx logger, warnings are suppressed, if their type.subtype are included in the suppress_warnings configuration. These are also appended to the end of messages.

process(msg, kwargs)

Process the logging message and keyword arguments passed in to a logging call to insert contextual information. You can either manipulate the message itself, the keyword args or both. Return the message and kwargs modified (or not) to suit your needs.

Normally, you’ll only need to override this one method in a LoggerAdapter subclass for your specific needs.