omnipython-applibs 0.1.2.dev16__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.dev16.dist-info/METADATA +90 -0
  63. omnipython_applibs-0.1.2.dev16.dist-info/RECORD +143 -0
  64. omnipython_applibs-0.1.2.dev16.dist-info/WHEEL +5 -0
  65. omnipython_applibs-0.1.2.dev16.dist-info/licenses/LICENSE +21 -0
  66. omnipython_applibs-0.1.2.dev16.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/launcher.pyi ADDED
@@ -0,0 +1,96 @@
1
+ # SPDX-FileCopyrightText: 2026 Brad Barnett
2
+ #
3
+ # SPDX-License-Identifier: MIT
4
+ """Launcher: start switchable apps by name, and switch between them."""
5
+
6
+ from collections.abc import Mapping
7
+ from typing import Any, Literal
8
+
9
+ from . import data as data, foreground as foreground
10
+ from .data import DESKTOPS as DESKTOPS
11
+ from .scope import AppScope as AppScope, mem_free as mem_free
12
+ from .shell import Shell
13
+
14
+ RESTART_EXIT_CODE: int
15
+ PROBE_LIMIT: int
16
+ MICROPYTHON: bool
17
+
18
+ def largest_free_block(limit: int | None = None) -> int | None:
19
+ """The largest bytearray that can be allocated now, in bytes; None where the heap can't be read."""
20
+ def lacks(needs: list[str] | tuple[str, ...] | None) -> str | None:
21
+ """The first of `needs` this interpreter doesn't have, or None."""
22
+
23
+ INIT_TEXT: str
24
+
25
+ def host() -> Literal['board', 'desktop', 'cpython', 'browser', 'circuitpython']:
26
+ """Which restart path this interpreter takes."""
27
+
28
+ SCRIPT: str
29
+
30
+ def save_next(name: str, count: int = 1, path: str | None = None) -> None:
31
+ """Keep `name` (and how many restarts in a row led here) for the next boot."""
32
+ def take_next() -> tuple[str, int] | None:
33
+ """The `(name, count)` a restart left for this boot, cleared once read, or None."""
34
+ def read_next(clear: bool = False) -> tuple[str, int, str | None] | None:
35
+ """The `(name, count, path)` a restart left for this boot, or None."""
36
+ def restart_into(name: str | None, count: int = 1, path: str | None = None) -> None:
37
+ """Restart the program straight into app `name`, the host's way."""
38
+ def run_pending_script(data_root: str | None = None) -> bool:
39
+ """Run the script a launcher restarted into, if there is one."""
40
+
41
+ class Launcher:
42
+ """Owns the long-lived App, starts apps by name and switches between them."""
43
+
44
+ app: Any
45
+ home: str | None
46
+ shell: Shell | None
47
+ info: dict[str, dict[str, Any]]
48
+ min_free: int | None
49
+ min_block: int | None
50
+ max_restarts: int
51
+ current: str | None
52
+ scope: AppScope | None
53
+ restarts: int
54
+ switches: int
55
+ problems: list[str]
56
+ baseline: tuple[int | None, int | None] | None
57
+ last: tuple[str, int | None, int | None] | None
58
+ def __init__(
59
+ self,
60
+ app: Any = None,
61
+ apps: Mapping[str, str] | None = None,
62
+ *,
63
+ home: str | None = None,
64
+ shell: Shell | None = None,
65
+ min_free: int | None = None,
66
+ min_block: int | None = None,
67
+ max_restarts: int = 3,
68
+ ) -> None: ...
69
+ def add(self, name: str, module: str | None = None) -> None:
70
+ """Register app `name`, whose `main(scope)` is in `module` (default `name`)."""
71
+ def add_script(self, name: str, module: str | None = None, path: str | None = None) -> None:
72
+ """Register `name` as a plain script that builds its own `App` when imported."""
73
+ def is_script(self, name: str) -> bool:
74
+ """True when `name` is a plain script rather than an app."""
75
+ def scan(self, folder: str = 'apps') -> dict[str, dict[str, Any]]:
76
+ """Register every app in `folder`; returns the apps' `app.json` contents, by name."""
77
+ @property
78
+ def names(self) -> tuple[str, ...]:
79
+ """Every app's and script's name, in the order they were added."""
80
+ def heap(self) -> tuple[int | None, int | None]:
81
+ """`(free, largest_free_block)` now, or `(None, None)` on CPython."""
82
+ def boot(self, default: str | None = None) -> str:
83
+ """Start the app a restart asked for, else `default`, else `home`; returns its name."""
84
+ def start(self, name: str) -> None:
85
+ """Start app `name`; the same as `switch`."""
86
+ def request(self, name: str) -> None:
87
+ """Switch to `name` at the next safe point, after the current callback."""
88
+ def switch(self, name: str) -> Literal['start', 'switch', 'restart']:
89
+ """Close the running app and start app `name`."""
90
+ def stop(self) -> list[str]:
91
+ """Close the running app and cancel a pending switch."""
92
+
93
+ def supervise(cmd: list[str] | tuple[str, ...]) -> int:
94
+ """Run `cmd`, and again each time it exits asking for a restart; returns its final exit code."""
95
+ def main(argv: list[str] | None = None) -> int:
96
+ """`python -m appkit.launcher [--] <command>`: run a launcher program, restarting it whenever it asks."""
appkit/manifest.py ADDED
@@ -0,0 +1,75 @@
1
+ # SPDX-FileCopyrightText: 2026 Brad Barnett
2
+ #
3
+ # SPDX-License-Identifier: MIT
4
+ # appkit's MicroPython manifest. From a board's manifest.py:
5
+ #
6
+ # include("/path/to/apps/lib/appkit") appkit and iconkit
7
+ #
8
+ # import os
9
+ # include("/path/to/apps/lib/appkit", apps=os.path.abspath("apps"))
10
+ # appkit, iconkit, every app in
11
+ # apps/, and their index, _appkit_apps
12
+ #
13
+ # appkit's Home and apps draw with iconkit, a package of its own in the omnipython
14
+ # repository (packages/iconkit). It is frozen with appkit, from the folder that
15
+ # iconkit= names: that repository's packages/iconkit, or <tree>/iconkit in an
16
+ # omnipython-lib tree. Without iconkit=, $OMNIPYTHON_LIBRARY (the tree build_mp.py
17
+ # sets) is used. With neither, this manifest raises: it never freezes appkit
18
+ # without the icons its Home needs. A build that gets appkit from the library
19
+ # with require("appkit", library="omnipython-lib") gets iconkit from the library
20
+ # instead, and doesn't include this file.
21
+ #
22
+ # apps= must be an absolute path: this file runs from appkit's own folder.
23
+ # index_dir= says where to write _appkit_apps.py (default: a temporary folder).
24
+
25
+ options.defaults(apps=None, index_dir=None, iconkit=None)
26
+
27
+
28
+ def _iconkit_folder():
29
+ """(the folder with iconkit's manifest.py, the folder its source imports from)."""
30
+ import os
31
+
32
+ named = options.iconkit
33
+ if named is None:
34
+ tree = os.environ.get("OMNIPYTHON_LIBRARY")
35
+ named = os.path.join(tree, "iconkit") if tree else None
36
+ if named is None:
37
+ raise ValueError(
38
+ "appkit manifest: iconkit is not found. appkit's Home draws with it. Pass "
39
+ 'iconkit="/path/to/omnipython/packages/iconkit", or set OMNIPYTHON_LIBRARY to an '
40
+ "omnipython-lib tree that has iconkit (build_mp.py does)"
41
+ )
42
+ named = os.path.abspath(named)
43
+ # packages/iconkit keeps its source in lib/iconkit, a library tree in iconkit/iconkit.
44
+ for source in (os.path.join(named, "lib"), named):
45
+ if os.path.isfile(os.path.join(source, "iconkit", "__init__.py")) and os.path.isfile(
46
+ os.path.join(named, "manifest.py")
47
+ ):
48
+ return named, source
49
+ raise ValueError(
50
+ "appkit manifest: %s is not iconkit's folder: it has no manifest.py beside lib/iconkit or iconkit. "
51
+ "Pass iconkit= the packages/iconkit folder of the omnipython repository" % (named,)
52
+ )
53
+
54
+
55
+ _iconkit, _iconkit_source = _iconkit_folder()
56
+
57
+ package("appkit", base_path="..") # this folder is appkit itself; its parent holds the package
58
+ include(_iconkit) # the icons appkit's Home and apps draw with
59
+
60
+ if options.apps:
61
+ import importlib.util
62
+ import os
63
+ import sys
64
+
65
+ if not os.path.isabs(options.apps):
66
+ raise ValueError("appkit manifest: apps=%r must be an absolute path" % (options.apps,))
67
+ spec = importlib.util.spec_from_file_location("appkit_index", os.path.abspath("index.py"))
68
+ index = importlib.util.module_from_spec(spec)
69
+ spec.loader.exec_module(index)
70
+ # index.freeze_apps checks each app's icon against iconkit, imported here on the host.
71
+ sys.path.insert(0, _iconkit_source)
72
+ try:
73
+ index.freeze_apps(options.apps, module, package, options.index_dir)
74
+ finally:
75
+ sys.path.remove(_iconkit_source)
appkit/manifest.pyi ADDED
@@ -0,0 +1,8 @@
1
+ # SPDX-FileCopyrightText: 2026 Brad Barnett
2
+ #
3
+ # SPDX-License-Identifier: MIT
4
+ from importlib.machinery import ModuleSpec
5
+ from types import ModuleType
6
+
7
+ spec: ModuleSpec | None
8
+ index: ModuleType
appkit/net.py ADDED
@@ -0,0 +1,167 @@
1
+ # SPDX-FileCopyrightText: 2026 Brad Barnett
2
+ #
3
+ # SPDX-License-Identifier: MIT
4
+ """appkit.net: sockets, HTTP and the clock, with the same calls on every Python.
5
+
6
+ CircuitPython reaches the network differently from MicroPython and a desktop.
7
+ It has no ``socket`` module: sockets come from a ``socketpool.SocketPool`` on
8
+ ``wifi.radio``, which has the same ``socket()``, ``getaddrinfo()`` and
9
+ constants. Its core has no HTTP client: Adafruit's ``adafruit_requests``, from
10
+ the CircuitPython library bundle, gives a ``Session`` with the calls of
11
+ ``requests``. And its clock is ``rtc.RTC()``, where MicroPython's is
12
+ ``machine.RTC()`` and a desktop keeps its own.
13
+
14
+ An app or library that goes through these runs on all three::
15
+
16
+ from appkit import net
17
+
18
+ resp = net.requests().get("https://example.com/", timeout=10)
19
+ sock = net.sockets().socket()
20
+
21
+ A missing piece raises ``ImportError`` saying what to install; nothing here
22
+ falls back quietly to something else.
23
+ """
24
+
25
+ import struct
26
+ import sys
27
+ import time
28
+
29
+ CIRCUITPYTHON = sys.implementation.name == "circuitpython"
30
+
31
+ try:
32
+ import machine
33
+ import ntptime
34
+ except ImportError: # a desktop keeps its own time; CircuitPython has neither
35
+ machine = None
36
+ ntptime = None
37
+
38
+ #: Where `ntp` asks on CircuitPython. MicroPython's ``ntptime`` has its own.
39
+ NTP_HOST = "pool.ntp.org"
40
+ # Seconds from NTP's epoch (1900) to the Unix one (1970).
41
+ _NTP_DELTA = 2208988800
42
+
43
+ _pool = None
44
+ _session = None
45
+
46
+
47
+ def sockets():
48
+ """Return what makes sockets: the ``socket`` module, or on CircuitPython a
49
+ ``socketpool.SocketPool`` on ``wifi.radio``.
50
+
51
+ Both have ``socket(family, type)``, ``getaddrinfo(host, port)`` and the
52
+ ``AF_INET``, ``SOCK_STREAM`` and ``SOCK_DGRAM`` constants. Read with `recv`,
53
+ since CircuitPython's sockets have ``recv_into`` but no ``recv``.
54
+ """
55
+ global _pool
56
+ if not CIRCUITPYTHON:
57
+ import socket
58
+
59
+ return socket
60
+ if _pool is None:
61
+ import socketpool
62
+ import wifi
63
+
64
+ _pool = socketpool.SocketPool(wifi.radio)
65
+ return _pool
66
+
67
+
68
+ def recv(sock, size):
69
+ """Return up to *size* bytes from *sock*, ``b""`` when the other end has closed.
70
+
71
+ Args:
72
+ sock: A socket made through `sockets`, stream or datagram.
73
+ size (int): The most to read.
74
+ """
75
+ if not CIRCUITPYTHON:
76
+ return sock.recv(size)
77
+ buf = bytearray(size)
78
+ n = sock.recv_into(buf)
79
+ return bytes(buf[:n])
80
+
81
+
82
+ def requests():
83
+ """Return an HTTP client with the calls of ``requests``.
84
+
85
+ That's the ``requests`` module on MicroPython and a desktop, and on
86
+ CircuitPython one ``adafruit_requests.Session`` on `sockets` with TLS,
87
+ kept for the program's life. Responses have ``json()``, ``content``,
88
+ ``headers`` and ``close()`` everywhere.
89
+
90
+ Raises:
91
+ ImportError: The client isn't installed; the message says how to get it.
92
+ """
93
+ global _session
94
+ if not CIRCUITPYTHON:
95
+ try:
96
+ import requests as client
97
+ except ImportError:
98
+ raise ImportError('HTTP needs requests: mip.install("requests"), or pip install requests on a computer')
99
+ return client
100
+ if _session is None:
101
+ try:
102
+ import adafruit_requests
103
+ except ImportError:
104
+ raise ImportError(
105
+ 'HTTP on CircuitPython needs adafruit_requests: omip.install("adafruit_requests") on the board, '
106
+ "or circup install adafruit_requests from a computer"
107
+ )
108
+ import ssl
109
+
110
+ _session = adafruit_requests.Session(sockets(), ssl.create_default_context())
111
+ return _session
112
+
113
+
114
+ def sets_clock():
115
+ """Return True where this program keeps the clock (a board), False where
116
+ the computer does (a desktop)."""
117
+ return CIRCUITPYTHON or machine is not None
118
+
119
+
120
+ def set_clock(year, month, day, hour, minute, second):
121
+ """Set the board's clock to a UTC time.
122
+
123
+ Raises:
124
+ OSError: This is a desktop, whose clock is the computer's.
125
+ """
126
+ weekday = time.localtime(time.mktime((year, month, day, 12, 0, 0, 0, 0, 0)))[6]
127
+ if CIRCUITPYTHON:
128
+ import rtc
129
+
130
+ rtc.RTC().datetime = time.struct_time((year, month, day, hour, minute, second, weekday, -1, -1))
131
+ elif machine is not None:
132
+ machine.RTC().datetime((year, month, day, weekday, hour, minute, second, 0))
133
+ else:
134
+ raise OSError("a desktop keeps its own clock")
135
+
136
+
137
+ def ntp(timeout=3):
138
+ """Set the board's clock from NTP. It blocks: call it from a worker.
139
+
140
+ MicroPython asks through its ``ntptime``; CircuitPython sends one SNTP
141
+ query to `NTP_HOST` over `sockets`.
142
+
143
+ Raises:
144
+ OSError: No answer within *timeout* seconds, or this is a desktop.
145
+ """
146
+ if not CIRCUITPYTHON:
147
+ if ntptime is None:
148
+ raise OSError("a desktop keeps its own clock")
149
+ ntptime.timeout = timeout
150
+ ntptime.settime()
151
+ return
152
+ pool = sockets()
153
+ addr = pool.getaddrinfo(NTP_HOST, 123)[0][-1]
154
+ s = pool.socket(pool.AF_INET, pool.SOCK_DGRAM)
155
+ try:
156
+ s.settimeout(timeout)
157
+ query = bytearray(48)
158
+ query[0] = 0x1B # version 3, client
159
+ s.sendto(query, addr)
160
+ reply = bytearray(48)
161
+ n = s.recvfrom_into(reply)[0]
162
+ finally:
163
+ s.close()
164
+ if n < 48:
165
+ raise OSError("a short NTP reply (%d bytes)" % n)
166
+ seconds = struct.unpack("!I", reply[40:44])[0] - _NTP_DELTA
167
+ set_clock(*time.localtime(seconds)[:6])
appkit/net.pyi ADDED
@@ -0,0 +1,34 @@
1
+ # SPDX-FileCopyrightText: 2026 Brad Barnett
2
+ #
3
+ # SPDX-License-Identifier: MIT
4
+ """appkit.net: sockets, HTTP and the clock, with the same calls on every Python."""
5
+
6
+ from typing import Any
7
+
8
+ CIRCUITPYTHON: bool
9
+ NTP_HOST: str
10
+
11
+ def sockets() -> Any:
12
+ """The `socket` module, or on CircuitPython a `socketpool.SocketPool` on `wifi.radio`."""
13
+ def recv(sock: Any, size: int) -> bytes:
14
+ """Up to `size` bytes from `sock`, `b""` when the other end has closed."""
15
+ def requests() -> Any:
16
+ """An HTTP client with the calls of `requests`.
17
+
18
+ Raises:
19
+ ImportError: The client isn't installed.
20
+ """
21
+ def sets_clock() -> bool:
22
+ """True where this program keeps the clock (a board), False on a desktop."""
23
+ def set_clock(year: int, month: int, day: int, hour: int, minute: int, second: int) -> None:
24
+ """Set the board's clock to a UTC time.
25
+
26
+ Raises:
27
+ OSError: This is a desktop.
28
+ """
29
+ def ntp(timeout: int = 3) -> None:
30
+ """Set the board's clock from NTP. It blocks: call it from a worker.
31
+
32
+ Raises:
33
+ OSError: No answer within `timeout` seconds, or this is a desktop.
34
+ """
appkit/places.py ADDED
@@ -0,0 +1,202 @@
1
+ # SPDX-FileCopyrightText: 2026 Brad Barnett
2
+ #
3
+ # SPDX-License-Identifier: MIT
4
+ """Find and save an app's files on the SD card, then flash, then the data root.
5
+
6
+ Each kind of file has one folder name, the same in all three places. For
7
+ ``photos`` on a board that is:
8
+
9
+ ============== ==============================================
10
+ the SD card ``/sd/photos``
11
+ flash ``/photos`` (``/flash/photos`` on an STM32)
12
+ the data root ``/data/photos`` (``/flash/data/photos`` on an STM32)
13
+ ============== ==============================================
14
+
15
+ An app reads from all three, in that order, and writes to the first one
16
+ that takes a file: the card when it's in and mounted for writing, else
17
+ flash, else the data root. On a desktop there is no card and no flash, so
18
+ the data root's folder is the only place (``~/.local/share/appkit/photos``
19
+ on Linux).
20
+
21
+ Example:
22
+ Mount the card while the app is open, then save and list::
23
+
24
+ places.hold_card(scope, write=True)
25
+ folder = places.write_folder("photos")
26
+ songs = places.files("music", (".mp3",))
27
+ """
28
+
29
+ import os
30
+ import sys
31
+
32
+ from . import data
33
+
34
+ #: Where the SD card is mounted.
35
+ SD = "/sd"
36
+
37
+ DIR_MODE = 0x4000 # S_IFDIR, in os.stat's mode on every interpreter
38
+
39
+
40
+ def flash_root(platform=None):
41
+ """The top of flash: ``""`` (so ``/photos``), or ``/flash`` on an STM32,
42
+ whose ``/`` only holds mounts."""
43
+ return "/flash" if (platform or sys.platform) == "pyboard" else ""
44
+
45
+
46
+ def folders(name):
47
+ """The folders a kind of file lives in, in the order they're looked at.
48
+
49
+ Args:
50
+ name: the folder name, such as ``"photos"``.
51
+
52
+ Returns:
53
+ The card's, flash's and the data root's folder on a board; the data
54
+ root's alone on a desktop.
55
+ """
56
+ in_data = data.join(data.root(), name)
57
+ if data.desktop():
58
+ return [in_data]
59
+ return [SD + "/" + name, flash_root() + "/" + name, in_data]
60
+
61
+
62
+ def where_text(name):
63
+ """The folders, for a message: ``/sd/music, /music or /data/music``."""
64
+ places = folders(name)
65
+ if len(places) == 1:
66
+ return places[0]
67
+ return ", ".join(places[:-1]) + " or " + places[-1]
68
+
69
+
70
+ def _exists(path):
71
+ try:
72
+ os.stat(path)
73
+ return True
74
+ except OSError:
75
+ return False
76
+
77
+
78
+ def _is_dir(path):
79
+ try:
80
+ return bool(os.stat(path)[0] & DIR_MODE)
81
+ except OSError:
82
+ return False
83
+
84
+
85
+ def find(name, filename):
86
+ """The first ``<folder>/<filename>`` that exists, or None."""
87
+ for folder in folders(name):
88
+ path = folder + "/" + filename
89
+ if _exists(path):
90
+ return path
91
+ return None
92
+
93
+
94
+ def files(name, extensions, deep=False):
95
+ """Every file of a kind, from all its folders.
96
+
97
+ Args:
98
+ name: the folder name, such as ``"music"``.
99
+ extensions: a tuple of lowercase endings with the dot, ``(".mp3",)``.
100
+ deep: look in the folders under them too.
101
+
102
+ Returns:
103
+ Full paths: the card's first, then flash's, then the data root's,
104
+ each in name order.
105
+ """
106
+ found = []
107
+ for folder in folders(name):
108
+ found.extend(_scan(folder, extensions, deep))
109
+ return found
110
+
111
+
112
+ def _scan(folder, extensions, deep):
113
+ try:
114
+ names = sorted(os.listdir(folder))
115
+ except OSError:
116
+ return []
117
+ found = []
118
+ for n in names:
119
+ path = folder + "/" + n
120
+ if deep and _is_dir(path):
121
+ found.extend(_scan(path, extensions, deep))
122
+ else:
123
+ low = n.lower()
124
+ for ext in extensions: # MicroPython's endswith takes no tuple
125
+ if low.endswith(ext):
126
+ found.append(path)
127
+ break
128
+ return found
129
+
130
+
131
+ def write_folder(name):
132
+ """The first folder a file of this kind can be written in, made if missing.
133
+
134
+ That's the card's when it's mounted and writable, else flash's, else the
135
+ data root's.
136
+
137
+ Raises:
138
+ OSError: none of them takes a file.
139
+ """
140
+ tried = []
141
+ for folder in folders(name):
142
+ # Never make /sd itself: with no card in, it would be a folder on flash.
143
+ if folder.startswith(SD + "/") and not _exists(SD):
144
+ continue
145
+ try:
146
+ data.makedirs(folder)
147
+ probe = folder + "/.write-test"
148
+ with open(probe, "wb") as f:
149
+ f.write(b"\n")
150
+ os.remove(probe)
151
+ return folder
152
+ except OSError as e:
153
+ tried.append("%s (%s)" % (folder, e))
154
+ raise OSError("nowhere to write %s: %s" % (name, "; ".join(tried) or "no folders"))
155
+
156
+
157
+ def mount_card(write=False):
158
+ """Mount the SD card at `SD`.
159
+
160
+ Returns:
161
+ The card, to pass to `unmount_card`; True when something else already
162
+ has it mounted; False when there's no card (the board has no
163
+ ``sdcard`` role, or the card won't mount).
164
+ """
165
+ if data.desktop():
166
+ return False
167
+ if _exists(SD):
168
+ return True # someone else's mount: leave it
169
+ try:
170
+ import board_peripherals as bp
171
+
172
+ card = bp.sdcard()
173
+ except Exception as e: # noqa: BLE001 - no card role or no card: flash and data still work
174
+ print("no SD card:", e)
175
+ return False
176
+ try:
177
+ os.mount(card, SD, readonly=not write)
178
+ except Exception as e: # noqa: BLE001
179
+ print("SD card didn't mount:", e)
180
+ try:
181
+ card.deinit()
182
+ except Exception: # noqa: BLE001
183
+ pass
184
+ return False
185
+ return card
186
+
187
+
188
+ def unmount_card(card):
189
+ """Undo `mount_card`; a mount that wasn't ours is left alone."""
190
+ if card in (True, False, None):
191
+ return
192
+ try:
193
+ os.umount(SD)
194
+ finally:
195
+ card.deinit()
196
+
197
+
198
+ def hold_card(scope, write=False):
199
+ """Mount the card while *scope*'s app is open; returns what `mount_card` did."""
200
+ card = mount_card(write)
201
+ scope.on_close(lambda: unmount_card(card))
202
+ return card
appkit/places.pyi ADDED
@@ -0,0 +1,39 @@
1
+ # SPDX-FileCopyrightText: 2026 Brad Barnett
2
+ #
3
+ # SPDX-License-Identifier: MIT
4
+ """Find and save an app's files on the SD card, then flash, then the data root."""
5
+
6
+ from typing import Any
7
+
8
+ from . import data as data
9
+ from .scope import AppScope
10
+
11
+ SD: str
12
+ DIR_MODE: int
13
+
14
+ def flash_root(platform: str | None = None) -> str:
15
+ """The top of flash: `""`, or `/flash` on an STM32."""
16
+ def folders(name: str) -> list[str]:
17
+ """The folders a kind of file lives in, in the order they're looked at."""
18
+ def where_text(name: str) -> str:
19
+ """The folders, for a message: `/sd/music, /music or /data/music`."""
20
+ def find(name: str, filename: str) -> str | None:
21
+ """The first `<folder>/<filename>` that exists, or None."""
22
+ def files(name: str, extensions: tuple[str, ...], deep: bool = False) -> list[str]:
23
+ """Every file of a kind, from all its folders, as full paths."""
24
+ def write_folder(name: str) -> str:
25
+ """The first folder a file of this kind can be written in, made if missing.
26
+
27
+ Raises:
28
+ OSError: none of them takes a file.
29
+ """
30
+ def mount_card(write: bool = False) -> Any:
31
+ """Mount the SD card at `SD`.
32
+
33
+ Returns the card to pass to `unmount_card`; True when something else already
34
+ has it mounted; False when there's no card.
35
+ """
36
+ def unmount_card(card: Any) -> None:
37
+ """Undo `mount_card`; a mount that wasn't ours is left alone."""
38
+ def hold_card(scope: AppScope, write: bool = False) -> Any:
39
+ """Mount the card while `scope`'s app is open; returns what `mount_card` did."""
appkit/py.typed ADDED
File without changes