Helper Modules#

AST Helpers#

wenmode.ast.UnknownNodePolicy#

alias of str

wenmode.ast.find(node, type=None, *, predicate=None, include_self=True)#

Return the first matching node in depth-first order.

type may be a node type string, a node class, a tuple of strings or classes, or None to match every node.

wenmode.ast.find_all(node, type=None, *, predicate=None, include_self=True)#

Return all matching nodes in depth-first order.

type may be a node type string, a node class, a tuple of strings or classes, or None to match every node.

wenmode.ast.from_ast(data, *, nodes=None, unknown='generic', allow_internal_metadata=False, max_depth=100, max_nodes=100000)#

Convert a mdast-like mapping into Wenmode nodes.

Pass plugin node classes with nodes. Unknown node types are preserved as generic nodes by default; use unknown="error" to reject them.

Restoration validates structure, applies depth and node-count limits, and only preserves internal metadata when allow_internal_metadata=True.

wenmode.ast.iter_children(node)#

Yield direct child nodes from a node.

The helper follows the mdast-style children field used by Wenmode’s parent nodes and by plugin nodes that follow the same convention.

wenmode.ast.plain_text(value, *, block_separator='\n')#

Return the concatenated plain text content of a node or node sequence.

Images contribute their alt text, literal nodes contribute value, parent nodes contribute their children’s text, and reference-like leaf nodes fall back to label or identifier fields. Block-level sibling nodes are separated with block_separator.

wenmode.ast.walk(node, *, include_self=True)#

Yield nodes in depth-first, pre-order traversal.

Parameters:

  • node (Node) – Root or subtree to traverse.

  • include_self (bool) – Yield node before its descendants when True.

Returns:

Iterator over nodes.

Return type:

Iterator[Node]

Presets#

wenmode.presets.create_preset(base, *, prepend=(), remove=(), replace=(), append=())#

Create a derived preset from an existing rule list.

Rules are matched by their stable name. Replacement rules keep the position of the rule they replace. Use append for rules that are not present in the base preset.

Heading Helpers#

class wenmode.headings.Slugger#

Generate unique slug IDs for headings.

slug(value)#

Return a unique slug for a heading title.

use(value)#

Mark an existing slug as already used.

class wenmode.headings.HeadingIdTransform(slugger_factory=<class 'wenmode.headings.Slugger'>)#

Node transform that adds generated IDs to heading nodes.

Parameters:

slugger_factory (type[Slugger]) – Slugger class used to generate heading IDs.

transform(parser, node, state)#

Mutate the supplied node in place.

wenmode.headings.add_heading_ids(node, *, slugger, min_depth=1, max_depth=6, overwrite=False)#

Add generated IDs to heading nodes in a tree.

Existing heading IDs are preserved unless overwrite is True.

Parameters:

  • node (Node) – Root or subtree to update.

  • slugger (Slugger) – Slug generator used to create unique IDs.

  • min_depth (int) – Minimum heading depth to update.

  • max_depth (int) – Maximum heading depth to update.

  • overwrite (bool) – Whether to replace existing heading IDs.

wenmode.headings.iter_headings(node)#

Return all heading nodes under a node.

wenmode.headings.slugify(value)#

Convert text into a URL-friendly slug.

Table of Contents Helpers#

class wenmode.toc.TocItem(id, title, depth, children=<factory>)#

One table-of-contents entry.

wenmode.toc.collect_toc(node, *, min_depth=1, max_depth=6)#

Collect heading nodes with IDs into a nested table of contents.

Parameters:

  • node (Node) – Root or subtree to inspect.

  • min_depth (int) – Minimum heading depth to include.

  • max_depth (int) – Maximum heading depth to include.

Returns:

Nested table-of-contents items.

Return type:

list[TocItem]

wenmode.toc.render_toc_html(items, *, label='Table of contents')#

Render table-of-contents items as an HTML nav element.

Parameters:

  • items (list[TocItem]) – Items returned by collect_toc().

  • label (str) – Accessible label for the navigation element.

Returns:

HTML string, or an empty string when items is empty.

Return type:

str

wenmode.toc.render_toc_list(items)#

Render table-of-contents items as a nested ordered list.

Extension State#

Public parser-state compatibility facade.

class wenmode.state.BlockState(lines, index=0, source=<factory>, store=<factory>, depth=0, defer_inlines=False, _deferred=<factory>)#

