readers: Format Readers (source text -> typed Doc)#

base defines the Reader protocol/registry and the shared markdown engine builder; myst and gfm are the launch readers, both thin declarations over the markdown pipeline. The optional wikitext frontend delegates translation to wikiparse before reusing the MyST reader; the heavy dependency is imported only when a wikitext read is requested. Importing this package registers all readers.

Format Readers (source text -> typed Doc).

base defines the Reader protocol/registry and the shared markdown engine builder; myst and gfm are the launch readers, both thin declarations over the markdown pipeline. The optional wikitext frontend delegates translation to wikiparse before reusing the MyST reader; the heavy dependency is imported only when a wikitext read is requested. Importing this package registers all readers.

class myform.readers.GfmReader#

Reader for GitHub-Flavored Markdown (the mdformat gfm extension stack).

name: ClassVar[str] = 'gfm'#

The format name this reader handles (set by concrete subclasses).

extensions: ClassVar[tuple[str, ...]] = ('myform_gfm', 'footnote')#

The mdformat parser-extension names this reader’s engine enables.

class myform.readers.MarkdownReader#

Shared base for markdown-pipeline readers (MyST, GFM): engine, tokens, bridge.

extensions: ClassVar[tuple[str, ...]] = ()#

The mdformat parser-extension names this reader’s engine enables.

tokenize(text: str, options: Mapping[str, Any] | None = None) → tuple[list[Token], dict[str, Any]]#

Parse text to its raw token stream and parse environment.

Exposed separately from read so the bridge’s round-trip property can be tested against the exact streams this reader produces.

Parameters:

  • text – The markdown source.

  • options – mdformat options, as mdformat.text takes them.

Returns:

The block-level token stream and the parse environment it populated (link-reference definitions and similar document-level state live in the latter).

read(text: str, options: Mapping[str, Any] | None = None) → Doc#

Parse text into a typed Doc, snapshotting the parse environment onto it.

class myform.readers.MystReader#

Reader for MyST markdown (the mdformat myst extension stack).

name: ClassVar[str] = 'myst'#

The format name this reader handles (set by concrete subclasses).

extensions: ClassVar[tuple[str, ...]] = ('myst',)#

The mdformat parser-extension names this reader’s engine enables.

class myform.readers.ObsidianReader#

Reader for Obsidian-flavored Markdown (GFM + footnotes + properties + the dialect).

name: ClassVar[str] = 'obsidian'#

The format name this reader handles (set by concrete subclasses).

extensions: ClassVar[tuple[str, ...]] = ('gfm', 'footnote', 'front_matters', 'obsidian')#

the base stacks register first so the obsidian rules can be inserted relative to rules that already exist (the wikilink rule must precede the built-in link).

Type:

Order matters

tokenize(text: str, options: Mapping[str, Any] | None = None) → tuple[list[Token], dict[str, Any]]#

Refuse a foreign registry owner only when the built-in reader is used.

class myform.readers.PlaneReader#

Reader for Plane’s Tiptap description_html (direct tag-tree walk).

name: ClassVar[str] = 'plane'#

The format name this reader handles (set by concrete subclasses).

read(text: str, options: Mapping[str, Any] | None = None) → Doc#

Parse text (a description_html payload) into a typed Doc.

Parameters:

  • text – The stored description_html string.

  • options – Unused; the dialect has no reader-tunable knobs today.

Returns:

The typed document tree.

class myform.readers.Reader#

The reader seam: parse one source format into a typed Doc.

REGISTRY: ClassVar[dict[str, Reader]] = {'gfm': <myform.readers.gfm.GfmReader object>, 'myst': <myform.readers.myst.MystReader object>, 'obsidian': <myform.readers.obsidian.ObsidianReader object>, 'plane': <myform.readers.plane.PlaneReader object>, 'rst': <myform.readers.rst.RstReader object>, 'typst': <myform.readers.typst.TypstReader object>, 'wikitext': <myform.readers.wikitext.WikitextReader object>}#

Format name -> ready-to-use reader instance; populated by register.

name: ClassVar[str] = ''#

The format name this reader handles (set by concrete subclasses).

classmethod register(reader_cls: type[R]) → type[R]#

Class decorator registering a concrete reader under its name.

classmethod get(name: str) → Reader#

Resolve a registered reader by format name (raising helpfully when unknown).

read(text: str, options: Mapping[str, Any] | None = None) → Doc#

Parse text into a typed Doc (concrete readers implement this).

class myform.readers.RstReader#

Map a Sphinx-flavored reStructuredText document into the absolute document tree.

name: ClassVar[str] = 'rst'#

The format name this reader handles (set by concrete subclasses).

read(text: str, options: Mapping[str, Any] | None = None) → Doc#

Parse one rST document through docutils and map its resolved doctree.

class myform.readers.TypstReader#

Map the lossless Typst CST into the absolute document tree without evaluation.

name: ClassVar[str] = 'typst'#

The format name this reader handles (set by concrete subclasses).

read(text: str, options: Mapping[str, Any] | None = None) → Doc#

Read one Typst document and retain bridge diagnostics in its environment snapshot.

class myform.readers.WikitextReader#

Translate wikitext through wikiparse and the existing MyST reader.

name: ClassVar[str] = 'wikitext'#

The format name this reader handles (set by concrete subclasses).

read(text: str, options: Mapping[str, Any] | None = None) → Doc#

Read one wikitext article without hiding upstream translation loss.

Parameters:

  • text – Raw MediaWiki wikitext for one article.

  • options – Reader options. title is forwarded exactly to wikiparse; remaining options are forwarded to the MyST reader.

Returns:

The MyST-derived document with wikitext source and article provenance.

Raises:

  • TypeError – An explicit title or the installed wikiparse API has the wrong type.

  • ValueError – An explicit title is blank.

  • RuntimeError – The optional package or Pandoc executable is unavailable.

myform.readers.build_engine(extensions: tuple[str, ...], options: Mapping[str, Any] | None = None) → MarkdownIt#

Build the exact engine mdformat.text builds for the given extension set.

Delegates to mdformat’s own build_mdit with the MDRenderer class and the same mdformat_opts shape (user options plus a blank filename), so every registered plugin – including this package’s myst entry point – configures the engine identically to the mdformat plugin path. This sharing is what makes convert(text, f, f) a byte-for-byte fixed point of today’s formatter.

Parameters:

  • extensions – The mdformat parser-extension names to enable (e.g. ('myst',)).

  • options – mdformat options (e.g. {'number': True}), as mdformat.text takes them.

Returns:

A configured MarkdownIt engine whose renderer is mdformat’s MDRenderer.