utils

heliaAOT Utility API

This module provides utility functions for various tasks.

Classes:

• MarkdownRichHandler –

  Custom logging handler for Rich library with Markdown support.

• StepContext –

  Context manager for logging steps in a process.

Functions:

• get_version –

  Get the version of the package

• setup_logger –

  Set up a logger with optional file output

• suppress_os_stdio –

  Context manager to suppress OS stdout and stderr

Copyright 2025 Ambiq. All Rights Reserved.

Classes

MarkdownRichHandler

Custom logging handler for Rich library with Markdown support.

StepContext

StepContext(name: str, ellipses: bool = True, icon: str = '▸', phase: str | None = None)

Context manager rendering a pipeline stage through the console layer.

Shows a live spinner while the block runs and resolves it to a ✓ 0.4s (or ✖) line; a new phase prints a phase header first. Silent at verbosity 0.

Parameters:

• name

  (str) –

  Name of the step.

• ellipses

  (bool, default: True ) –

  Unused; retained for call-site compatibility.

• icon

  (str, default: '▸' ) –

  Emoji/pictogram prefix for the stage line.

• phase

  (str, default: None ) –

  Phase group header (printed on change).

Functions

Functions

validate_power_of_two

validate_power_of_two(value: int | None, *, label: str) -> int | None

Reject non-positive or non-power-of-two alignment values.

Shared by the CLI boundary (PlatformArgs.min_alignment), the platform model (SocPlatform.min_alignment), and per-arena constraints (MemoryConstraint.arena_alignment) so the three sites cannot drift.

Parameters:

• value

  (int | None) –

  The alignment to validate; None passes through.

• label

  (str) –

  Field name used in the error message (e.g. "platform.min_alignment").

Returns:

• int | None –

  value, unchanged.

Raises:

• ValueError –

  If value is not a positive power of two.

get_version

get_version() -> str

Get the version of the package.

Returns:

• str ( str ) –

  Version string.

setup_logger

setup_logger(log_name: str, level: int | None = None, recursive: bool = True, file_path: str | Path | None = None) -> logging.Logger

Configure a logger with optional file output.

This function ensures that the logger is only initialized once per name. The logger can be configured to propagate messages to the root logger.

Included handlers are

• RichHandler: For console output with rich formatting.
• FileHandler: For file output (optional).

Parameters:

• log_name

  (str) –

  Name of the logger.

• level

  (int, default: None ) –

  Logging level (0: ERROR, 1: INFO, 2: DEBUG). Defaults to None.

• recursive

  (bool, default: True ) –

  If True, use the root logger name. Defaults to True.

• file_path

  (str | Path, default: None ) –

  Path to the log file. Defaults to None.

Returns:

• Logger –

  logging.Logger: Configured logger instance.

suppress_os_stdio

suppress_os_stdio()

Redirects the OS stdout (fd=1) and stderr (fd=2) to /dev/null, then restores them on exit. Suppresses all output unless an exception is raised, in which case it will be logged.

Example

with suppress_os_stdio(): noisy_function()