omnipython-applibs 0.1.2__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.
Files changed (143) hide show
  1. appkit/__init__.py +52 -0
  2. appkit/__init__.pyi +17 -0
  3. appkit/data.py +149 -0
  4. appkit/data.pyi +25 -0
  5. appkit/foreground.py +357 -0
  6. appkit/foreground.pyi +45 -0
  7. appkit/home.py +19 -0
  8. appkit/home.pyi +8 -0
  9. appkit/hover.py +59 -0
  10. appkit/hover.pyi +13 -0
  11. appkit/index.py +199 -0
  12. appkit/index.pyi +30 -0
  13. appkit/launcher.py +1075 -0
  14. appkit/launcher.pyi +96 -0
  15. appkit/manifest.py +75 -0
  16. appkit/manifest.pyi +8 -0
  17. appkit/net.py +167 -0
  18. appkit/net.pyi +34 -0
  19. appkit/places.py +202 -0
  20. appkit/places.pyi +39 -0
  21. appkit/py.typed +0 -0
  22. appkit/scope.py +636 -0
  23. appkit/scope.pyi +110 -0
  24. appkit/shell.py +121 -0
  25. appkit/shell.pyi +32 -0
  26. appkit/worker.py +409 -0
  27. appkit/worker.pyi +83 -0
  28. controlkit/__init__.py +19 -0
  29. controlkit/__init__.pyi +10 -0
  30. controlkit/_draw.py +88 -0
  31. controlkit/_safe.py +29 -0
  32. controlkit/dotmatrix.py +101 -0
  33. controlkit/dotmatrix.pyi +23 -0
  34. controlkit/encoder.py +297 -0
  35. controlkit/encoder.pyi +55 -0
  36. controlkit/font5x7.py +22 -0
  37. controlkit/font5x7.pyi +11 -0
  38. controlkit/lamp_button.py +92 -0
  39. controlkit/lamp_button.pyi +40 -0
  40. controlkit/meter.py +86 -0
  41. controlkit/meter.pyi +30 -0
  42. controlkit/mock.py +116 -0
  43. controlkit/mock.pyi +35 -0
  44. controlkit/pad_grid.py +113 -0
  45. controlkit/pad_grid.pyi +41 -0
  46. controlkit/py.typed +0 -0
  47. controlkit/slider.py +185 -0
  48. controlkit/slider.pyi +49 -0
  49. controlkit/sprites.py +279 -0
  50. controlkit/sprites.pyi +22 -0
  51. controlkit/theme.py +120 -0
  52. controlkit/theme.pyi +15 -0
  53. deskkit/__init__.py +74 -0
  54. deskkit/__init__.pyi +18 -0
  55. deskkit/forecast.py +261 -0
  56. deskkit/forecast.pyi +40 -0
  57. deskkit/localtime.py +215 -0
  58. deskkit/localtime.pyi +33 -0
  59. deskkit/py.typed +0 -0
  60. deskkit/shell.py +113 -0
  61. deskkit/shell.pyi +33 -0
  62. omnipython_applibs-0.1.2.dist-info/METADATA +90 -0
  63. omnipython_applibs-0.1.2.dist-info/RECORD +143 -0
  64. omnipython_applibs-0.1.2.dist-info/WHEEL +5 -0
  65. omnipython_applibs-0.1.2.dist-info/licenses/LICENSE +21 -0
  66. omnipython_applibs-0.1.2.dist-info/top_level.txt +9 -0
  67. programkit/__init__.py +27 -0
  68. programkit/__init__.pyi +8 -0
  69. programkit/board.py +56 -0
  70. programkit/board.pyi +20 -0
  71. programkit/press.py +63 -0
  72. programkit/press.pyi +17 -0
  73. programkit/py.typed +0 -0
  74. programkit/rows.py +149 -0
  75. programkit/rows.pyi +34 -0
  76. sayso/__init__.py +109 -0
  77. sayso/__init__.pyi +124 -0
  78. sayso/auth.py +811 -0
  79. sayso/auth.pyi +102 -0
  80. sayso/client.py +1286 -0
  81. sayso/client.pyi +138 -0
  82. sayso/keepalive.py +371 -0
  83. sayso/keepalive.pyi +53 -0
  84. sayso/local.py +85 -0
  85. sayso/local.pyi +28 -0
  86. sayso/object_specs.py +706 -0
  87. sayso/object_specs.pyi +8 -0
  88. sayso/objects.py +411 -0
  89. sayso/objects.pyi +854 -0
  90. sayso/py.typed +0 -0
  91. sayso/schema_coverage.py +210 -0
  92. sayso/schema_coverage.pyi +13 -0
  93. sayso/transport.py +426 -0
  94. sayso/transport.pyi +47 -0
  95. songmodel/__init__.py +30 -0
  96. songmodel/__init__.pyi +9 -0
  97. songmodel/link.py +189 -0
  98. songmodel/link.pyi +53 -0
  99. songmodel/model.py +238 -0
  100. songmodel/model.pyi +40 -0
  101. songmodel/page.html +225 -0
  102. songmodel/page_data.py +236 -0
  103. songmodel/page_data.pyi +6 -0
  104. songmodel/py.typed +0 -0
  105. soundmodule/__init__.py +7 -0
  106. soundmodule/__init__.pyi +6 -0
  107. soundmodule/engine.py +1001 -0
  108. soundmodule/engine.pyi +196 -0
  109. soundmodule/names.py +298 -0
  110. soundmodule/names.pyi +30 -0
  111. soundmodule/pipes.py +105 -0
  112. soundmodule/pipes.pyi +31 -0
  113. soundmodule/py.typed +0 -0
  114. soundmodule/run.py +249 -0
  115. soundmodule/run.pyi +49 -0
  116. spectrum/__init__.py +72 -0
  117. spectrum/__init__.pyi +30 -0
  118. spectrum/analyzer.py +231 -0
  119. spectrum/analyzer.pyi +67 -0
  120. spectrum/fake_music.py +201 -0
  121. spectrum/fake_music.pyi +36 -0
  122. spectrum/pump_levels.py +126 -0
  123. spectrum/pump_levels.pyi +46 -0
  124. spectrum/py.typed +0 -0
  125. spectrum/spectrum_view.py +403 -0
  126. spectrum/spectrum_view.pyi +80 -0
  127. touchkit/__init__.py +4 -0
  128. touchkit/__init__.pyi +4 -0
  129. touchkit/cam.py +146 -0
  130. touchkit/cam.pyi +35 -0
  131. touchkit/clock.py +18 -0
  132. touchkit/clock.pyi +6 -0
  133. touchkit/ecp.py +134 -0
  134. touchkit/ecp.pyi +28 -0
  135. touchkit/net.py +347 -0
  136. touchkit/net.pyi +27 -0
  137. touchkit/py.typed +0 -0
  138. touchkit/settings.py +85 -0
  139. touchkit/settings.pyi +17 -0
  140. touchkit/shell.py +268 -0
  141. touchkit/shell.pyi +42 -0
  142. touchkit/ui.py +167 -0
  143. touchkit/ui.pyi +53 -0
