myst_parser.mocking

This module provides classes to Mock the core components of the docutils.RSTParser, the key difference being that nested parsing treats the text as Markdown not rST.

1.  Module Contents

1.1.  Classes

MockInliner	A mock version of docutils.parsers.rst.states.Inliner.
MockState	A mock version of docutils.parsers.rst.states.RSTState.
MockStateMachine	A mock version of docutils.parsers.rst.states.RSTStateMachine.
MockIncludeDirective	This directive uses a lot of statemachine logic that is not yet mocked. Therefore, we treat it as a special case (at least for now).
MockRSTParser	RSTParser which avoids a negative side effect.

1.2.  API

exception myst_parser.mocking.MockingError

Bases: Exception

An exception to signal an error during mocking of docutils components.

Initialization

Initialize self. See help(type(self)) for accurate signature.

class myst_parser.mocking.MockInliner(renderer: myst_parser.mdit_to_docutils.base.DocutilsRenderer)

A mock version of docutils.parsers.rst.states.Inliner.

This is parsed to role functions.

Initialization

Initialize the mock inliner.

problematic(text: str, rawsource: str, message: docutils.nodes.system_message) → docutils.nodes.problematic

Record a system message from parsing.

parse(text: str, lineno: int, memo: Any, parent: docutils.nodes.Node) → tuple[list[docutils.nodes.Node], list[docutils.nodes.system_message]]

Parse the text and return a list of nodes.

class myst_parser.mocking.MockState(renderer: myst_parser.mdit_to_docutils.base.DocutilsRenderer, state_machine: myst_parser.mocking.MockStateMachine, lineno: int)

A mock version of docutils.parsers.rst.states.RSTState.

This is parsed to the Directives.run() method, so that they may run nested parses on their content that will be parsed as markdown, rather than RST.

Initialization

parse_directive_block(content: docutils.statemachine.StringList, line_offset: int, directive: type[docutils.parsers.rst.Directive], option_presets: dict) → tuple[list, dict, docutils.statemachine.StringList, int]

Parse the full directive text

Raises:

MarkupError – for errors in parsing the directive

Returns:

(arguments, options, content, content_offset)

nested_parse(block: docutils.statemachine.StringList, input_offset: int, node: docutils.nodes.Element, match_titles: bool = False, state_machine_class=None, state_machine_kwargs=None) → None

Perform a nested parse of the input block, with node as the parent.

Parameters:

• block – The block of lines to parse.

• input_offset – The offset of the first line of block, to the starting line of the state (i.e. directive).

• node – The parent node to attach the parsed content to.

• match_titles – Whether to to allow the parsing of headings (normally this is false, since nested heading would break the document structure)

parse_target(block, block_text, lineno: int)

Taken from docutils-mirror/docutils

inline_text(text: str, lineno: int) → tuple[list[docutils.nodes.Element], list[docutils.nodes.Element]]

Parse text with only inline rules.

Returns:

(list of nodes, list of messages)

attribution_pattern = None

block_quote(lines: list[str], line_offset: int) → list[docutils.nodes.Element]

Parse a block quote, which is a block of text, followed by an (optional) attribution.

No matter where you go, there you are.

-- Buckaroo Banzai

build_table(tabledata, tableline, stub_columns: int = 0, widths=None)

build_table_row(rowdata, tableline)

class myst_parser.mocking.MockStateMachine(renderer: myst_parser.mdit_to_docutils.base.DocutilsRenderer, lineno: int)

A mock version of docutils.parsers.rst.states.RSTStateMachine.

This is parsed to the Directives.run() method.

Initialization

get_source(lineno: int | None = None)

Return document source path.

get_source_and_line(lineno: int | None = None)

Return (source path, line) tuple for current or given line number.

class myst_parser.mocking.MockIncludeDirective(renderer: myst_parser.mdit_to_docutils.base.DocutilsRenderer, name: str, klass: docutils.parsers.rst.directives.misc.Include, arguments: list, options: dict, body: list[str], lineno: int)

This directive uses a lot of statemachine logic that is not yet mocked. Therefore, we treat it as a special case (at least for now).

See: https://docutils.sourceforge.io/docs/ref/rst/directives.html#including-an-external-document-fragment

Initialization

run() → list[docutils.nodes.Element]

add_name(node: docutils.nodes.Element)

Append self.options[‘name’] to node[‘names’] if it exists.

Also normalize the name string and register it as explicit target.

class myst_parser.mocking.MockRSTParser(rfc2822=False, inliner=None)

Bases: docutils.parsers.rst.Parser

RSTParser which avoids a negative side effect.

Initialization

parse(inputstring: str, document: docutils.nodes.document)

Parse the input to populate the document AST.