@allansantos-dev/smart-tool 0.9.57 → 0.9.65

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/doc_cli.py ADDED
@@ -0,0 +1,239 @@
1
+ """Command-line interfaces the Python code declares with argparse and the functions its `__main__` blocks run, read
2
+ from the syntax tree without running anything."""
3
+ import ast
4
+ import posixpath
5
+
6
+ _GROUPS = ("add_argument_group", "add_mutually_exclusive_group")
7
+
8
+
9
+ def _constant(node, bound):
10
+ if isinstance(node, ast.Constant):
11
+ return node.value
12
+ if isinstance(node, ast.Name):
13
+ return bound.get(node.id)
14
+ return None
15
+
16
+
17
+ def _text(node, bound):
18
+ """Text of a help or description argument: the literal, an f-string with its holes as {expression}, or the source
19
+ of any other expression in backticks."""
20
+ value = _constant(node, bound)
21
+ if isinstance(value, str):
22
+ return value
23
+ if isinstance(node, ast.JoinedStr):
24
+ return "".join(p.value if isinstance(p, ast.Constant) else "{" + ast.unparse(p.value) + "}" for p in node.values)
25
+ return f"`{ast.unparse(node)}`"
26
+
27
+
28
+ class _Scope:
29
+ """argparse objects of one function body (or of the module's top level), followed statement by statement."""
30
+
31
+ def __init__(self, path, function, found):
32
+ self.path, self.function, self.found = path, function, found
33
+ self.names, self.bound, self.definition = {}, {}, None
34
+
35
+ def _define(self, line, shared=False):
36
+ self.definition = {"path": self.path, "function": self.function, "line": line, "shared": shared, "commands": {}}
37
+ self.found.append(self.definition)
38
+ return self.definition
39
+
40
+ def _command(self, definition, words, help_text, line):
41
+ return definition["commands"].setdefault(words, {"words": list(words), "help": help_text, "line": line,
42
+ "arguments": []})
43
+
44
+ def call(self, node):
45
+ """The argparse handle an expression yields: (kind, definition, words) or None."""
46
+ if isinstance(node, ast.Name):
47
+ return self.names.get(node.id)
48
+ if not isinstance(node, ast.Call):
49
+ return None
50
+ func = node.func
51
+ method = func.attr if isinstance(func, ast.Attribute) else func.id if isinstance(func, ast.Name) else None
52
+ keywords = {k.arg: k.value for k in node.keywords if k.arg}
53
+ if method == "ArgumentParser":
54
+ definition = self._define(node.lineno)
55
+ described = keywords.get("description")
56
+ self._command(definition, (), _text(described, self.bound) if described is not None else "", node.lineno)
57
+ return ("parser", definition, ())
58
+ if not isinstance(func, ast.Attribute):
59
+ return None
60
+ base = self.call(func.value)
61
+ if base is None and method == "add_argument" and isinstance(func.value, ast.Name):
62
+ definition = self.definition if self.definition and self.definition["shared"] else self._define(node.lineno, True)
63
+ self._command(definition, (), "", node.lineno)
64
+ base = ("parser", definition, ())
65
+ self.names[func.value.id] = base
66
+ if base is None:
67
+ return None
68
+ kind, definition, words = base
69
+ if kind == "parser" and method == "add_subparsers":
70
+ return ("subparsers", definition, words)
71
+ if kind == "subparsers" and method == "add_parser" and node.args:
72
+ name = _constant(node.args[0], self.bound)
73
+ words = words + (name if isinstance(name, str) else f"<{ast.unparse(node.args[0])}>",)
74
+ told = keywords.get("help", keywords.get("description"))
75
+ self._command(definition, words, _text(told, self.bound) if told is not None else "", node.lineno)
76
+ return ("parser", definition, words)
77
+ if kind in ("parser", "group") and method in _GROUPS:
78
+ return ("group", definition, words)
79
+ if kind in ("parser", "group") and method == "add_argument":
80
+ flags = [_constant(a, self.bound) for a in node.args]
81
+ argument = {"flags": [f for f in flags if isinstance(f, str)], "line": node.lineno,
82
+ "help": _text(keywords["help"], self.bound) if "help" in keywords else ""}
83
+ for key in ("default", "required", "choices", "action", "nargs", "metavar"):
84
+ if key in keywords:
85
+ argument[key] = ast.unparse(keywords[key])
86
+ self._command(definition, words, "", node.lineno)["arguments"].append(argument)
87
+ return None
88
+
89
+ def block(self, statements):
90
+ for statement in statements:
91
+ if isinstance(statement, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
92
+ continue
93
+ if isinstance(statement, (ast.Assign, ast.AnnAssign)) and statement.value is not None:
94
+ handle = self.call(statement.value)
95
+ targets = statement.targets if isinstance(statement, ast.Assign) else [statement.target]
96
+ for target in targets:
97
+ if isinstance(target, ast.Name):
98
+ if handle:
99
+ self.names[target.id] = handle
100
+ else:
101
+ self.names.pop(target.id, None)
102
+ elif isinstance(statement, (ast.Expr, ast.Return)) and statement.value is not None:
103
+ self.call(statement.value)
104
+ elif isinstance(statement, ast.For):
105
+ self._loop(statement)
106
+ else:
107
+ for field in ("body", "orelse", "finalbody"):
108
+ self.block(getattr(statement, field, None) or [])
109
+ for handler in getattr(statement, "handlers", None) or []:
110
+ self.block(handler.body)
111
+
112
+ def _loop(self, statement):
113
+ """A loop over a literal list of names runs its body once per item with the loop variables bound."""
114
+ items = statement.iter.elts if isinstance(statement.iter, (ast.Tuple, ast.List)) else None
115
+ target = statement.target
116
+ names = [target.id] if isinstance(target, ast.Name) else \
117
+ [t.id if isinstance(t, ast.Name) else None for t in target.elts] if isinstance(target, ast.Tuple) else None
118
+ if not items or names is None:
119
+ self.block(statement.body)
120
+ return
121
+ for item in items:
122
+ values = [item] if len(names) == 1 else item.elts if isinstance(item, (ast.Tuple, ast.List)) else None
123
+ if values is None or len(values) != len(names):
124
+ self.block(statement.body)
125
+ return
126
+ for name, value in zip(names, values):
127
+ if name:
128
+ self.bound[name] = value.value if isinstance(value, ast.Constant) else None
129
+ self.block(statement.body)
130
+ for name in names:
131
+ self.bound.pop(name, None)
132
+
133
+
134
+ def definitions(path, source):
135
+ """argparse command lines declared in one Python file.
136
+
137
+ Parameters: path (str) project-relative path; source (str) the file's text.
138
+ Returns: list of {'path', 'function' (None at module level), 'line', 'shared' (options added to a parser the function
139
+ receives), 'commands': [{'words', 'help', 'line', 'arguments': [{'flags', 'help', 'line', 'default', ...}]}]}.
140
+ """
141
+ if "argparse" not in source and "add_argument" not in source:
142
+ return []
143
+ try:
144
+ tree = ast.parse(source)
145
+ except (SyntaxError, ValueError):
146
+ return []
147
+ found = []
148
+ _Scope(path, None, found).block(tree.body)
149
+ for node in ast.walk(tree):
150
+ if isinstance(node, ast.ClassDef):
151
+ for child in node.body:
152
+ if isinstance(child, (ast.FunctionDef, ast.AsyncFunctionDef)):
153
+ child._owner = node.name
154
+ if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
155
+ owner = getattr(node, "_owner", None)
156
+ _Scope(path, f"{owner}.{node.name}" if owner else node.name, found).block(node.body)
157
+ for definition in found:
158
+ definition["commands"] = sorted(definition["commands"].values(), key=lambda c: (c["line"], c["words"]))
159
+ return [d for d in found if any(c["arguments"] or c["words"] for c in d["commands"])]
160
+
161
+
162
+ def _is_main_guard(test):
163
+ return (isinstance(test, ast.Compare) and isinstance(test.left, ast.Name) and test.left.id == "__name__"
164
+ and len(test.comparators) == 1 and isinstance(test.comparators[0], ast.Constant)
165
+ and test.comparators[0].value == "__main__")
166
+
167
+
168
+ def _module_file(path, module, level, files):
169
+ """Project path of the module an import names, or None when it is not a project file."""
170
+ base = posixpath.dirname(path).split("/") if path.count("/") else []
171
+ if level:
172
+ base = base[:len(base) - (level - 1)] if level > 1 else base
173
+ parts = base + (module.split(".") if module else [])
174
+ else:
175
+ parts = module.split(".") if module else []
176
+ stem = "/".join(p for p in parts if p)
177
+ for candidate in (f"{stem}.py", f"{stem}/__init__.py"):
178
+ if candidate in files:
179
+ return candidate
180
+ return None
181
+
182
+
183
+ def launched(path, source, files):
184
+ """Functions a `__main__` block of a Python file runs: (project path, function name) pairs.
185
+
186
+ Parameters: path (str) project-relative path; source (str) the file's text; files (set) project-relative paths.
187
+ """
188
+ if "__main__" not in source:
189
+ return []
190
+ try:
191
+ tree = ast.parse(source)
192
+ except (SyntaxError, ValueError):
193
+ return []
194
+ imported = {}
195
+ for node in ast.walk(tree):
196
+ if isinstance(node, ast.ImportFrom):
197
+ target = _module_file(path, node.module, node.level, files)
198
+ if target:
199
+ imported.update({(a.asname or a.name): (target, a.name) for a in node.names})
200
+ local = {n.name for n in tree.body if isinstance(n, (ast.FunctionDef, ast.AsyncFunctionDef))}
201
+ found = []
202
+ for node in tree.body:
203
+ if isinstance(node, ast.If) and _is_main_guard(node.test):
204
+ for inner in ast.walk(ast.Module(body=node.body, type_ignores=[])):
205
+ if isinstance(inner, ast.Call) and isinstance(inner.func, ast.Name):
206
+ name = inner.func.id
207
+ pair = (path, name) if name in local else imported.get(name)
208
+ if pair and pair not in found:
209
+ found.append(pair)
210
+ return found
211
+
212
+
213
+ def _argument(argument):
214
+ details = []
215
+ for key, label in (("default", "default"), ("choices", "one of"), ("nargs", "nargs"), ("metavar", "shown as")):
216
+ if key in argument:
217
+ details.append(f"{label} `{argument[key]}`")
218
+ if argument.get("required") == "True":
219
+ details.append("required")
220
+ if argument.get("action") in ("'store_true'", "'store_false'", "'count'", "'version'"):
221
+ details.append(argument["action"].strip("'").replace("store_", "sets "))
222
+ help_text = " ".join(argument["help"].split())
223
+ return (f" - {', '.join(f'`{f}`' for f in argument['flags']) or '(no name)'}"
224
+ + (f" ({'; '.join(details)})" if details else "") + (f": {help_text}" if help_text else ""))
225
+
226
+
227
+ def command_title(command):
228
+ """How the documentation names a command: its words, or 'without a command' for the parser itself."""
229
+ return f"`{' '.join(command['words'])}`" if command["words"] else "Without a command"
230
+
231
+
232
+ def lines(definition):
233
+ """Markdown list of a command line's commands, each with its arguments and options and their defaults."""
234
+ out = []
235
+ for command in definition["commands"]:
236
+ help_text = " ".join(command["help"].split())
237
+ out.append(f"- {command_title(command)} (line {command['line']})" + (f": {help_text}" if help_text else ""))
238
+ out += [_argument(a) for a in command["arguments"]]
239
+ return out