Utilities (astra.utils)

Overview

Utility modules include helpers for logging, QR rendering, and small adapters used by higher-level APIs.

Notable utilities

  • QR helpers (terminal rendering)

  • Small conversion helpers used by the bridge serializers

Utility modules (manual reference)

The astra.utils package contains small helpers used across the framework. These modules are lightweight and are intentionally documented here without autodoc to avoid importing runtime-only helpers during the doc build.

HealthMonitor (health.py)

  • Purpose: aggregate component health (browser, tasks, gateway) into a

single report.

  • Main API:

  • HealthMonitor.consolidate(client_state, browser_health, tasks_health, gateway_ready) — returns a dictionary summary.

Example:

report = HealthMonitor.consolidate("READY", {"engine_active": True}, {"running": 5}, True)

Media helpers (media.py)

  • Purpose: small helpers around media handling and MIME/type inference used

by the MediaMethods layer. These helpers are internal and have thin wrappers in the public client.media API.

Retry utilities (retry.py, retry_handler.py)

  • Purpose: provide retry/backoff strategies and a small retry handler used

across network and protocol operations.

  • Key concepts: exponential backoff, jitter, configurable max attempts.

Task supervisor (task_supervisor.py)

  • Purpose: helper for supervising background asyncio tasks and graceful

shutdown. Used to centralize lifecycle handling for long-running workers.

Notes

  • These utilities are internal implementation details and are intentionally

documented with short summaries to avoid importing package modules during Sphinx builds (some utilities reference runtime-only objects). If you need a full programmatic API reference for any of these, I can generate small wrapper pages that import them in a safe mocked environment.

Example

from astra.utils import logging as astra_log
astra_log.setup(level="INFO")