embeddedpy 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.

Potentially problematic release.


This version of embeddedpy might be problematic. Click here for more details.

@@ -0,0 +1,583 @@
1
+ """Module parsing and multi-file inlining.
2
+
3
+ Resolve "entry .py + the user modules it imports" at compile time into a merged single-module AST:
4
+ user module symbols get a `module_name__` prefix, and the entry module as root gets no prefix. This downgrades
5
+ the multi-module problem to a single-module problem, so checker / codegen need no changes at all.
6
+
7
+ Key constraints:
8
+ - Only read the **source text** of imported modules, never exec (compile-time, no side effects).
9
+ - The entry module is root (no prefix), and its top-level ``main`` is C's ``main``.
10
+ - Functions declared with ``@c.extern_function`` represent fixed external C symbols and get **no** prefix on cross-module reference,
11
+ to stay consistent with the real C link name.
12
+ - The project root comes from the entry file's location and the consecutive ``__init__.py`` chain; one compilation has exactly one root,
13
+ and absolute dotted import names resolve segment by segment against it.
14
+ - The namespace prefix is the module file's dotted path relative to the project root, joined with ``__``;
15
+ every segment is a legal Python identifier, so the resulting C identifier is legal too.
16
+ - User-visible names (module name, top-level def/class/global, struct field, enum member) **must not contain**
17
+ ``__`` (double underscore)—it is the module namespace separator, reserved to avoid name collisions after concatenation
18
+ (e.g. module ``a``'s symbol ``b__c`` and module ``a__b``'s symbol ``c`` would both become ``a__b__c``).
19
+ """
20
+
21
+ from __future__ import annotations
22
+
23
+ import ast
24
+ import sys
25
+ from dataclasses import dataclass, field
26
+ from pathlib import Path
27
+ from typing import Dict, List, Optional, Set, Tuple
28
+
29
+ from .errors import CompileError, Diagnostic
30
+ from .frontend import parse_source
31
+ from .lang_api import ALLOWED_IMPORT_ROOTS as BUILTIN_ROOTS
32
+
33
+ EXTERN_DECORATOR = "c.extern_function"
34
+
35
+
36
+ def _package_layout(path: Path) -> Tuple[Optional[Path], int]:
37
+ """Walk up from the module file looking for consecutive ``__init__.py``, returning (package root's parent dir, package depth).
38
+
39
+ The package root is "the parent directory of the topmost package": for ``proj/pkg/sub/main.py`` with both
40
+ ``pkg`` and ``sub`` having ``__init__.py``, the package root is ``proj`` and the depth is 2. A directory
41
+ without ``__init__.py`` is not a package, and relative imports do not hold there.
42
+ """
43
+ current = Path(path).parent
44
+ depth = 0
45
+ root: Optional[Path] = None
46
+ while (current / "__init__.py").is_file():
47
+ depth += 1
48
+ root = current.parent
49
+ current = current.parent
50
+ return (root, depth)
51
+
52
+
53
+ def _missing_module_message(name: str, tried: List[Path]) -> str:
54
+ """Distinguish "standard library / third-party" from "local file not found"; the latter lists the paths actually tried."""
55
+ stdlib = set(getattr(sys, "stdlib_module_names", ())) | set(sys.builtin_module_names)
56
+ if name.split(".")[0] in stdlib:
57
+ return (
58
+ f"standard library module {name!r} is not supported; only local .py "
59
+ "modules and embeddedpy category modules can be compiled"
60
+ )
61
+ return (
62
+ f"module {name} not found (looked for: {[str(p) for p in tried]}); "
63
+ "standard library and third-party modules cannot be compiled. "
64
+ "Imports resolve from the project root: use a dotted path, a relative "
65
+ "import, or place the .py file under that root"
66
+ )
67
+
68
+ # embeddedpy is the namespace where the compiler itself lives; it is not itself an importable category module.
69
+ # When encountered, **skip parsing** (do not treat it as a user module and look for a file),
70
+ # letting the frontend gate give the precise error "can only import from embeddedpy's category modules".
71
+ EMBEDDEDPY_NAMESPACE = "embeddedpy"
72
+
73
+ # The module namespace separator is "__" (double underscore). The prefix form is `module_name__symbol_name`.
74
+ # If the user writes "__" into a module name or symbol name, concatenation produces ambiguity and possible collisions (e.g.
75
+ # module a + symbol b__c and module a__b + symbol c both yield a__b__c).
76
+ # Thus "__" is a reserved word for user naming: its appearance raises an error, eliminating collision potential at the source.
77
+ _RESERVED_DOUBLE_UNDERSCORE = "__"
78
+
79
+
80
+ def _check_user_name(name: str, filename: str, line: int, col: int) -> None:
81
+ """User-visible names must not contain "__", otherwise they collide with the module namespace separator."""
82
+ if _RESERVED_DOUBLE_UNDERSCORE in name:
83
+ raise CompileError(
84
+ [
85
+ Diagnostic(
86
+ message=(
87
+ f"name '{name}' contains '__', which is reserved for the "
88
+ f"module namespace separator; use a single underscore instead"
89
+ ),
90
+ line=line,
91
+ col=col,
92
+ filename=filename,
93
+ code="reserved-name",
94
+ )
95
+ ]
96
+ )
97
+
98
+
99
+ def _is_c_extern(node: ast.AST) -> bool:
100
+ """Function decorators whose C name is given by the user and must not receive a module prefix.
101
+
102
+ ``@c.extern_function``'s name comes from external C, and ``@c.export``'s name comes from the link
103
+ script / startup code; neither belongs to this module's namespace.
104
+ """
105
+ target = node.func if isinstance(node, ast.Call) else node
106
+ return (
107
+ isinstance(target, ast.Attribute)
108
+ and target.attr in ("extern_function", "export")
109
+ and isinstance(target.value, ast.Name)
110
+ and target.value.id == "c"
111
+ )
112
+
113
+
114
+ def _project_root(entry_path: Path) -> Path:
115
+ # Project root: the top-level package's parent when the entry is in a package, otherwise the entry file's directory.
116
+ root, depth = _package_layout(entry_path)
117
+ return Path(root) if depth > 0 else Path(entry_path).parent
118
+
119
+
120
+ def find_module(name: str, root: Path) -> Tuple[Optional[Path], List[Path]]:
121
+ # Resolve a dotted name against the project root to one file; return (source path or None, paths tried).
122
+ # The last segment follows CPython's order: a package (<segment>/__init__.py) wins over a module (<segment>.py).
123
+ parts = name.split(".")
124
+ base = Path(root).joinpath(*parts[:-1])
125
+ init = base / parts[-1] / "__init__.py"
126
+ module = base / f"{parts[-1]}.py"
127
+ tried = [init, module]
128
+ if init.is_file():
129
+ return init, tried
130
+ if module.is_file():
131
+ return module, tried
132
+ return None, tried
133
+
134
+
135
+ @dataclass
136
+ class Module:
137
+ """A source-file module participating in compilation: path, AST, name prefix, and import maps."""
138
+ name: str # module key: dotted path relative to the project root, joined with "__"
139
+ path: Path
140
+ tree: ast.Module
141
+ prefix: str # "" for the entry, "<module_key>__" for the rest
142
+ is_entry: bool
143
+ import_user: Dict[str, str] = field(default_factory=dict) # alias -> module_name
144
+ import_from: Dict[str, Tuple[str, str]] = field(
145
+ default_factory=dict
146
+ ) # local_name -> (module_name, orig_name)
147
+ # dotted import name (or alias) -> module key; used to fold attribute chains to a module prefix
148
+ import_dotted: Dict[str, str] = field(default_factory=dict)
149
+ exports: Dict[str, bool] = field(default_factory=dict) # name -> is_extern
150
+ # Module-level variable names (constants / loop variables). The definition site gets a prefix, so the reference site must too,
151
+ # otherwise referencing a constant defined in the same module would "not find the name".
152
+ globals: Set[str] = field(default_factory=set)
153
+
154
+
155
+ class ProgramBuilder:
156
+ """Parse the entry and all its user modules, building the module graph (including cycle detection)."""
157
+
158
+ def __init__(self, entry_path: Path):
159
+ self.entry_path = Path(entry_path)
160
+ self.root = _project_root(self.entry_path)
161
+ self.modules: Dict[str, Module] = {}
162
+ self.entry_name = self.entry_path.stem
163
+ # Collect the same source only once: dedupe by absolute path, so absolute and relative imports pointing to
164
+ # the same file reuse the same module key and do not generate two sets of C symbols.
165
+ self._by_path: Dict[Path, str] = {}
166
+ self._collect(self.entry_path, is_entry=True, alias=self.entry_name,
167
+ stack=[], check_user_name=False)
168
+
169
+ def _module_key(self, path: Path) -> str:
170
+ # Module key = dotted path relative to the project root, joined with "__"; an __init__.py uses its directory.
171
+ rel = Path(path).resolve().relative_to(self.root.resolve())
172
+ parts = rel.parts[:-1] if rel.name == "__init__.py" else rel.with_suffix("").parts
173
+ return "__".join(parts)
174
+
175
+ def _relative_error(self, stmt: ast.AST, path: Path, message: str) -> None:
176
+ raise CompileError(
177
+ [Diagnostic(message=message, line=getattr(stmt, "lineno", 0),
178
+ col=getattr(stmt, "col_offset", 0), filename=str(path),
179
+ code="import-relative")]
180
+ )
181
+
182
+ def _collect_relative(
183
+ self, mod: Module, stmt: ast.ImportFrom, path: Path, stack: List[str]
184
+ ) -> None:
185
+ # Relative imports are converted by level into an absolute dotted name relative to the project root,
186
+ # then resolved exactly like absolute imports. level=1 is the current package directory; each extra
187
+ # dot goes up one level, and going out of bounds reports the same error as CPython.
188
+ _root, depth = _package_layout(path)
189
+ if depth == 0:
190
+ self._relative_error(
191
+ stmt, path,
192
+ "attempted relative import with no known parent package; "
193
+ "add __init__.py to the package directory or use a plain import",
194
+ )
195
+ if stmt.level > depth:
196
+ self._relative_error(stmt, path,
197
+ "attempted relative import beyond top-level package")
198
+ current = Path(path).parent.resolve().relative_to(self.root.resolve())
199
+ up = stmt.level - 1
200
+ base_parts = list(current.parts[:len(current.parts) - up])
201
+ parts = [p for p in (stmt.module or "").split(".") if p]
202
+ for p in parts:
203
+ _check_user_name(p, str(path), stmt.lineno, stmt.col_offset)
204
+
205
+ def star_check() -> None:
206
+ if any(a.name == "*" for a in stmt.names):
207
+ self._relative_error(stmt, path,
208
+ "star imports (import *) are not supported")
209
+
210
+ star_check()
211
+ if parts:
212
+ full = ".".join(base_parts + parts)
213
+ child, tried = find_module(full, self.root)
214
+ if child is None:
215
+ self._relative_error(
216
+ stmt, path,
217
+ f"relative import target {full!r} not found "
218
+ f"(looked for: {[str(p) for p in tried]})",
219
+ )
220
+ key = self._collect(child, is_entry=False,
221
+ alias=self._module_key(child), stack=stack,
222
+ check_user_name=False)
223
+ for a in stmt.names:
224
+ mod.import_from[a.asname or a.name] = (key, a.name)
225
+ else:
226
+ for a in stmt.names:
227
+ _check_user_name(a.name, str(path), stmt.lineno, stmt.col_offset)
228
+ full = ".".join(base_parts + [a.name])
229
+ child, tried = find_module(full, self.root)
230
+ if child is None:
231
+ self._relative_error(
232
+ stmt, path,
233
+ f"relative import target {full!r} not found "
234
+ f"(looked for: {[str(p) for p in tried]})",
235
+ )
236
+ key = self._collect(child, is_entry=False,
237
+ alias=self._module_key(child), stack=stack,
238
+ check_user_name=False)
239
+ mod.import_user[a.asname or a.name] = key
240
+
241
+ def _collect(
242
+ self,
243
+ path: Path,
244
+ is_entry: bool,
245
+ alias: str,
246
+ stack: List[str],
247
+ check_user_name: bool = True,
248
+ ) -> str:
249
+ path = Path(path)
250
+ name = alias or path.stem
251
+ if check_user_name:
252
+ _check_user_name(name, str(path), 0, 0)
253
+ if name in stack:
254
+ chain = " -> ".join(stack + [name])
255
+ raise CompileError(
256
+ [
257
+ Diagnostic(
258
+ message=f"circular import detected: {chain}",
259
+ line=0,
260
+ col=0,
261
+ filename=str(path),
262
+ code="import-cycle",
263
+ )
264
+ ]
265
+ )
266
+ resolved = path.resolve()
267
+ if resolved in self._by_path:
268
+ return self._by_path[resolved]
269
+
270
+ source = path.read_text(encoding="utf-8")
271
+ # Syntax errors in user source must become compile diagnostics (not a raw Python traceback)
272
+ tree = parse_source(source, str(path))
273
+ mod = Module(
274
+ name=name,
275
+ path=path,
276
+ tree=tree,
277
+ prefix=("" if is_entry else name + "__"),
278
+ is_entry=is_entry,
279
+ )
280
+ self.modules[name] = mod
281
+ self._by_path[resolved] = name
282
+
283
+ # Register this module's imports and exports first, then recurse into submodules (using the updated stack to detect cycles)
284
+ new_stack = stack + [name]
285
+ for stmt in tree.body:
286
+ if isinstance(stmt, ast.Import):
287
+ for a in stmt.names:
288
+ first = a.name.split(".")[0]
289
+ if first in BUILTIN_ROOTS or first == EMBEDDEDPY_NAMESPACE:
290
+ continue
291
+ for part in a.name.split("."):
292
+ _check_user_name(part, str(path), stmt.lineno, stmt.col_offset)
293
+ child, tried = find_module(a.name, self.root)
294
+ if child is None:
295
+ raise CompileError(
296
+ [Diagnostic(
297
+ message=_missing_module_message(a.name, tried),
298
+ line=getattr(stmt, "lineno", 0), col=0,
299
+ filename=str(path), code="import-not-found")]
300
+ )
301
+ key = self._collect(child, is_entry=False,
302
+ alias=self._module_key(child),
303
+ stack=new_stack,
304
+ check_user_name=False)
305
+ # Dotted names are registered for attribute-chain folding; single-segment names become module aliases
306
+ if "." in a.name:
307
+ mod.import_dotted[a.asname or a.name] = key
308
+ else:
309
+ mod.import_user[a.asname or a.name] = key
310
+ elif isinstance(stmt, ast.ImportFrom):
311
+ module = stmt.module or ""
312
+ if stmt.level > 0:
313
+ self._collect_relative(mod, stmt, path, new_stack)
314
+ continue
315
+ if module == "" or module in BUILTIN_ROOTS or module == EMBEDDEDPY_NAMESPACE:
316
+ continue
317
+ first = module.split(".")[0]
318
+ if first in BUILTIN_ROOTS or first == EMBEDDEDPY_NAMESPACE:
319
+ continue
320
+ for part in module.split("."):
321
+ _check_user_name(part, str(path), stmt.lineno, stmt.col_offset)
322
+ for a in stmt.names:
323
+ if a.name == "*":
324
+ raise CompileError(
325
+ [Diagnostic(
326
+ message="star imports (import *) are not supported",
327
+ line=getattr(stmt, "lineno", 0), col=0,
328
+ filename=str(path), code="import-star")]
329
+ )
330
+ child, tried = find_module(module, self.root)
331
+ pkg_key: Optional[str] = None
332
+ if child is not None:
333
+ pkg_key = self._collect(child, is_entry=False,
334
+ alias=self._module_key(child),
335
+ stack=new_stack,
336
+ check_user_name=False)
337
+ for a in stmt.names:
338
+ # Look for the exported symbol in <module> itself first, then for the submodule <module>.<name>.
339
+ if pkg_key is not None:
340
+ info = self.modules[pkg_key]
341
+ if a.name in info.exports or a.name in info.globals:
342
+ mod.import_from[a.asname or a.name] = (pkg_key, a.name)
343
+ continue
344
+ sub, _ = find_module(module + "." + a.name, self.root)
345
+ if sub is not None:
346
+ sub_key = self._collect(sub, is_entry=False,
347
+ alias=self._module_key(sub),
348
+ stack=new_stack,
349
+ check_user_name=False)
350
+ mod.import_user[a.asname or a.name] = sub_key
351
+ continue
352
+ if pkg_key is None:
353
+ raise CompileError(
354
+ [Diagnostic(
355
+ message=_missing_module_message(module, tried),
356
+ line=getattr(stmt, "lineno", 0), col=0,
357
+ filename=str(path), code="import-not-found")]
358
+ )
359
+ mod.import_from[a.asname or a.name] = (pkg_key, a.name)
360
+
361
+ # Register top-level exports (functions / classes) and record whether each is extern
362
+ for stmt in tree.body:
363
+ if isinstance(stmt, ast.FunctionDef):
364
+ mod.exports[stmt.name] = any(_is_c_extern(d) for d in stmt.decorator_list)
365
+ elif isinstance(stmt, ast.ClassDef):
366
+ mod.exports[stmt.name] = False
367
+
368
+ # Register module-level variable names (constants / loop variables). In Python they are the module's public names,
369
+ # so both cross-module `from mod import NAME` and `mod.NAME` must be able to locate them.
370
+ for stmt in tree.body:
371
+ if isinstance(stmt, ast.AnnAssign):
372
+ if isinstance(stmt.target, ast.Name):
373
+ mod.globals.add(stmt.target.id)
374
+ elif isinstance(stmt, ast.Assign):
375
+ for tgt in stmt.targets:
376
+ if isinstance(tgt, ast.Name):
377
+ mod.globals.add(tgt.id)
378
+ elif isinstance(stmt, ast.For):
379
+ if isinstance(stmt.target, ast.Name):
380
+ mod.globals.add(stmt.target.id)
381
+ return name
382
+
383
+ def ordered(self) -> List[Module]:
384
+ """Dependency topological order: dependency modules come first, the entry module comes last."""
385
+ visited: Set[str] = set()
386
+ order: List[str] = []
387
+
388
+ def dfs(n: str) -> None:
389
+ if n in visited:
390
+ return
391
+ visited.add(n)
392
+ for (_alias, child) in self.modules[n].import_user.items():
393
+ dfs(child)
394
+ for (_local, (child, _orig)) in self.modules[n].import_from.items():
395
+ dfs(child)
396
+ # Dotted imports are dependency edges too
397
+ for (_dotted, child) in self.modules[n].import_dotted.items():
398
+ dfs(child)
399
+ order.append(n)
400
+
401
+ dfs(self.entry_name)
402
+ return [self.modules[n] for n in order]
403
+
404
+
405
+ def _is_builtin_root(root: str) -> bool:
406
+ """Whether this is embeddedpy's own namespace (a category module or the compiler itself).
407
+
408
+ The compiler itself (``embeddedpy``) is not an importable category module, but it is **built-in**:
409
+ when encountered, the import statement must be preserved and handed to the frontend gate for a precise error,
410
+ not treated as a user module to look up a file, nor stripped as a user import.
411
+ """
412
+ return root in BUILTIN_ROOTS or root == EMBEDDEDPY_NAMESPACE
413
+
414
+
415
+ def _is_user_import(stmt: ast.stmt) -> bool:
416
+ if isinstance(stmt, ast.Import):
417
+ return any(not _is_builtin_root(a.name.split(".")[0]) for a in stmt.names)
418
+ if isinstance(stmt, ast.ImportFrom):
419
+ module = stmt.module or ""
420
+ return not (stmt.level == 0 and _is_builtin_root(module.split(".")[0]))
421
+ return False
422
+
423
+
424
+ class ModuleRenamer(ast.NodeTransformer):
425
+ """Rename a module's symbols according to namespace rules.
426
+
427
+ Rules:
428
+ - This module's top-level def/class/global constants: add this module's prefix (except extern).
429
+ - ``module.alias`` (where module is a user module alias): rewrite to ``prefix+attr`` (except extern).
430
+ - Dotted attribute chains from dotted imports (e.g. ``lib.a.get``): fold the longest dotted prefix into a module key,
431
+ then rewrite the remaining segment by that module's symbols (except extern).
432
+ - ``from module import name``: rewrite the reference to ``prefix+name`` (except extern).
433
+ - In-scope local variables, builtin / embeddedpy import names: keep unchanged.
434
+ """
435
+
436
+ def __init__(self, mod: Module, all_modules: Dict[str, Module]):
437
+ self.mod = mod
438
+ self.all = all_modules
439
+ self.prefix = mod.prefix
440
+ self.scopes: List[Set[str]] = []
441
+ # Class-body nesting depth. A class body is "the type's own namespace": field names / enum member names
442
+ # do not get a module prefix (otherwise after cross-module `from mod import Point`, `p.x` would not find the field).
443
+ # Use a separate counter rather than pushing a scope stack, to avoid polluting visit_Name's name resolution.
444
+ self._class_depth = 0
445
+
446
+ # ---- Scope and definitions ----
447
+ def visit_FunctionDef(self, node: ast.FunctionDef) -> ast.AST:
448
+ params: Set[str] = set()
449
+ for a in (
450
+ node.args.posonlyargs
451
+ + node.args.args
452
+ + node.args.kwonlyargs
453
+ ):
454
+ params.add(a.arg)
455
+ if node.args.vararg:
456
+ params.add(node.args.vararg.arg)
457
+ if node.args.kwarg:
458
+ params.add(node.args.kwarg.arg)
459
+ self.scopes.append(params)
460
+ if not any(_is_c_extern(d) for d in node.decorator_list):
461
+ _check_user_name(node.name, str(self.mod.path), node.lineno, node.col_offset)
462
+ node.name = self.prefix + node.name
463
+ self.generic_visit(node)
464
+ self.scopes.pop()
465
+ return node
466
+
467
+ def visit_ClassDef(self, node: ast.ClassDef) -> ast.AST:
468
+ _check_user_name(node.name, str(self.mod.path), node.lineno, node.col_offset)
469
+ node.name = self.prefix + node.name
470
+ self._class_depth += 1
471
+ self.generic_visit(node)
472
+ self._class_depth -= 1
473
+ return node
474
+
475
+ def visit_AnnAssign(self, node: ast.AnnAssign) -> ast.AST:
476
+ if isinstance(node.target, ast.Name):
477
+ if self._class_depth > 0:
478
+ # Struct field names belong to the type itself, not prefixed with the module prefix, but "__" is still forbidden
479
+ _check_user_name(node.target.id, str(self.mod.path), node.lineno, node.col_offset)
480
+ elif self.scopes:
481
+ self.scopes[-1].add(node.target.id)
482
+ else:
483
+ _check_user_name(node.target.id, str(self.mod.path), node.lineno, node.col_offset)
484
+ node.target.id = self.prefix + node.target.id
485
+ self.generic_visit(node)
486
+ return node
487
+
488
+ def visit_Assign(self, node: ast.Assign) -> ast.AST:
489
+ if len(node.targets) == 1 and isinstance(node.targets[0], ast.Name):
490
+ if self._class_depth > 0:
491
+ # Enum member names belong to the enum itself, not prefixed with the module prefix, but "__" is still forbidden
492
+ _check_user_name(node.targets[0].id, str(self.mod.path), node.lineno, node.col_offset)
493
+ elif self.scopes:
494
+ self.scopes[-1].add(node.targets[0].id)
495
+ else:
496
+ _check_user_name(node.targets[0].id, str(self.mod.path), node.lineno, node.col_offset)
497
+ # Record the original name the user wrote: c.define's macro-name validation compares against the binding name in source,
498
+ # not the internal name after the module prefix is added (macros are plain text on the C side, with no namespace).
499
+ node._embeddedpy_orig_name = node.targets[0].id
500
+ node.targets[0].id = self.prefix + node.targets[0].id
501
+ self.generic_visit(node)
502
+ return node
503
+
504
+ def visit_For(self, node: ast.For) -> ast.AST:
505
+ if isinstance(node.target, ast.Name):
506
+ if self.scopes:
507
+ self.scopes[-1].add(node.target.id)
508
+ elif self._class_depth == 0:
509
+ # A module-level for-loop variable is a module global; both definition and reference must be prefixed
510
+ _check_user_name(node.target.id, str(self.mod.path), node.lineno, node.col_offset)
511
+ node.target.id = self.prefix + node.target.id
512
+ self.generic_visit(node)
513
+ return node
514
+
515
+ # ---- Reference rewriting ----
516
+ def visit_Attribute(self, node: ast.Attribute) -> ast.AST:
517
+ parts: List[str] = []
518
+ cur: ast.AST = node
519
+ while isinstance(cur, ast.Attribute):
520
+ parts.append(cur.attr)
521
+ cur = cur.value
522
+ if isinstance(cur, ast.Name) and parts:
523
+ chain = [cur.id] + list(reversed(parts))
524
+ # Fold the longest dotted prefix into a module; the remaining segment is the symbol name in that module
525
+ for i in range(len(chain) - 1, 0, -1):
526
+ key = self.mod.import_dotted.get(".".join(chain[:i]))
527
+ if key is None:
528
+ continue
529
+ if len(chain) - i == 1:
530
+ info = self.all[key]
531
+ if info.exports.get(chain[i], False):
532
+ return ast.Name(id=chain[i], ctx=ast.Load())
533
+ return ast.Name(id=info.prefix + chain[i], ctx=ast.Load())
534
+ break
535
+ self.generic_visit(node)
536
+ if isinstance(node.value, ast.Name) and node.value.id in self.mod.import_user:
537
+ modname = self.mod.import_user[node.value.id]
538
+ info = self.all[modname]
539
+ if info.exports.get(node.attr, False):
540
+ return ast.Name(id=node.attr, ctx=ast.Load())
541
+ return ast.Name(id=info.prefix + node.attr, ctx=ast.Load())
542
+ return node
543
+
544
+ def visit_Name(self, node: ast.Name) -> ast.AST:
545
+ if isinstance(node.ctx, ast.Store):
546
+ return node
547
+ for scope in reversed(self.scopes):
548
+ if node.id in scope:
549
+ return node
550
+ if node.id in self.mod.import_from:
551
+ modname, orig = self.mod.import_from[node.id]
552
+ info = self.all[modname]
553
+ if info.exports.get(orig, False):
554
+ return ast.Name(id=orig, ctx=ast.Load())
555
+ return ast.Name(id=info.prefix + orig, ctx=ast.Load())
556
+ if node.id in self.mod.exports:
557
+ if self.mod.exports[node.id]:
558
+ return node # this module's extern: keep as-is
559
+ return ast.Name(id=self.prefix + node.id, ctx=ast.Load())
560
+ if node.id in self.mod.globals:
561
+ # This module's module-level variable: the definition site was prefixed, so the reference site must match
562
+ return ast.Name(id=self.prefix + node.id, ctx=ast.Load())
563
+ return node
564
+
565
+
566
+ def build_program(entry_path: Path) -> Tuple[ast.Module, str]:
567
+ """Parse the entry program, returning the merged single-module AST and the filename for diagnostics."""
568
+ builder = ProgramBuilder(Path(entry_path))
569
+ combined_body: List[ast.stmt] = []
570
+ for mod in builder.ordered():
571
+ kept = [s for s in mod.tree.body if not _is_user_import(s)]
572
+ renamed = ModuleRenamer(mod, builder.modules).visit(
573
+ ast.Module(body=kept, type_ignores=[])
574
+ )
575
+ # Diagnostics are reported by the node's source file: the merged AST has only one filename,
576
+ # so without per-node marking, type errors in submodules would all be attributed to the entry file.
577
+ for node in ast.walk(renamed):
578
+ node._embeddedpy_filename = str(mod.path)
579
+ combined_body.extend(renamed.body)
580
+
581
+ combined = ast.Module(body=combined_body, type_ignores=[])
582
+ ast.fix_missing_locations(combined)
583
+ return combined, str(entry_path)