Runtime and Configuration

Most code never constructs a Runtime. This is the advanced surface: isolated progress state, logging, and runtime-scoped configuration.

mqdm.runtime.configure

configure(**kw: Any) -> Runtime

Set display options on the implicit global runtime, before its first bar.

Keywords are forwarded to the progress backend (Rich by default), e.g. refresh_per_second, expand, redirect_stdout / redirect_stderr, speed_estimate_period. Must run before any bar is created — it raises once the shared display exists.

Example

import mqdm as M
M.configure(refresh_per_second=12, expand=True)
for x in M.mqdm(range(10)):
    ...

mqdm.runtime.Runtime

Runtime(
    on_event: Callable[[EventEnvelope], Any] | None = None,
    *,
    create_backend: Callable[..., ProgressBackend]
    | None = None,
    backend_options: dict[str, Any] | None = None,
)

Owns progress, pause, and logging state for one mqdm session.

A runtime coordinates the active progress display, worker-process plumbing, and optional logging integration. Most code can rely on the current runtime implicitly, but constructing a separate Runtime is useful when you want isolated progress or logging behavior.

backend_options property

backend_options: dict[str, Any]

Runtime-scoped options used when creating the shared Progress.

configure

configure(
    *,
    create_backend: Callable[..., ProgressBackend]
    | None = None,
    backend_options: dict[str, Any] | None = None,
) -> Runtime

Set display options for this runtime, before its first bar.

backend_options are forwarded to the progress backend (Rich by default, e.g. refresh_per_second, expand, redirect_stdout); create_backend swaps the backend factory entirely. Raises if the shared display already exists.

context

context(**context: Any)

Attach key/values to every event emitted inside this block.

Emitted events (print, log, task lifecycle) carry a context dict; this pushes extra fields onto it for the duration of the with block and pops them on exit. Useful for tagging output with a phase, request id, or similar so an on_event sink can group it. Nestable; see :meth:set_base_context for long-lived values like worker identity.

Example

with runtime.context(phase="index"):
    mqdm.print("scanning")   # event context includes phase="index"

emit

emit(event_type: str, **data: Any) -> Any

Emit an event. Routes to on_event if set, else :meth:handle_event.

Every event dict receives a time timestamp (time.time(), float) pegged to this call site and the current runtime context.

get_context

get_context() -> dict[str, Any]

Get context for this runtime without leaking values across runtimes.

handle_event

handle_event(event_type: str, **data: Any) -> Any

Default fallback for events with no sink attached.

Output events (print, log) are forwarded to the active progress-bar console so they interleave with the live display. If no progress bar is active, they fall back to the default Rich console.

Telemetry events (task_started, task_finished, task_failed) are no-ops here — they exist purely for programmatic consumers attached via on_event.

install_logging

install_logging(
    logger: Logger | None = None,
    *,
    level: int | None = None,
    capture_warnings: WarningCapturePolicy = "process",
    markup: bool = True,
    formatter: Formatter | None = None,
) -> MQDMHandler

Attach an MQDMHandler to a logger for this runtime.

Parameters:

Name	Type	Description	Default
logger	Logger | None	Logger to attach to. Defaults to the root logger.	None
level	int | None	Optional handler level to set on the attached handler.	None
capture_warnings	WarningCapturePolicy	Warning routing policy. False leaves warnings alone, True captures warnings immediately, and "process" captures warnings automatically only in process pool workers installed by mqdm.	'process'
markup	bool	Whether to allow Rich markup in emitted log messages.	True
formatter	Formatter | None	Optional formatter for the handler.	None

Returns:

Type	Description
MQDMHandler	The attached or reused MQDMHandler instance.

set_base_context

set_base_context(**context: Any) -> None

Set a persistent base context for this thread/worker.

Unlike :meth:context (a scoped push/pop), this seeds long-lived values such as worker identity that every subsequent event should carry.

sustain

sustain()

Keep the live progress display alive across this block.

Normally mqdm tears the display down as soon as the last bar finishes, so a sequence of separate bars renders one at a time — each freezes into the scrollback as the next begins. Inside sustain() a single display spans the whole block: the bars stack and stay visible together as a growing panel while print/logging flows above them. Nestable.

uninstall_logging

uninstall_logging(logger: Logger | None = None) -> None

Remove this runtime's logging handler from a logger.

Parameters:

Name	Type	Description	Default
logger	Logger | None	Logger to detach from. Defaults to the root logger.	None

mqdm.Result dataclass

Result(
    index: int,
    arg: args,
    value: R | None = None,
    error: BaseException | None = None,
)

A single task's outcome: its input, return value, and any error.

index matches the task_index carried on the event stream, so a result correlates to its live events by key rather than by completion order.

mqdm.install_logging

install_logging(
    logger=None,
    *,
    level=None,
    capture_warnings="process",
    markup=True,
    formatter=None,
)

Route a logger's records above the live bars (and across pool workers).

Attaches an mqdm handler to logger (the root logger by default) so log output renders above the progress display instead of clobbering it, and worker logs are forwarded to the display owner. capture_warnings='process' also captures :mod:warnings in process-pool workers. See :meth:Runtime.install_logging for the full argument reference.

Example

import logging
mqdm.install_logging(level=logging.INFO)
logging.getLogger(__name__).info("started")   # appears above the bars

mqdm.uninstall_logging

uninstall_logging(*, logger=None)

Remove mqdm's log routing from logger (the root logger by default).

Reverses :func:install_logging and releases any warning capture it enabled.