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,310 @@
1
+ """Command-line entry point.
2
+
3
+ Only produces C code (a .c source file or a .h header) and invokes no C compiler.
4
+ Imports resolve from the project root, not from command-line arguments.
5
+ The compilation shape is controlled by CompileConfig, read from the ``[tool.embeddedpy]``
6
+ section of ``pyproject.toml`` at the project root (TOML format), and can also be
7
+ overridden item by item by command-line options.
8
+
9
+ Command structure (the verb must be written explicitly; there is no default action):
10
+
11
+ embeddedpy build [SOURCE] [options] compile entry to C
12
+ embeddedpy check [SOURCE] [options] check only, write no files
13
+ embeddedpy --help help
14
+
15
+ Any config that determines the output content / location / destination is
16
+ configurable in both directions under the same name in TOML and the CLI
17
+ (snake_case <-> kebab-case): source / line_output / output_type / output /
18
+ output_dir / output_name / include / exclude / assets_dir / arena_cap /
19
+ arena_manual_ratio / link_script / link_flags / link_libs.
20
+ The verbs and --help exist only on the command line and do not determine the output.
21
+ """
22
+
23
+ import argparse
24
+ import sys
25
+ from pathlib import Path
26
+ from typing import List, Optional
27
+
28
+ from . import api
29
+ from .config import OUTPUT_TYPES, CompileConfig
30
+ from .errors import CompileError
31
+
32
+
33
+ def _add_common_options(p: argparse.ArgumentParser) -> None:
34
+ """The same set of options shared by build / check: one name per config item, no short options."""
35
+ p.add_argument("--help", action="help", help="show this help message and exit")
36
+ p.add_argument(
37
+ "source",
38
+ nargs="?",
39
+ help="entry .py file; may be omitted if 'source' is set in [tool.embeddedpy]",
40
+ )
41
+ p.add_argument(
42
+ "--line-output",
43
+ choices=["noline", "line", "both"],
44
+ help="override line_output (default: from [tool.embeddedpy])",
45
+ )
46
+ p.add_argument(
47
+ "--output-type",
48
+ choices=OUTPUT_TYPES,
49
+ dest="output_type",
50
+ help=("output role: program = standalone .c with main, "
51
+ "header = declarations-only .h, library = linkable .c without main"),
52
+ )
53
+ p.add_argument(
54
+ "--output",
55
+ metavar="PATH",
56
+ help="full output path; overrides output and output_dir / output_name",
57
+ )
58
+ p.add_argument("--output-dir", metavar="DIR", help="output directory")
59
+ p.add_argument(
60
+ "--output-name",
61
+ metavar="NAME",
62
+ help="output name template (supports ${fileName})",
63
+ )
64
+ p.add_argument(
65
+ "--include",
66
+ action="append",
67
+ metavar="HEADER",
68
+ help="system header to include; repeatable, replaces the whole include set",
69
+ )
70
+ p.add_argument(
71
+ "--exclude",
72
+ action="append",
73
+ metavar="HEADER",
74
+ help="header to remove from the include set; repeatable, replaces the whole set",
75
+ )
76
+ p.add_argument("--assets-dir", metavar="DIR", help="assets directory to flatten into output_dir")
77
+ p.add_argument(
78
+ "--arena-cap",
79
+ type=int,
80
+ metavar="N",
81
+ help="total size in bytes of the two scratch pools; must be an integer of at least 2",
82
+ )
83
+ p.add_argument(
84
+ "--arena-manual-ratio",
85
+ type=float,
86
+ metavar="R",
87
+ help="share of arena_cap given to the manual pool; a number between 0 and 1 (default 0.5)",
88
+ )
89
+ p.add_argument(
90
+ "--link-script",
91
+ metavar="PATH",
92
+ help="linker script to validate and copy next to the generated C",
93
+ )
94
+ p.add_argument(
95
+ "--link-flags",
96
+ action="append",
97
+ metavar="FLAG",
98
+ help="extra link flag; repeatable, replaces the whole set",
99
+ )
100
+ p.add_argument(
101
+ "--link-libs",
102
+ action="append",
103
+ metavar="LIB",
104
+ help="library name to link (printed as -lLIB); repeatable, replaces the whole set",
105
+ )
106
+
107
+
108
+ def _make_parser(command: str) -> argparse.ArgumentParser:
109
+ description = (
110
+ "Compile a statically-typed subset of Python into C"
111
+ if command == "build"
112
+ else "Only run subset and type checks; write no files"
113
+ )
114
+ p = argparse.ArgumentParser(
115
+ prog=f"embeddedpy {command}",
116
+ description=description,
117
+ add_help=False,
118
+ )
119
+ _add_common_options(p)
120
+ return p
121
+
122
+
123
+ def _print_usage() -> None:
124
+ print(
125
+ "usage:\n"
126
+ " embeddedpy build [SOURCE] [options] compile entry to C\n"
127
+ " embeddedpy check [SOURCE] [options] check only, write no files\n"
128
+ " embeddedpy --help show this help\n"
129
+ "\n"
130
+ "run 'embeddedpy build --help' for the full option list\n"
131
+ "\n"
132
+ "[tool.embeddedpy] key CLI option\n"
133
+ " source SOURCE (positional)\n"
134
+ " line_output --line-output {noline,line,both}\n"
135
+ " output_type --output-type {program,header,library}\n"
136
+ " output --output PATH\n"
137
+ " output_dir --output-dir DIR\n"
138
+ " output_name --output-name NAME\n"
139
+ " include --include HEADER (repeatable)\n"
140
+ " exclude --exclude HEADER (repeatable)\n"
141
+ " assets_dir --assets-dir DIR\n"
142
+ " arena_cap --arena-cap N\n"
143
+ " arena_manual_ratio --arena-manual-ratio R (0 < R < 1)\n"
144
+ " link_script --link-script PATH\n"
145
+ " link_flags --link-flags FLAG (repeatable)\n"
146
+ " link_libs --link-libs LIB (repeatable)\n"
147
+ "\n"
148
+ "Config: [tool.embeddedpy] in pyproject.toml at the project root.\n"
149
+ "Priority: defaults < config file < CLI options."
150
+ )
151
+
152
+
153
+ def _config_root(start: Path) -> Path:
154
+ # Project root: when the entry sits in an __init__.py package chain take the outermost package's parent, otherwise the entry's own directory; with no entry take the current working directory.
155
+ # A file start (an entry) walks up the package chain; a directory start (no entry, source comes from the config) is used directly.
156
+ if start.is_file():
157
+ cur = start.parent.resolve()
158
+ while (cur / "__init__.py").is_file():
159
+ cur = cur.parent
160
+ return cur
161
+ return start.resolve()
162
+
163
+
164
+ def _load_config(start: Path, parser: argparse.ArgumentParser) -> CompileConfig:
165
+ """Assemble CompileConfig by priority: defaults < config file < CLI options.
166
+
167
+ ``start`` is the entry file path (when an entry is given) or the current working
168
+ directory (when no entry is given and source comes from the config).
169
+ The config is read only from the ``[tool.embeddedpy]`` section of ``pyproject.toml``
170
+ at the project root; if it is not found there, no further lookup is done.
171
+
172
+ Relative paths (output / output_dir / assets_dir / source) are based on the
173
+ **directory containing the config file**, so writing ``output_dir = "build"``
174
+ means "project-root/build/", with no ``../`` needed.
175
+ """
176
+ config = CompileConfig()
177
+ cand = _config_root(start) / "pyproject.toml"
178
+ path: Optional[Path] = cand if cand.is_file() else None
179
+ if path is not None:
180
+ import tomllib
181
+ try:
182
+ with path.open("rb") as fh:
183
+ data = tomllib.load(fh)
184
+ except Exception as exc: # noqa: BLE001
185
+ parser.error(f"failed to parse config file {path}: {exc}")
186
+ section = data.get("tool", {}).get("embeddedpy", {})
187
+ if "source" in section:
188
+ config.source = str(section["source"])
189
+ if "line_output" in section:
190
+ config.line_output = str(section["line_output"])
191
+ if "output_dir" in section:
192
+ config.output_dir = str(section["output_dir"])
193
+ if "output_name" in section:
194
+ config.output_name = str(section["output_name"])
195
+ if "output" in section:
196
+ config.output = str(section["output"])
197
+ if "include" in section:
198
+ config.include = [str(x) for x in section["include"]]
199
+ if "exclude" in section:
200
+ config.exclude = [str(x) for x in section["exclude"]]
201
+ if "assets_dir" in section:
202
+ config.assets_dir = str(section["assets_dir"])
203
+ if "output_type" in section:
204
+ config.output_type = str(section["output_type"])
205
+ if "arena_cap" in section:
206
+ config.arena_cap = section["arena_cap"]
207
+ if "arena_manual_ratio" in section:
208
+ config.arena_manual_ratio = section["arena_manual_ratio"]
209
+ if "link_script" in section:
210
+ config.link_script = str(section["link_script"])
211
+ if "link_flags" in section:
212
+ config.link_flags = [str(x) for x in section["link_flags"]]
213
+ if "link_libs" in section:
214
+ config.link_libs = [str(x) for x in section["link_libs"]]
215
+ # Base for relative paths: the directory containing the config file
216
+ config.config_dir = str(path.parent.resolve())
217
+ return config
218
+
219
+
220
+ def _apply_cli_overrides(config: CompileConfig, args: argparse.Namespace) -> None:
221
+ """CLI flags are uniformly written into the same config object, then consumed through api's single channel."""
222
+ for key in (
223
+ "line_output",
224
+ "output_type",
225
+ "output",
226
+ "output_dir",
227
+ "output_name",
228
+ "include",
229
+ "exclude",
230
+ "assets_dir",
231
+ "arena_cap",
232
+ "arena_manual_ratio",
233
+ "link_script",
234
+ "link_flags",
235
+ "link_libs",
236
+ ):
237
+ value = getattr(args, key)
238
+ if value is not None:
239
+ setattr(config, key, list(value) if isinstance(value, list) else value)
240
+
241
+
242
+ def main(argv: Optional[List[str]] = None) -> int:
243
+ """Command-line entry point: parse the ``build`` / ``check`` verb and options, returning the process exit code."""
244
+ argv = sys.argv[1:] if argv is None else list(argv)
245
+
246
+ if argv and argv[0] == "--help":
247
+ _print_usage()
248
+ return 0
249
+ if not argv or argv[0] not in ("build", "check"):
250
+ print(
251
+ "error: a command is required (build or check)\n"
252
+ " embeddedpy build [SOURCE] [options]\n"
253
+ " embeddedpy check [SOURCE] [options]\n"
254
+ " embeddedpy --help",
255
+ file=sys.stderr,
256
+ )
257
+ return 2
258
+
259
+ command, rest = argv[0], argv[1:]
260
+ parser = _make_parser(command)
261
+ args = parser.parse_args(rest)
262
+
263
+ # Config lookup start: with an entry pass the entry file itself (the project root is derived from it); with no entry pass the current working directory (source comes from the config).
264
+ source_path = Path(args.source) if args.source else None
265
+ start = source_path if source_path is not None else Path.cwd()
266
+ config = _load_config(start, parser)
267
+
268
+ # Entry file: command line > config source > error
269
+ if source_path is None:
270
+ if not config.source:
271
+ parser.error(
272
+ "missing source file (pass it as an argument or set 'source' in [tool.embeddedpy])"
273
+ )
274
+ base = Path(config.config_dir) if config.config_dir else Path.cwd()
275
+ src = config.source
276
+ effective_source = str(base / src) if not Path(src).is_absolute() else src
277
+ source_path = Path(effective_source)
278
+
279
+ _apply_cli_overrides(config, args)
280
+ try:
281
+ api.validate_link_config(config, source_path)
282
+ except ValueError as exc:
283
+ parser.error(str(exc))
284
+ except CompileError as exc:
285
+ for diag in exc.diagnostics:
286
+ print(diag.format(), file=sys.stderr)
287
+ return 2
288
+
289
+ if command == "check":
290
+ diagnostics = api.check_file(source_path, config=config)
291
+ if not diagnostics:
292
+ return 0
293
+ for diag in diagnostics:
294
+ print(diag.format(), file=sys.stderr)
295
+ return 2
296
+
297
+ try:
298
+ targets = api.compile_file(source_path, config=config)
299
+ except CompileError as exc:
300
+ for diag in exc.diagnostics:
301
+ print(diag.format(), file=sys.stderr)
302
+ return 2
303
+
304
+ for t in targets:
305
+ print(f"generated {t}", file=sys.stderr)
306
+ return 0
307
+
308
+
309
+ if __name__ == "__main__":
310
+ sys.exit(main())