# visitor URL: /patitas/api/visitor/ Section: api Description: AST Visitor and Transformer for Patitas. Provides a base visitor class with match-based dispatch and an immutable transform function for rewriting frozen ASTs. Example — collect all headings: class HeadingCollector(BaseVisitor[None]): def __init__(self) -> None: self.headings: list[Heading] = [] def visit_heading(self, node: Heading) -> None: self.headings.append(node) collector = HeadingCollector() collector.visit(doc) Example — shift heading levels: def shift_headings(node: Node) -> Node: if isinstance(node, Heading): new_level = min(node.level + 1, 6) return dataclasses.replace(node, level=new_level) return node new_doc = transform(doc, shift_headings) Thread Safety: Visitors are NOT shared across threads by default (they may accumulate mutable state). Create a new visitor per thread. The transform function is pure — safe to call from any thread. --- > For a complete page index, fetch /patitas/llms.txt. Open LLM text (/patitas/api/visitor/index.txt) Share with AI Ask Claude (https://claude.ai/new?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fpatitas%2Fapi%2Fvisitor%2Findex.txt) Ask ChatGPT (https://chatgpt.com/?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fpatitas%2Fapi%2Fvisitor%2Findex.txt) Ask Gemini (https://gemini.google.com/app?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fpatitas%2Fapi%2Fvisitor%2Findex.txt) Ask Copilot (https://copilot.microsoft.com/?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fpatitas%2Fapi%2Fvisitor%2Findex.txt) Module # `visitor` AST Visitor and Transformer for Patitas. Provides a base visitor class with match-based dispatch and an immutable transform function for rewriting frozen ASTs. Example — collect all headings: ``` class HeadingCollector(BaseVisitor[None]): def __init__(self) -> None: self.headings: list[Heading] = [] def visit_heading(self, node: Heading) -> None: self.headings.append(node) collector = HeadingCollector() collector.visit(doc) ``` Example — shift heading levels: ``` def shift_headings(node: Node) -> Node: if isinstance(node, Heading): new_level = min(node.level + 1, 6) return dataclasses.replace(node, level=new_level) return node new_doc = transform(doc, shift_headings) ``` Thread Safety: ``` Visitors are NOT shared across threads by default (they may accumulate mutable state). Create a new visitor per thread. The transform function is pure — safe to call from any thread. ``` 1Class3Functions ## Classes `BaseVisitor` 33 ▼ Base AST visitor with match-based dispatch. Subclass and override ``visit_*`` methods for node typ… Base AST visitor with match-based dispatch. Subclass and override`visit_*`methods for node types you care about. Unhandled node types fall through to`visit_default`. Children are walked automatically after the`visit_*`call. Type parameter`T` is the return type of visit methods (use `None` for side-effect-only visitors). #### Methods `visit` 1 `T` ▼ Dispatch to the appropriate ``visit_*`` method. Walks children automatically a… `def visit(self, node: Node) -> T` Dispatch to the appropriate`visit_*`method. Walks children automatically after the visit method returns. ##### Parameters Name Type Description `node` `—` ##### Returns `T` `visit_default` 1 `T` ▼ Called for node types without a specific ``visit_*`` method. Override this for… `def visit_default(self, node: Node) -> T` Called for node types without a specific`visit_*`method. Override this for catch-all behavior. Default returns None (suitable for`BaseVisitor[None]`). ##### Parameters Name Type Description `node` `—` ##### Returns `T` `visit_document` 1 `T` ▼ `def visit_document(self, node: Document) -> T` ##### Parameters Name Type Description `node` `—` ##### Returns `T` `visit_heading` 1 `T` ▼ `def visit_heading(self, node: Heading) -> T` ##### Parameters Name Type Description `node` `—` ##### Returns `T` `visit_paragraph` 1 `T` ▼ `def visit_paragraph(self, node: Paragraph) -> T` ##### Parameters Name Type Description `node` `—` ##### Returns `T` `visit_fenced_code` 1 `T` ▼ `def visit_fenced_code(self, node: FencedCode) -> T` ##### Parameters Name Type Description `node` `—` ##### Returns `T` `visit_indented_code` 1 `T` ▼ `def visit_indented_code(self, node: IndentedCode) -> T` ##### Parameters Name Type Description `node` `—` ##### Returns `T` `visit_block_quote` 1 `T` ▼ `def visit_block_quote(self, node: BlockQuote) -> T` ##### Parameters Name Type Description `node` `—` ##### Returns `T` `visit_list` 1 `T` ▼ `def visit_list(self, node: List) -> T` ##### Parameters Name Type Description `node` `—` ##### Returns `T` `visit_list_item` 1 `T` ▼ `def visit_list_item(self, node: ListItem) -> T` ##### Parameters Name Type Description `node` `—` ##### Returns `T` `visit_thematic_break` 1 `T` ▼ `def visit_thematic_break(self, node: ThematicBreak) -> T` ##### Parameters Name Type Description `node` `—` ##### Returns `T` `visit_html_block` 1 `T` ▼ `def visit_html_block(self, node: HtmlBlock) -> T` ##### Parameters Name Type Description `node` `—` ##### Returns `T` `visit_directive` 1 `T` ▼ `def visit_directive(self, node: Directive) -> T` ##### Parameters Name Type Description `node` `—` ##### Returns `T` `visit_table` 1 `T` ▼ `def visit_table(self, node: Table) -> T` ##### Parameters Name Type Description `node` `—` ##### Returns `T` `visit_table_row` 1 `T` ▼ `def visit_table_row(self, node: TableRow) -> T` ##### Parameters Name Type Description `node` `—` ##### Returns `T` `visit_table_cell` 1 `T` ▼ `def visit_table_cell(self, node: TableCell) -> T` ##### Parameters Name Type Description `node` `—` ##### Returns `T` `visit_math_block` 1 `T` ▼ `def visit_math_block(self, node: MathBlock) -> T` ##### Parameters Name Type Description `node` `—` ##### Returns `T` `visit_footnote_def` 1 `T` ▼ `def visit_footnote_def(self, node: FootnoteDef) -> T` ##### Parameters Name Type Description `node` `—` ##### Returns `T` `visit_text` 1 `T` ▼ `def visit_text(self, node: Text) -> T` ##### Parameters Name Type Description `node` `—` ##### Returns `T` `visit_emphasis` 1 `T` ▼ `def visit_emphasis(self, node: Emphasis) -> T` ##### Parameters Name Type Description `node` `—` ##### Returns `T` `visit_strong` 1 `T` ▼ `def visit_strong(self, node: Strong) -> T` ##### Parameters Name Type Description `node` `—` ##### Returns `T` `visit_strikethrough` 1 `T` ▼ `def visit_strikethrough(self, node: Strikethrough) -> T` ##### Parameters Name Type Description `node` `—` ##### Returns `T` `visit_link` 1 `T` ▼ `def visit_link(self, node: Link) -> T` ##### Parameters Name Type Description `node` `—` ##### Returns `T` `visit_image` 1 `T` ▼ `def visit_image(self, node: Image) -> T` ##### Parameters Name Type Description `node` `—` ##### Returns `T` `visit_code_span` 1 `T` ▼ `def visit_code_span(self, node: CodeSpan) -> T` ##### Parameters Name Type Description `node` `—` ##### Returns `T` `visit_line_break` 1 `T` ▼ `def visit_line_break(self, node: LineBreak) -> T` ##### Parameters Name Type Description `node` `—` ##### Returns `T` `visit_soft_break` 1 `T` ▼ `def visit_soft_break(self, node: SoftBreak) -> T` ##### Parameters Name Type Description `node` `—` ##### Returns `T` `visit_html_inline` 1 `T` ▼ `def visit_html_inline(self, node: HtmlInline) -> T` ##### Parameters Name Type Description `node` `—` ##### Returns `T` `visit_role` 1 `T` ▼ `def visit_role(self, node: Role) -> T` ##### Parameters Name Type Description `node` `—` ##### Returns `T` `visit_math` 1 `T` ▼ `def visit_math(self, node: Math) -> T` ##### Parameters Name Type Description `node` `—` ##### Returns `T` `visit_footnote_ref` 1 `T` ▼ `def visit_footnote_ref(self, node: FootnoteRef) -> T` ##### Parameters Name Type Description `node` `—` ##### Returns `T` Internal Methods 2 ▼ `_dispatch` 1 `T` ▼ Match-based dispatch to visit_* methods. `def _dispatch(self, node: Node) -> T` ##### Parameters Name Type Description `node` `—` ##### Returns `T` `_walk_children` 1 ▼ Recursively visit child nodes. `def _walk_children(self, node: Node) -> None` ##### Parameters Name Type Description `node` `—` ## Functions `transform` 2 `Document (/patitas/api/nodes/#Document)` ▼ Apply a function to every node in the AST, returning a new tree. The function … `def transform(doc: Document, fn: Callable[[Node], Node | None]) -> Document` Apply a function to every node in the AST, returning a new tree. The function`fn`is called bottom-up: children are transformed first, then the parent is transformed with its new children. This ensures`fn` always receives nodes with already-transformed children. Return`None` from `fn`to remove a node from the tree. The root Document cannot be removed; returning None for it raises TypeError. Since all nodes are frozen dataclasses, this produces a new immutable tree. The original tree is untouched. ##### Parameters Name Type Description `doc` `Document (/patitas/api/nodes/#Document)` The document to transform. `fn` `Callable[[Node (/patitas/api/nodes/#Node)], Node (/patitas/api/nodes/#Node) | None]` Function that receives a node and returns a (possibly new) node, or None to remove the node from the tree. ##### Returns `Document (/patitas/api/nodes/#Document)` `_transform_node` 2 `Node (/patitas/api/nodes/#Node) | None` ▼ Transform a single node bottom-up: children first, then self. `def _transform_node(node: Node, fn: Callable[[Node], Node | None]) -> Node | None` ##### Parameters Name Type Description `node` `Node (/patitas/api/nodes/#Node)` `fn` `Callable[[Node (/patitas/api/nodes/#Node)], Node (/patitas/api/nodes/#Node) | None]` ##### Returns `Node (/patitas/api/nodes/#Node) | None` `_transform_children` 2 `Node (/patitas/api/nodes/#Node)` ▼ Produce a new node with children transformed; filter out None (removed) nodes. `def _transform_children(node: Node, fn: Callable[[Node], Node | None]) -> Node` Produce a new node with children transformed; filter out None (removed) nodes. ##### Parameters Name Type Description `node` `Node (/patitas/api/nodes/#Node)` `fn` `Callable[[Node (/patitas/api/nodes/#Node)], Node (/patitas/api/nodes/#Node) | None]` ##### Returns `Node (/patitas/api/nodes/#Node)`