Skip to content

App

rn_forge.cli.app

Typer application setup and error-to-exit-code handling.

CliApp(name, help=None, *, default_log_level=LogLevel.VERBOSE, **typer_kwargs)

Bases: Typer

Typer application with standard logging, output, and exit handling.

Construct one directly, or build it from a repository's declared [cli] surface::

app = CliApp("golden-app", "Do the thing.")            # explicit
app = CliApp.from_config(Path(__file__).parent / "config.toml")

Either way the root callback already takes --log-level/--log-file and --quiet/--json, and :meth:__call__ returns a mapped exit code — so [project.scripts] needs nothing but mypkg.cli:app, with no main().

Typer is inherited rather than wrapped, so @app.command(), add_typer and the full constructor keyword set remain available.

Initialize the application and register its root callback.

no_args_is_help=True and pretty_exceptions_show_locals=False are set by default and may be overridden through typer_kwargs.

Parameters:

Name Type Description Default
name str

The app name, also used (lowercased, spaces replaced with _) as the root logger name.

required
help str | None

The app's --help description.

None
default_log_level LogLevel

Default value for --log-level.

VERBOSE
**typer_kwargs Any

Forwarded to the :class:typer.Typer constructor.

{}

__call__(*args, **kwargs)

Invoke the application and return its exit code.

Unlike :meth:typer.Typer.__call__, which runs Click in standalone mode and raises :exc:SystemExit, this returns the code — so a generated console script (sys.exit(app())) gets the mapping in :func:run for free.

add_declared(command)

Attach one declared command or namespace, importing its target by name.

Raises:

Type Description
AppException

The target cannot be imported, or is neither a :class:typer.Typer nor callable.

from_config(source, *, key=SURFACE_KEY, **typer_kwargs) classmethod

Build the application a repository's [cli] table describes.

Parameters:

Name Type Description Default
source str | Path | Mapping[str, Any]

A path to the configuration document, or an already-parsed mapping. See :meth:CliSurface.load.

required
key str

The table the surface lives under.

SURFACE_KEY
**typer_kwargs Any

Forwarded to the constructor.

{}

Raises:

Type Description
AppException

The document has no surface table, a declared value has the wrong type, or a command's target cannot be imported.

from_surface(surface, **typer_kwargs) classmethod

Build the application an already-parsed surface describes.

run(args=None, **kwargs)

Invoke this application and return its exit code. See :func:run.

ExitCode

Bases: IntEnum

Exit codes returned by an rn-forge CLI.

FAILURE = 1 class-attribute instance-attribute

The command ran and failed — the ordinary error exit.

INTERRUPTED = 130 class-attribute instance-attribute

The user interrupted the command (128 + SIGINT).

OK = 0 class-attribute instance-attribute

The command succeeded.

USAGE = 2 class-attribute instance-attribute

The command line itself was wrong: an unknown flag, a bad value.

for_error(error) classmethod

Return the exit code error maps to.

Explicit exit signals retain their supplied code, including codes not represented by :class:ExitCode.

run(app, args=None, **kwargs)

Invoke app, reporting whatever escapes it, and return an exit code.

Diagnosed :class:~rn_forge.commons.exceptions.AppException instances are reported without a traceback; unexpected exceptions are logged in full. The console mode on return is the mode on entry.

Parameters:

Name Type Description Default
app Typer

The Typer application to run.

required
args Sequence[str] | None

The command line, defaulting to sys.argv[1:].

None
**kwargs Any

Forwarded to the underlying Click command.

{}

Returns:

Type Description
int

The exit code to hand to :func:sys.exit.