Coverage for src/renaissance/integrations/python/ast/factory.py: 98%
116 statements
« prev ^ index » next coverage.py v7.17.0, created at 2026-11-16 16:04 +0000
« prev ^ index » next coverage.py v7.17.0, created at 2026-11-16 16:04 +0000
1# Copyright (C) 2024-2026 TNO
2#
3# Licensed under the terms specified in the LICENSE file in the root directory
4# of this repository, also available at:
5# https://github.com/TNO/Renaissance.Py/blob/main/LICENSE
7"""AI: Factories for creating Python AST/pattern nodes for parsing and pattern matching."""
9import ast
10import re
11from collections.abc import Sequence
12from pathlib import Path
14import tree_sitter_python
15from libcst import SimpleStatementLine
17from renaissance.integrations import MATCH_ALL, MATCH_ONE
18from renaissance.integrations.python.ast.ast_node import ASTExtension
19from renaissance.integrations.python.ast.cst_node import PythonCstNode
20from renaissance.integrations.python.ast.rst_node import PythonRstNode
21from renaissance.integrations.tree_sitter.adapter import TreeSitterAdapter
22from renaissance.integrations.tree_sitter.lst import LSTNode
23from renaissance.syntax_tree.match_finder import is_match
24from renaissance.syntax_tree.node_protocol import NodeProtocol
25from renaissance.syntax_tree.pattern_kind import PatternKind
26from renaissance.syntax_tree.semantic_kind import SemanticKind
27from renaissance.utils.ast_utils import replace_dollar, use_dollar
29_MATCH_ALL_RE = re.compile(r"^" + re.escape(MATCH_ALL) + r"\w+$")
30_MATCH_ONE_RE = re.compile(r"^" + re.escape(MATCH_ONE) + r"\w+$")
32# TODO(FrancescoPezzella): a placeholder outside these kinds silently becomes a text match.
33# https://github.com/TNO/Renaissance.Py/issues/387
34_PLACEHOLDER_PARSER_KINDS = frozenset({"Name", "Expr", "arg", "Param", "TypeVar", "ParamSpec", "TypeVarTuple"})
37class PythonPattern:
38 """AI: Wrap a Python AST/RST node as a matchable pattern, detecting match-all/match-one placeholders."""
40 def __init__(self, node, parent: PythonPattern | None = None) -> None:
41 """AI: Wrap a Python AST/RST node as a matchable pattern, detecting match-all/match-one placeholders."""
42 self.node: PythonRstNode = node
43 self.parent = parent
44 if type(node) is str:
45 print(node)
46 return
47 self.parser_kind = getattr(node, "parser_kind", type(node).__name__)
48 self.semantic_kind = getattr(node, "semantic_kind", SemanticKind.NODE)
49 self.pattern_kind = None
50 self._derive_pattern_kind(node)
52 self.properties: dict = node.properties
53 self.children: list[PythonPattern] = [PythonPattern(child, self) for child in node.children]
54 self.signature: str = node.signature
55 if hasattr(node, "name") and node.name:
56 self.name: str = use_dollar(node.name)
57 else:
58 self.name = ""
60 def __eq__(self, other: NodeProtocol) -> bool:
61 """AI: Return whether `other` matches this pattern node."""
62 return is_match(other, self)
64 def __repr__(self) -> str:
65 """AI: Return a dollar-escaped repr of the wrapped node."""
66 return use_dollar(str(self.node))
68 def _derive_pattern_kind(self, node) -> None:
69 """Set pattern_kind to MATCH_ONE or MATCH_ALL when node is a `$x` or `$$x` placeholder, including a type parameter."""
70 if isinstance(node, ast.arg):
71 signature = node.arg
72 elif isinstance(node, ast.Name):
73 signature = node.id
74 elif isinstance(node, ast.Expr) and isinstance(node.value, ast.Name):
75 signature = node.value.id
76 elif isinstance(node, ast.AST):
77 signature = str(node)
78 else:
79 signature = node.name
81 if node.parser_kind in _PLACEHOLDER_PARSER_KINDS:
82 if _MATCH_ALL_RE.match(signature):
83 self.pattern_kind = PatternKind.MATCH_ALL
84 elif _MATCH_ONE_RE.match(signature):
85 self.pattern_kind = PatternKind.MATCH_ONE
88class PythonFactory:
89 """AI: Factory for creating Python AST nodes of a configured node-implementation type."""
91 def __init__(self, clazz: type[PythonRstNode | PythonCstNode | LSTNode | ast.AST]) -> None:
92 """AI: Configure a factory that creates Python AST nodes of the given node-implementation type."""
93 self.clazz = clazz
94 if clazz == LSTNode:
95 clazz.load_from_text = self.load_from_lst
96 elif clazz == ast.AST:
97 clazz.load_from_text = ASTExtension.load_from_ast
98 # matcher
99 clazz.node = ASTExtension.ast_node
100 clazz.parser_kind = ASTExtension.parser_kind
101 clazz.semantic_kind = ASTExtension.semantic_kind
102 clazz.properties = ASTExtension.ast_properties
103 clazz.children = ASTExtension.ast_children
104 clazz.signature = ASTExtension.ast_signature
106 # writer
107 clazz.text = ASTExtension.ast_signature
108 clazz.filename = "dummy.py"
110 # shower
111 clazz.is_implicit = True
112 clazz.show_props = False
113 clazz.indent = ""
115 def create(self, file_path: Path) -> PythonRstNode | PythonCstNode:
116 """AI: Parse the Python source file at file_path into an AST node tree."""
117 atu = self.clazz.load(file_path=file_path)
118 assert isinstance(atu, self.clazz)
119 return atu
121 def create_from_text(self, text: str, file_name: str = "snippet.py") -> PythonRstNode | PythonCstNode | LSTNode | ast.AST:
122 """AI: Parse Python source text (attributed to file_name) into an AST node tree."""
123 atu = self.clazz.load_from_text(text, file_name)
124 assert isinstance(atu, self.clazz)
125 return atu
127 @staticmethod
128 def load_from_lst(text: str, _file_name: str) -> LSTNode:
129 """AI: Parse Python source text with tree-sitter into an LST node tree."""
130 adapter = TreeSitterAdapter(tree_sitter_python)
131 tree = adapter.parse_code(text)
132 return adapter.to_lst(text, tree).root
135class PythonPatternFactory:
136 """AI: Factory for building Python AST patterns from text."""
138 def __init__(self, factory: PythonFactory) -> None:
139 """AI: Prepare a pattern factory for creating Python AST patterns from text."""
140 self.factory = factory
142 def _create(self, text: str) -> PythonPattern:
143 return PythonPattern(self.factory.create_from_text(text, "pattern.py"))
145 def create(self, text: str) -> PythonPattern:
146 """AI: Parse text as a Python pattern, substituting placeholder dollar syntax first."""
147 text = replace_dollar(text)
148 return self._create(text)
150 def create_statements(self, text: str) -> Sequence[PythonPattern]:
151 """AI: Parse text and return its top-level statement pattern nodes."""
152 atu = self.create(text)
153 return atu.children
155 def create_statement(self, text: str) -> PythonPattern:
156 """AI: Parse text and return its last top-level statement pattern node."""
157 stmt = self.create_statements(text)[-1]
158 if isinstance(stmt.node.node, SimpleStatementLine):
159 return stmt.children[0]
160 return stmt
161 # return stmt
163 def create_expression(self, text: str) -> PythonPattern:
164 """AI: Parse text and return the expression pattern node of its last statement."""
165 my_pattern = self.create_statement(text)
166 if isinstance(my_pattern.node, PythonRstNode):
167 return PythonPattern(my_pattern.node.expression)
168 if isinstance(my_pattern.node, (LSTNode, PythonCstNode)):
169 return PythonPattern(my_pattern.node.children[-1])
170 return PythonPattern(my_pattern.node.children[0])
172 def create_decorators(self, param):
173 """AI: Parse param as a decorator applied to a dummy test function and return the decorator pattern node."""
174 return self.create_statement(param + "\ndef test(): pass").children[2]
176 @staticmethod
177 def create_kwargs(kw_str) -> Sequence[PythonPattern]:
178 """AI: Parse kw_str as call keyword arguments and return their pattern nodes."""
179 call = ast.parse(f"fun({replace_dollar(kw_str)})", "kwarg_pattern.py").body[0].value
180 return [PythonPattern(PythonRstNode(kwarg)) for kwarg in call.keywords]