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,163 @@
1
+ """The **category registry** for embeddedpy's public import namespace (the single source of truth on the compiler side).
2
+
3
+ User source may only import language symbols from these category modules:
4
+
5
+ from embeddedpy.types import int32, uint8, Str, Bytes # all types
6
+ from embeddedpy.arrays import make_array # array functions
7
+ from embeddedpy.pointers import ptr # pointer functions
8
+ from embeddedpy.memory import mem # heap memory
9
+ from embeddedpy.io import File, io # file I/O
10
+ from embeddedpy.bytes import bytes # byte buffer
11
+ from embeddedpy.interop import c # C interop
12
+
13
+ **Ownership criterion**: a type enters ``embeddedpy.types`` if and only if it is a type **defined by the language itself and for which the language has built-in semantics** (length, dereference, fields, text, ...). Opaque handles of a feature domain stay in their own domain module — for example the file handle ``File`` stays in ``embeddedpy.io``, alongside the ``io`` API that reads/writes it.
14
+
15
+ The remaining modules hold only functions, not types.
16
+
17
+ "Which names belong to which category" is a fact of the **language library** — we ask the language library itself (each module's ``__all__``); "what each name means at compile time" is the **compiler's** concern, registered by ``_SPECIAL_KINDS``. If the two disagree, we error out here immediately rather than waiting until the user source is compiled.
18
+
19
+ The top-level ``embeddedpy`` is merely the language library's package name, not an importable category module, so it is not open for import from user source.
20
+ """
21
+
22
+ import embeddedpy.arrays as _arrays
23
+ import embeddedpy.bytes as _bytes
24
+ import embeddedpy.enums as _enums
25
+ import embeddedpy.interop as _interop
26
+ import embeddedpy.io as _io
27
+ import embeddedpy.memory as _memory
28
+ import embeddedpy.pointers as _pointers
29
+ import embeddedpy.strings as _strings
30
+ import embeddedpy.types as _types
31
+
32
+ # Category module -> the names and kinds that category exports.
33
+ #
34
+ # embeddedpy.types holds all types, but "scalar" and "constructed" mean different
35
+ # things at compile time, so they are registered individually here; the other
36
+ # modules hold only functions and are registered one by one.
37
+ _SPECIAL_KINDS = {
38
+ _types: {
39
+ # Scalars
40
+ "int8": "scalar",
41
+ "int16": "scalar",
42
+ "int32": "scalar",
43
+ "int64": "scalar",
44
+ "uint8": "scalar",
45
+ "uint16": "scalar",
46
+ "uint32": "scalar",
47
+ "uint64": "scalar",
48
+ "char": "scalar",
49
+ "schar": "scalar",
50
+ "uchar": "scalar",
51
+ "float32": "scalar",
52
+ "float64": "scalar",
53
+ "Bool": "scalar",
54
+ # Empty value: void (C's "no value")
55
+ "void": "scalar",
56
+ # Text and bytes
57
+ "Str": "scalar",
58
+ "Bytes": "scalar",
59
+ # Containers and pointers
60
+ "Array": "array_type",
61
+ "Ptr": "ptr_type",
62
+ "Func": "func_type",
63
+ # Aggregates
64
+ "Struct": "struct_base",
65
+ "Union": "union_base",
66
+ "Bits": "bits_type",
67
+ "Enum": "enum_base",
68
+ "auto": "auto_func",
69
+ # Qualifiers
70
+ "const": "qualifier_const",
71
+ "volatile": "qualifier_volatile",
72
+ },
73
+ _arrays: {"make_array": "make_array_func"},
74
+ _pointers: {"ptr": "ptr_func"},
75
+ _enums: {"auto": "auto_func"},
76
+ _memory: {"mem": "mem_module", "sizeof": "sizeof_func", "copy_aggregate": "copy_aggregate_func"},
77
+ _io: {"io": "io_module", "File": "file_type"},
78
+ _strings: {"strings": "strings_module"},
79
+ _bytes: {"bytes": "bytes_module"},
80
+ # C interop exposes only a single entry point c: headers / external symbols /
81
+ # macros / preprocessor directives, plus declaration modifiers like
82
+ # @c.packed / @c.word / @c.inline / @c.section.
83
+ _interop: {"c": "c_module"},
84
+ }
85
+
86
+ # Category order is the order used in the gate hint
87
+ _CATEGORY_MODULES = (
88
+ _types,
89
+ _arrays,
90
+ _pointers,
91
+ _enums,
92
+ _memory,
93
+ _io,
94
+ _strings,
95
+ _bytes,
96
+ _interop,
97
+ )
98
+
99
+
100
+ def _build_registry() -> dict:
101
+ registry = {}
102
+ for module in _CATEGORY_MODULES:
103
+ kinds = _SPECIAL_KINDS.get(module)
104
+ entries = {}
105
+ for name in module.__all__:
106
+ if kinds is None:
107
+ entries[name] = "scalar"
108
+ continue
109
+ if name not in kinds:
110
+ raise RuntimeError(
111
+ f"{module.__name__} exports {name!r} but the compiler has no kind for it"
112
+ )
113
+ entries[name] = kinds[name]
114
+ registry[module.__name__] = entries
115
+ return registry
116
+
117
+
118
+ CATEGORY_SPECIALS = _build_registry()
119
+
120
+ # Import roots allowed by the front-end gate (= all category modules)
121
+ ALLOWED_IMPORT_ROOTS = tuple(CATEGORY_SPECIALS.keys())
122
+
123
+ # Public symbols the top-level embeddedpy package allows via direct
124
+ # ``from embeddedpy import X``. All types are provided by embeddedpy.types;
125
+ # the top level accepts no names.
126
+ ALLOWED_TOPLEVEL_NAMES: tuple = ()
127
+
128
+ # Kinds of names that may appear in **type annotation** positions.
129
+ _TYPE_LIKE_KINDS = frozenset(
130
+ {
131
+ "scalar",
132
+ "ptr_type",
133
+ "func_type",
134
+ "array_type",
135
+ "enum_base",
136
+ "struct_base",
137
+ "union_base",
138
+ "bits_type",
139
+ "file_type",
140
+ }
141
+ )
142
+
143
+ # Type name -> owning category module (reverse index).
144
+ # Used for "type name not imported" errors: gives a directly copyable import
145
+ # statement.
146
+ TYPE_NAME_OWNERS: dict = {}
147
+ for _module_name, _entries in CATEGORY_SPECIALS.items():
148
+ for _name, _kind in _entries.items():
149
+ if _kind in _TYPE_LIKE_KINDS:
150
+ TYPE_NAME_OWNERS.setdefault(_name, _module_name)
151
+
152
+
153
+ def type_import_hint(name: str) -> str:
154
+ """Give an unimported type name a directly copyable import suggestion."""
155
+ owner = TYPE_NAME_OWNERS.get(name)
156
+ if owner is None:
157
+ return f"unknown type name '{name}'"
158
+ return f"type '{name}' is not imported; use 'from {owner} import {name}'"
159
+
160
+
161
+ def category_hint() -> str:
162
+ """A hint to the user: list all available category modules."""
163
+ return ", ".join(ALLOWED_IMPORT_ROOTS)