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
|
required |
help
|
str | None
|
The app's |
None
|
default_log_level
|
LogLevel
|
Default value for |
VERBOSE
|
**typer_kwargs
|
Any
|
Forwarded to the :class: |
{}
|
__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: |
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: |
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 |
None
|
**kwargs
|
Any
|
Forwarded to the underlying Click command. |
{}
|
Returns:
| Type | Description |
|---|---|
int
|
The exit code to hand to :func: |