Skip to content

API Reference

chumicro_workspace

Host-side runtime for ChuMicro project workspaces.

Combines:

  • Config merge: secrets.toml (workspace-wide credentials and device defaults) and per-project project_config.toml deep-merge into /runtime_config.msgpack. Both inputs are gitignored and share a [section]-keyed TOML layout.
  • Deploy integration: :class:~chumicro_workspace.deploy_source.WithRuntimeConfig and the project_*_source helpers compose with chumicro-deploy's FileSource s so a single Deployer.deploy_diff(...) call ships app code, the merged config, and an optional boot shim in one shot.
  • devices.yml round-trip: three-zone writer (USER_OWNED / HARDWARE_ONCE / PROBED_ALWAYS), owned by chumicro-deploy.
  • Onboarding: board-state detection, firmware URL derivation (CP S3 listing plus MP curated machine-to-BOARD map).
  • Init / update: clone the workspace template repo and re-flow tool-owned files.
  • CLI dispatch: :func:chumicro_workspace.cli.main powers the chumicro-workspace entry-point and the workspace run.py shim.

Package-root surface (__all__ below) is intentionally narrow. It exposes the :class:WorkspaceLayout type and the few helpers sibling packages reach for through the root::

from chumicro_workspace import (
    WorkspaceLayout,             # workspace path resolution + project tree
    compose_runtime_config,      # functional-test config merge
    read_workspace_yml_template, # workspace.yml template content
    read_devices_yml_template,   # devices.yml template content
    verify_examples,             # AST-based example verifier
)

Everything else lives in submodules (chumicro_workspace.deploy_source, chumicro_workspace.pipeline, chumicro_workspace.config_manifest, chumicro_workspace.workspace for :data:ENTRY_POINT_FILENAMES / :class:ProjectClassification, etc.) and stays reachable via explicit submodule imports.

Workbench-only: runs on CPython, never lands on a microcontroller. Workbench tools and the workspace's run.py shim consume this package. The on-device counterpart is chumicro-config.

ProjectClassification

Bases: StrEnum

How a directory under projects/ is treated by the workspace tools.

WorkspaceLayout dataclass

Resolved paths for a single project workspace.

Construct with :meth:from_dir (walks up from a starting directory) or by passing root directly when the location is already known.

Attributes:

Name Type Description
root Path

Directory containing workspace.yml. Every other path is derived from this.

workspace_yaml property

Path to <root>/workspace.yml.

secrets_toml property

Path to <root>/secrets.toml (gitignored device-bound config).

Materialized on first setup from the shipped template (:func:read_secrets_toml_template). Carries wifi credentials, MQTT broker auth, and any other workspace-wide default that flows onto a board through runtime_config.msgpack. May not exist on a fresh workspace before setup runs.

devices_yaml property

Path to <root>/devices.yml. May not exist on a fresh workspace.

projects_dir property

Path to <root>/projects/.

shared_dir property

Path to <root>/shared/ for flat shared modules.

A file shared/foo.py is imported by projects under its bare module name (from foo import bar), never shared.foo: the deploy search path roots at this directory, so its modules resolve as top-level names without any package scaffolding. No tests, no version, no chumicro library shape.

libraries_dir property

Path to <root>/libraries/ for full chumicro-style library trees.

Each entry is a proper chumicro library package with src/<name>/, tests/, optional docs/ and examples/, pyproject.toml, VERSION. Created by chumicro-workspace new --library. Use this when the library is meant to be publishable.

import_graph.build_search_paths includes libraries/<name>/src/ for every entry so projects can import my_lib without a separate :data:library_sources mapping.

packages_dir property

Path to <root>/packages/ (third-party packages, gitignored).

project_dir(name)

Return the directory for the named project (existence not checked).

name may be a single segment ("bedroom_sensor"), slash-form ("upstairs/bedroom_sensor"), or dotted ("upstairs.bedroom_sensor"). Dotted forms are normalized to slash so the Path join lands in the right directory.

list_projects()

Return slash-form paths for every project under projects/, sorted.

Walks the tree recursively per the classifier in :data:ProjectClassification. Each path returned is a deployable leaf. Namespaces, supporting directories, _template / _generated and hidden dirs are filtered out.

Returns an empty list when projects/ doesn't exist yet.

iter_projects_with_classification()

Return every classified directory under projects/, sorted.

Includes both projects and namespaces. Namespaces are needed so the tree renderer can draw branches above leaves and callers that report on supporting branches. Sorting is by slash-form path, which gives natural depth-first display order.

from_dir(start=None) classmethod

Walk up from start until a workspace.yml is found.

The walk lets users run python3 run.py deploy ... from any directory inside the workspace. The root is resolved as the nearest ancestor with a workspace.yml.

Parameters:

Name Type Description Default
start Path | None

Starting directory. Defaults to Path.cwd().

 None

Raises:

Type Description
WorkspaceNotFoundError

When no workspace.yml exists in start or any of its parents.

WorkspaceNotFoundError

Bases: FileNotFoundError

Raised when no workspace.yml is found above the start directory.

verify_examples(package_dirs, *, display_root=None)

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:

Name Type Description Default
package_dirs list[Path]

Package directories whose examples/ to verify.

 required
display_root Path | None

Path that relative-display paths are computed against. Defaults to Path.cwd(). Purely cosmetic, since the verifier walks package_dirs to find files regardless.

 None

Returns:

Type Description
int

Exit code (0 for success, 1 for failures).

compose_runtime_config(*, secrets_toml, project_config)

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:

Name Type Description Default
secrets_toml Path

Path to secrets.toml.

 required
project_config Path | None

Per-project / per-library config file. None or a missing path means no overrides: the secrets-toml defaults pass through verbatim.

 required

Returns:

Type Description
dict

The merged, flattened dict with dotted keys.

Raises:

Type Description
TOMLDecodeError

A TOML source file is malformed.

read_workspace_yml_template()

Return the workspace.yml template content.

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