Skip to content

Console

rn_forge.commons.runtime.console

Console output: a Rich-based, quiet/JSON-aware output facade.

Human-readable logs use stderr; :meth:AppConsole.emit writes command output to stdout so machine-readable output remains separate.

Typical usage::

from rn_forge.commons import console, OutputMode

console.info("Starting {}", "job")
console.table("name", "status", rows=[("alpha", "ok"), ("beta", "failed")])
console.set_mode(OutputMode.JSON)
console.emit({"status": "ok"})

AppConsole(*, mode=None, stderr=False, theme=None)

Facade over :class:rich.console.Console with quiet and JSON modes.

Access :attr:rich for unsupported Rich features such as progress bars, live displays, and custom renderables.

Initialize :class:AppConsole.

Parameters:

Name Type Description Default
mode OutputMode | None

Initial output mode. Defaults to :attr:OutputMode.RICH when stdout is a TTY, else :attr:OutputMode.PLAIN.

None
stderr bool

When True, the primary console (and therefore :attr:rich) writes to stderr instead of stdout.

False
theme Theme | None

A Rich theme applied to the underlying console(s).

None

mode property

The current :class:OutputMode.

rich property

The underlying :class:rich.console.Console.

confirm(msg, *, default=False)

Prompt for a yes/no confirmation. Ignores the current output mode.

detail(msg, *args)

Print msg dimmed. No-op in QUIET/JSON.

diff(text, *, title=None)

Print text as a syntax-highlighted unified diff. No-op in QUIET/JSON.

text is rendered via :class:rich.syntax.Syntax, which never interprets markup — diff text is untrusted.

emit(value, *, quiet_text=None)

Emit value according to the current mode.

  • JSON -> :meth:json.
  • QUIET -> print quiet_text unstyled if given, else nothing.
  • else -> self.rich.print(value) (renders Table/Panel/str/renderables).

error(msg, *args)

Print msg in red to stderr. No-op in QUIET/JSON.

fail(msg, *args, code=1)

Call :meth:error, then raise :exc:SystemExit with code.

Raises SystemExit rather than typer.Exit — this module has no Typer dependency; Typer/Click both handle a bare SystemExit fine.

info(msg, *args)

Print msg unstyled. No-op in QUIET/JSON.

json(value)

Serialize value via :meth:JsonUtils.serialize and print it. Always emits, even in QUIET.

Printed with soft_wrap so Rich neither wraps nor crops it: a machine-readable payload that the console reflowed at terminal width is no longer parseable, and the consumer is a pipe, not a reader.

print(msg='', *args, style=None, markup=True)

Print msg, {}-formatted with args. No-op in QUIET/JSON.

prompt(msg, *, default=None, password=False)

Prompt for a line of input. Ignores the current output mode.

rule(title='')

Print a horizontal rule. No-op in QUIET/JSON.

set_mode(mode)

Set the output mode. Returns self for chaining.

status(msg)

Return a spinner context manager in RICH mode, a no-op otherwise.

success(msg, *args)

Print msg in green. No-op in QUIET/JSON.

table(*columns, rows, title=None, **table_kwargs)

Build and print a table in one call. No-op in QUIET.

Non-str cells go through str(). Cell content is never interpreted as markup — data values are untrusted. In JSON mode, emits [{column: cell, ...}, ...] instead of a table.

warning(msg, *args)

Print msg in yellow to stderr. No-op in QUIET/JSON.

OutputMode

Bases: StrEnum

Output mode for :class:AppConsole.

JSON = 'json' class-attribute instance-attribute

Machine-readable output only.

PLAIN = 'plain' class-attribute instance-attribute

No styling (explicit override; also what a non-TTY gets).

QUIET = 'quiet' class-attribute instance-attribute

Suppress everything except explicit quiet_text.

RICH = 'rich' class-attribute instance-attribute

Default: styled output, tables, colour.