Skip to content

bridge

heliaAOT CLI Bridge API

Generates the convert command's typer parameters from the ConvertArgs pydantic model, so the model remains the single source of truth for the CLI surface (flag names, defaults, and help text), mirroring the historical argdantic behavior:

  • Nested fields become dotted kebab-case flags (--model.path, --memory.auto-hydrate-constants).
  • Booleans become --flag/--no-flag pairs.
  • List fields accept space-separated values (--platform.speeds 96 192), repeated flags (which accumulate), and a bare flag meaning an explicit empty list (which overrides a YAML-provided list).
  • Every option defaults to None: real defaults live in the pydantic model and are applied after the YAML/CLI merge, so only flags explicitly typed on the command line override YAML values.

Why synthesized signatures instead of click objects: typer >=0.20 vendors its own copy of click (typer._click), so a command built from the real click package raises exception classes (Exit, UsageError) that typer's vendored main loop does not catch — --help would print and then crash. Building parameters as Annotated[..., typer.Option(...)] entries on a dynamic __signature__ keeps everything inside typer's public API and works on both sides of the vendoring divide (verified on 0.16 and 0.27).

Copyright 2025 Ambiq. All Rights Reserved.

Classes

BridgeParam dataclass 

BridgeParam(dest: str, loc: tuple[str, ...], annotation: object, variadic: bool = False)

One generated CLI parameter.

BridgeSpec dataclass 

BridgeSpec(params: list[BridgeParam] = list(), variadic_flags: set[str] = set(), locs: dict[str, tuple[str, ...]] = dict())

The generated CLI surface for a pydantic model.

Functions

build_params 

build_params(model_cls: type[BaseModel]) -> BridgeSpec

Walk model_cls and produce the full typer parameter surface.

make_command_function 

make_command_function(spec: BridgeSpec, impl)

Create a typer-compatible function exposing spec's parameters.

impl is called as impl(ctx, kwargs) with the raw typer values. Typer reads the CLI surface from the synthesized __signature__ / __annotations__.

normalize_value 

normalize_value(value)

Map typer values to what the pydantic merge expects.

Lists (from multi-value options) get the bare-flag sentinel removed, so a bare list flag yields an explicit empty list.

make_variadic_command_class 

make_variadic_command_class(variadic_flags: frozenset[str]) -> type[typer.core.TyperCommand]

Build a TyperCommand subclass preserving argparse-style nargs='*' flags.

Rewrites argv before parsing: --f a b becomes --f a --f b, and a bare --f becomes --f <sentinel> (an explicit empty list).