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,186 @@
1
+ """Compile configuration.
2
+
3
+ Adjustable items:
4
+
5
+ - ``line_output``: whether the generated C keeps ``#line`` directives.
6
+ ``#line`` is the C preprocessor's native "source line reflection", making C compiler errors point back to ``.py``,
7
+ equivalent to a source map in other languages, but inlined in ``.c`` with no external ``.map``.
8
+ Values:
9
+
10
+ - ``"noline"``: no ``#line`` (clean C, convenient for third-party review or old IDEs);
11
+ - ``"line"`` : with ``#line``;
12
+ - ``"both"`` : produce both the "without" (``foo.c``) and "with" (``foo.line.c``) versions.
13
+
14
+ - ``output_type``: the role of the output, default ``"program"``. Three values:
15
+
16
+ - ``"program"``: a complete executable program (``.c``), with ``main``; ordinary functions are file-private;
17
+ - ``"header"``: a declaration set (``.h``), containing only types/macros/externs/function prototypes and an include guard,
18
+ without main and runtime function bodies;
19
+ - ``"library"``: a linkable implementation (``.c``), no ``main``, for other C projects to link against.
20
+ Only functions declared with ``@c.export("CName")`` are external symbols; top-level executable statements are not allowed in source.
21
+ - ``output_dir``: the output directory, default ``build``.
22
+ - ``output_name``: the output name template (without extension), default ``${fileName}``.
23
+ The template recognizes only the ``${fileName}`` variable, representing the source file base name (``foo.py`` -> ``foo``);
24
+ an unknown variable name causes compilation to fail. The extension is added by the tool per ``output_type`` (``.c`` / ``.h``).
25
+ - ``output``: write the full ``directory/name`` (relative to ``config_dir``) at once, equivalent to setting
26
+ ``output_dir`` + ``output_name`` together, but in one place.
27
+
28
+ - ``include``: the set of system headers ``#include``d at the top of the generated C, defaulting to all
29
+ 8 system headers the runtime might use (stdio / stdint / inttypes / math / stdbool / stddef / stdlib / string).
30
+ If the user writes it, it **fully replaces** the default set. ``exclude`` subtracts from the final set.
31
+ The compiler will not add any header on its own: if the output actually uses a header that is not in the final set,
32
+ it only prints a hint on stderr and continues generating, leaving it to the user whether to add it back.
33
+ - ``exclude``: header file names removed from the final include set, default empty.
34
+ - ``assets_dir``: a resource directory to be flattened into ``output_dir`` (recursively copied, flattened to the output_dir root).
35
+ Default ``"assets"``; if the directory does not exist, it is silently skipped (no files copied).
36
+
37
+ - ``source``: the entry ``.py``. An explicitly given CLI value has the highest priority; if absent, fall back to this config's
38
+ ``source`` (resolved relative to ``config_dir``); if both are absent, compilation errors. Once ``source`` is written into the config,
39
+ running ``embeddedpy build`` at the project root works without entering the entry file name each time.
40
+
41
+ - ``arena_cap``: the **total** capacity (bytes) of the two static pools for string intermediate values, default 8192, at least 2.
42
+ Adjusting this value scales the two pools proportionally. Embedded targets shrink it per RAM; string-heavy or scientific computing raise it per peak.
43
+ - ``arena_manual_ratio``: the manual pool's (module-level data) proportion of total capacity, a fraction between 0..1,
44
+ default 0.5 (the two pools each take half). At compile time, ``round(arena_cap × arena_manual_ratio)``
45
+ computes the manual pool byte count, the remainder goes to the auto pool, and they are written into the integer macros ``PY_ARENA_MANUAL_CAP`` and
46
+ ``PY_ARENA_AUTO_CAP``; adjusting this value does not change the total RAM budget. Raise it when module-level strings are more numerous,
47
+ lower it when intra-function temporaries are more numerous. The C side can use ``-DPY_ARENA_MANUAL_CAP`` /
48
+ ``-DPY_ARENA_AUTO_CAP`` to override the two pools' capacities independently.
49
+
50
+ - ``link_script``: the linker script path (relative to ``config_dir``, e.g. ``"ld/stm32f4.ld"``).
51
+ The compiler only **validates and copies** it to the output directory; it does not invoke the linker itself. The target board must rely on the linker script
52
+ to specify segment addresses, which the compiler cannot infer, so this item is written by the user.
53
+ - ``link_flags``: an extra-argument list for the link command (e.g. ``["-mcpu=cortex-m4", "-mthumb",
54
+ "-nostartfiles"]``). It is spliced verbatim into the suggested link command printed on stderr; the compiler does not interpret it.
55
+ - ``link_libs``: the list of library names to link (e.g. ``["m", "c"]``), each written as ``-l<name>``.
56
+
57
+ When all three are empty, the link hint is not printed. The compiler does not perform linking--the toolchain, target triple, and startup
58
+ files are decided by the user's build system; here we only summarize the known information into one copyable command.
59
+
60
+ - ``line_output`` / ``output_type`` / ``output`` / ``output_dir`` / ``output_name`` /
61
+ ``include`` / ``exclude`` / ``assets_dir`` / ``source`` /
62
+ ``arena_cap`` / ``arena_manual_ratio`` / ``link_script`` / ``link_flags`` /
63
+ ``link_libs`` -- these 14 items are bidirectionally configurable in both TOML and
64
+ CLI under the same name (snake_case <-> kebab-case), with priority
65
+ defaults < config file < CLI options. The verbs and --help exist only on the
66
+ command line and do not determine the output.
67
+
68
+ The base for relative paths is ``config_dir`` (the config file's directory);
69
+ without a config file it degrades to the source file's directory.
70
+ So writing ``output_dir = "build"`` in the config places the output under
71
+ "project root/build/", no ``../`` needed.
72
+ """
73
+
74
+ import re
75
+ from dataclasses import dataclass, field
76
+ from typing import List, Optional
77
+
78
+ from .runtime_lib import DEFAULT_ARENA_CAP, DEFAULT_MANUAL_RATIO
79
+
80
+ DEFAULT_OUTPUT_DIR = "build"
81
+
82
+ # The two pools' default values are defined only once in runtime_lib; the config layer does not duplicate the numbers:
83
+ # the two capacity macros in the output are always computed on the fly from arena_cap and arena_manual_ratio.
84
+
85
+ # The sole value set for the output role: named by "what this output is for", not by extension.
86
+ # program and library both produce .c; the value distinguishes whether main is present.
87
+ OUTPUT_TYPES = ("program", "header", "library")
88
+
89
+
90
+ @dataclass
91
+ class CompileConfig:
92
+ """Compile configuration: 14 items bidirectionally share names between TOML and CLI, determining output shape, location, and link hints."""
93
+ source: Optional[str] = None # entry .py; CLI > config > (none = error)
94
+ line_output: str = "noline" # noline | line | both
95
+ output_type: str = "program" # program | header | library
96
+ output_dir: str = "build"
97
+ output_name: str = "${fileName}"
98
+ output: Optional[str] = None
99
+ include: List[str] = field( # default = all system headers the runtime might use
100
+ default_factory=lambda: [
101
+ "stdio.h", "stdint.h", "inttypes.h", "math.h",
102
+ "stdbool.h", "stddef.h", "stdlib.h", "string.h",
103
+ ]
104
+ )
105
+ exclude: List[str] = field(default_factory=list)
106
+ assets_dir: str = "assets" # empty / not exist = disabled
107
+ arena_cap: int = DEFAULT_ARENA_CAP # total bytes of the two pools; positive integer
108
+ arena_manual_ratio: float = DEFAULT_MANUAL_RATIO # manual pool proportion; any fraction 0..1
109
+ link_script: str = "" # linker script; only validated + copied, not linked
110
+ link_flags: List[str] = field(default_factory=list)
111
+ link_libs: List[str] = field(default_factory=list)
112
+ config_dir: Optional[str] = None
113
+
114
+ # Only tokens that go into the "printed command" are allowed; no whitespace or shell metacharacters.
115
+ _LINK_TOKEN_RE = re.compile(r"^[A-Za-z0-9_./+=,:+@-]+$")
116
+
117
+ def __post_init__(self) -> None:
118
+ self.validate()
119
+
120
+ def header_guard(self, filename: str) -> str:
121
+ """Derive the include-guard macro name from the output name (``bme280`` -> ``BME280_H``).
122
+
123
+ Both codegen (emitting the guard) and the checker (testing C name occupation) go through here, avoiding two separate derivations.
124
+ """
125
+ source = filename.rsplit("/", 1)[-1].rsplit("\\", 1)[-1]
126
+ source_stem = source.rsplit(".", 1)[0]
127
+ if self.output:
128
+ name = str(self.output)
129
+ elif self.output_name:
130
+ name = self.output_name
131
+ else:
132
+ name = source
133
+ name = name.replace("${fileName}", source_stem)
134
+ name = name.rsplit("/", 1)[-1].rsplit("\\", 1)[-1].rsplit(".", 1)[0]
135
+ if not name or name == "<string>":
136
+ return "EMBEDDEDPY_H"
137
+ chars = [ch if ch.isalnum() else "_" for ch in name.upper()]
138
+ guard = "".join(chars)
139
+ if not guard or not guard[0].isalpha():
140
+ guard = "H_" + guard
141
+ return guard + "_H"
142
+
143
+ def validate(self) -> None:
144
+ """Unified validation after the config is assembled (including TOML / CLI direct assignment)."""
145
+ if self.output_type not in OUTPUT_TYPES:
146
+ raise ValueError(
147
+ "output_type must be one of " + ", ".join(OUTPUT_TYPES)
148
+ )
149
+ if (not isinstance(self.arena_cap, int) or isinstance(self.arena_cap, bool)
150
+ or self.arena_cap < 2):
151
+ raise ValueError("arena_cap must be an integer of at least 2 bytes")
152
+ ratio = self.arena_manual_ratio
153
+ if (isinstance(ratio, bool) or not isinstance(ratio, (int, float))
154
+ or not (0.0 < float(ratio) < 1.0)):
155
+ raise ValueError("arena_manual_ratio must be a number between 0 and 1")
156
+ if not isinstance(self.link_script, str):
157
+ raise ValueError("link_script must be a string path")
158
+ for key in ("link_flags", "link_libs"):
159
+ value = getattr(self, key)
160
+ if not isinstance(value, list) or any(not isinstance(x, str) for x in value):
161
+ raise ValueError(f"{key} must be a list of strings")
162
+ for token in value:
163
+ if not self._LINK_TOKEN_RE.match(token):
164
+ raise ValueError(
165
+ f"{key} token {token!r} contains unsupported characters "
166
+ "(use letters, digits and - _ . / + = , : @)"
167
+ )
168
+
169
+ @property
170
+ def manual_cap(self) -> int:
171
+ """Round the total budget by proportion into the manual pool byte count, written directly into the output capacity macro.
172
+
173
+ The config layer lets the user write any 0..1 fraction, while the output keeps only integers; this is the sole conversion point,
174
+ leaving at least 1 byte at each end so even an extreme proportion never yields a zero-length array.
175
+ """
176
+ n = int(self.arena_cap * float(self.arena_manual_ratio) + 0.5)
177
+ return max(1, min(self.arena_cap - 1, n))
178
+
179
+ @property
180
+ def auto_cap(self) -> int:
181
+ """Auto pool byte count = total budget - manual pool; the two always sum to arena_cap."""
182
+ return self.arena_cap - self.manual_cap
183
+
184
+ @property
185
+ def link_configured(self) -> bool:
186
+ return bool(self.link_script or self.link_flags or self.link_libs)
@@ -0,0 +1,26 @@
1
+ """Compilation diagnostics and exception definitions."""
2
+
3
+ from dataclasses import dataclass
4
+ from typing import List
5
+
6
+
7
+ @dataclass
8
+ class Diagnostic:
9
+ """A single compilation diagnostic."""
10
+
11
+ message: str
12
+ line: int = 0
13
+ col: int = 0
14
+ filename: str = "<unknown>"
15
+ code: str = "error"
16
+
17
+ def format(self) -> str:
18
+ return f"{self.filename}:{self.line}:{self.col}: error: {self.message}"
19
+
20
+
21
+ class CompileError(Exception):
22
+ """Compilation failed, carrying one or more diagnostics."""
23
+
24
+ def __init__(self, diagnostics: List[Diagnostic]) -> None:
25
+ self.diagnostics = list(diagnostics)
26
+ super().__init__("\n".join(d.format() for d in self.diagnostics))
@@ -0,0 +1,381 @@
1
+ """Syntax front end: parse source and run the subset gate check.
2
+
3
+ The gate is only responsible for "structural-level" decisions; type-level
4
+ judgments are made in the checker.
5
+ """
6
+
7
+ import ast
8
+ from typing import Iterator, List, Optional, Tuple
9
+
10
+ from .errors import CompileError, Diagnostic
11
+ from .lang_api import (
12
+ ALLOWED_IMPORT_ROOTS,
13
+ ALLOWED_TOPLEVEL_NAMES,
14
+ category_hint,
15
+ type_import_hint,
16
+ )
17
+
18
+ _BANNED_NODES: List[Tuple[type, str]] = [
19
+ (ast.AsyncFunctionDef, "async functions are not supported"),
20
+ (ast.Lambda, "lambda expressions are not supported"),
21
+ (ast.ListComp, "comprehensions are not supported"),
22
+ (ast.SetComp, "comprehensions are not supported"),
23
+ (ast.DictComp, "comprehensions are not supported"),
24
+ (ast.GeneratorExp, "generator expressions are not supported"),
25
+ (ast.Try, "exception handling (try/except) is not supported"),
26
+ (ast.TryStar, "exception handling (try/except) is not supported"),
27
+ (ast.With, "'with' statements are not supported"),
28
+ (ast.AsyncWith, "'async with' statements are not supported"),
29
+ (ast.Await, "'await' expressions are not supported"),
30
+ (ast.Yield, "'yield' expressions are not supported"),
31
+ (ast.YieldFrom, "'yield from' expressions are not supported"),
32
+ (ast.Raise, "'raise' statements are not supported"),
33
+ (ast.Assert, "'assert' statements are not supported"),
34
+ (ast.Delete, "'del' statements are not supported"),
35
+ (ast.Global, "'global' statements are not supported"),
36
+ (ast.Nonlocal, "'nonlocal' statements are not supported"),
37
+ (ast.Match, "'match' statements are not supported"),
38
+ (ast.Starred, "star-unpacking is not supported"),
39
+ (ast.NamedExpr, "walrus operator (:=) is not supported"),
40
+ (ast.Dict, "dict literals are not supported"),
41
+ (ast.Set, "set literals are not supported"),
42
+ (ast.Tuple, "tuples and multiple assignment targets are not supported"),
43
+ (ast.SetComp, "comprehensions are not supported"),
44
+ (ast.Slice, "slicing is not supported"),
45
+ (ast.AsyncFor, "'async for' loops are not supported"),
46
+ (ast.MatMult, "matrix multiplication (@) is not supported"),
47
+ ]
48
+
49
+ _BANNED_CMP = {
50
+ ast.In: "'in' comparisons are not supported",
51
+ ast.NotIn: "'not in' comparisons are not supported",
52
+ ast.Is: "'is' comparisons are not supported",
53
+ ast.IsNot: "'is not' comparisons are not supported",
54
+ }
55
+
56
+
57
+ def parse_source(source: str, filename: str) -> ast.Module:
58
+ """Parse Python source into an AST; syntax errors are uniformly wrapped as CompileError."""
59
+ try:
60
+ return ast.parse(source, filename=filename)
61
+ except SyntaxError as exc:
62
+ raise CompileError(
63
+ [
64
+ Diagnostic(
65
+ message=f"syntax error: {exc.msg}",
66
+ line=exc.lineno or 0,
67
+ col=exc.offset or 0,
68
+ filename=filename,
69
+ code="syntax",
70
+ )
71
+ ]
72
+ ) from None
73
+
74
+
75
+ def _walk_with_parent(
76
+ node: ast.AST, parent: Optional[ast.AST] = None
77
+ ) -> Iterator[Tuple[ast.AST, Optional[ast.AST]]]:
78
+ yield node, parent
79
+ for child in ast.iter_child_nodes(node):
80
+ yield from _walk_with_parent(child, node)
81
+
82
+
83
+ def _fail(node: ast.AST, filename: str, message: str) -> None:
84
+ raise CompileError(
85
+ [
86
+ Diagnostic(
87
+ message=message,
88
+ line=getattr(node, "lineno", 0),
89
+ col=getattr(node, "col_offset", 0),
90
+ filename=getattr(node, "_embeddedpy_filename", filename),
91
+ code="unsupported",
92
+ )
93
+ ]
94
+ )
95
+
96
+
97
+ def gate(tree: ast.Module, filename: str) -> None:
98
+ """Reject every structure outside the language subset."""
99
+ banned = dict(_BANNED_NODES)
100
+
101
+ for node, parent in _walk_with_parent(tree):
102
+ # The generated C identifier must share the source name, so a non-ASCII
103
+ # name would make the output no longer pure ASCII, which may fail to
104
+ # compile under MSVC / strict C99. The content of string constants is
105
+ # exempt from this restriction.
106
+ for attr in ("id", "name", "arg", "attr", "asname"):
107
+ val = getattr(node, attr, None)
108
+ if isinstance(val, str) and not val.isascii():
109
+ _fail(node, filename, "non-ASCII identifiers are not supported "
110
+ "(generated C names must be ASCII)")
111
+ node_type = type(node)
112
+ if node_type in banned:
113
+ # Tuples in type annotations (e.g. the slice of Func[[a, b], r]) are
114
+ # legal syntax, not runtime tuples, so allow them.
115
+ if node_type is ast.Tuple and isinstance(parent, ast.Subscript):
116
+ continue
117
+ _fail(node, filename, banned[node_type])
118
+
119
+ if isinstance(node, ast.Compare):
120
+ for op in node.ops:
121
+ if type(op) in _BANNED_CMP:
122
+ _fail(node, filename, _BANNED_CMP[type(op)])
123
+
124
+ elif isinstance(node, ast.FunctionDef):
125
+ if isinstance(parent, (ast.FunctionDef, ast.AsyncFunctionDef)):
126
+ _fail(node, filename, "nested functions and closures are not supported")
127
+ for dec in node.decorator_list:
128
+ info = _c_decorator(dec)
129
+ if info is None or info[0] not in _FUNC_DECORATORS:
130
+ _fail(
131
+ node,
132
+ filename,
133
+ "only @c.extern_function, @c.export(...), @c.inline, "
134
+ "@c.section(...), @c.weak, @c.aligned(N) and "
135
+ "@c.visibility(...) decorators are supported on functions",
136
+ )
137
+ name, call = info
138
+ if call is not None and call.keywords:
139
+ _fail(dec, filename, "decorator keyword arguments are not supported")
140
+ if name == "inline" and call is not None:
141
+ _fail(dec, filename, "@c.inline does not take arguments; "
142
+ "write @c.inline without parentheses")
143
+ if name == "section" and (call is None or len(call.args) != 1):
144
+ _fail(
145
+ dec,
146
+ filename,
147
+ "@c.section requires exactly one section name: @c.section(\".ramfunc\")"
148
+ )
149
+ if name == "aligned" and (call is None or len(call.args) != 1 or not _is_int_literal(call.args[0])):
150
+ _fail(dec, filename, "@c.aligned requires exactly one integer width: @c.aligned(16)")
151
+ if name == "weak" and call is not None:
152
+ _fail(dec, filename, "@c.weak does not take arguments; write @c.weak without parentheses")
153
+ if name == "visibility" and (call is None or len(call.args) != 1 or not _is_str_literal(call.args[0])):
154
+ _fail(dec, filename, "@c.visibility requires exactly one string: @c.visibility(\"hidden\")")
155
+ if name == "export" and (call is None or len(call.args) != 1 or not _is_str_literal(call.args[0])):
156
+ _fail(dec, filename, "@c.export requires exactly one C symbol name: @c.export(\"Reset_Handler\")")
157
+ args = node.args
158
+ if args.vararg or args.kwarg:
159
+ _fail(node, filename, "*args / **kwargs are not supported")
160
+ if args.kwonlyargs:
161
+ _fail(node, filename, "keyword-only arguments are not supported")
162
+ if args.defaults or args.kw_defaults:
163
+ _fail(node, filename, "default arguments are not supported")
164
+
165
+ elif isinstance(node, ast.ClassDef):
166
+ if not isinstance(parent, ast.Module):
167
+ _fail(node, filename, "structs must be defined at module top level")
168
+ is_enum = _is_enum_base(node.bases)
169
+ if node.decorator_list:
170
+ if is_enum:
171
+ _fail(node, filename, "enums do not support decorators")
172
+ for dec in node.decorator_list:
173
+ info = _c_decorator(dec)
174
+ if info is None or info[0] not in _CLASS_DECORATORS:
175
+ _fail(
176
+ dec,
177
+ filename,
178
+ "only @c.packed, @c.word(W) and @c.aligned(N) decorators are supported on structs and unions",
179
+ )
180
+ name, call = info
181
+ if call is not None and call.keywords:
182
+ _fail(dec, filename, "decorator keyword arguments are not supported")
183
+ if name == "packed" and call is not None:
184
+ _fail(dec, filename, "@c.packed does not take arguments; write @c.packed without parentheses")
185
+ if name == "word":
186
+ if call is None or len(call.args) != 1:
187
+ _fail(dec, filename, "@c.word requires exactly one width: @c.word(32)")
188
+ if name == "aligned" and (call is None or len(call.args) != 1 or not _is_int_literal(call.args[0])):
189
+ _fail(dec, filename, "@c.aligned requires exactly one integer width: @c.aligned(16)")
190
+ if node.keywords:
191
+ _fail(node, filename, "structs do not support keyword arguments")
192
+ if node.bases:
193
+ if _is_struct_base(node.bases) or _is_union_base(node.bases):
194
+ # Aggregate base class: struct / union both go through the
195
+ # field handling below
196
+ pass
197
+ elif is_enum:
198
+ for item in node.body:
199
+ if (
200
+ isinstance(item, ast.Expr)
201
+ and isinstance(item.value, ast.Constant)
202
+ and isinstance(item.value.value, str)
203
+ ):
204
+ continue # docstring
205
+ if not isinstance(item, ast.Assign):
206
+ _fail(item, filename, "enums may only contain member assignments")
207
+ if len(item.targets) != 1 or not isinstance(item.targets[0], ast.Name):
208
+ _fail(item, filename, "enum members must be plain names")
209
+ continue
210
+ else:
211
+ _fail(node, filename, "structs do not support base classes (inheritance)")
212
+ for item in node.body:
213
+ if (
214
+ isinstance(item, ast.Expr)
215
+ and isinstance(item.value, ast.Constant)
216
+ and isinstance(item.value.value, str)
217
+ ):
218
+ continue # docstring
219
+ if not isinstance(item, ast.AnnAssign):
220
+ _fail(item, filename, "structs may only contain annotated fields")
221
+ if not isinstance(item.target, ast.Name):
222
+ _fail(item, filename, "struct fields must be plain names")
223
+ if item.value is not None:
224
+ _fail(item, filename, "struct fields may not have default values")
225
+
226
+ elif isinstance(node, ast.For):
227
+ if node.orelse:
228
+ _fail(node, filename, "'for ... else' is not supported")
229
+ if not isinstance(node.target, ast.Name):
230
+ _fail(node, filename, "'for' loop target must be a single variable name")
231
+
232
+ elif isinstance(node, ast.While):
233
+ if node.orelse:
234
+ _fail(node, filename, "'while ... else' is not supported")
235
+
236
+ elif isinstance(node, ast.Assign):
237
+ if len(node.targets) != 1:
238
+ _fail(node, filename, "only single-target assignment is supported")
239
+ target = node.targets[0]
240
+ # Allowed: variable name, struct field access (obj.field), pointer
241
+ # dereference (p[0])
242
+ if not isinstance(target, (ast.Name, ast.Attribute, ast.Subscript)):
243
+ _fail(node, filename, "only single-target assignment is supported")
244
+
245
+ elif isinstance(node, ast.AnnAssign):
246
+ if not isinstance(node.target, ast.Name):
247
+ _fail(node, filename, "annotated assignment target must be a variable name")
248
+ # Struct field annotations and module-level variable declarations may
249
+ # have no initializer: the latter corresponds to a C static object
250
+ # (.bss / .noinit); its definition is emitted by the file-header
251
+ # global declaration, and main does not assign to it.
252
+ if node.value is None and not isinstance(parent, (ast.ClassDef, ast.Module)):
253
+ _fail(node, filename, "annotated assignment must include an initializer")
254
+
255
+ elif isinstance(node, ast.AugAssign):
256
+ # Allowed: variable name, pointer dereference (p[0] += 1)
257
+ if not isinstance(node.target, (ast.Name, ast.Subscript)):
258
+ _fail(node, filename, "augmented assignment target must be a variable name or pointer subscript")
259
+
260
+ elif isinstance(node, (ast.Import, ast.ImportFrom)):
261
+ if not isinstance(parent, ast.Module):
262
+ _fail(node, filename, "imports are only allowed at module top level")
263
+ _check_import(node, filename)
264
+
265
+
266
+ def _is_enum_base(bases: List[ast.expr]) -> bool:
267
+ """Determine whether the base-class list is the enum base class (Enum)."""
268
+ if len(bases) != 1:
269
+ return False
270
+ base = bases[0]
271
+ return isinstance(base, ast.Name) and base.id == "Enum"
272
+
273
+
274
+ def _is_struct_base(bases) -> bool:
275
+ """Determine whether the base class contains only embeddedpy.Struct (struct base class)."""
276
+ if len(bases) != 1:
277
+ return False
278
+ base = bases[0]
279
+ return isinstance(base, ast.Name) and base.id == "Struct"
280
+
281
+
282
+ def _is_union_base(bases) -> bool:
283
+ """Determine whether the base class contains only embeddedpy.Union (union base class)."""
284
+ if len(bases) != 1:
285
+ return False
286
+ base = bases[0]
287
+ return isinstance(base, ast.Name) and base.id == "Union"
288
+
289
+
290
+ # Members of the c namespace allowed as declaration modifiers. Decorators only
291
+ # change output attributes and produce no Python value, so they are uniformly
292
+ # allowed at the gate layer via a name whitelist, with per-member shape
293
+ # constraints checked right after.
294
+ _FUNC_DECORATORS = frozenset(
295
+ {"extern_function", "export", "inline", "section", "weak", "aligned", "visibility"}
296
+ )
297
+ _CLASS_DECORATORS = frozenset({"packed", "word", "aligned"})
298
+
299
+
300
+ def _c_decorator(node: ast.AST) -> Optional[Tuple[str, Optional[ast.Call]]]:
301
+ """Recognize ``@c.xxx`` / ``@c.xxx(...)``, returning (member name, Call node or None)."""
302
+ call = node if isinstance(node, ast.Call) else None
303
+ target = node.func if isinstance(node, ast.Call) else node
304
+ if not (
305
+ isinstance(target, ast.Attribute)
306
+ and isinstance(target.value, ast.Name)
307
+ and target.value.id == "c"
308
+ ):
309
+ return None
310
+ return target.attr, call
311
+
312
+
313
+ def _is_int_literal(node: ast.AST) -> bool:
314
+ """Determine whether a node is a positive integer literal (excluding bool)."""
315
+ return (
316
+ isinstance(node, ast.Constant)
317
+ and isinstance(node.value, int)
318
+ and not isinstance(node.value, bool)
319
+ and node.value > 0
320
+ )
321
+
322
+
323
+ def _is_str_literal(node: ast.AST) -> bool:
324
+ """Determine whether a node is a string literal."""
325
+ return isinstance(node, ast.Constant) and isinstance(node.value, str)
326
+
327
+
328
+ def _is_c_extern_decorator(node: ast.AST) -> bool:
329
+ """Determine whether the decorator is @c.extern_function (with or without arguments)."""
330
+ target = node.func if isinstance(node, ast.Call) else node
331
+ return (
332
+ isinstance(target, ast.Attribute)
333
+ and target.attr == "extern_function"
334
+ and isinstance(target.value, ast.Name)
335
+ and target.value.id == "c"
336
+ )
337
+
338
+
339
+ def _check_import(node: ast.AST, filename: str) -> None:
340
+ if isinstance(node, ast.Import):
341
+ for alias in node.names:
342
+ if alias.name not in ALLOWED_IMPORT_ROOTS:
343
+ _fail(
344
+ node,
345
+ filename,
346
+ f"can only import from embeddedpy category modules ({category_hint()}); cannot import {alias.name}",
347
+ )
348
+ elif isinstance(node, ast.ImportFrom):
349
+ module = node.module or ""
350
+ if node.level != 0:
351
+ _fail(
352
+ node,
353
+ filename,
354
+ "relative imports require a package project; use compile_file() "
355
+ "with the entry .py file (compile_source() has no file system context)",
356
+ )
357
+ elif module == "embeddedpy":
358
+ # All types are provided by embeddedpy.types; the top-level embeddedpy
359
+ # accepts no names.
360
+ for alias in node.names:
361
+ if alias.name == "*":
362
+ _fail(node, filename, "star imports (import *) are not supported")
363
+ if alias.name not in ALLOWED_TOPLEVEL_NAMES:
364
+ _fail(
365
+ node,
366
+ filename,
367
+ f"cannot import {alias.name!r} from embeddedpy; "
368
+ f"import it from its category module instead "
369
+ f"({type_import_hint(alias.name)})",
370
+ )
371
+ elif module not in ALLOWED_IMPORT_ROOTS:
372
+ _fail(
373
+ node,
374
+ filename,
375
+ f"can only import from embeddedpy category modules ({category_hint()}); "
376
+ f"cannot import from {module or '.'}",
377
+ )
378
+ else:
379
+ for alias in node.names:
380
+ if alias.name == "*":
381
+ _fail(node, filename, "star imports (import *) are not supported")