API
- class Device(*args, startup: Optional[str] = None, attempts: int = 0, **kwargs)
Belay interface into a micropython device.
- implementation
Implementation details of device.
- Type
- task(f: Optional[Callable[..., None]] = None, /, minify: bool = True, register: bool = True)
Decorator that send code to device that executes when decorated function is called on-host.
- Parameters
f (Callable) -- Function to decorate. Can only accept and return python literals.
minify (bool) -- Minify
cmd
code prior to sending. Defaults toTrue
.register (bool) -- Assign an attribute to
self.task
with same name asf
. Defaults toTrue
.
- thread(f: Optional[Callable[..., None]] = None, /, minify: bool = True, register: bool = True)
Decorator that send code to device that spawns a thread when executed.
- Parameters
f (Callable) -- Function to decorate. Can only accept python literals as arguments.
minify (bool) -- Minify
cmd
code prior to sending. Defaults toTrue
.register (bool) -- Assign an attribute to
self.thread
with same name asf
. Defaults toTrue
.
- __call__(cmd: str, minify: bool = True, stream_out: ~typing.TextIO = <_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>, record=True)
Execute code on-device.
- Parameters
cmd (str) -- Python code to execute.
minify (bool) -- Minify
cmd
code prior to sending. Reduces the number of characters that need to be transmitted. Defaults toTrue
.record (bool) -- Record the call for state-reconstruction if device is accidentally reset. Defaults to
True
.
- Return type
Return value from executing code on-device.
- close() None
Close the connection to device.
- reconnect(attempts: Optional[int] = None) None
Reconnect to the device and replay the command history.
- Parameters
attempts (int) -- Number of times to attempt to connect to board with a 1 second delay in-between. If
None
, defaults to whatever value was supplied to init. If init value is 0, then defaults to 1.
- sync(folder: Union[str, Path], dst: str = '/', keep: Union[None, list, str, bool] = None, ignore: Union[None, list, str] = None, minify: bool = True, mpy_cross_binary: Optional[Union[str, Path]] = None, progress_update=None) None
Sync a local directory to the remote filesystem.
For each local file, check the remote file's hash, and transfer if they differ. If a file/folder exists on the remote filesystem that doesn't exist in the local folder, then delete it (unless it's in
keep
).- Parameters
folder (str, Path) -- Single file or directory of files to sync to the root of the board's filesystem.
dst (str) -- Destination directory on device. Defaults to unpacking
folder
to root.keep (None | str | list | bool) -- Do NOT delete these file(s) on-device if not present in
folder
. Iftrue
, don't delete any files on device. Iffalse
, delete all unsynced files (same as passing[]
). Ifdst is None
, defaults to["boot.py", "webrepl_cfg.py"]
.ignore (None | str | list) -- Git's wildmatch patterns to NOT sync to the device. Defaults to
["*.pyc", "__pycache__", ".DS_Store", ".pytest_cache"]
.minify (bool) -- Minify python files prior to syncing. Defaults to
True
.mpy_cross_binary (Union[str, Path, None]) -- Path to mpy-cross binary. If provided,
.py
will automatically be compiled. Takes precedence over minifying.progress_update -- Partial for
rich.progress.Progress.update(task_id,...)
to update with sync status.
- exception AuthenticationError
Bases:
BelayException
Invalid password or similar.
Bases:
BelayException
Feature unavailable for your board's implementation.
- class Implementation(name: str, version: Tuple[int, int, int], platform: str, emitters: Tuple[str])
Bases:
object
Implementation dataclass detailing the device.
- Parameters
name (str) -- Type of python running on device. One of
{"micropython", "circuitpython"}
.version (Tuple[int, int, int]) --
(major, minor, patch)
Semantic versioning of device's firmware.platform (str) -- Board identifier. May not be consistent from MicroPython to CircuitPython. e.g. The Pi Pico is "rp2" in MicroPython, but "RP2040" in CircuitPython.
emitters (tuple[str]) -- Tuple of available emitters on-device
{"native", "viper"}
.
- emitters: Tuple[str]
- name: str
- platform: str
- version: Tuple[int, int, int]
- exception PyboardException
Bases:
Exception
Uncaught exception from the device.
- exception SpecialFunctionNameError
Bases:
BelayException
Reserved function name that may impact Belay functionality.
Currently limited to:
Names that start and end with double underscore,
__
.Names that start with
_belay
or__belay
- minify(code: str) str
Minify python code.
Naive code minifying that preserves names and linenos. Performs the following:
Removes docstrings.
Removes comments.
Removes unnecessary whitespace.
- Parameters
code (str) -- Python code to minify.
- Returns
Minified code.
- Return type
str