Python API
Contents
Python API#
The parsing of a notebook consists of a number of stages, with each stage separated into a separate module:
The configuration is set (from a file or CLI)
The parser is called with an input string and source
The parser reads the input string to a notebook node
The notebook is converted to a Markdown-It tokens syntax tree
The notebook code outputs are potentially updated, via execution or from a cache
The syntax tree is transformed to a docutils document AST (calling the renderer plugin)
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>, 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, number_source_lines: bool = False, builder_name: str = 'html', mime_priority_overrides: typing.Sequence[typing.Tuple[str, str, typing.Optional[int]]] = (), 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)[source]#
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, dataclasses.Field]] [source]#
Yield triples of (name, value, field).
- copy(**changes) myst_nb.core.config.NbParserConfig [source]#
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, str], Any]) Any [source]#
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)[source]#
Docutils parser for Jupyter Notebooks, containing MyST Markdown.
- parse(inputstring: str, document: docutils.nodes.document) None [source]#
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'], {'dest': 'nb_read_as_md', 'default': UNSET, 'metavar': '<boolean>', 'validator': <function validate_boolean>}), ("Notebook level metadata key for config overrides (default: 'mystnb')", ['--nb-metadata-key'], {'dest': 'nb_metadata_key', 'default': UNSET, 'metavar': '<str>'}), ("Cell level metadata key for config overrides (default: 'mystnb')", ['--nb-cell-metadata-key'], {'dest': 'nb_cell_metadata_key', 'default': UNSET, 'metavar': '<str>'}), ("Execution mode for notebooks (default: 'auto')", ['--nb-execution-mode'], {'dest': 'nb_execution_mode', 'default': UNSET, 'metavar': "<'off'|'force'|'auto'|'cache'|'inline'>", 'type': 'choice', 'choices': ('off', 'force', 'auto', 'cache', 'inline')}), ("Path to folder for caching notebooks (default: <outdir>) (default: '')", ['--nb-execution-cache-path'], {'dest': 'nb_execution_cache_path', 'default': UNSET, 'metavar': '<str>'}), ('Execution timeout (seconds) (default: 30)', ['--nb-execution-timeout'], {'dest': 'nb_execution_timeout', 'default': UNSET, 'metavar': '<int>', 'validator': <function _validate_int>}), ('Use temporary folder for the execution current working directory (default: False)', ['--nb-execution-in-temp'], {'dest': 'nb_execution_in_temp', 'default': UNSET, 'metavar': '<boolean>', 'validator': <function validate_boolean>}), ('Allow errors during execution (default: False)', ['--nb-execution-allow-errors'], {'dest': 'nb_execution_allow_errors', 'default': UNSET, 'metavar': '<boolean>', 'validator': <function validate_boolean>}), ('Raise an exception on failed execution, rather than emitting a warning (default: False)', ['--nb-execution-raise-on-error'], {'dest': 'nb_execution_raise_on_error', 'default': UNSET, 'metavar': '<boolean>', 'validator': <function validate_boolean>}), ('Print traceback to stderr on execution error (default: False)', ['--nb-execution-show-tb'], {'dest': 'nb_execution_show_tb', 'default': UNSET, 'metavar': '<boolean>', 'validator': <function validate_boolean>}), ('Merge stdout/stderr execution output streams (default: False)', ['--nb-merge-streams'], {'dest': 'nb_merge_streams', 'default': UNSET, 'metavar': '<boolean>', 'validator': <function validate_boolean>}), ("The entry point for the execution output render class (in group `myst_nb.output_renderer`) (default: 'default')", ['--nb-render-plugin'], {'dest': 'nb_render_plugin', 'default': UNSET, 'metavar': '<str>'}), ('Remove code cell source (default: False)', ['--nb-remove-code-source'], {'dest': 'nb_remove_code_source', 'default': UNSET, 'metavar': '<boolean>', 'validator': <function validate_boolean>}), ('Remove code cell outputs (default: False)', ['--nb-remove-code-outputs'], {'dest': 'nb_remove_code_outputs', 'default': UNSET, 'metavar': '<boolean>', 'validator': <function validate_boolean>}), ('Number code cell source lines (default: False)', ['--nb-number-source-lines'], {'dest': 'nb_number_source_lines', 'default': UNSET, 'metavar': '<boolean>', 'validator': <function validate_boolean>}), ("Builder name, to select render priority for mime types (default: 'html')", ['--nb-builder-name'], {'dest': 'nb_builder_name', 'default': UNSET, 'metavar': '<str>'}), ("Behaviour for stderr output (default: 'show')", ['--nb-output-stderr'], {'dest': 'nb_output_stderr', 'default': UNSET, 'metavar': "<'show'|'remove'|'remove-warn'|'warn'|'error'|'severe'>", 'type': 'choice', 'choices': ('show', 'remove', 'remove-warn', 'warn', 'error', 'severe')}), ("Pygments lexer applied to stdout/stderr and text/plain outputs (default: 'myst-ansi')", ['--nb-render-text-lexer'], {'dest': 'nb_render_text_lexer', 'default': UNSET, 'metavar': '<str>'}), ("Pygments lexer applied to error/traceback outputs (default: 'ipythontb')", ['--nb-render-error-lexer'], {'dest': 'nb_render_error_lexer', 'default': UNSET, 'metavar': '<str>'}), ("The format to use for text/markdown rendering (default: 'commonmark')", ['--nb-render-markdown-format'], {'dest': 'nb_render_markdown_format', 'default': UNSET, 'metavar': "<'commonmark'|'gfm'|'myst'>", 'type': 'choice', 'choices': ('commonmark', 'gfm', 'myst')}), ("Folder for external outputs (like images), skipped if empty (default: 'build')", ['--nb-output-folder'], {'dest': 'nb_output_folder', 'default': UNSET, 'metavar': '<str>'}), ('Add default MyST-NB CSS to HTML outputs (default: True)', ['--nb-append-css'], {'dest': 'nb_append_css', 'default': UNSET, 'metavar': '<boolean>', 'validator': <function validate_boolean>}), ('Convert unhandled metadata to frontmatter (default: False)', ['--nb-metadata-to-fm'], {'dest': 'nb_metadata_to_fm', 'default': UNSET, 'metavar': '<boolean>', 'validator': <function validate_boolean>})), 'MyST options', None, (('Use strict CommonMark parser (default: False)', ['--myst-commonmark-only'], {'dest': 'myst_commonmark_only', 'default': UNSET, 'metavar': '<boolean>', 'validator': <function validate_boolean>}), ('Use strict Github Flavoured Markdown parser (default: False)', ['--myst-gfm-only'], {'dest': 'myst_gfm_only', 'default': UNSET, 'metavar': '<boolean>', 'validator': <function validate_boolean>}), ("Enable syntax extensions (default: '')", ['--myst-enable-extensions'], {'dest': 'myst_enable_extensions', 'default': UNSET, 'metavar': '<comma-delimited>', 'validator': <function validate_comma_separated_list>}), ("Disable Commonmark syntax elements (default: '')", ['--myst-disable-syntax'], {'dest': 'myst_disable_syntax', 'default': UNSET, 'metavar': '<comma-delimited>', 'validator': <function validate_comma_separated_list>}), ('Parse all links as simple hyperlinks (default: False)', ['--myst-all-links-external'], {'dest': 'myst_all_links_external', 'default': UNSET, 'metavar': '<boolean>', 'validator': <function validate_boolean>}), ("URL scheme prefixes identified as external links (default: 'http,https,mailto,ftp')", ['--myst-url-schemes'], {'dest': 'myst_url_schemes', 'default': UNSET, 'metavar': '<null|comma-delimited>', 'validator': <function validate_comma_separated_list>}), ('Syntax highlight code blocks with pygments (default: True)', ['--myst-highlight-code-blocks'], {'dest': 'myst_highlight_code_blocks', 'default': UNSET, 'metavar': '<boolean>', 'validator': <function validate_boolean>}), ("Add line numbers to code blocks with these languages (default: '')", ['--myst-number-code-blocks'], {'dest': 'myst_number_code_blocks', 'default': UNSET, 'metavar': '<comma-delimited>', 'validator': <function validate_comma_separated_list>}), ('Convert a `title` field in the top-matter to a H1 header (default: False)', ['--myst-title-to-header'], {'dest': 'myst_title_to_header', 'default': UNSET, 'metavar': '<boolean>', 'validator': <function validate_boolean>}), ('Place a transition before any footnotes (default: True)', ['--myst-footnote-transition'], {'dest': 'myst_footnote_transition', 'default': UNSET, 'metavar': '<boolean>', 'validator': <function validate_boolean>}), ('For reading speed calculations (default: 200)', ['--myst-words-per-minute'], {'dest': 'myst_words_per_minute', 'default': UNSET, 'metavar': '<int>', 'validator': <function _validate_int>}), ('Recognise URLs without schema prefixes (default: True)', ['--myst-linkify-fuzzy-links'], {'dest': 'myst_linkify_fuzzy_links', 'default': UNSET, 'metavar': '<boolean>', 'validator': <function validate_boolean>}), ('Parse `$$...$$ (label)` (default: True)', ['--myst-dmath-allow-labels'], {'dest': 'myst_dmath_allow_labels', 'default': UNSET, 'metavar': '<boolean>', 'validator': <function validate_boolean>}), ('Allow initial/final spaces in `$ ... $` (default: True)', ['--myst-dmath-allow-space'], {'dest': 'myst_dmath_allow_space', 'default': UNSET, 'metavar': '<boolean>', 'validator': <function validate_boolean>}), ('Allow initial/final digits `1$ ...$2` (default: True)', ['--myst-dmath-allow-digits'], {'dest': 'myst_dmath_allow_digits', 'default': UNSET, 'metavar': '<boolean>', 'validator': <function validate_boolean>}), ('Parse inline `$$ ... $$` (default: False)', ['--myst-dmath-double-inline'], {'dest': 'myst_dmath_double_inline', 'default': UNSET, 'metavar': '<boolean>', 'validator': <function validate_boolean>})), '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'], {'metavar': '<length>', 'type': 'int', 'default': 10000, '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 "http://www.python.org/dev/peps/").', ['--pep-base-url'], {'metavar': '<URL>', 'default': 'http://www.python.org/dev/peps/', 'validator': <function validate_url_trailing_slash>}), ('Template for PEP file part of URL. (default "pep-%04d")', ['--pep-file-url-template'], {'metavar': '<URL>', 'default': 'pep-%04d'}), ('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 "http://tools.ietf.org/html/").', ['--rfc-base-url'], {'metavar': '<URL>', 'default': 'http://tools.ietf.org/html/', 'validator': <function validate_url_trailing_slash>}), ('Set number of spaces for tab expansion (default 8).', ['--tab-width'], {'metavar': '<width>', 'type': 'int', 'default': 8, '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'], {'metavar': '<language:quotes[,language:quotes,...]>', 'action': 'append', '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.
Read#
- class myst_nb.core.read.NbReader(read: Callable[[str], nbf.NotebookNode], md_config: MdParserConfig, read_fmt: dict | None = None)[source]#
A data class for reading a notebook format.
- md_config: MdParserConfig#
The configuration for parsing markdown cells.
- myst_nb.core.read.create_nb_reader(path: str, md_config: MdParserConfig, nb_config: NbParserConfig, content: None | str | Iterator[str]) NbReader | None [source]#
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 [source]#
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) nbf.NotebookNode [source]#
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 [source]#
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: LoggerType, **kwargs: Any)[source]#
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.
- code_cell_outputs(cell_index: int) tuple[int | None, list[NotebookNode]] [source]#
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) NotebookNode | None [source]#
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
a code cell output
- 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()[source]#
Finalise the client.
This is called before final rendering and should be used, for example, to finalise the widget state on the metadata.
- property logger: Union[myst_nb.core.loggers.DocutilsDocLogger, myst_nb.core.loggers.SphinxDocLogger]#
Get the logger.
- property nb_config: myst_nb.core.config.NbParserConfig#
Get the notebook configuration.
- property notebook: nbformat.notebooknode.NotebookNode#
Get the notebook.
- class myst_nb.core.execute.direct.NotebookClientDirect(notebook: NotebookNode, path: Path | None, nb_config: NbParserConfig, logger: LoggerType, **kwargs: Any)[source]#
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: LoggerType, **kwargs: Any)[source]#
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: LoggerType, **kwargs: Any)[source]#
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[source]#
An exception for failed execution and execution_raise_on_error is true.
- exception myst_nb.core.execute.base.EvalNameError[source]#
An exception for if an evaluation variable name is invalid.
Render plugin#
- class myst_nb.core.render.MimeData(mime_type: str, content: str | bytes, cell_metadata: dict[str, Any] = <factory>, output_metadata: dict[str, Any] = <factory>, cell_index: int | None = None, output_index: int | None = None, line: int | None = None, md_headings: bool = False)[source]#
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
- class myst_nb.core.render.NbElementRenderer(renderer: DocutilsNbRenderer | SphinxNbRenderer, logger: LoggerType)[source]#
A class for rendering notebook elements.
- add_js_file(key: str, uri: str | None, kwargs: dict[str, str]) None [source]#
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: myst_nb.core.config.NbParserConfig#
The notebook parser config
- property logger: Union[myst_nb.core.loggers.DocutilsDocLogger, myst_nb.core.loggers.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[nodes.Element] [source]#
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[nodes.Element] [source]#
Render a notebook image mime data output.
- render_image_inline(data: MimeData) list[nodes.Element] [source]#
Render a notebook image mime data output.
- render_javascript(data: MimeData) list[nodes.Element] [source]#
Render a notebook application/javascript mime data output.
- render_javascript_inline(data: MimeData) list[nodes.Element] [source]#
Render a notebook application/javascript mime data output.
- render_markdown(data: MimeData) list[nodes.Element] [source]#
Render a notebook text/markdown mime data output.
- render_markdown_inline(data: MimeData) list[nodes.Element] [source]#
Render a notebook text/markdown mime data output.
- render_mime_type(data: MimeData) list[nodes.Element] [source]#
Render a notebook mime output, as a block level element.
- render_mime_type_inline(data: MimeData) list[nodes.Element] [source]#
Render a notebook mime output, as an inline level element.
- render_raw_cell(content: str, metadata: dict, cell_index: int, source_line: int) list[nodes.Element] [source]#
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[nodes.Element] [source]#
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[nodes.Element] [source]#
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[nodes.Element] [source]#
Render a notebook text/html mime data output.
- render_text_html_inline(data: MimeData) list[nodes.Element] [source]#
Render a notebook text/html mime data output.
- render_text_latex(data: MimeData) list[nodes.Element] [source]#
Render a notebook text/latex mime data output.
- render_text_latex_inline(data: MimeData) list[nodes.Element] [source]#
Render a notebook text/latex mime data output.
- render_text_plain(data: MimeData) list[nodes.Element] [source]#
Render a notebook text/plain mime data output.
- render_text_plain_inline(data: MimeData) list[nodes.Element] [source]#
Render a notebook text/plain mime data output.
- render_unhandled(data: MimeData) list[nodes.Element] [source]#
Render a notebook output of unknown mime type.
- render_unhandled_inline(data: MimeData) list[nodes.Element] [source]#
Render a notebook output of unknown mime type.
- render_widget_view(data: MimeData) list[nodes.Element] [source]#
Render a notebook application/vnd.jupyter.widget-view+json mime output.
- render_widget_view_inline(data: MimeData) list[nodes.Element] [source]#
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 [source]#
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)[source]#
Protocol for a mime renderer plugin.
- class myst_nb.core.render.ExampleMimeRenderPlugin(*args, **kwargs)[source]#
Example mime renderer for custommimetype.
Lexers#
- class myst_nb.core.lexers.AnsiColorLexer(*args, **kwds)[source]#
Bases:
pygments.lexer.RegexLexer
Pygments lexer for text containing ANSI color codes.
Adapted from https://github.com/chriskuehl/pygments-ansi-color
- aliases = ('myst-ansi',)#
Shortcuts for the lexer
- property current_token#
- flags = 24#
Flags for compiling the regular expressions. Defaults to MULTILINE.
- name = 'ANSI Color'#
Name of the lexer
- process(match)[source]#
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:
- tokens = {'root': [('\\x1b\\[([^\\x1b]*)', <function AnsiColorLexer.process>), ('[^\\x1b]+', Token.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. Ifnew_state
is a string, it is pushed on the stack. This ensure the new current state isnew_state
. Ifnew_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 becombined('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: docutils.nodes.document, type_name: str = 'mystnb')[source]#
Bases:
logging.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)[source]#
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: docutils.nodes.document, type_name: str = 'mystnb')[source]#
Bases:
logging.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 thesuppress_warnings
configuration. These are also appended to the end of messages.- process(msg, kwargs)[source]#
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.