specrig 0.1.0__py3-none-any.whl

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.
Files changed (48) hide show
  1. specrig/__init__.py +7 -0
  2. specrig/__main__.py +5 -0
  3. specrig/_yaml.py +117 -0
  4. specrig/asgi.py +120 -0
  5. specrig/backend.py +153 -0
  6. specrig/clock.py +41 -0
  7. specrig/code/__init__.py +31 -0
  8. specrig/code/calls.py +61 -0
  9. specrig/code/django.py +118 -0
  10. specrig/code/fastapi.py +129 -0
  11. specrig/code/index.py +477 -0
  12. specrig/code/settings.py +132 -0
  13. specrig/contract.py +106 -0
  14. specrig/django/__init__.py +188 -0
  15. specrig/docker.py +133 -0
  16. specrig/fastapi/__init__.py +244 -0
  17. specrig/flows.py +285 -0
  18. specrig/gate.py +95 -0
  19. specrig/http.py +168 -0
  20. specrig/postgres.py +278 -0
  21. specrig/protocol/agents/contributing.md +6 -0
  22. specrig/protocol/agents/header.md +5 -0
  23. specrig/protocol/agents/reference.md +1 -0
  24. specrig/protocol/agents/rule11.md +423 -0
  25. specrig/protocol/agents/short.md +19 -0
  26. specrig/protocol/modes.yaml +55 -0
  27. specrig/proxy.py +73 -0
  28. specrig/py.typed +0 -0
  29. specrig/records.py +48 -0
  30. specrig/redis.py +154 -0
  31. specrig/resource.py +49 -0
  32. specrig/rig.py +370 -0
  33. specrig/run.py +22 -0
  34. specrig/standins.py +112 -0
  35. specrig/suite.py +239 -0
  36. specrig/surface.py +87 -0
  37. specrig/tool/__init__.py +0 -0
  38. specrig/tool/agents.py +150 -0
  39. specrig/tool/cli.py +137 -0
  40. specrig/tool/init.py +244 -0
  41. specrig/tool/modes.py +54 -0
  42. specrig/tool/service.py +209 -0
  43. specrig/tool/templates.py +196 -0
  44. specrig-0.1.0.dist-info/METADATA +603 -0
  45. specrig-0.1.0.dist-info/RECORD +48 -0
  46. specrig-0.1.0.dist-info/WHEEL +4 -0
  47. specrig-0.1.0.dist-info/entry_points.txt +5 -0
  48. specrig-0.1.0.dist-info/licenses/LICENSE +21 -0
