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

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 

6 

7"""AI: Factories for creating Python AST/pattern nodes for parsing and pattern matching.""" 

8 

9import ast 

10import re 

11from collections.abc import Sequence 

12from pathlib import Path 

13 

14import tree_sitter_python 

15from libcst import SimpleStatementLine 

16 

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 

28 

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+$") 

31 

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"}) 

35 

36 

37class PythonPattern: 

38 """AI: Wrap a Python AST/RST node as a matchable pattern, detecting match-all/match-one placeholders.""" 

39 

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) 

51 

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 = "" 

59 

60 def __eq__(self, other: NodeProtocol) -> bool: 

61 """AI: Return whether `other` matches this pattern node.""" 

62 return is_match(other, self) 

63 

64 def __repr__(self) -> str: 

65 """AI: Return a dollar-escaped repr of the wrapped node.""" 

66 return use_dollar(str(self.node)) 

67 

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 

80 

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 

86 

87 

88class PythonFactory: 

89 """AI: Factory for creating Python AST nodes of a configured node-implementation type.""" 

90 

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 

105 

106 # writer 

107 clazz.text = ASTExtension.ast_signature 

108 clazz.filename = "dummy.py" 

109 

110 # shower 

111 clazz.is_implicit = True 

112 clazz.show_props = False 

113 clazz.indent = "" 

114 

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 

120 

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 

126 

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 

133 

134 

135class PythonPatternFactory: 

136 """AI: Factory for building Python AST patterns from text.""" 

137 

138 def __init__(self, factory: PythonFactory) -> None: 

139 """AI: Prepare a pattern factory for creating Python AST patterns from text.""" 

140 self.factory = factory 

141 

142 def _create(self, text: str) -> PythonPattern: 

143 return PythonPattern(self.factory.create_from_text(text, "pattern.py")) 

144 

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) 

149 

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 

154 

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 

162 

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]) 

171 

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] 

175 

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]