appkit/__init__.py ADDED
@@ -0,0 +1,52 @@
1
+ # SPDX-FileCopyrightText: 2026 Brad Barnett
2
+ #
3
+ # SPDX-License-Identifier: MIT
4
+ """appkit: apps you can switch between, and a launcher to run them.
5
+
6
+ ::
7
+
8
+ import appkit
9
+ appkit.run() # a home screen of every app in ./apps
10
+ appkit.run("hello") # one app, alone
11
+ """
12
+
13
+ from .foreground import serve
14
+ from .launcher import Launcher, host, run_pending_script
15
+ from .scope import AppScope
16
+ from .shell import Shell
17
+
18
+
19
+ def run(name=None, folder="apps", *, data_root=None):
20
+ """Run the apps in *folder*: a home screen listing them, or app *name* alone.
21
+
22
+ The home screen is the folder's own app named ``home`` when it has one,
23
+ and otherwise appkit's list of buttons, ``appkit.home``.
24
+
25
+ It ends in the main-thread loop, `serve`, and returns the
26
+ ``Launcher`` when the program quits. In a browser, where the page has
27
+ the main thread, it returns the launcher at once. *data_root* moves
28
+ every app's ``data_dir`` and the launcher's restart file (see
29
+ ``appkit.data``). A plain script the home screen started runs here
30
+ first, before the display opens, and doesn't return.
31
+ """
32
+ if run_pending_script(data_root):
33
+ return None # a browser, reloading
34
+ from display_driver import app # the one App every LVGL program shares
35
+
36
+ launcher = Launcher(app)
37
+ launcher.scan(folder)
38
+ if name is None:
39
+ _use_home(launcher)
40
+ launcher.shell = Shell(launcher)
41
+ launcher.boot(name)
42
+ if host() != "browser":
43
+ serve(app)
44
+ return launcher
45
+
46
+
47
+ def _use_home(launcher):
48
+ """Make ``home`` the launcher's home screen: the folder's own app named
49
+ home when the scan found one, else appkit's list of buttons."""
50
+ if "home" not in launcher.names:
51
+ launcher.add("home", "appkit.home")
52
+ launcher.home = "home"
appkit/__init__.pyi ADDED
@@ -0,0 +1,17 @@
1
+ # SPDX-FileCopyrightText: 2026 Brad Barnett
2
+ #
3
+ # SPDX-License-Identifier: MIT
4
+ """appkit: apps you can switch between, and a launcher to run them."""
5
+
6
+ from .foreground import serve as serve
7
+ from .launcher import Launcher as Launcher, host as host, run_pending_script as run_pending_script
8
+ from .scope import AppScope as AppScope
9
+ from .shell import Shell as Shell
10
+
11
+ def run(name: str | None = None, folder: str = 'apps', *, data_root: str | None = None) -> Launcher | None:
12
+ """Run the apps in `folder`: a home screen listing them, or app `name` alone.
13
+
14
+ Ends in the main-thread loop and returns the `Launcher` when the program
15
+ quits. In a browser it returns the launcher at once. `data_root` moves every
16
+ app's `data_dir` and the launcher's restart file.
17
+ """
appkit/data.py ADDED
@@ -0,0 +1,149 @@
1
+ # SPDX-FileCopyrightText: 2026 Brad Barnett
2
+ #
3
+ # SPDX-License-Identifier: MIT
4
+ """Where apps keep their files: the data root, and a folder per app under it.
5
+
6
+ The data root is one setting for the whole program. Each app's folder is
7
+ ``<root>/<app>``, made on first use. The launcher's restart file lives in
8
+ the root too. By default the root is:
9
+
10
+ ============== ==========================================================
11
+ Linux ``$XDG_DATA_HOME/appkit``, or ``~/.local/share/appkit``
12
+ Windows ``%LOCALAPPDATA%\\appkit``
13
+ macOS ``~/Library/Application Support/appkit``
14
+ a board ``/data`` (``/flash/data`` on an STM32, whose ``/`` only holds mounts)
15
+ the browser ``/data``
16
+ ============== ==========================================================
17
+
18
+ ``appkit.run(data_root=...)``, the same argument to ``Shell`` or
19
+ `set_root` moves it everywhere. Without one, ``APPKIT_DATA`` moves it
20
+ on a desktop.
21
+ """
22
+
23
+ import sys
24
+
25
+ #: Platforms that are a desktop operating system, whatever the interpreter.
26
+ DESKTOPS = ("linux", "darwin", "win32", "cygwin", "freebsd", "openbsd", "netbsd")
27
+
28
+ _root = None
29
+
30
+
31
+ def desktop(platform=None, implementation=None):
32
+ """True on a desktop operating system (CPython, or MicroPython's unix or
33
+ Windows port), False on a board or in the browser."""
34
+ platform = platform or sys.platform
35
+ implementation = implementation or sys.implementation.name
36
+ if platform in ("webassembly", "emscripten", "wasi"):
37
+ return False
38
+ if implementation == "cpython":
39
+ return True
40
+ return platform in DESKTOPS
41
+
42
+
43
+ def _getenv(name):
44
+ import os
45
+
46
+ getenv = getattr(os, "getenv", None) # boards have none
47
+ if getenv is None:
48
+ return None
49
+ try:
50
+ return getenv(name) or None
51
+ except Exception:
52
+ return None
53
+
54
+
55
+ def default_root(platform=None, implementation=None, getenv=None):
56
+ """The data root this host uses when nothing sets one.
57
+
58
+ *platform*, *implementation* and *getenv* stand in for ``sys.platform``,
59
+ ``sys.implementation.name`` and ``os.getenv``, to ask about another host.
60
+ """
61
+ platform = platform or sys.platform
62
+ if getenv is None:
63
+ getenv = _getenv
64
+ if not desktop(platform, implementation):
65
+ # The stm32 port's "/" is only where /flash and /sd are mounted, and
66
+ # a folder can't be made there.
67
+ return "/flash/data" if platform == "pyboard" else "/data"
68
+ explicit = getenv("APPKIT_DATA")
69
+ if explicit:
70
+ return explicit
71
+ if platform == "win32":
72
+ base = getenv("LOCALAPPDATA")
73
+ if not base:
74
+ base = (getenv("USERPROFILE") or ".") + "\\AppData\\Local"
75
+ return base + "\\appkit"
76
+ home = getenv("HOME") or getenv("USERPROFILE") or "."
77
+ if platform == "darwin":
78
+ # Untested: macOS is community-supported.
79
+ return home + "/Library/Application Support/appkit"
80
+ base = getenv("XDG_DATA_HOME") or home + "/.local/share"
81
+ return base + "/appkit"
82
+
83
+
84
+ def root():
85
+ """The data root: what `set_root` set, else `default_root`."""
86
+ return _root if _root is not None else default_root()
87
+
88
+
89
+ def set_root(path):
90
+ """Move the data root for the whole program; None goes back to the default."""
91
+ global _root
92
+ if path is not None:
93
+ path = str(path)
94
+ while len(path) > 1 and path[-1] in "/\\" and not path.endswith(":\\"):
95
+ path = path[:-1]
96
+ _root = path
97
+
98
+
99
+ def join(base, *parts):
100
+ """*base* and *parts* joined with the separator *base* already uses."""
101
+ sep = "\\" if ("\\" in base and "/" not in base) else "/"
102
+ out = base
103
+ for part in parts:
104
+ if out and out[-1] in "/\\":
105
+ out += part
106
+ else:
107
+ out += sep + part
108
+ return out
109
+
110
+
111
+ def _exists(path):
112
+ import os
113
+
114
+ try:
115
+ os.stat(path)
116
+ return True
117
+ except OSError:
118
+ return False
119
+
120
+
121
+ def makedirs(path):
122
+ """Make folder *path* and any parents it needs; fine if it exists.
123
+
124
+ ``os.makedirs`` for MicroPython, which has only ``os.mkdir``.
125
+ """
126
+ import os
127
+
128
+ if _exists(path):
129
+ return path
130
+ # Every prefix, shortest first: "/a", "/a/b", ... or "C:\\a", "C:\\a\\b".
131
+ prefixes = []
132
+ for i in range(1, len(path)):
133
+ if path[i] in "/\\" and path[i - 1] not in "/\\:":
134
+ prefixes.append(path[:i])
135
+ prefixes.append(path)
136
+ for p in prefixes:
137
+ if not _exists(p):
138
+ try:
139
+ os.mkdir(p)
140
+ except OSError:
141
+ pass # made meanwhile, or a drive or root we can't make
142
+ if not _exists(path):
143
+ raise OSError("could not make the folder %r" % (path,))
144
+ return path
145
+
146
+
147
+ def app_dir(name, base=None):
148
+ """App *name*'s folder under *base* (default: the data root), made if missing."""
149
+ return makedirs(join(base if base is not None else root(), name))
appkit/data.pyi ADDED
@@ -0,0 +1,25 @@
1
+ # SPDX-FileCopyrightText: 2026 Brad Barnett
2
+ #
3
+ # SPDX-License-Identifier: MIT
4
+ """Where apps keep their files: the data root, and a folder per app under it."""
5
+
6
+ from collections.abc import Callable
7
+
8
+ DESKTOPS: tuple[str, ...]
9
+
10
+ def desktop(platform: str | None = None, implementation: str | None = None) -> bool:
11
+ """True on a desktop operating system, False on a board or in the browser."""
12
+ def default_root(
13
+ platform: str | None = None, implementation: str | None = None, getenv: Callable[[str], str | None] | None = None
14
+ ) -> str:
15
+ """The data root this host uses when nothing sets one."""
16
+ def root() -> str:
17
+ """The data root: what `set_root` set, else `default_root`."""
18
+ def set_root(path: str | None) -> None:
19
+ """Move the data root for the whole program; None goes back to the default."""
20
+ def join(base: str, *parts: str) -> str:
21
+ """`base` and `parts` joined with the separator `base` already uses."""
22
+ def makedirs(path: str) -> str:
23
+ """Make folder `path` and any parents it needs; fine if it exists."""
24
+ def app_dir(name: str, base: str | None = None) -> str:
25
+ """App `name`'s folder under `base` (default: the data root), made if missing."""
appkit/foreground.py ADDED
@@ -0,0 +1,357 @@
1
+ # SPDX-FileCopyrightText: 2026 Brad Barnett
2
+ #
3
+ # SPDX-License-Identifier: MIT
4
+ """The main-thread loop, for work too heavy for a timer.
5
+
6
+ Some work can't run from a timer: waiting on each camera frame, or copying
7
+ USB audio every millisecond. An app hands it to the program's main thread::
8
+
9
+ def main(scope):
10
+ def frame():
11
+ cam.capture(fb, timeout=200) # one frame, then return
12
+ display.show()
13
+
14
+ scope.foreground(frame)
15
+
16
+ `serve` calls the app's function over and over, outside every timer
17
+ callback, until the app closes or clears it. ``appkit.run()`` ends in
18
+ `serve`; an app set with its own launcher calls ``appkit.serve()`` as
19
+ the last line of ``main.py``.
20
+
21
+ There's one foreground function at a time, for the whole program: the last
22
+ app to set one has it. It runs on the main thread, and the timers still
23
+ preempt it where the host can (on a board, between any two bytecodes). A
24
+ switch made from a timer can close the app while its function is in the
25
+ middle of a call, so a function returns promptly once its app has closed,
26
+ and an exception it raises after that is ignored.
27
+
28
+ Where nothing runs `serve` (a browser page, an app started at the
29
+ REPL, or the REPL after Ctrl-C), a function that does one step and returns,
30
+ like a frame, runs from a timer instead. One that never returns
31
+ (``steps=False``) waits until `serve` runs again, so it can't take the
32
+ REPL: ``scope.foreground()`` returns False, so the app can say so.
33
+
34
+ Ctrl-C in the loop goes to the REPL with every timer still running. One
35
+ that lands inside a timer's callback is kept by the timers until they're
36
+ done, so it sometimes needs pressing twice. ``appkit.serve()`` resumes the
37
+ loop.
38
+
39
+ CircuitPython has no REPL to go to with the program still running: Ctrl-C
40
+ ends ``code.py``, and the display with it. There `serve` reads lines typed
41
+ on the console instead, runs each in ``code.py``'s namespace and prints what
42
+ it returns, so ``apps.system.stats()`` answers while the apps keep running.
43
+ """
44
+
45
+ import sys
46
+
47
+ import multimer
48
+
49
+ #: How often a step-at-a-time function runs from a timer, in ms.
50
+ STEP_MS = 5
51
+ #: How long the loop sleeps between looks when there's nothing to run, in ms.
52
+ IDLE_MS = 20
53
+
54
+ _fn = None # the foreground function
55
+ _owner = None # the scope that set it
56
+ _steps = True # whether it does one step and returns
57
+ _timer = None # the timer stepping it, while nothing runs the loop
58
+ _token = None # changes with the function: a stale timer step sees it
59
+ _calls = 0 # calls of the foreground function in progress
60
+ _after_calls = [] # what to run once no call is in progress
61
+ _turns = [] # what runs at the loop's next turn (`next_turn`)
62
+ _serving = False
63
+ _stop = False
64
+
65
+
66
+ def _report(exc):
67
+ print("appkit.foreground: the foreground function failed:")
68
+ _print_exc(exc)
69
+
70
+
71
+ def _print_exc(exc):
72
+ pe = getattr(sys, "print_exception", None)
73
+ if pe is not None:
74
+ pe(exc)
75
+ else:
76
+ import traceback
77
+
78
+ traceback.print_exception(type(exc), exc, exc.__traceback__)
79
+
80
+
81
+ def set_function(scope, fn, steps=True):
82
+ """Make *fn* the foreground function, owned by *scope*; None clears
83
+ *scope*'s. This is ``scope.foreground(fn, steps=steps)``.
84
+
85
+ Returns True when *fn* runs now (the loop is running, or *fn* steps from
86
+ a timer), False when it waits for `serve`.
87
+ """
88
+ global _fn, _owner, _steps, _token
89
+ if fn is None:
90
+ clear(scope)
91
+ return True
92
+ if not callable(fn):
93
+ raise ValueError("the foreground function must be callable")
94
+ _stop_timer()
95
+ _fn = fn
96
+ _owner = scope
97
+ _steps = bool(steps)
98
+ _token = object()
99
+ if _serving:
100
+ return True
101
+ return _arm()
102
+
103
+
104
+ def clear(scope=None):
105
+ """Clear the foreground function, if *scope* (default: anyone) set it."""
106
+ global _fn, _owner, _token
107
+ if scope is not None and _owner is not scope:
108
+ return
109
+ _fn = None
110
+ _owner = None
111
+ _token = None
112
+ _stop_timer()
113
+
114
+
115
+ def calling(scope):
116
+ """True while *scope*'s foreground function is in a call now."""
117
+ return _calls > 0 and _owner is scope
118
+
119
+
120
+ def after_calls(fn, *args):
121
+ """Call ``fn(*args)`` once no call of the foreground function is in
122
+ progress: at once when none is, else when the call returns.
123
+
124
+ A scope closed from inside its own function still has that function
125
+ on the stack, so its module is alive until the call returns; the
126
+ check that it was released waits for that.
127
+ """
128
+ if _calls == 0:
129
+ fn(*args)
130
+ else:
131
+ _after_calls.append((fn, args))
132
+
133
+
134
+ def _call(fn):
135
+ """Call *fn* once. An error in it is reported, and clears the function
136
+ if it is still the foreground one. The caller keeps no reference to
137
+ *fn* while the call runs, and drops its own before `_run_after`."""
138
+ global _calls
139
+ _calls += 1
140
+ try:
141
+ fn()
142
+ except Exception as exc:
143
+ if _fn is fn:
144
+ _report(exc)
145
+ clear()
146
+ # else: its app closed under it, and that's how it noticed
147
+ finally:
148
+ _calls -= 1
149
+
150
+
151
+ def _run_after():
152
+ """Run what `after_calls` queued, now that the call is over."""
153
+ while _calls == 0 and _after_calls:
154
+ fn, args = _after_calls.pop(0)
155
+ fn(*args)
156
+
157
+
158
+ def current():
159
+ """The foreground function, or None."""
160
+ return _fn
161
+
162
+
163
+ def owner():
164
+ """The scope that set the foreground function, or None."""
165
+ return _owner
166
+
167
+
168
+ def serving():
169
+ """True while `serve` is running the loop."""
170
+ return _serving
171
+
172
+
173
+ def next_turn(fn, arg):
174
+ """Call ``fn(arg)`` from `serve`'s loop at its next turn, outside every
175
+ callback, and return True; return False when nothing runs the loop.
176
+
177
+ The launcher starts the next app this way after closing one, so the
178
+ calls below the start are the loop's own and none made while the old app
179
+ ran. An error in *fn* is reported and the loop carries on.
180
+ """
181
+ if not _serving:
182
+ return False
183
+ _turns.append((fn, arg))
184
+ return True
185
+
186
+
187
+ def _run_turns():
188
+ while _turns:
189
+ fn, arg = _turns.pop(0)
190
+ try:
191
+ fn(arg)
192
+ except Exception as exc:
193
+ _print_exc(exc)
194
+
195
+
196
+ def stop():
197
+ """Have `serve` return after the call it's in."""
198
+ global _stop
199
+ _stop = True
200
+
201
+
202
+ def _stop_timer():
203
+ global _timer
204
+ t = _timer
205
+ _timer = None
206
+ if t is not None:
207
+ try:
208
+ t.deinit()
209
+ except Exception:
210
+ pass
211
+
212
+
213
+ def _arm():
214
+ """Step the foreground function from a timer, when it steps; else False."""
215
+ global _timer
216
+ fn = _fn
217
+ scope = _owner
218
+ if fn is None or not _steps:
219
+ return False
220
+ if scope is None or getattr(scope, "closed", False) or getattr(scope, "_closing", False):
221
+ return False
222
+
223
+ token = _token
224
+
225
+ def step(t):
226
+ # The closure keeps no reference to the function: a call that closes
227
+ # its own app must not find this timer holding its module.
228
+ if _token is not token or _serving:
229
+ # Not ours any more, or the loop has it: the loop re-arms one
230
+ # when it stops.
231
+ t.deinit()
232
+ return
233
+ f = _fn
234
+ if f is None:
235
+ return
236
+ _call(f)
237
+ f = None
238
+ _run_after()
239
+
240
+ _timer = scope.every(STEP_MS, step, name="appkit.foreground")
241
+ return True
242
+
243
+
244
+ def _done(app):
245
+ if _stop:
246
+ return True
247
+ return app is not None and app.quit_requested
248
+
249
+
250
+ def _console():
251
+ """A function that runs the lines typed on CircuitPython's console so
252
+ far, or None on any other host (or a CircuitPython with no console)."""
253
+ if sys.implementation.name != "circuitpython":
254
+ return None
255
+ try:
256
+ import supervisor
257
+
258
+ rt = supervisor.runtime
259
+ rt.serial_bytes_available
260
+ # code.py's globals; CircuitPython keeps __main__ out of sys.modules.
261
+ namespace = __import__("__main__").__dict__
262
+ except Exception:
263
+ return None
264
+ buf = [""]
265
+
266
+ def poll():
267
+ n = rt.serial_bytes_available
268
+ if not n:
269
+ return
270
+ text = buf[0] + sys.stdin.read(n).replace("\r", "\n")
271
+ while "\n" in text:
272
+ line, text = text.split("\n", 1)
273
+ line = line.strip()
274
+ if line:
275
+ print(">>> " + line)
276
+ _run_line(line, namespace)
277
+ buf[0] = text
278
+
279
+ return poll
280
+
281
+
282
+ def _run_line(src, namespace):
283
+ try:
284
+ try:
285
+ code = compile(src, "<console>", "eval")
286
+ except SyntaxError:
287
+ exec(compile(src, "<console>", "exec"), namespace)
288
+ else:
289
+ value = eval(code, namespace)
290
+ if value is not None:
291
+ print(repr(value))
292
+ except Exception as exc:
293
+ _print_exc(exc)
294
+
295
+
296
+ def serve(app=None):
297
+ """Run the foreground function over and over until the program quits.
298
+
299
+ The last call of an app set's ``main.py`` (``appkit.run()`` makes it).
300
+ It idles, delivering timers, while there's no foreground function, and
301
+ returns when *app* (default: the current ``App``) quits or a restart
302
+ needs the program to end. Ctrl-C raises out of it to the REPL with the
303
+ timers still running; calling it again resumes the loop.
304
+ """
305
+ global _serving, _stop
306
+ if _serving:
307
+ raise RuntimeError("the foreground loop is already running")
308
+ if app is None:
309
+ from appdev import App
310
+
311
+ app = App.current()
312
+ # A stop() asked for before the loop started still counts: a restart
313
+ # from inside boot(), say.
314
+ _stop_timer()
315
+ console = _console()
316
+ _serving = True
317
+ try:
318
+ while not _done(app):
319
+ if _turns:
320
+ _run_turns()
321
+ if console is not None:
322
+ console()
323
+ fn = _fn
324
+ if fn is None:
325
+ multimer.sleep_ms(IDLE_MS)
326
+ continue
327
+ _call(fn)
328
+ fn = None
329
+ _run_after()
330
+ # Due timers, on a host whose timers only fire when asked.
331
+ multimer.pump()
332
+ finally:
333
+ _serving = False
334
+ _stop = False
335
+ _arm()
336
+ recover()
337
+
338
+
339
+ def recover():
340
+ """After a Ctrl-C: one that lands inside a timer delivery can leave
341
+ multimer with no wake armed, or LVGL's own timer disarmed. Put both back
342
+ before the REPL takes over."""
343
+ try:
344
+ multimer.pump()
345
+ except (Exception, KeyboardInterrupt):
346
+ pass # a second Ctrl-C, kept by a timer: this one is on its way out already
347
+ display_driver = sys.modules.get("display_driver")
348
+ if display_driver is None:
349
+ return # no LVGL event loop to put back
350
+ try:
351
+ loop = display_driver.event_loop.current_instance()
352
+ t = loop.timer
353
+ if not (t.running and t.due_in > -1000):
354
+ multimer.pump()
355
+ loop._arm()
356
+ except Exception:
357
+ pass
appkit/foreground.pyi ADDED
@@ -0,0 +1,45 @@
1
+ # SPDX-FileCopyrightText: 2026 Brad Barnett
2
+ #
3
+ # SPDX-License-Identifier: MIT
4
+ """The main-thread loop, for work too heavy for a timer."""
5
+
6
+ from collections.abc import Callable
7
+ from typing import Any, Protocol
8
+
9
+ class _Scope(Protocol):
10
+ @property
11
+ def closed(self) -> bool: ...
12
+ def every(self, ms: int, callback: Callable[[Any], Any], *, name: str | None = None) -> Any: ...
13
+
14
+ class _App(Protocol):
15
+ @property
16
+ def quit_requested(self) -> bool: ...
17
+
18
+ STEP_MS: int
19
+ IDLE_MS: int
20
+
21
+ def set_function(scope: _Scope, fn: Callable[[], Any] | None, steps: bool = True) -> bool:
22
+ """Make `fn` the foreground function, owned by `scope`; None clears `scope`'s.
23
+
24
+ Returns True when `fn` runs now, False when it waits for `serve`.
25
+ """
26
+ def clear(scope: _Scope | None = None) -> None:
27
+ """Clear the foreground function, if `scope` (default: anyone) set it."""
28
+ def calling(scope: _Scope) -> bool:
29
+ """True while `scope`'s foreground function is in a call now."""
30
+ def after_calls(fn: Callable[..., Any], *args: Any) -> None:
31
+ """Call `fn(*args)` once no call of the foreground function is in progress."""
32
+ def current() -> Callable[[], Any] | None:
33
+ """The foreground function, or None."""
34
+ def owner() -> _Scope | None:
35
+ """The scope that set the foreground function, or None."""
36
+ def serving() -> bool:
37
+ """True while `serve` is running the loop."""
38
+ def next_turn(fn: Callable[[Any], Any], arg: Any) -> bool:
39
+ """Call `fn(arg)` from `serve`'s loop at its next turn; False when nothing runs the loop."""
40
+ def stop() -> None:
41
+ """Have `serve` return after the call it's in."""
42
+ def serve(app: _App | None = None) -> None:
43
+ """Run the foreground function over and over until the program quits."""
44
+ def recover() -> None:
45
+ """After a Ctrl-C: put multimer's wake and LVGL's timer back before the REPL takes over."""
appkit/home.py ADDED
@@ -0,0 +1,19 @@
1
+ # SPDX-FileCopyrightText: 2026 Brad Barnett
2
+ #
3
+ # SPDX-License-Identifier: MIT
4
+ """The home screen: a button for each app."""
5
+
6
+ import lvgl as lv
7
+
8
+
9
+ def main(scope):
10
+ launcher = scope.launcher
11
+ page = scope.root
12
+ page.set_flex_flow(lv.FLEX_FLOW.COLUMN)
13
+ page.set_flex_align(lv.FLEX_ALIGN.CENTER, lv.FLEX_ALIGN.CENTER, lv.FLEX_ALIGN.CENTER)
14
+ for name in launcher.names:
15
+ if name == launcher.home:
16
+ continue
17
+ b = lv.button(page)
18
+ lv.label(b).set_text(launcher.info[name].get("title", name))
19
+ b.add_event_cb(lambda e, n=name: scope.switch(n), lv.EVENT.CLICKED, None)
appkit/home.pyi ADDED
@@ -0,0 +1,8 @@
1
+ # SPDX-FileCopyrightText: 2026 Brad Barnett
2
+ #
3
+ # SPDX-License-Identifier: MIT
4
+ """The home screen: a button for each app."""
5
+
6
+ from .scope import AppScope
7
+
8
+ def main(scope: AppScope) -> None: ...