@@ -0,0 +1,129 @@
1
+ from __future__ import annotations
2
+
3
+ import ast
4
+ from dataclasses import dataclass, field
5
+
6
+ from ..http import route
7
+ from ..surface import Surface
8
+ from .index import UNCALLED, VARYING, Code
9
+
10
+ _APPS = {"fastapi.FastAPI", "fastapi.applications.FastAPI"}
11
+ _ROUTERS = {"fastapi.APIRouter", "fastapi.routing.APIRouter"}
12
+ _VERBS = {"get", "post", "put", "patch", "delete", "head", "options", "trace"}
13
+
14
+
15
+ @dataclass(eq=False)
16
+ class _Router:
17
+ app: bool
18
+ prefix: str
19
+ routes: list[tuple[list[str], str]] = field(default_factory=list)
20
+ includes: list[tuple[_Router, str]] = field(default_factory=list)
21
+ included: bool = False
22
+
23
+
24
+ def read(code: Code, surface: Surface) -> None:
25
+ routers: dict[ast.Call, _Router] = {}
26
+ for module in code.modules.values():
27
+ for node in ast.walk(module.tree):
28
+ if isinstance(node, ast.Call):
29
+ kind = code.qualified(node.func)
30
+ if kind in _APPS or kind in _ROUTERS:
31
+ prefix = code.keyword(node, "prefix")
32
+ routers[node] = _Router(kind in _APPS, "" if prefix is None else _constant(code, prefix, node))
33
+ for module in code.modules.values():
34
+ for node in ast.walk(module.tree):
35
+ if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
36
+ for decorator in node.decorator_list:
37
+ if isinstance(decorator, ast.Call) and isinstance(decorator.func, ast.Attribute):
38
+ _route(code, routers, decorator, decorator.func)
39
+ elif isinstance(node, ast.Call) and isinstance(node.func, ast.Attribute):
40
+ owner = _router(code, routers, node.func.value)
41
+ if owner is None:
42
+ continue
43
+ if node.func.attr == "add_api_route":
44
+ methods = _methods(code, code.keyword(node, "methods")) or ["GET"]
45
+ owner.routes.append((methods, _constant(code, code.argument(node, 0, "path"), node)))
46
+ elif node.func.attr in ("include_router", "mount"):
47
+ child = _router(
48
+ code,
49
+ routers,
50
+ code.argument(
51
+ node,
52
+ 0 if node.func.attr == "include_router" else 1,
53
+ "router" if node.func.attr == "include_router" else "app",
54
+ ),
55
+ )
56
+ if child is not None:
57
+ at = (
58
+ code.keyword(node, "prefix")
59
+ if node.func.attr == "include_router"
60
+ else code.argument(node, 0, "path")
61
+ )
62
+ child.included = True
63
+ owner.includes.append((child, "" if at is None else _constant(code, at, node)))
64
+ for root in routers.values():
65
+ if root.app or not root.included:
66
+ _serve(root, "", surface, set())
67
+
68
+
69
+ def _route(code: Code, routers: dict[ast.Call, _Router], decorator: ast.Call, func: ast.Attribute) -> None:
70
+ owner = _router(code, routers, func.value)
71
+ if owner is None:
72
+ return
73
+ if func.attr in _VERBS:
74
+ owner.routes.append(([func.attr.upper()], _constant(code, code.argument(decorator, 0, "path"), decorator)))
75
+ elif func.attr == "api_route":
76
+ methods = _methods(code, code.keyword(decorator, "methods")) or ["GET"]
77
+ owner.routes.append((methods, _constant(code, code.argument(decorator, 0, "path"), decorator)))
78
+
79
+
80
+ def _router(code: Code, routers: dict[ast.Call, _Router], expr: ast.AST | None) -> _Router | None:
81
+ for value in _values(code, expr):
82
+ if value in routers:
83
+ return routers[value]
84
+ return None
85
+
86
+
87
+ def _values(code: Code, expr: ast.AST | None) -> list[ast.AST]:
88
+ if isinstance(expr, ast.Call):
89
+ return [expr]
90
+ if isinstance(expr, ast.Name):
91
+ scope = code.scope(expr)
92
+ if scope is not None and not isinstance(scope, ast.Lambda):
93
+ local = [
94
+ n.value
95
+ for n in ast.walk(scope)
96
+ if isinstance(n, ast.Assign) and any(isinstance(t, ast.Name) and t.id == expr.id for t in n.targets)
97
+ ]
98
+ if local:
99
+ return local
100
+ definition = code.definitions.get(code.qualified(expr) or "")
101
+ return [definition] if definition is not None else []
102
+
103
+
104
+ def _methods(code: Code, expr: ast.AST | None) -> list[str]:
105
+ if isinstance(expr, (ast.List, ast.Tuple, ast.Set)):
106
+ return [m.upper() for e in expr.elts for m in code.templates(e) if VARYING not in m and UNCALLED not in m]
107
+ return []
108
+
109
+
110
+ def _constant(code: Code, expr: ast.AST | None, at: ast.AST) -> str:
111
+ found = code.templates(expr)
112
+ if len(found) != 1 or VARYING in found[0] or UNCALLED in found[0]:
113
+ file = code.module_of(at).file.relative_to(code.root)
114
+ raise ValueError(
115
+ f"{file}:{getattr(at, 'lineno', 0)}: serves a route that is not a constant — it is a contract, give it one"
116
+ )
117
+ return found[0]
118
+
119
+
120
+ def _serve(router: _Router, prefix: str, surface: Surface, seen: set[int]) -> None:
121
+ if id(router) in seen:
122
+ return
123
+ seen = {*seen, id(router)}
124
+ under = prefix + router.prefix
125
+ for methods, path in router.routes:
126
+ for method in methods:
127
+ surface.serves.add(f"{method} {route(under + path, lambda name, kind: kind == 'path')}")
128
+ for child, at in router.includes:
129
+ _serve(child, under + at, surface, seen)
specrig/code/index.py ADDED
@@ -0,0 +1,477 @@
1
+ from __future__ import annotations
2
+
3
+ import ast
4
+ import itertools
5
+ import re
6
+ from collections.abc import Iterator
7
+ from dataclasses import dataclass, field
8
+ from pathlib import Path
9
+ from typing import cast
10
+
11
+ VARYING = "{}"
12
+ # A parameter of a function nobody calls carries no value at all.
13
+ UNCALLED = "\0"
14
+ DEEPEST = 12
15
+
16
+ Scope = ast.FunctionDef | ast.AsyncFunctionDef | ast.Lambda
17
+
18
+
19
+ @dataclass
20
+ class Module:
21
+ name: str
22
+ file: Path
23
+ tree: ast.Module
24
+ package: str
25
+ imports: dict[str, str] = field(default_factory=dict)
26
+
27
+
28
+ class Code:
29
+ def __init__(self, root: Path, files: list[Path]) -> None:
30
+ self.root = root
31
+ self.modules: dict[str, Module] = {}
32
+ self.parents: dict[ast.AST, ast.AST] = {}
33
+ self.owner: dict[ast.AST, Module] = {}
34
+ self.definitions: dict[str, ast.AST] = {}
35
+ self._names: dict[ast.AST, str] = {}
36
+ self.bases: dict[str, list[str]] = {}
37
+ self.calls: dict[str, list[ast.Call]] = {}
38
+ self._templates: dict[ast.AST, list[str]] = {}
39
+ self._types: dict[ast.AST, list[str]] = {}
40
+ self._bindings: dict[ast.AST, dict[str, list[ast.expr]]] = {}
41
+ for file in files:
42
+ try:
43
+ tree = ast.parse(file.read_text(encoding="utf-8"), filename=str(file))
44
+ except SyntaxError as e:
45
+ raise ValueError(f"{file}: {e}") from e
46
+ name, package = _module_name(root, file)
47
+ module = Module(name, file, tree, package)
48
+ self.modules[name] = module
49
+ self.owner[tree] = module
50
+ for node in ast.walk(tree):
51
+ for child in ast.iter_child_nodes(node):
52
+ self.parents[child] = node
53
+ for module in self.modules.values():
54
+ self._index(module)
55
+
56
+ def _index(self, module: Module) -> None:
57
+ for node in ast.walk(module.tree):
58
+ if isinstance(node, ast.Import):
59
+ for alias in node.names:
60
+ if alias.asname:
61
+ module.imports[alias.asname] = alias.name
62
+ else:
63
+ module.imports[alias.name.split(".")[0]] = alias.name.split(".")[0]
64
+ elif isinstance(node, ast.ImportFrom):
65
+ base = _absolute(module, node)
66
+ for alias in node.names:
67
+ module.imports[alias.asname or alias.name] = f"{base}.{alias.name}" if base else alias.name
68
+ elif isinstance(node, ast.Call):
69
+ callee = node.func.attr if isinstance(node.func, ast.Attribute) else getattr(node.func, "id", None)
70
+ if callee:
71
+ self.calls.setdefault(callee, []).append(node)
72
+ self._define(module.tree.body, module.name)
73
+
74
+ def _define(self, body: list[ast.stmt], prefix: str) -> None:
75
+ for stmt in body:
76
+ if isinstance(stmt, (ast.FunctionDef, ast.AsyncFunctionDef)):
77
+ self.definitions[f"{prefix}.{stmt.name}"] = stmt
78
+ self._names[stmt] = f"{prefix}.{stmt.name}"
79
+ elif isinstance(stmt, ast.ClassDef):
80
+ name = f"{prefix}.{stmt.name}"
81
+ self.definitions[name] = stmt
82
+ self._names[stmt] = name
83
+ self.bases[name] = [b for b in (self.qualified(base) for base in stmt.bases) if b]
84
+ self._define(stmt.body, name)
85
+ elif isinstance(stmt, ast.Assign):
86
+ for target in stmt.targets:
87
+ if isinstance(target, ast.Name):
88
+ self.definitions[f"{prefix}.{target.id}"] = stmt.value
89
+ elif isinstance(stmt, ast.AnnAssign) and isinstance(stmt.target, ast.Name) and stmt.value is not None:
90
+ self.definitions[f"{prefix}.{stmt.target.id}"] = stmt.value
91
+ elif isinstance(stmt, (ast.If, ast.Try)):
92
+ self._define([*stmt.body, *stmt.orelse], prefix)
93
+
94
+ def module_of(self, node: ast.AST) -> Module:
95
+ at = node
96
+ while at not in self.owner:
97
+ at = self.parents[at]
98
+ return self.owner[at]
99
+
100
+ def enclosing(self, node: ast.AST, *kinds: type) -> ast.AST | None:
101
+ at = self.parents.get(node)
102
+ while at is not None and not isinstance(at, kinds):
103
+ at = self.parents.get(at)
104
+ return at
105
+
106
+ def scope(self, node: ast.AST) -> Scope | None:
107
+ return cast(Scope | None, self.enclosing(node, ast.FunctionDef, ast.AsyncFunctionDef, ast.Lambda))
108
+
109
+ def class_of(self, node: ast.AST) -> str | None:
110
+ found = self.enclosing(node, ast.ClassDef)
111
+ return None if found is None else self.name_of(found)
112
+
113
+ def name_of(self, definition: ast.AST) -> str | None:
114
+ return self._names.get(definition)
115
+
116
+ def where(self, node: ast.AST) -> str:
117
+ return self.class_of(node) or self.module_of(node).name
118
+
119
+ def ancestry(self, name: str) -> list[str]:
120
+ line: list[str] = []
121
+ todo = [name]
122
+ while todo and len(line) < DEEPEST:
123
+ at = todo.pop(0)
124
+ if at not in line:
125
+ line.append(at)
126
+ todo.extend(self.bases.get(at, []))
127
+ return line
128
+
129
+ def extends(self, name: str, ancestor: str) -> bool:
130
+ return ancestor in self.ancestry(name)[1:]
131
+
132
+ # The qualified name an expression refers to, as an import would reach it.
133
+ def qualified(self, expr: ast.AST | None) -> str | None:
134
+ if isinstance(expr, ast.Name):
135
+ module = self.module_of(expr)
136
+ if expr.id in module.imports:
137
+ return module.imports[expr.id]
138
+ klass = self.class_of(expr)
139
+ for prefix in ([klass] if klass else []) + [module.name]:
140
+ if f"{prefix}.{expr.id}" in self.definitions:
141
+ return f"{prefix}.{expr.id}"
142
+ return expr.id
143
+ if isinstance(expr, ast.Attribute):
144
+ owner = self.qualified(expr.value)
145
+ return None if owner is None else f"{owner}.{expr.attr}"
146
+ return None
147
+
148
+ def call_args(self, call: ast.Call) -> tuple[list[ast.expr], dict[str, ast.expr]]:
149
+ return [a for a in call.args if not isinstance(a, ast.Starred)], {
150
+ k.arg: k.value for k in call.keywords if k.arg
151
+ }
152
+
153
+ def keyword(self, call: ast.Call, name: str) -> ast.expr | None:
154
+ return self.call_args(call)[1].get(name)
155
+
156
+ def argument(self, call: ast.Call, position: int, name: str) -> ast.expr | None:
157
+ positional, named = self.call_args(call)
158
+ if name in named:
159
+ return named[name]
160
+ return positional[position] if position < len(positional) else None
161
+
162
+ # Each expression is read once: a name assigned from itself — x = x.strip() — is a
163
+ # cycle, and a visit inside it sees what varies.
164
+ def templates(self, expr: ast.AST | None, depth: int = 0) -> list[str]:
165
+ if expr is None or depth > DEEPEST:
166
+ return [VARYING]
167
+ if expr not in self._templates:
168
+ self._templates[expr] = [VARYING]
169
+ self._templates[expr] = self._template_of(expr, depth)
170
+ return self._templates[expr]
171
+
172
+ def _template_of(self, expr: ast.AST, depth: int) -> list[str]:
173
+ if isinstance(expr, ast.Constant):
174
+ return (
175
+ [str(expr.value)]
176
+ if isinstance(expr.value, (str, int, float)) and not isinstance(expr.value, bool)
177
+ else [VARYING]
178
+ )
179
+ if isinstance(expr, ast.JoinedStr):
180
+ sofar = [""]
181
+ for part in expr.values:
182
+ if isinstance(part, ast.Constant):
183
+ pieces = [str(part.value)]
184
+ elif isinstance(part, ast.FormattedValue):
185
+ pieces = self.templates(part.value, depth + 1)
186
+ else:
187
+ pieces = [VARYING]
188
+ sofar = _product(sofar, pieces)
189
+ return sofar
190
+ if isinstance(expr, ast.BinOp) and isinstance(expr.op, ast.Add):
191
+ return _product(self.templates(expr.left, depth + 1), self.templates(expr.right, depth + 1))
192
+ if isinstance(expr, ast.BinOp) and isinstance(expr.op, ast.Mod) and isinstance(expr.left, ast.Constant):
193
+ return [
194
+ re.sub(
195
+ r"%%|%[-+ 0#]*\d*(?:\.\d+)?[a-zA-Z]",
196
+ lambda m: "%" if m.group(0) == "%%" else VARYING,
197
+ str(expr.left.value),
198
+ )
199
+ ]
200
+ if isinstance(expr, ast.IfExp):
201
+ return [*self.templates(expr.body, depth + 1), *self.templates(expr.orelse, depth + 1)]
202
+ if isinstance(expr, ast.BoolOp):
203
+ return [t for value in expr.values for t in self.templates(value, depth + 1)]
204
+ if isinstance(expr, ast.Call):
205
+ return self._called(expr, depth)
206
+ if isinstance(expr, ast.Name):
207
+ return self._name(expr, depth)
208
+ if isinstance(expr, ast.Attribute):
209
+ return self._attribute(expr, depth)
210
+ return [VARYING]
211
+
212
+ def _called(self, call: ast.Call, depth: int) -> list[str]:
213
+ func = call.func
214
+ if isinstance(func, ast.Attribute) and func.attr == "format" and isinstance(func.value, ast.Constant):
215
+ return [re.sub(r"\{[^{}]*\}", VARYING, str(func.value.value))]
216
+ if isinstance(func, ast.Name) and func.id == "str" and call.args:
217
+ return self.templates(call.args[0], depth + 1)
218
+ if (
219
+ isinstance(func, ast.Attribute)
220
+ and func.attr in ("rstrip", "strip", "lstrip", "removesuffix")
221
+ and not call.args
222
+ ):
223
+ return self.templates(func.value, depth + 1)
224
+ return [VARYING]
225
+
226
+ def _name(self, name: ast.Name, depth: int) -> list[str]:
227
+ scope = self.scope(name)
228
+ if scope is not None and not isinstance(scope, ast.Lambda):
229
+ for position, param in enumerate(_params(scope)):
230
+ if param.arg == name.id:
231
+ return self.parameter(scope, position, name.id, depth)
232
+ found = [t for value in self.bound(scope, name.id) for t in self.templates(value, depth + 1)]
233
+ if found:
234
+ return list(dict.fromkeys(found))
235
+ qualified = self.qualified(name)
236
+ definition = self.definitions.get(qualified or "")
237
+ if isinstance(definition, ast.expr):
238
+ return self.templates(definition, depth + 1)
239
+ return [VARYING]
240
+
241
+ def _attribute(self, attribute: ast.Attribute, depth: int) -> list[str]:
242
+ if isinstance(attribute.value, ast.Name) and attribute.value.id in ("self", "cls"):
243
+ klass = self.class_of(attribute)
244
+ found: list[str] = []
245
+ for at in self.ancestry(klass) if klass else []:
246
+ definition = self.definitions.get(f"{at}.{attribute.attr}")
247
+ if isinstance(definition, ast.expr):
248
+ found += self.templates(definition, depth + 1)
249
+ found += [
250
+ t for value in self._self_assigned(at, attribute.attr) for t in self.templates(value, depth + 1)
251
+ ]
252
+ return list(dict.fromkeys(found)) or [VARYING]
253
+ definition = self.definitions.get(self.qualified(attribute) or "")
254
+ if isinstance(definition, ast.expr):
255
+ return self.templates(definition, depth + 1)
256
+ return [VARYING]
257
+
258
+ def _self_assigned(self, klass: str, attribute: str) -> Iterator[ast.expr]:
259
+ definition = self.definitions.get(klass)
260
+ if not isinstance(definition, ast.ClassDef):
261
+ return
262
+ for node in ast.walk(definition):
263
+ targets = (
264
+ node.targets
265
+ if isinstance(node, ast.Assign)
266
+ else [node.target]
267
+ if isinstance(node, ast.AnnAssign)
268
+ else []
269
+ )
270
+ value = getattr(node, "value", None)
271
+ for target in targets:
272
+ if (
273
+ value is not None
274
+ and isinstance(target, ast.Attribute)
275
+ and isinstance(target.value, ast.Name)
276
+ and target.value.id == "self"
277
+ and target.attr == attribute
278
+ ):
279
+ yield value
280
+
281
+ def parameter(self, function: Scope, position: int, name: str, depth: int) -> list[str]:
282
+ callers = self.callers(function)
283
+ if not callers:
284
+ return [UNCALLED]
285
+ found: list[str] = []
286
+ bound = 1 if self._method(function) else 0
287
+ for call in callers:
288
+ found += self.templates(self.argument(call, position - bound, name), depth + 1)
289
+ return list(dict.fromkeys(found))
290
+
291
+ def _method(self, function: Scope) -> bool:
292
+ parent = self.parents.get(function)
293
+ params = _params(function)
294
+ return isinstance(parent, ast.ClassDef) and bool(params) and params[0].arg in ("self", "cls")
295
+
296
+ def callers(self, function: Scope) -> list[ast.Call]:
297
+ if isinstance(function, ast.Lambda):
298
+ return []
299
+ defined = self.name_of(function)
300
+ klass = self.class_of(function)
301
+ callers = []
302
+ for call in self.calls.get(function.name, []):
303
+ if isinstance(call.func, ast.Name):
304
+ if self.qualified(call.func) == defined:
305
+ callers.append(call)
306
+ elif isinstance(call.func, ast.Attribute) and klass is not None:
307
+ receiver = call.func.value
308
+ types = (
309
+ [self.class_of(call) or ""]
310
+ if isinstance(receiver, ast.Name) and receiver.id in ("self", "cls")
311
+ else self.types(receiver)
312
+ )
313
+ if any(t == klass or klass in self.ancestry(t) for t in types):
314
+ callers.append(call)
315
+ elif isinstance(call.func, ast.Attribute) and self.qualified(call.func) == defined:
316
+ callers.append(call)
317
+ return callers
318
+
319
+ # The classes an expression may hold, as far as the code says: what it was built
320
+ # from, what it was declared as, what returned it.
321
+ def types(self, expr: ast.AST | None, depth: int = 0) -> list[str]:
322
+ if expr is None or depth > DEEPEST:
323
+ return []
324
+ if expr not in self._types:
325
+ self._types[expr] = []
326
+ self._types[expr] = list(dict.fromkeys(self._types_of(expr, depth)))
327
+ return self._types[expr]
328
+
329
+ def bound(self, scope: ast.AST, name: str) -> list[ast.expr]:
330
+ if scope not in self._bindings:
331
+ self._bindings[scope] = _bindings(scope)
332
+ return self._bindings[scope].get(name, [])
333
+
334
+ def _types_of(self, expr: ast.AST, depth: int) -> list[str]:
335
+ if isinstance(expr, ast.Await):
336
+ return self.types(expr.value, depth + 1)
337
+ if isinstance(expr, ast.Call):
338
+ callee = self.qualified(expr.func)
339
+ definition = self.definitions.get(callee or "")
340
+ if isinstance(definition, (ast.FunctionDef, ast.AsyncFunctionDef)):
341
+ return self._returns(definition, depth)
342
+ if isinstance(expr.func, ast.Attribute) and not isinstance(definition, ast.ClassDef):
343
+ owners = [
344
+ o
345
+ for o in self.types(expr.func.value, depth + 1)
346
+ if o not in self.modules and o not in _KNOWN_MODULES
347
+ ]
348
+ if owners:
349
+ return [t for owner in owners for t in self._method_returns(owner, expr.func.attr, depth)]
350
+ return [callee] if callee else []
351
+ if isinstance(expr, ast.Name):
352
+ if expr.id in ("self", "cls"):
353
+ klass = self.class_of(expr)
354
+ return [klass] if klass else []
355
+ scope = self.scope(expr)
356
+ if scope is not None and not isinstance(scope, ast.Lambda):
357
+ for param in _params(scope):
358
+ if param.arg == expr.id:
359
+ return self._annotated(param.annotation)
360
+ found = [t for value in self.bound(scope, expr.id) for t in self.types(value, depth + 1)]
361
+ if found:
362
+ return found
363
+ qualified = self.qualified(expr)
364
+ definition = self.definitions.get(qualified or "")
365
+ if isinstance(definition, ast.expr):
366
+ return self.types(definition, depth + 1)
367
+ return [qualified] if qualified in self.modules or qualified in _KNOWN_MODULES else []
368
+ if isinstance(expr, ast.Attribute):
369
+ if isinstance(expr.value, ast.Name) and expr.value.id in ("self", "cls"):
370
+ klass = self.class_of(expr)
371
+ found = []
372
+ for at in self.ancestry(klass) if klass else []:
373
+ found += self._attribute_types(at, expr.attr, depth)
374
+ return found
375
+ qualified = self.qualified(expr)
376
+ definition = self.definitions.get(qualified or "")
377
+ if isinstance(definition, ast.expr):
378
+ return self.types(definition, depth + 1)
379
+ return []
380
+ return []
381
+
382
+ def _attribute_types(self, klass: str, attribute: str, depth: int) -> list[str]:
383
+ definition = self.definitions.get(klass)
384
+ if not isinstance(definition, ast.ClassDef):
385
+ return []
386
+ found: list[str] = []
387
+ for node in definition.body:
388
+ if isinstance(node, ast.AnnAssign) and isinstance(node.target, ast.Name) and node.target.id == attribute:
389
+ found += self._annotated(node.annotation)
390
+ for value in self._self_assigned(klass, attribute):
391
+ found += self.types(value, depth + 1)
392
+ return found
393
+
394
+ def _method_returns(self, owner: str, method: str, depth: int) -> list[str]:
395
+ for at in self.ancestry(owner):
396
+ definition = self.definitions.get(f"{at}.{method}")
397
+ if isinstance(definition, (ast.FunctionDef, ast.AsyncFunctionDef)):
398
+ return self._returns(definition, depth)
399
+ return []
400
+
401
+ def _returns(self, function: ast.FunctionDef | ast.AsyncFunctionDef, depth: int) -> list[str]:
402
+ declared = self._annotated(function.returns)
403
+ if declared:
404
+ return declared
405
+ return [
406
+ t for node in ast.walk(function) if isinstance(node, ast.Return) for t in self.types(node.value, depth + 1)
407
+ ]
408
+
409
+ def _annotated(self, annotation: ast.AST | None) -> list[str]:
410
+ if annotation is None:
411
+ return []
412
+ if isinstance(annotation, ast.Constant) and isinstance(annotation.value, str):
413
+ try:
414
+ parsed = ast.parse(annotation.value, mode="eval").body
415
+ except SyntaxError:
416
+ return []
417
+ self.parents[parsed] = annotation
418
+ return self._annotated(parsed)
419
+ if isinstance(annotation, ast.BinOp) and isinstance(annotation.op, ast.BitOr):
420
+ return [*self._annotated(annotation.left), *self._annotated(annotation.right)]
421
+ if isinstance(annotation, ast.Subscript):
422
+ return (
423
+ [t for t in self._annotated(annotation.slice) if t]
424
+ if self.qualified(annotation.value) in ("typing.Optional", "Optional", "typing.Union", "Union")
425
+ else []
426
+ )
427
+ if isinstance(annotation, ast.Tuple):
428
+ return [t for e in annotation.elts for t in self._annotated(e)]
429
+ qualified = self.qualified(annotation)
430
+ return [qualified] if qualified and qualified != "None" else []
431
+
432
+
433
+ _KNOWN_MODULES = {"httpx", "httpx2", "requests", "os"}
434
+
435
+
436
+ def _params(function: Scope) -> list[ast.arg]:
437
+ args = function.args
438
+ return [*args.posonlyargs, *args.args, *args.kwonlyargs]
439
+
440
+
441
+ def _bindings(scope: ast.AST) -> dict[str, list[ast.expr]]:
442
+ found: dict[str, list[ast.expr]] = {}
443
+ for node in ast.walk(scope):
444
+ if isinstance(node, ast.Assign):
445
+ for target in node.targets:
446
+ if isinstance(target, ast.Name):
447
+ found.setdefault(target.id, []).append(node.value)
448
+ elif isinstance(node, ast.AnnAssign) and isinstance(node.target, ast.Name) and node.value:
449
+ found.setdefault(node.target.id, []).append(node.value)
450
+ elif isinstance(node, (ast.With, ast.AsyncWith)):
451
+ for item in node.items:
452
+ if isinstance(item.optional_vars, ast.Name):
453
+ found.setdefault(item.optional_vars.id, []).append(item.context_expr)
454
+ return found
455
+
456
+
457
+ def _product(left: list[str], right: list[str]) -> list[str]:
458
+ return [a + b for a, b in itertools.product(left, right or [VARYING])]
459
+
460
+
461
+ def _module_name(root: Path, file: Path) -> tuple[str, str]:
462
+ parts = list(file.relative_to(root).with_suffix("").parts)
463
+ if parts and parts[0] == "src" and not (root / "src" / "__init__.py").is_file():
464
+ parts = parts[1:]
465
+ if parts[-1] == "__init__":
466
+ parts = parts[:-1]
467
+ return ".".join(parts), ".".join(parts)
468
+ return ".".join(parts), ".".join(parts[:-1])
469
+
470
+
471
+ def _absolute(module: Module, node: ast.ImportFrom) -> str:
472
+ if node.level == 0:
473
+ return node.module or ""
474
+ base = module.package.split(".") if module.package else []
475
+ if node.level > 1:
476
+ base = base[: len(base) - (node.level - 1)]
477
+ return ".".join([*base, *([node.module] if node.module else [])])