API Reference¶

Verify examples have valid syntax and resolvable imports.

Each package_dirs entry should point at a package directory that contains an examples/ subdirectory (e.g. libraries/timing). For each examples/*.py:

1. Parse the file. Syntax errors fail it.
2. Detect whether it's hardware-only via the __chumicro_runtimes__ marker.
3. Walk imports: every chumicro_* import must resolve. Non-chumicro_ imports must resolve only on non-hardware files. Hardware files skip them so platform built-ins don't fail on the host.

Parameters:

Returns:

Read sources, deep-merge, flatten to dotted keys, return the dict.

Same flow as build_runtime_config minus the write_runtime_config call, for callers that need the resolved dict in memory rather than an on-disk msgpack. See :mod:chumicro_workspace.merge for precedence rules.

Parameters:

Returns:

Raises:

Return the workspace.yml template content.

Complete commented-example file with schema for library_sources: / deploy_targets: / quality: / environments: blocks.

Return the command prefix a hint should name for this workspace.

A workspace driven by the template's run.py shim keeps its venv off PATH, so a hint naming chumicro-workspace ... fails with command-not-found when pasted; a standalone install has no run.py and drives the CLI directly. Picks whichever invocation actually resolves: python3 run.py when the shim exists at workspace_root, chumicro-workspace otherwise.

Read sources, deep-merge, flatten to dotted keys, return the dict.

Same flow as build_runtime_config minus the write_runtime_config call, for callers that need the resolved dict in memory rather than an on-disk msgpack. See :mod:chumicro_workspace.merge for precedence rules.

Parameters:

Returns:

Raises:

Read all sources, deep-merge, flatten, write msgpack.

Parameters:

Returns:

Raises:

Read a secrets.toml and return its contents as a nested dict.

Returns an empty dict when the file is empty. TOML stdlib guarantees the top level is a table, so no shape check is needed on this side. Malformed bytes raise :class:tomllib.TOMLDecodeError.

Parameters:

Raises:

Read a project's project_config.toml.

Parameters:

Raises:

Deep-merge two or more dicts left-to-right.

Later sources override earlier ones key-by-key. Nested dicts merge recursively; non-dict leaf values are replaced wholesale. Lists do not merge: a later source's list replaces the earlier source's list entirely. Merge is key-level, not element-level.

Parameters:

Returns:

Raises:

Return a flat dotted-key copy of nested.

Walks nested recursively; each non-dict leaf value lands at "<dotted.path>" in the result. Empty dicts are dropped (no key is emitted for an inner table that has no leaf descendants). Lists, tuples, and scalars are taken verbatim. The per-key value isn't recursed into, only nested dicts are.

Parameters:

Returns:

Raises:

Write merged as msgpack bytes to output_path.

Creates the parent directory if needed.

Parameters:

Raises:

Return the per-project config path for project_dir.

The project-config filename is project_config.toml.

Parameters:

Raises:

Wrap inner in :class:WithRuntimeConfig after filling in conventional defaults.

Each front-end (directory source, boot-shim source, import-graph source) calls this once it has built its inner FileSource, so the four conventional paths the wrapper needs are resolved here instead of in each builder.

Defaults applied when the corresponding argument is None:

• secrets_toml falls back to workspace.secrets_toml; workspace is required when secrets_toml is None.
• project_config falls back to :func:find_project_config under project_dir.
• output_path falls back to project_dir / _generated / runtime_config.msgpack (the gitignored build-artifact directory).
• library_roots (for manifest validation) is derived from search_paths when given (an import-graph front-end) and left empty otherwise (a directory or boot-shim front-end without walked libraries; validation is then off).

Parameters:

Raises:

Build a deploy-ready FileSource for a typical project directory.

Walks project_dir with :class:chumicro_deploy.DirectorySource, skipping the project's host-side config files and _generated/ output directory, then wraps the result with :class:WithRuntimeConfig so the merged msgpack rides the deploy.

Parameters:

Raises:

Return True when app.py defines a top-level synchronous run.

Only a plain def run(...) qualifies. The shim calls run() synchronously (from app import run; run()), so an async def run is not a usable entrypoint and returns False here. :func:project_app_exports_async_run distinguishes the async case so callers can surface it as a clear failure instead of shipping a board that boots and silently does nothing.

Return True when app.py's top-level run is async def.

The boot shim calls run() synchronously, so an async def run would evaluate to a coroutine that is created and immediately discarded. The board boots and does nothing, with no traceback. Detecting that case lets the deploy path surface it as a clear failure instead of letting it through.

Line of a module-top-level board-reset call in source, or None.

The closure-scan companion to :func:module_calls_hard_reset: an imported module's top-level code runs at boot exactly like the entrypoint's, so a reset there crash-loops the board just the same. But a reset inside a def is the recommended pattern (called on a deliberate condition), so this walk descends into top-level if / try / loop / with blocks (they run at import) and prunes at any function or class body (those run only when called). Unreadable or unparseable source returns None, because the deploy's own compile step reports those failures with better context.

Return the line of a microcontroller.reset() / machine.reset() call in path, or None.

Either call reboots the board. In a shipped boot entrypoint, which the board runs on every boot, a reset reboots the board, which re-runs the entrypoint and resets again: a crash loop that bricks the deploy cycle until the board is wiped. Returns the first such call's line so the deploy path can refuse it. Import aliases are resolved first, so import machine as m; m.reset() and from microcontroller import reset as r; r() are caught alongside the plain microcontroller.reset() / machine.reset() forms. A file that can't be read or parsed returns None.

Return the synthesized shim file map (a single entry).

The shim is a three-line module that imports the project's app.run and calls it. Lands at /<entrypoint_filename> on the device: /code.py for CircuitPython, /main.py for MicroPython. Only the runtime-matching file is synthesized. Both are never shipped speculatively.

Parameters:

Returns:

Build a deploy-ready FileSource using the boot-shim layout.

Bundles the synthesized entrypoint shim with the project's own files (at the device root) and the merged runtime-config msgpack (via :class:WithRuntimeConfig).

Parameters:

Raises:

Boot-shim layout PLUS import-graph-discovered libraries.

Use when a project authored for the boot-shim convention also needs library code (chumicro / shared / packages / library_sources overrides) shipped to the device. Common case: dev mode with a sibling chumicro/ checkout configured via chumicro-dev.toml. Without this composition, chumicro_* libraries the project imports never reach the board.

Auto-detect picks this layout when a project ships app.py with run() and no code.py / main.py.

Parameters:

Raises:

Parse library_sources: out of workspace_yaml.

Returns {package_or_root_name: Path}. The key is what a Python import statement would spell (e.g. chumicro_wifi or my_house_libs), and the value points at a directory whose children are importable under that name.

Returns an empty dict when workspace.yml has no library_sources: block. The no-overrides case is normal, not an error.

Parameters:

Raises:

Compose the import-resolution search-path list for workspace.

First match wins inside :class:ImportGraphSource, so order encodes precedence: explicit overrides, then workspace-internal sources, then third-party packages. Pure path arithmetic: the caller passes any library_sources: map already parsed, so this function performs no YAML I/O. Paths that don't exist on disk are dropped, and duplicates collapse.

Resolution order::

1. library_sources_override values
2. workspace/shared/                (user-authored shared modules)
3. workspace/libraries/<name>/src/  (scaffolded chumicro-style
                                     library packages)
4. workspace/packages/              (third-party, gitignored)
5. extra_search_paths               (caller-supplied tail; e.g.
                                     mono-repo dogfooding with the
                                     live chumicro src/)

Parameters:

Return the bare-name fix when an unresolved import names shared.

unresolved is the (importing_file, module_name) list an :class:chumicro_deploy.UnresolvedImportError collected before refusing a deploy. When any module_name's top segment is shared (shared or shared.foo), the project spelled a shared/ module as if shared were a package; the search path roots at shared/ instead, so the module resolves by its bare stem. Returns :data:SHARED_BARE_NAME_HINT for that case, or None when no unresolved import names shared (nothing to coach).

Build a deploy-ready FileSource using AST-walked imports.

Uses :class:chumicro_deploy.ImportGraphSource so only transitively-imported modules ship. This keeps the device payload minimal even when the workspace has many shared libs.

The project's entrypoint file is parsed and every reachable module via shared/ / packages/ / library_sources: lands in the deploy. Modules that don't resolve (gc, time, board, etc.) are silently skipped. They're assumed to be runtime built-ins the host can't ship.

Parameters:

Raises:

Parse deploy_targets: out of workspace_yaml.

Returns {project_slash_path: [device_id, ...]}. Dotted keys (garage.door) normalize to slash form. A scalar string value auto-promotes to a single-element list so one-target projects can stay terse::

garage/door: pi-pico-w-circuitpython-board    # bare string
garage/door: [pi-pico-w-circuitpython-board]  # equivalent

Returns an empty dict when the block is missing or empty.

Parameters:

Returns:

Raises:

Scan platform-default mount paths for a directory with INFO_UF2.TXT.

INFO_UF2.TXT is the marker the UF2 bootloader writes to its mass-storage drive on every mount, regardless of board family or drive label (RPI-RP2, RPI-RP3, SAMD51, CIRCUITPYUF2, etc.). Scanning for it is the only board-agnostic detection method.

Parameters:

Returns:

Diagnose what state device's board is in right now.

Order of operations:

1. Try the probe. If it returns an implementation marker, the board is in :attr:~BoardState.REPL_REACHABLE. No UF2 scan is needed. A running firmware can't also be the bootloader for the same board, and a stray UF2 drive from a different board would be a false positive.
2. On probe failure, scan for a UF2 drive. If found, the board is in :attr:~BoardState.UF2_BOOTLOADER (or one of the user's other boards is, but the user-facing recommendation is the same: flash firmware before retrying).
3. Otherwise, the probe error string disambiguates. A "could not open port" type failure maps to :attr:~BoardState.SERIAL_UNREACHABLE. Anything else maps to :attr:~BoardState.NO_PROBE_RESPONSE (port opens but the board doesn't speak Python, typically an ESP32 in ROM bootloader).

Parameters:

Probe address without knowing the runtime up-front.

Tries each candidate transport in :data:DEFAULT_RUNTIME_INFERENCE_ORDER until one returns an implementation marker. Returns the :class:RuntimeInferenceResult so the caller can record the probed runtime and version once a candidate succeeds.

Both runtimes speak the same probe script (reads sys.implementation), so the returned implementation name is truthful regardless of which transport delivered it. See :data:DEFAULT_RUNTIME_INFERENCE_ORDER for why both candidates are tried.

Parameters:

Returns:

Parse a dotted version string into an int tuple.

Takes the leading run of int-parseable dotted components and returns them as a tuple:

• "10.1.4" → (10, 1, 4)
• "1.26.0" → (1, 26, 0)
• "10.2.0." → (10, 2, 0). Trailing dot comes from CP's (10, 2, 0, '') 4-tuple shape on RC builds.
• "10.2.0.rc.0" → (10, 2, 0). Non-int suffix stops parsing.
• "10.1.0-rc1" / "1.27.0-dev" → (10, 1, 0) / (1, 27, 0). Release-suffix stripped before splitting.
• "" / "abc" / no leading ints → None

Returns None for empty input, no leading int component, or any other parse failure. Callers treat None as :attr:FirmwareSupportStatus.UNPARSEABLE.

Parameters:

Classify a probed implementation against the floor.

Parameters:

Returns:

Return human-readable lines describing the result.

Empty list for :attr:FirmwareSupportStatus.SUPPORTED (silent on the happy path). Non-empty for OLD / UNKNOWN / UNPARSEABLE, each ending with the install-firmware pointer when applicable.

Parameters:

Verify workspace.yml parses as the expected shape.

Only confirms the file exists and parses to a mapping. Schema validation for the library_sources: / deploy_targets: / quality: blocks happens lazily inside the modules that consume each one.

Verify secrets.toml exists and parses cleanly.

secrets.toml is gitignored and materialized on first setup. Its absence on a fresh clone is a setup-not-yet-run state rather than a configuration error.

Count entries in devices.yml (no reachability probe).

Summarize the projects tree (count + first few names).

Run every status check and return the findings in display order.

Verify the host Python is recent enough for the workspace deps.

Verify each boot-shim-shaped project's app.py defines run().

Projects without an app.py (the code.py / main.py layouts) are skipped. The run() contract only binds the workspace-runtime boot shim. Projects with a syntax error are counted as missing run() so the user sees the failure here rather than at deploy-time.

Flag the macOS FSKit wedge that makes CIRCUITPY mounts unreachable.

On non-macOS the wedge cannot happen. The check returns a "not applicable" OK row without probing. On macOS :func:detect_fskit_wedge runs ps -o state= -p $(pgrep diskarbitrationd) to detect a stuck diskarbitrationd. A wedged daemon surfaces as ERROR with the recovery command in the hint. A healthy daemon surfaces as OK.

Doctor-only.

Flag registered devices whose serial port is held by another process.

Walks devices.yml addresses and runs :func:diagnose_port_holders on each. When a port has at least one holder, surfaces as a WARN finding listing the PIDs and commands of the holders, typically a serial-terminal app the user has open against the board. A held port doesn't imply something is broken (the user may be debugging), but if the next action is a deploy, the deploy will fail with Resource busy until the holder is closed.

Doctor-only.

Returns OK on Windows (no portable lsof equivalent without handle.exe) and when no devices are registered.

Run the strict (status + Python version + AST + FSKit + ports) check set.

Return remediation hints matching patterns in traceback_text.

Order matches the table, so earlier patterns fire first. Multiple patterns can match the same traceback, and each independent match becomes its own hint.

Empty input or no match returns an empty list.

Render hints as the block printed under a traceback.

Returns an empty string for an empty list, so an unmatched traceback doesn't get a "--- hints ---" header with nothing under it.

Load + validate the workspace quality config.

Two sources merge, per key: the committed quality.toml next to workspace_yaml carries the policy that travels with the repo, and workspace.yml's quality: block carries per-machine overrides that win over it. When neither exists, the defaults apply (lint enabled, no coverage gate from these files; pyproject.toml's fail_under still holds the floor).

Each source validates separately, so a shape violation raises :class:WorkspaceConfigError naming the file that carries the bad value rather than a vague tool exit code later.

Create a library tree at target_dir / name.

Parameters:

Returns:

Raises:

Whether libraries/<package>/ carries the user-edit sentinel.

Return the VERSION of a curated library on disk, or None if absent.

Delete a curated library's tree. Returns True if it existed.

Fetch one package from a channel snapshot into the workspace.

version is :data:HEAD (the channel's latest snapshot) or a pinned snapshot tag. An existing curated copy is backed up, not clobbered. Returns the destination directory; raises :class:LibraryFetchError with a classified kind on any failure.

Fetch root and every chumicro library reachable from it.

The snapshot tarball already contains every library in the channel, so one index.json GET and one tarball GET cover the whole closure regardless of size. Each library's direct deps are read from its placed pyproject.toml, and the walk is breadth-first from root via :func:~chumicro_workspace.dep_resolver.transitive_closure (cycle-safe, deterministic order).

Returns the closure as import names in BFS order, root first. Raises :class:LibraryFetchError on the first member that fails to extract; libraries already placed stay on disk and the caller decides whether to roll back.

Create a minimal workspace at tmp_path and return the root.

Writes workspace.yml (machinery placeholder), secrets.toml (wifi block with placeholder credentials), and devices.yml with a single device targeting /dev/cu.fake.

Parameters:

Add projects/<name>/ under workspace_root and return its dir.

Carries both code.py (CircuitPython convention) and main.py (MicroPython convention) so the deploy command's runtime-derived entrypoint resolves cleanly regardless of the test fixture's chosen transport.

name may be slash-form ("upstairs/bedroom_sensor"). The intermediate parent directories are created automatically.

Build a probe-info object for tests of probe-driven commands.

Default version is at the supported floor for micropython so tests that don't care about firmware support don't trip the firmware-floor warning path. Tests that exercise the floor pass a lower or runtime-specific version.

Pass with_implementation=False to simulate a board where the probe couldn't read an implementation marker. The returned object has implementation=None and empty board_id / uid, matching what production code returns in that branch.