embeddedpy 0.1.0__tar.gz

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.

Files changed (38) hide show
  1. embeddedpy-0.1.0/LICENSE +21 -0
  2. embeddedpy-0.1.0/PKG-INFO +258 -0
  3. embeddedpy-0.1.0/README.md +239 -0
  4. embeddedpy-0.1.0/pyproject.toml +31 -0
  5. embeddedpy-0.1.0/setup.cfg +4 -0
  6. embeddedpy-0.1.0/src/embeddedpy/__init__.py +55 -0
  7. embeddedpy-0.1.0/src/embeddedpy/arrays.py +142 -0
  8. embeddedpy-0.1.0/src/embeddedpy/bytes.py +65 -0
  9. embeddedpy-0.1.0/src/embeddedpy/compiler/__init__.py +55 -0
  10. embeddedpy-0.1.0/src/embeddedpy/compiler/__main__.py +8 -0
  11. embeddedpy-0.1.0/src/embeddedpy/compiler/api.py +337 -0
  12. embeddedpy-0.1.0/src/embeddedpy/compiler/cgen_helpers.py +298 -0
  13. embeddedpy-0.1.0/src/embeddedpy/compiler/checker.py +244 -0
  14. embeddedpy-0.1.0/src/embeddedpy/compiler/checker_pass1.py +3229 -0
  15. embeddedpy-0.1.0/src/embeddedpy/compiler/checker_pass2.py +1879 -0
  16. embeddedpy-0.1.0/src/embeddedpy/compiler/cli.py +310 -0
  17. embeddedpy-0.1.0/src/embeddedpy/compiler/codegen.py +2407 -0
  18. embeddedpy-0.1.0/src/embeddedpy/compiler/config.py +186 -0
  19. embeddedpy-0.1.0/src/embeddedpy/compiler/errors.py +26 -0
  20. embeddedpy-0.1.0/src/embeddedpy/compiler/frontend.py +381 -0
  21. embeddedpy-0.1.0/src/embeddedpy/compiler/irtypes.py +663 -0
  22. embeddedpy-0.1.0/src/embeddedpy/compiler/lang_api.py +163 -0
  23. embeddedpy-0.1.0/src/embeddedpy/compiler/modules.py +583 -0
  24. embeddedpy-0.1.0/src/embeddedpy/compiler/preprocessor.py +364 -0
  25. embeddedpy-0.1.0/src/embeddedpy/compiler/runtime_lib.py +1395 -0
  26. embeddedpy-0.1.0/src/embeddedpy/compiler/type_symbols.py +278 -0
  27. embeddedpy-0.1.0/src/embeddedpy/enums.py +20 -0
  28. embeddedpy-0.1.0/src/embeddedpy/interop.py +444 -0
  29. embeddedpy-0.1.0/src/embeddedpy/io.py +119 -0
  30. embeddedpy-0.1.0/src/embeddedpy/memory.py +196 -0
  31. embeddedpy-0.1.0/src/embeddedpy/pointers.py +552 -0
  32. embeddedpy-0.1.0/src/embeddedpy/strings.py +68 -0
  33. embeddedpy-0.1.0/src/embeddedpy/types.py +510 -0
  34. embeddedpy-0.1.0/src/embeddedpy.egg-info/PKG-INFO +258 -0
  35. embeddedpy-0.1.0/src/embeddedpy.egg-info/SOURCES.txt +36 -0
  36. embeddedpy-0.1.0/src/embeddedpy.egg-info/dependency_links.txt +1 -0
  37. embeddedpy-0.1.0/src/embeddedpy.egg-info/entry_points.txt +2 -0
  38. embeddedpy-0.1.0/src/embeddedpy.egg-info/top_level.txt +1 -0
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) lubanqihao9875
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,258 @@
1
+ Metadata-Version: 2.4
2
+ Name: embeddedpy
3
+ Version: 0.1.0
4
+ Summary: Write complete C99 using valid Python syntax: compile .py source into full C source files, declaration headers, or linkable libraries — the same program also runs directly under CPython
5
+ Author: lubanqihao9875
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/lubanqihao9875/embeddedpy
8
+ Project-URL: Documentation, https://lubanqihao9875.github.io/embeddedpyDocs
9
+ Project-URL: Repository, https://github.com/lubanqihao9875/embeddedpy
10
+ Project-URL: Issues, https://github.com/lubanqihao9875/embeddedpy/issues
11
+ Keywords: compiler,c,c99,embedded,python-to-c,codegen
12
+ Classifier: Programming Language :: Python :: 3
13
+ Classifier: Operating System :: OS Independent
14
+ Classifier: Topic :: Software Development :: Code Generators
15
+ Requires-Python: >=3.12
16
+ Description-Content-Type: text/markdown
17
+ License-File: LICENSE
18
+ Dynamic: license-file
19
+
20
+ # embeddedpy
21
+
22
+ Write **C99** using **Python syntax**.
23
+
24
+ Source is `.py`: types are imported from `embeddedpy.types`, pointers and memory use a purely functional API, C declaration qualifiers are written as decorators, and preprocessing is written as Python conditional expressions and module-level calls. The compiler turns this source into portable C99 code (a complete program, a declaration header, or a linkable library), where every type definition and every layout is determined solely by the information you write.
25
+
26
+ Overall principle: **only information known to the user should be written by the user, and written only once**; anything that can be derived from what is already written is computed by the compiler. Every C capability must have a Python shape: operators/expressions go through module functions or methods, declaration qualifiers go through decorators, type construction goes through base classes and parameterized types, preprocessing/text-layer goes through module-level calls; `c.emit(...)` is used for the long tail of C constructs that have no dedicated shape.
27
+
28
+ ## Features
29
+
30
+ - Fixed-width numeric types: `int8/16/32/64`, `uint8/16/32/64`, `float32/64`
31
+ - Single-byte characters: `char` / `schar` / `uchar`
32
+ - Fixed-length arrays: `Array[T]` + `make_array(T, N)`; the length is not part of the type
33
+ - Purely functional pointer API: `ptr.ref / peek / poke / skip / field / cast / from_int`
34
+ - Heap memory: `mem.alloc / free / realloc`; string/byte intermediate values go through two static pools each with an independent upper bound; the total size `arena_cap` and the allocation ratio `arena_manual_ratio` (0..1) are configurable. The automatic pool (frame-based rollback inside function bodies, return-value ownership moved up to the caller) and the manual pool (module-level data, cleared only by `mem.arena_reset()` and not affecting in-function data) have independent capacities
35
+ - Aggregate types: whole-assignment `b = a` is rejected at compile time; an independent copy uses `copy_aggregate`; arrays / structs land in compile-time fixed-size C objects, not in the arena and not on the heap
36
+ - Aggregate types: `Struct` / `Union` / `Bits[N]`; `@c.packed` and `@c.word(W)` determine layout; storage type and padding are computed by the compiler
37
+ - Declaration qualifiers: `@c.inline` / `@c.section("...")` / `@c.aligned(N)` / `@c.weak` / `@c.visibility("...")` / `@c.extern_function`
38
+ - C interop: `c.include("x.h")`, `c.extern_type("T")`, `c.typedef(...)`, `c.define(...)`
39
+ - Conditional compilation: `if c.defined("X") and c.macro("V") >= 2:` / `elif` / `else` generate `#if / #elif / #else / #endif`; `c.define / c.include` inside the block are emitted in place; `c.pragma / error / warning / undef` are named single-line directives, and `c.emit(...)` is the long-tail fallback
40
+ - Byte strings: `b"..."`, `b[0]` yields `uchar` (keeps the byte form, does not participate in arithmetic); an explicit `uint8(b[0])` is needed for numeric use, used for protocol / text parsing
41
+ - Enums: `class Mode(Enum)` + `auto()`, members can serve as the compile-time length for `make_array`
42
+ - Modifiers: `const[T]` / `volatile[T]` (written in annotations); `sizeof(T)` generates a real `sizeof`
43
+ - Bit builtins and barriers: `c.clz / ctz / popcount` use GCC / Clang's `__builtin_*`; `c.barrier()` emits a compiler barrier
44
+
45
+ ## Installation
46
+
47
+ ```bash
48
+ pip install embeddedpy
49
+ ```
50
+
51
+ ## Quick Start
52
+
53
+ Write a `hello.py`:
54
+
55
+ ```python
56
+ from embeddedpy.types import int32
57
+
58
+ def add(a: int32, b: int32) -> int32:
59
+ return a + b
60
+
61
+ result: int32 = add(2, 3)
62
+ print("2 + 3 =", result)
63
+ ```
64
+
65
+ The same file can be run directly or compiled to C:
66
+
67
+ ```bash
68
+ python hello.py # CPython track
69
+ embeddedpy build hello.py # generate C source file
70
+ embeddedpy check hello.py # check only, no file written
71
+ ```
72
+
73
+ The output form is chosen by `output_type`: `program`, `header`, `library`.
74
+
75
+ ## Import by Category
76
+
77
+ Language symbols are split into modules by purpose, one category per line, so you can tell at a glance what each is:
78
+
79
+ ```python
80
+ from embeddedpy.types import int32, uint8 # fixed-width scalars
81
+ from embeddedpy.types import Ptr, Func, Struct, Union, Bits # type construction
82
+ from embeddedpy.types import Enum, const, volatile # enums and qualifiers
83
+ from embeddedpy.arrays import make_array # fixed-length arrays
84
+ from embeddedpy.pointers import ptr # pointer API
85
+ from embeddedpy.enums import auto # enum auto-increment
86
+ from embeddedpy.memory import mem, sizeof # heap memory and type sizing
87
+ from embeddedpy.memory import copy_aggregate # aggregate type copies
88
+ from embeddedpy.io import io, File # file I/O
89
+ from embeddedpy.strings import strings # text buffers
90
+ from embeddedpy.interop import c # C interop
91
+ ```
92
+
93
+ The compiler validates imported names per module: writing `from embeddedpy.arrays import int32` raises `embeddedpy.arrays has no attribute named int32`; names from different categories are never mixed.
94
+
95
+ ## Two Top-Level Packages: Language Library / Compiler
96
+
97
+ A single distribution ships both the **library** and the **command**, but the source tree is split into two top-level packages:
98
+
99
+ | Package | What it is | Used by |
100
+ |---|---|---|
101
+ | `embeddedpy` | **Language library**: the category modules above | User source via `from embeddedpy.types import int32` |
102
+ | `embeddedpy.compiler` | **Compiler**: gates, type checking, code generation, CLI | Command `embeddedpy` / `python -m embeddedpy.compiler`, and host programs |
103
+
104
+ The dependency direction is "compiler → language library"; the language library does not import the compiler — names imported via `from embeddedpy...` belong to the language semantics layer and do not expose the compiler's internals.
105
+
106
+ Host program (using the compiler as a library):
107
+
108
+ ```python
109
+ from embeddedpy.compiler import compile_file, check_source, CompileConfig
110
+ ```
111
+
112
+ Compile to C:
113
+
114
+ ```bash
115
+ embeddedpy build hello.py # writes to build/hello.c by default
116
+ embeddedpy build hello.py --output out.c # specify output
117
+ embeddedpy check hello.py # language and type checking only (no file written)
118
+ embeddedpy build --help # list all options
119
+ ```
120
+
121
+ ## Multi-File Projects
122
+
123
+ Multi-file projects are organized with `import`, and namespaces are automatically isolated. Imports resolve from a single project root: for a flat project it is the entry file's directory; for a package project it is derived from the consecutive `__init__.py` chain (the top-level package's parent directory). A dotted name maps to the directory levels under that root, so `lib/filters.py` is imported as `lib.filters`.
124
+
125
+ Flat sibling modules:
126
+
127
+ ```python
128
+ # multi_sensor.py
129
+ from embeddedpy.types import int32
130
+ def read(p: int32) -> int32:
131
+ return p + 1
132
+ ```
133
+ ```python
134
+ # main.py
135
+ import multi_sensor
136
+ from embeddedpy.types import int32
137
+ result: int32 = multi_sensor.read(41)
138
+ print("multi_sensor.read(41) =", result)
139
+ ```
140
+
141
+ Modules under a subdirectory are imported by dotted path; `lib/filters.py` becomes `import lib.filters`:
142
+
143
+ ```python
144
+ # lib/filters.py
145
+ from embeddedpy.types import int32
146
+ def smooth(v: int32) -> int32:
147
+ return v * 2
148
+ ```
149
+ ```python
150
+ # main.py
151
+ import lib.filters
152
+ from embeddedpy.types import int32
153
+ result: int32 = lib.filters.smooth(3)
154
+ print("lib.filters.smooth(3) =", result)
155
+ ```
156
+
157
+ The compiler inlines all modules into **the same `.c`**: symbols from imported modules are prefixed with the module key (the dotted path relative to the project root, joined with `__`), combined with the purpose prefix into `f_lib__filters__smooth` / `f_multi_sensor__read` (global variables use the `g_` prefix); the entry module gets no module prefix (the entry module's **top-level statements** are inlined into C's `int main()`). `__` is the module namespace separator; directory names, module names and top-level definition names must not contain it.
158
+
159
+ Importing a module checks it in full, but the generated C keeps only the top-level functions: `main`, functions referenced by top-level statements, `@c.export` / `@c.extern_function` / `@c.weak` functions, and all the functions they call transitively; the rest are not written into the `.c`. Removal happens after type checking (so type errors in removed functions are still reported), and the whole pass is skipped if the source uses `c.emit` / `c.asm` / `c.goto` / `c.label` — the AST cannot see symbol names embedded in strings, so removal cannot be guaranteed safe.
160
+
161
+ ## Configurable Build Form
162
+
163
+ What form the compiler produces is decided by `CompileConfig`. There are only three entry points, and the **verb must be written explicitly**:
164
+
165
+ ```bash
166
+ embeddedpy build [SOURCE] [options] # compile entry to C
167
+ embeddedpy check [SOURCE] [options] # check only, no file written
168
+ embeddedpy --help # help (embeddedpy build --help lists all options)
169
+ ```
170
+
171
+ Options have **only long names, no short options** (no `-o` / `-h`).
172
+
173
+ The 14 settings that determine the output are **configurable in both directions and share the same names** between TOML and the command line: TOML uses snake_case, the command line uses kebab-case.
174
+
175
+ | `[tool.embeddedpy]` key | command line |
176
+ |---|---|
177
+ | `source` | positional argument `SOURCE` |
178
+ | `line_output` | `--line-output {noline,line,both}` |
179
+ | `output_type` | `--output-type {program,header,library}` |
180
+ | `output` | `--output PATH` |
181
+ | `output_dir` | `--output-dir DIR` |
182
+ | `output_name` | `--output-name NAME` |
183
+ | `include` | `--include HEADER` (repeatable) |
184
+ | `exclude` | `--exclude HEADER` (repeatable) |
185
+ | `assets_dir` | `--assets-dir DIR` |
186
+ | `arena_cap` | `--arena-cap N` |
187
+ | `arena_manual_ratio` | `--arena-manual-ratio R` |
188
+ | `link_script` | `--link-script PATH` |
189
+ | `link_flags` | `--link-flags FLAG` (repeatable) |
190
+ | `link_libs` | `--link-libs LIB` (repeatable) |
191
+
192
+ `link_script` points to the link script: the compiler only checks that it exists and copies it to the output directory; after a successful `build` it prints a copyable link command to stderr (`link_flags` / `link_libs` are spliced in, and the compiler is specified by the `CC` environment variable, defaulting to `cc`). **The compiler does not run linking**; when all three are empty, no hint is printed.
193
+
194
+ For the array-typed `include` / `exclude` / `link_flags` / `link_libs`, providing them on the command line **replaces** the array in the config wholesale rather than appending; if `output` is set then `output_dir` / `output_name` are ignored. `check` and `build` share the same options and the same config, except `check` ignores keys unrelated to output (without error).
195
+
196
+ ```bash
197
+ embeddedpy build hello.py --line-output noline # don't write #line directives, produce clean C
198
+ embeddedpy build hello.py --output-dir out # override output directory
199
+ embeddedpy build hello.py --output-name demo # override output name
200
+ ```
201
+
202
+ The compiler reads only the `[tool.embeddedpy]` section of `pyproject.toml` at the project root; if it is not found there, no further lookup is done. Priority: **default < config file < command-line options**.
203
+
204
+ ```toml
205
+ [tool.embeddedpy]
206
+ line_output = "line" # noline | line | both
207
+ output_type = "program" # program = complete program, header = declaration set, library = linkable implementation
208
+
209
+ # output location: directory and name can be configured separately or together
210
+ output_dir = "build" # directory (defaults to build)
211
+ output_name = "hello" # name, without .c (defaults to the source file name)
212
+ # output = "build/hello.c" # or write the full path at once
213
+
214
+ # include = ["stdio.h", "stdint.h"] # 8 system headers by default; setting this replaces them wholesale
215
+ # exclude = ["math.h"] # removed from the final set
216
+ # arena_cap = 8192 # total bytes for both pools; lower for embedded, higher for string-heavy use
217
+ # arena_manual_ratio = 0.5 # manual-pool fraction (0..1); changing it only adjusts allocation, total RAM unchanged
218
+ # link_script = "ld/stm32f4.ld" # link script: only validated + copied, not linked by the compiler
219
+ # link_flags = ["-mcpu=cortex-m4", "-mthumb", "-nostartfiles"]
220
+ # link_libs = ["m"] # written as -lm each
221
+ ```
222
+
223
+ **Relative paths are based on the "config file's directory"**, so `output_dir = "build"` means "project_root/build/", without awkward `../` paths; when there is no config file, the base is the entry file's directory. If `output_dir` is not set it also defaults to `build`; if `output_name` is not set it defaults to the source file name (`main.py` uses its containing folder name).
224
+
225
+ ## Current Boundaries and Known Limitations
226
+
227
+ - Dictionaries / sets are not supported; `Str` / `Bytes` have **immutable value semantics**, not mutable buffers
228
+ - Arrays are fixed-length (fixed at compile time); variable length relies on `mem.*` heap memory
229
+ - `const` on pointer parameters is not supported
230
+ - `sizeof` accepts only types, not variables / structs / enums
231
+ - **The output only requires C99**: just compile with `cc -std=c99`. Bit builtins, barriers, and declaration qualifiers are GCC / Clang extensions
232
+
233
+ ### Scope of Two-Track Consistency
234
+
235
+ Two-track consistency means programs that **have runtime output and have equivalent implementations on both tracks** produce byte-for-byte identical output. Capabilities that only take effect on the artifact track are not compared: conditional compilation (`c.defined` / `c.macro`, where the CPython track always takes `else`, a clear branch point), bare preprocessing calls, section descriptors, `@c.export`, declaration qualifiers, link configuration, and `.h` mode. These capabilities have no comparable output on the CPython track, so no mock should be (or needs to be) built for them.
236
+
237
+ ### Known Two-Track Divergence: Scalar Aliasing
238
+
239
+ `ptr.ref(x)` (`x` is a scalar) gets a value copy on the CPython track, and `ptr.poke` writes to that copy; on the C track it gets `&x` and writes back to the original variable. So after `poke` you **must read with `ptr.peek(p)`** for the two tracks to agree; directly doing `print(x)` diverges (C track shows the new value, CPython track shows the original).
240
+
241
+ This rule **does not support write-back**: the CPython track hands the `.py` source verbatim to the interpreter, so `ptr.ref` only receives a value and cannot get the variable binding, making write-back impossible. For writable targets, choose array elements, struct fields, or `mem.alloc` heap memory.
242
+
243
+
244
+ ### f-string Support Scope
245
+
246
+ The format spec only supports `[align][0][width][.precision][type]`; floats must explicitly specify the type (`.2f`). `^` centering, `,` thousands separator, `#` prefix, non-zero fill characters, nested fields, and `!r`/`!s`/`!a` conversions are **not supported** and cause a compile-time error; for complex formatting, concatenate strings yourself.
247
+
248
+ ### Naming Constraints for `c.define`
249
+
250
+ The assignment form requires the macro name and the binding name to match: `N = c.define("N", 4)`; a mismatched name (`a = c.define("b", 1)`) causes a compile-time error. Only when the names match can the macro value be used as a compile-time constant (`make_array(int32, N)`).
251
+
252
+ A bare call `c.define("N", 4)` only emits one `#define`; the name does not enter scope and does not participate in constant evaluation. A macro name must not collide with the compiler's inlined runtime identifiers (such as `b`, `i`, `py_arena_alloc`, `NULL`), otherwise textual substitution would pollute the generated C — a collision triggers an error.
253
+
254
+ ## Project Links
255
+
256
+ - [Documentation](https://lubanqihao9875.github.io/embeddedpyDocs)
257
+ - [Repository](https://github.com/lubanqihao9875/embeddedpy)
258
+ - [Issues](https://github.com/lubanqihao9875/embeddedpy/issues)
@@ -0,0 +1,239 @@
1
+ # embeddedpy
2
+
3
+ Write **C99** using **Python syntax**.
4
+
5
+ Source is `.py`: types are imported from `embeddedpy.types`, pointers and memory use a purely functional API, C declaration qualifiers are written as decorators, and preprocessing is written as Python conditional expressions and module-level calls. The compiler turns this source into portable C99 code (a complete program, a declaration header, or a linkable library), where every type definition and every layout is determined solely by the information you write.
6
+
7
+ Overall principle: **only information known to the user should be written by the user, and written only once**; anything that can be derived from what is already written is computed by the compiler. Every C capability must have a Python shape: operators/expressions go through module functions or methods, declaration qualifiers go through decorators, type construction goes through base classes and parameterized types, preprocessing/text-layer goes through module-level calls; `c.emit(...)` is used for the long tail of C constructs that have no dedicated shape.
8
+
9
+ ## Features
10
+
11
+ - Fixed-width numeric types: `int8/16/32/64`, `uint8/16/32/64`, `float32/64`
12
+ - Single-byte characters: `char` / `schar` / `uchar`
13
+ - Fixed-length arrays: `Array[T]` + `make_array(T, N)`; the length is not part of the type
14
+ - Purely functional pointer API: `ptr.ref / peek / poke / skip / field / cast / from_int`
15
+ - Heap memory: `mem.alloc / free / realloc`; string/byte intermediate values go through two static pools each with an independent upper bound; the total size `arena_cap` and the allocation ratio `arena_manual_ratio` (0..1) are configurable. The automatic pool (frame-based rollback inside function bodies, return-value ownership moved up to the caller) and the manual pool (module-level data, cleared only by `mem.arena_reset()` and not affecting in-function data) have independent capacities
16
+ - Aggregate types: whole-assignment `b = a` is rejected at compile time; an independent copy uses `copy_aggregate`; arrays / structs land in compile-time fixed-size C objects, not in the arena and not on the heap
17
+ - Aggregate types: `Struct` / `Union` / `Bits[N]`; `@c.packed` and `@c.word(W)` determine layout; storage type and padding are computed by the compiler
18
+ - Declaration qualifiers: `@c.inline` / `@c.section("...")` / `@c.aligned(N)` / `@c.weak` / `@c.visibility("...")` / `@c.extern_function`
19
+ - C interop: `c.include("x.h")`, `c.extern_type("T")`, `c.typedef(...)`, `c.define(...)`
20
+ - Conditional compilation: `if c.defined("X") and c.macro("V") >= 2:` / `elif` / `else` generate `#if / #elif / #else / #endif`; `c.define / c.include` inside the block are emitted in place; `c.pragma / error / warning / undef` are named single-line directives, and `c.emit(...)` is the long-tail fallback
21
+ - Byte strings: `b"..."`, `b[0]` yields `uchar` (keeps the byte form, does not participate in arithmetic); an explicit `uint8(b[0])` is needed for numeric use, used for protocol / text parsing
22
+ - Enums: `class Mode(Enum)` + `auto()`, members can serve as the compile-time length for `make_array`
23
+ - Modifiers: `const[T]` / `volatile[T]` (written in annotations); `sizeof(T)` generates a real `sizeof`
24
+ - Bit builtins and barriers: `c.clz / ctz / popcount` use GCC / Clang's `__builtin_*`; `c.barrier()` emits a compiler barrier
25
+
26
+ ## Installation
27
+
28
+ ```bash
29
+ pip install embeddedpy
30
+ ```
31
+
32
+ ## Quick Start
33
+
34
+ Write a `hello.py`:
35
+
36
+ ```python
37
+ from embeddedpy.types import int32
38
+
39
+ def add(a: int32, b: int32) -> int32:
40
+ return a + b
41
+
42
+ result: int32 = add(2, 3)
43
+ print("2 + 3 =", result)
44
+ ```
45
+
46
+ The same file can be run directly or compiled to C:
47
+
48
+ ```bash
49
+ python hello.py # CPython track
50
+ embeddedpy build hello.py # generate C source file
51
+ embeddedpy check hello.py # check only, no file written
52
+ ```
53
+
54
+ The output form is chosen by `output_type`: `program`, `header`, `library`.
55
+
56
+ ## Import by Category
57
+
58
+ Language symbols are split into modules by purpose, one category per line, so you can tell at a glance what each is:
59
+
60
+ ```python
61
+ from embeddedpy.types import int32, uint8 # fixed-width scalars
62
+ from embeddedpy.types import Ptr, Func, Struct, Union, Bits # type construction
63
+ from embeddedpy.types import Enum, const, volatile # enums and qualifiers
64
+ from embeddedpy.arrays import make_array # fixed-length arrays
65
+ from embeddedpy.pointers import ptr # pointer API
66
+ from embeddedpy.enums import auto # enum auto-increment
67
+ from embeddedpy.memory import mem, sizeof # heap memory and type sizing
68
+ from embeddedpy.memory import copy_aggregate # aggregate type copies
69
+ from embeddedpy.io import io, File # file I/O
70
+ from embeddedpy.strings import strings # text buffers
71
+ from embeddedpy.interop import c # C interop
72
+ ```
73
+
74
+ The compiler validates imported names per module: writing `from embeddedpy.arrays import int32` raises `embeddedpy.arrays has no attribute named int32`; names from different categories are never mixed.
75
+
76
+ ## Two Top-Level Packages: Language Library / Compiler
77
+
78
+ A single distribution ships both the **library** and the **command**, but the source tree is split into two top-level packages:
79
+
80
+ | Package | What it is | Used by |
81
+ |---|---|---|
82
+ | `embeddedpy` | **Language library**: the category modules above | User source via `from embeddedpy.types import int32` |
83
+ | `embeddedpy.compiler` | **Compiler**: gates, type checking, code generation, CLI | Command `embeddedpy` / `python -m embeddedpy.compiler`, and host programs |
84
+
85
+ The dependency direction is "compiler → language library"; the language library does not import the compiler — names imported via `from embeddedpy...` belong to the language semantics layer and do not expose the compiler's internals.
86
+
87
+ Host program (using the compiler as a library):
88
+
89
+ ```python
90
+ from embeddedpy.compiler import compile_file, check_source, CompileConfig
91
+ ```
92
+
93
+ Compile to C:
94
+
95
+ ```bash
96
+ embeddedpy build hello.py # writes to build/hello.c by default
97
+ embeddedpy build hello.py --output out.c # specify output
98
+ embeddedpy check hello.py # language and type checking only (no file written)
99
+ embeddedpy build --help # list all options
100
+ ```
101
+
102
+ ## Multi-File Projects
103
+
104
+ Multi-file projects are organized with `import`, and namespaces are automatically isolated. Imports resolve from a single project root: for a flat project it is the entry file's directory; for a package project it is derived from the consecutive `__init__.py` chain (the top-level package's parent directory). A dotted name maps to the directory levels under that root, so `lib/filters.py` is imported as `lib.filters`.
105
+
106
+ Flat sibling modules:
107
+
108
+ ```python
109
+ # multi_sensor.py
110
+ from embeddedpy.types import int32
111
+ def read(p: int32) -> int32:
112
+ return p + 1
113
+ ```
114
+ ```python
115
+ # main.py
116
+ import multi_sensor
117
+ from embeddedpy.types import int32
118
+ result: int32 = multi_sensor.read(41)
119
+ print("multi_sensor.read(41) =", result)
120
+ ```
121
+
122
+ Modules under a subdirectory are imported by dotted path; `lib/filters.py` becomes `import lib.filters`:
123
+
124
+ ```python
125
+ # lib/filters.py
126
+ from embeddedpy.types import int32
127
+ def smooth(v: int32) -> int32:
128
+ return v * 2
129
+ ```
130
+ ```python
131
+ # main.py
132
+ import lib.filters
133
+ from embeddedpy.types import int32
134
+ result: int32 = lib.filters.smooth(3)
135
+ print("lib.filters.smooth(3) =", result)
136
+ ```
137
+
138
+ The compiler inlines all modules into **the same `.c`**: symbols from imported modules are prefixed with the module key (the dotted path relative to the project root, joined with `__`), combined with the purpose prefix into `f_lib__filters__smooth` / `f_multi_sensor__read` (global variables use the `g_` prefix); the entry module gets no module prefix (the entry module's **top-level statements** are inlined into C's `int main()`). `__` is the module namespace separator; directory names, module names and top-level definition names must not contain it.
139
+
140
+ Importing a module checks it in full, but the generated C keeps only the top-level functions: `main`, functions referenced by top-level statements, `@c.export` / `@c.extern_function` / `@c.weak` functions, and all the functions they call transitively; the rest are not written into the `.c`. Removal happens after type checking (so type errors in removed functions are still reported), and the whole pass is skipped if the source uses `c.emit` / `c.asm` / `c.goto` / `c.label` — the AST cannot see symbol names embedded in strings, so removal cannot be guaranteed safe.
141
+
142
+ ## Configurable Build Form
143
+
144
+ What form the compiler produces is decided by `CompileConfig`. There are only three entry points, and the **verb must be written explicitly**:
145
+
146
+ ```bash
147
+ embeddedpy build [SOURCE] [options] # compile entry to C
148
+ embeddedpy check [SOURCE] [options] # check only, no file written
149
+ embeddedpy --help # help (embeddedpy build --help lists all options)
150
+ ```
151
+
152
+ Options have **only long names, no short options** (no `-o` / `-h`).
153
+
154
+ The 14 settings that determine the output are **configurable in both directions and share the same names** between TOML and the command line: TOML uses snake_case, the command line uses kebab-case.
155
+
156
+ | `[tool.embeddedpy]` key | command line |
157
+ |---|---|
158
+ | `source` | positional argument `SOURCE` |
159
+ | `line_output` | `--line-output {noline,line,both}` |
160
+ | `output_type` | `--output-type {program,header,library}` |
161
+ | `output` | `--output PATH` |
162
+ | `output_dir` | `--output-dir DIR` |
163
+ | `output_name` | `--output-name NAME` |
164
+ | `include` | `--include HEADER` (repeatable) |
165
+ | `exclude` | `--exclude HEADER` (repeatable) |
166
+ | `assets_dir` | `--assets-dir DIR` |
167
+ | `arena_cap` | `--arena-cap N` |
168
+ | `arena_manual_ratio` | `--arena-manual-ratio R` |
169
+ | `link_script` | `--link-script PATH` |
170
+ | `link_flags` | `--link-flags FLAG` (repeatable) |
171
+ | `link_libs` | `--link-libs LIB` (repeatable) |
172
+
173
+ `link_script` points to the link script: the compiler only checks that it exists and copies it to the output directory; after a successful `build` it prints a copyable link command to stderr (`link_flags` / `link_libs` are spliced in, and the compiler is specified by the `CC` environment variable, defaulting to `cc`). **The compiler does not run linking**; when all three are empty, no hint is printed.
174
+
175
+ For the array-typed `include` / `exclude` / `link_flags` / `link_libs`, providing them on the command line **replaces** the array in the config wholesale rather than appending; if `output` is set then `output_dir` / `output_name` are ignored. `check` and `build` share the same options and the same config, except `check` ignores keys unrelated to output (without error).
176
+
177
+ ```bash
178
+ embeddedpy build hello.py --line-output noline # don't write #line directives, produce clean C
179
+ embeddedpy build hello.py --output-dir out # override output directory
180
+ embeddedpy build hello.py --output-name demo # override output name
181
+ ```
182
+
183
+ The compiler reads only the `[tool.embeddedpy]` section of `pyproject.toml` at the project root; if it is not found there, no further lookup is done. Priority: **default < config file < command-line options**.
184
+
185
+ ```toml
186
+ [tool.embeddedpy]
187
+ line_output = "line" # noline | line | both
188
+ output_type = "program" # program = complete program, header = declaration set, library = linkable implementation
189
+
190
+ # output location: directory and name can be configured separately or together
191
+ output_dir = "build" # directory (defaults to build)
192
+ output_name = "hello" # name, without .c (defaults to the source file name)
193
+ # output = "build/hello.c" # or write the full path at once
194
+
195
+ # include = ["stdio.h", "stdint.h"] # 8 system headers by default; setting this replaces them wholesale
196
+ # exclude = ["math.h"] # removed from the final set
197
+ # arena_cap = 8192 # total bytes for both pools; lower for embedded, higher for string-heavy use
198
+ # arena_manual_ratio = 0.5 # manual-pool fraction (0..1); changing it only adjusts allocation, total RAM unchanged
199
+ # link_script = "ld/stm32f4.ld" # link script: only validated + copied, not linked by the compiler
200
+ # link_flags = ["-mcpu=cortex-m4", "-mthumb", "-nostartfiles"]
201
+ # link_libs = ["m"] # written as -lm each
202
+ ```
203
+
204
+ **Relative paths are based on the "config file's directory"**, so `output_dir = "build"` means "project_root/build/", without awkward `../` paths; when there is no config file, the base is the entry file's directory. If `output_dir` is not set it also defaults to `build`; if `output_name` is not set it defaults to the source file name (`main.py` uses its containing folder name).
205
+
206
+ ## Current Boundaries and Known Limitations
207
+
208
+ - Dictionaries / sets are not supported; `Str` / `Bytes` have **immutable value semantics**, not mutable buffers
209
+ - Arrays are fixed-length (fixed at compile time); variable length relies on `mem.*` heap memory
210
+ - `const` on pointer parameters is not supported
211
+ - `sizeof` accepts only types, not variables / structs / enums
212
+ - **The output only requires C99**: just compile with `cc -std=c99`. Bit builtins, barriers, and declaration qualifiers are GCC / Clang extensions
213
+
214
+ ### Scope of Two-Track Consistency
215
+
216
+ Two-track consistency means programs that **have runtime output and have equivalent implementations on both tracks** produce byte-for-byte identical output. Capabilities that only take effect on the artifact track are not compared: conditional compilation (`c.defined` / `c.macro`, where the CPython track always takes `else`, a clear branch point), bare preprocessing calls, section descriptors, `@c.export`, declaration qualifiers, link configuration, and `.h` mode. These capabilities have no comparable output on the CPython track, so no mock should be (or needs to be) built for them.
217
+
218
+ ### Known Two-Track Divergence: Scalar Aliasing
219
+
220
+ `ptr.ref(x)` (`x` is a scalar) gets a value copy on the CPython track, and `ptr.poke` writes to that copy; on the C track it gets `&x` and writes back to the original variable. So after `poke` you **must read with `ptr.peek(p)`** for the two tracks to agree; directly doing `print(x)` diverges (C track shows the new value, CPython track shows the original).
221
+
222
+ This rule **does not support write-back**: the CPython track hands the `.py` source verbatim to the interpreter, so `ptr.ref` only receives a value and cannot get the variable binding, making write-back impossible. For writable targets, choose array elements, struct fields, or `mem.alloc` heap memory.
223
+
224
+
225
+ ### f-string Support Scope
226
+
227
+ The format spec only supports `[align][0][width][.precision][type]`; floats must explicitly specify the type (`.2f`). `^` centering, `,` thousands separator, `#` prefix, non-zero fill characters, nested fields, and `!r`/`!s`/`!a` conversions are **not supported** and cause a compile-time error; for complex formatting, concatenate strings yourself.
228
+
229
+ ### Naming Constraints for `c.define`
230
+
231
+ The assignment form requires the macro name and the binding name to match: `N = c.define("N", 4)`; a mismatched name (`a = c.define("b", 1)`) causes a compile-time error. Only when the names match can the macro value be used as a compile-time constant (`make_array(int32, N)`).
232
+
233
+ A bare call `c.define("N", 4)` only emits one `#define`; the name does not enter scope and does not participate in constant evaluation. A macro name must not collide with the compiler's inlined runtime identifiers (such as `b`, `i`, `py_arena_alloc`, `NULL`), otherwise textual substitution would pollute the generated C — a collision triggers an error.
234
+
235
+ ## Project Links
236
+
237
+ - [Documentation](https://lubanqihao9875.github.io/embeddedpyDocs)
238
+ - [Repository](https://github.com/lubanqihao9875/embeddedpy)
239
+ - [Issues](https://github.com/lubanqihao9875/embeddedpy/issues)
@@ -0,0 +1,31 @@
1
+ [build-system]
2
+ requires = ["setuptools>=77"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "embeddedpy"
7
+ version = "0.1.0"
8
+ description = "Write complete C99 using valid Python syntax: compile .py source into full C source files, declaration headers, or linkable libraries — the same program also runs directly under CPython"
9
+ readme = "README.md"
10
+ requires-python = ">=3.12"
11
+ license = "MIT"
12
+ license-files = ["LICENSE"]
13
+ authors = [{ name = "lubanqihao9875" }]
14
+ keywords = ["compiler", "c", "c99", "embedded", "python-to-c", "codegen"]
15
+ classifiers = [
16
+ "Programming Language :: Python :: 3",
17
+ "Operating System :: OS Independent",
18
+ "Topic :: Software Development :: Code Generators",
19
+ ]
20
+
21
+ [project.urls]
22
+ Homepage = "https://github.com/lubanqihao9875/embeddedpy"
23
+ Documentation = "https://lubanqihao9875.github.io/embeddedpyDocs"
24
+ Repository = "https://github.com/lubanqihao9875/embeddedpy"
25
+ Issues = "https://github.com/lubanqihao9875/embeddedpy/issues"
26
+
27
+ [project.scripts]
28
+ embeddedpy = "embeddedpy.compiler.cli:main"
29
+
30
+ [tool.setuptools.packages.find]
31
+ where = ["src"]
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1,55 @@
1
+ """embeddedpy language library: the target of user source ``import``.
2
+
3
+ The compiler lives in another package, ``embeddedpy.compiler``; this package does
4
+ **not** depend on it. The dependency direction is "compiler -> language library",
5
+ and the language library does not depend on the compiler.
6
+
7
+ User source imports language symbols by category:
8
+
9
+ from embeddedpy.types import int32, uint8, Str, Array, Ptr # all types
10
+ from embeddedpy.arrays import make_array # array functions
11
+ from embeddedpy.pointers import ptr # pointer functions
12
+ from embeddedpy.enums import auto # enum functions
13
+ from embeddedpy.memory import mem # heap memory
14
+ from embeddedpy.interop import c # C interop
15
+ from embeddedpy.io import File, io # file I/O
16
+ from embeddedpy.bytes import bytes # byte buffer
17
+
18
+ **All types live in ``embeddedpy.types``** (scalars, text, containers, pointers,
19
+ aggregates, modifiers); the other modules only hold functions. The file handle
20
+ ``File`` is an opaque handle of the io domain, kept in ``embeddedpy.io``.
21
+ """
22
+
23
+ from typing import Any, List
24
+
25
+ __version__ = "0.1.0"
26
+
27
+ # Language runtime submodules: lazily imported to avoid pulling in all the
28
+ # implementation when `import embeddedpy` is run.
29
+ _LANG_MODULES = (
30
+ "types",
31
+ "arrays",
32
+ "pointers",
33
+ "enums",
34
+ "memory",
35
+ "interop",
36
+ "io",
37
+ "bytes",
38
+ )
39
+
40
+ __all__ = ["__version__"] + list(_LANG_MODULES)
41
+
42
+
43
+ def __getattr__(name: str) -> Any:
44
+ """PEP 562 lazy attribute access."""
45
+ if name in _LANG_MODULES:
46
+ import importlib
47
+
48
+ module = importlib.import_module(f".{name}", __name__)
49
+ globals()[name] = module
50
+ return module
51
+ raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
52
+
53
+
54
+ def __dir__() -> List[str]:
55
+ return sorted(__all__)