Main API#

class wenmode.Wenmode(rules=None, renderer=None, directives=(), plugins=(), positions=False)#

Convenience facade that combines a parser and a renderer.

Wenmode is the main high-level API for applications. It parses Markdown with a configured rule set and renders the resulting node tree with a renderer.

Parameters:

  • rules (Iterable[type[Rule] | Rule] | None) – Rule classes or configured rule instances. When omitted, the CommonMark-style preset is used.

  • renderer (BaseRenderer | None) – Renderer instance used by render() and render_node(). When omitted, HTMLRenderer is used.

  • directives (Iterable[DirectiveHtmlRenderer]) – HTML directive renderers to register on the default or supplied HTML renderer.

  • plugins (Iterable[PluginModule | ModuleType]) – Plugin modules or plugin objects to install during initialization.

  • positions (bool) – Attach source positions to parsed nodes when True.

parse(source)#

Parse Markdown into a root node.

Parameters:

source (str | Iterable[str]) – Markdown source as a string or an iterable of lines.

Returns:

Parsed document root.

Return type:

Root

render(source)#

Parse Markdown and render it with the configured renderer.

Parameters:

source (str | Iterable[str]) – Markdown source as a string or an iterable of lines.

Returns:

Rendered output.

Return type:

str

render_node(node)#

Render an existing AST node.

Parameters:

node (Node) – Node to render.

Returns:

Rendered output.

Return type:

str

stream(source)#

Yield rendered chunks while parsing Markdown incrementally.

Streaming is only supported when the parser has no document-wide transforms and the renderer has no required root hooks.

Parameters:

source (str | Iterable[str]) – Markdown source as a string or an iterable of lines.

Returns:

Iterator of rendered chunks.

Raises:

wenmode.StreamingUnsupportedError – Raised on first iteration when parser transforms or renderer root hooks require a complete root.

Return type:

Iterator[str]

register_rule(rule)#

Register or replace one parser rule.

Parameters:

rule (type[Rule] | Rule) – Rule class or configured rule instance.

register_rules(rules)#

Register or replace multiple parser rules.

Parameters:

rules (Iterable[type[Rule] | Rule]) – Rule classes or configured rule instances.

register_renderer_handlers(handlers)#

Register renderer handlers for the configured renderer.

The mapping is keyed by renderer name, then node type. Handlers for other renderer names are ignored.

register_directive_renderer(directive)#

Register an HTML directive renderer.

Parameters:

directive (DirectiveHtmlRenderer) – Directive renderer implementing DirectiveHtmlRenderer.

Raises:

TypeError – If this Wenmode instance does not use an HTMLRenderer.

property supports_streaming: bool#

Return whether the configured parser and renderer can stream.

streaming_blockers()#

Return transform and root hook labels that prevent streaming output.

use(plugin)#

Install a plugin module or plugin object on this parser and renderer.

class wenmode.Parser(rules, positions=False)#

Parse Markdown into Wenmode nodes with an explicit rule set.

Parser instances are reusable. Per-document state such as reference definitions, footnotes, abbreviation definitions, and deferred inline queues is created for each parse.

Parameters:

  • rules (Iterable[type[Rule] | Rule]) – Rule classes or configured rule instances to enable.

  • positions (bool) – Attach source positions to parsed nodes when True.

property supports_streaming: bool#

Return whether this parser can yield nodes incrementally.

streaming_blockers()#

Return document-wide transform names that prevent streaming output.

register_rule(rule)#

Register or replace one rule by name.

Parameters:

rule (type[Rule] | Rule) – Rule class or configured rule instance.

register_rules(rules)#

Register or replace multiple rules by name.

Parameters:

rules (Iterable[type[Rule] | Rule]) – Rule classes or configured rule instances.

parse(source)#

Parse Markdown into a root node.

Parameters:

source (str | Iterable[str]) – Markdown source as a string or an iterable of lines.

Returns:

Parsed document root.

Return type:

Root

parse_iter(source)#

Yield top-level block nodes as they are parsed.

This API is intended for streaming renderers and rejects rule sets with parser transforms that cannot stream. With positions=True, yielded nodes store source offsets, but they do not have root-level line-start context; calling to_ast() on them emits offset-only positions.

Parameters:

source (str | Iterable[str]) – Markdown source as a string or an iterable of lines.

Returns:

Iterator of parsed block nodes.

Raises:

StreamingUnsupportedError – If enabled rules require parser transforms that cannot stream.

Return type:

Iterator[Node]

parse_blocks(text, parent_state, source=None)#

Parse nested block content using a parent parse state.

Custom block rules should use this helper for nested Markdown content so extension state and deferred inline queues are shared with the enclosing parse. This helper centrally enforces max_container_depth; at the boundary it returns shallow paragraph content instead of recursively running block rules again.

Parameters:

  • text (str) – Markdown block content.

  • parent_state (BlockState) – Current block state from the outer parse.

  • source (SourceMap | None) – Optional source map for text when positions are enabled.

Returns:

Parsed child nodes.

Return type:

list[Node]

parse_inlines(text, state, source=None)#

Parse inline Markdown into child nodes.

Custom inline, block, and continuation rules can call this method when they need nested inline parsing.

Parameters:

  • text (str) – Inline Markdown source.

  • state (BlockState) – Current block state used for extension state, deferred inline queues, and active inline source maps.

  • source (SourceMap | None) – Optional source map for text when positions are enabled.

Returns:

Parsed inline nodes.

Return type:

list[Node]

is_paragraph_interrupt(line, state=None)#

Return whether a line would interrupt a paragraph.

Custom block parsing code can use this helper to mirror the parser’s paragraph-interruption behavior.

Parameters:

  • line (str) – Candidate source line.

  • state (BlockState | None) – Current block state, if available.

Returns:

True if the line starts an interrupting block.

Return type:

bool

inline_source(text, state, start, end)#

Return a source map for a slice of the state’s active inline source.

class wenmode.StreamingUnsupportedError#

Raised when a rule set or renderer cannot be used for streaming output.