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.
- appkit/__init__.py +52 -0
- appkit/__init__.pyi +17 -0
- appkit/data.py +149 -0
- appkit/data.pyi +25 -0
- appkit/foreground.py +357 -0
- appkit/foreground.pyi +45 -0
- appkit/home.py +19 -0
- appkit/home.pyi +8 -0
- appkit/hover.py +59 -0
- appkit/hover.pyi +13 -0
- appkit/index.py +199 -0
- appkit/index.pyi +30 -0
- appkit/launcher.py +1075 -0
- appkit/launcher.pyi +96 -0
- appkit/manifest.py +75 -0
- appkit/manifest.pyi +8 -0
- appkit/net.py +167 -0
- appkit/net.pyi +34 -0
- appkit/places.py +202 -0
- appkit/places.pyi +39 -0
- appkit/py.typed +0 -0
- appkit/scope.py +636 -0
- appkit/scope.pyi +110 -0
- appkit/shell.py +121 -0
- appkit/shell.pyi +32 -0
- appkit/worker.py +409 -0
- appkit/worker.pyi +83 -0
- controlkit/__init__.py +19 -0
- controlkit/__init__.pyi +10 -0
- controlkit/_draw.py +88 -0
- controlkit/_safe.py +29 -0
- controlkit/dotmatrix.py +101 -0
- controlkit/dotmatrix.pyi +23 -0
- controlkit/encoder.py +297 -0
- controlkit/encoder.pyi +55 -0
- controlkit/font5x7.py +22 -0
- controlkit/font5x7.pyi +11 -0
- controlkit/lamp_button.py +92 -0
- controlkit/lamp_button.pyi +40 -0
- controlkit/meter.py +86 -0
- controlkit/meter.pyi +30 -0
- controlkit/mock.py +116 -0
- controlkit/mock.pyi +35 -0
- controlkit/pad_grid.py +113 -0
- controlkit/pad_grid.pyi +41 -0
- controlkit/py.typed +0 -0
- controlkit/slider.py +185 -0
- controlkit/slider.pyi +49 -0
- controlkit/sprites.py +279 -0
- controlkit/sprites.pyi +22 -0
- controlkit/theme.py +120 -0
- controlkit/theme.pyi +15 -0
- deskkit/__init__.py +74 -0
- deskkit/__init__.pyi +18 -0
- deskkit/forecast.py +261 -0
- deskkit/forecast.pyi +40 -0
- deskkit/localtime.py +215 -0
- deskkit/localtime.pyi +33 -0
- deskkit/py.typed +0 -0
- deskkit/shell.py +113 -0
- deskkit/shell.pyi +33 -0
- omnipython_applibs-0.1.2.dev16.dist-info/METADATA +90 -0
- omnipython_applibs-0.1.2.dev16.dist-info/RECORD +143 -0
- omnipython_applibs-0.1.2.dev16.dist-info/WHEEL +5 -0
- omnipython_applibs-0.1.2.dev16.dist-info/licenses/LICENSE +21 -0
- omnipython_applibs-0.1.2.dev16.dist-info/top_level.txt +9 -0
- programkit/__init__.py +27 -0
- programkit/__init__.pyi +8 -0
- programkit/board.py +56 -0
- programkit/board.pyi +20 -0
- programkit/press.py +63 -0
- programkit/press.pyi +17 -0
- programkit/py.typed +0 -0
- programkit/rows.py +149 -0
- programkit/rows.pyi +34 -0
- sayso/__init__.py +109 -0
- sayso/__init__.pyi +124 -0
- sayso/auth.py +811 -0
- sayso/auth.pyi +102 -0
- sayso/client.py +1286 -0
- sayso/client.pyi +138 -0
- sayso/keepalive.py +371 -0
- sayso/keepalive.pyi +53 -0
- sayso/local.py +85 -0
- sayso/local.pyi +28 -0
- sayso/object_specs.py +706 -0
- sayso/object_specs.pyi +8 -0
- sayso/objects.py +411 -0
- sayso/objects.pyi +854 -0
- sayso/py.typed +0 -0
- sayso/schema_coverage.py +210 -0
- sayso/schema_coverage.pyi +13 -0
- sayso/transport.py +426 -0
- sayso/transport.pyi +47 -0
- songmodel/__init__.py +30 -0
- songmodel/__init__.pyi +9 -0
- songmodel/link.py +189 -0
- songmodel/link.pyi +53 -0
- songmodel/model.py +238 -0
- songmodel/model.pyi +40 -0
- songmodel/page.html +225 -0
- songmodel/page_data.py +236 -0
- songmodel/page_data.pyi +6 -0
- songmodel/py.typed +0 -0
- soundmodule/__init__.py +7 -0
- soundmodule/__init__.pyi +6 -0
- soundmodule/engine.py +1001 -0
- soundmodule/engine.pyi +196 -0
- soundmodule/names.py +298 -0
- soundmodule/names.pyi +30 -0
- soundmodule/pipes.py +105 -0
- soundmodule/pipes.pyi +31 -0
- soundmodule/py.typed +0 -0
- soundmodule/run.py +249 -0
- soundmodule/run.pyi +49 -0
- spectrum/__init__.py +72 -0
- spectrum/__init__.pyi +30 -0
- spectrum/analyzer.py +231 -0
- spectrum/analyzer.pyi +67 -0
- spectrum/fake_music.py +201 -0
- spectrum/fake_music.pyi +36 -0
- spectrum/pump_levels.py +126 -0
- spectrum/pump_levels.pyi +46 -0
- spectrum/py.typed +0 -0
- spectrum/spectrum_view.py +403 -0
- spectrum/spectrum_view.pyi +80 -0
- touchkit/__init__.py +4 -0
- touchkit/__init__.pyi +4 -0
- touchkit/cam.py +146 -0
- touchkit/cam.pyi +35 -0
- touchkit/clock.py +18 -0
- touchkit/clock.pyi +6 -0
- touchkit/ecp.py +134 -0
- touchkit/ecp.pyi +28 -0
- touchkit/net.py +347 -0
- touchkit/net.pyi +27 -0
- touchkit/py.typed +0 -0
- touchkit/settings.py +85 -0
- touchkit/settings.pyi +17 -0
- touchkit/shell.py +268 -0
- touchkit/shell.pyi +42 -0
- touchkit/ui.py +167 -0
- 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
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
|