Mutable state for one block parse.

Custom block and continuation rules receive this object and should advance it when they consume input.

Parameters:

  • lines (list[str]) – Source lines for this block parse.

  • index (int) – Current line index.

  • store (StateStore) – Per-parse extension state store.

  • depth (int) – Container nesting depth.

  • defer_inlines (bool) – Whether inline parsing is currently deferred.

property done: bool#

Whether the state has consumed all available lines.

property line: str#

Current source line.

advance(count=1)#

Advance the current line index.

Parameters:

count (int) – Number of lines to consume.

consume_until(is_closer, transform=None)#

Consume lines through an optional closing line.

The closing line is consumed but not returned.

has(offset=0)#

Return whether a line exists at an offset from the current index.

peek(offset=0)#

Return a line at an offset from the current index.

has_index(index)#

Return whether an absolute line index is available.

line_at(index)#

Return a line by absolute index.

defer_inline_parse(nodes, text, source)#

Queue an inline parse target until document-wide state is ready.

take_pending_inlines()#

Remove and return queued inline parse targets.

defer_inline_callback(callback)#

Queue a callback to run after deferred inline parsing resolves.

take_pending_inline_callbacks()#

Remove and return deferred inline callbacks.

push_inline_source(source)#

Push an active inline source map.

pop_inline_source()#

Pop the active inline source map.

inline_source_for(text)#

Return the innermost active inline source matching text.

class wenmode.state.NullSourceCollector#

No-op source collector used when positions are disabled.

class wenmode.state.NullSourceTracker#

Source tracker used when positions are disabled.

bind(state)#

Bind this tracker to a block state.

class wenmode.state.PositionSourceCollector(tracker)#

Source collector backed by a position-aware tracker.

add(index, offset, text)#

Add text that originated at index and offset.

map()#

Return the collected source map, if source tracking is enabled.

class wenmode.state.PositionSourceTracker(line_offsets)#

Source tracker that maps generated parser text to source positions.

bind(state)#

Bind this tracker to a block state.

class wenmode.state.SourceCollector#

Collect source spans for generated nested parser text.

add(index, offset, text)#

Add text that originated at index and offset.

map()#

Return the collected source map, if source tracking is enabled.

class wenmode.state.SourceMap(text, segments)#

Map parser text offsets back to source offsets.

class wenmode.state.SourceSegment(start, end, offset)#

Map a contiguous slice of generated parser text to source offsets.

class wenmode.state.StreamPositionSourceTracker(line_buffer)#

Position tracker backed by a compactable stream line buffer.

class wenmode.state.StateKey(name, factory)#

Typed key for per-parse extension state.

Rules and transforms should use StateKey instead of storing mutable per-document data on rule instances.

Parameters:

  • name (str) – Unique key name. Use a package-qualified name to avoid collisions.

  • factory (Callable[[], T]) – Callable that creates the initial value for each parse.

class wenmode.state.StateStore#

Per-parse storage for extension state.

get(key)#

Return the value for a key, creating it if necessary.

Parameters:

key (StateKey[T]) – State key to read.

Returns:

Stored value for this parse.

Return type:

T

set(key, value)#

Store a value for a key in this parse.

class wenmode.state.StreamBlockState(line_buffer, index=0, source=None, store=None, depth=0, defer_inlines=False, deferred=None)#

Block state backed by a lazy StreamLineBuffer.

property done: bool#

Whether the state has consumed all available lines.

property line: str#

Current source line.

has(offset=0)#

Return whether a line exists at an offset from the current index.

peek(offset=0)#

Return a line at an offset from the current index.

has_index(index)#

Return whether an absolute line index is available.

line_at(index)#

Return a line by absolute index.

discard_consumed()#

Release buffered lines before the current absolute state index.

class wenmode.state.StreamLineBuffer(source, track_positions=False)#

Lazy line buffer for iterable Markdown sources.

property start_index: int#

Absolute index of the first buffered line.

property end_index: int#

Absolute index immediately after the buffered line window.

has(index)#

Return whether a line index can be read.

get(index)#

Return a buffered line by absolute index.

offset_at_index(index)#

Return the absolute source offset for a buffered line boundary.

discard_before(index)#

Discard buffered lines strictly before an absolute boundary.