Skip to content

Commands

Tooling's own command surfaces.

rn_forge.tooling.cli.lifecycle

Typer commands for a declared tool lifecycle.

LIFECYCLE_KEY = 'lifecycle' module-attribute

The table :meth:LifecycleSurface.load reads by default.

VERBS = tuple(_COMMANDS) module-attribute

Every verb this module can mount, in --help order.

LifecycleSurface(product, verbs=(lambda: VERBS)(), namespace=None) dataclass

Bases: DataclassMixin

A declared [lifecycle] table: which verbs a tool exposes, and where.

Parameters:

Name Type Description Default
product str

Import path of the :class:ToolProduct the verbs act on.

required
verbs tuple[str, ...]

Which of :data:VERBS to expose. Default: all six.

(lambda: VERBS)()
namespace str | None

Sub-command group the verbs are mounted under, e.g. "self" for <tool> self status. Default: mounted at the root of the application.

None

__repr__()

Return an unambiguous ClassName(field=value, ...) representation.

Excluded fields (metadata={"exclude": True}) are omitted. Falls back to :func:object.__repr__ when the class is not a dataclass.

Returns:

Type Description
str

A string of the form ClassName(field1=value1, field2=value2).

__str__()

Return a JSON string representation of this instance.

Equivalent to calling :meth:to_json. Excluded fields are omitted.

Returns:

Type Description
str

A compact JSON string (no indentation).

as_dict(*, exclude_hidden=True)

Convert this dataclass instance to a plain dict.

Parameters:

Name Type Description Default
exclude_hidden bool

When True (default), fields decorated with metadata={"exclude": True} are omitted from the result, recursively throughout nested dataclasses. Pass False to include every field.

True

Returns:

Type Description
dict[str, Any]

A dict mapping field names to their current values. Nested

dict[str, Any]

dataclasses are recursively converted, respecting exclude

dict[str, Any]

metadata at every level.

Raises:

Type Description
TypeError

If the subclass was not decorated with @dataclasses.dataclass.

from_dict(data) classmethod

Create an instance from a dict, recursively rebuilding nested dataclasses.

Only keys that match declared dataclass field names are passed to the constructor. This makes from_dict tolerant of extra data (e.g. when loading from a config file that has fields added in a newer schema version). Nested dataclass-typed fields are reconstructed recursively for common container annotations, via :mod:dacite.

Note a nested dataclass field's own overridden from_dict (if any) is not called — dacite structures nested dataclasses itself.

Parameters:

Name Type Description Default
data dict[str, Any]

A dict whose keys correspond to dataclass field names. Unrecognised keys are silently ignored, or rejected when the class's __dacite_config__ sets strict.

required

Returns:

Type Description
Self

A new instance of this class populated with matching field values.

Raises:

Type Description
AppException

A value does not match its field's declared type, a required field is absent, or an enum-typed field names a member the enum does not define. Under strict, also a key that names no field, at any nesting level; the message lists every such key by its dotted path (repository.archtype).

TypeError

If the subclass was not decorated with @dataclasses.dataclass.

from_json(text) classmethod

Create an instance from a JSON string.

Delegates to :meth:from_dict after parsing, so unknown keys are ignored.

Parameters:

Name Type Description Default
text str

A JSON string representing a dict of field values.

required

Returns:

Type Description
Self

A new instance populated from the parsed JSON.

Raises:

Type Description
JSONDecodeError

If text is not valid JSON.

from_yaml(text) classmethod

Create an instance from a YAML string.

Delegates to :meth:from_dict after parsing, so unknown keys are ignored.

Parameters:

Name Type Description Default
text str

A YAML string representing a mapping of field values.

required

Returns:

Type Description
Self

A new instance populated from the parsed YAML.

Raises:

Type Description
YAMLError

If text is not valid YAML.

load(source, *, key=LIFECYCLE_KEY) classmethod

Read a lifecycle surface from a config document or an in-memory mapping.

Parameters:

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

A path to a TOML/YAML/JSON document, or an already-parsed mapping. Either may be the whole document (with the table under key) or the table itself.

required
key str

The table the surface lives under. Ignored when source is already the table.

LIFECYCLE_KEY

Raises:

Type Description
AppException

The document has no key table, or a declared value does not match its field's type.

to_json(*, indent=None, **kwargs)

Serialise this instance to a JSON string.

Fields excluded via metadata={"exclude": True} are omitted.

Parameters:

Name Type Description Default
indent str | int | None

Indentation level passed to :func:json.dumps. None produces compact output.

None
**kwargs Any

Additional keyword arguments forwarded to :func:json.dumps.

{}

Returns:

Type Description
str

A JSON string representation of this instance.

to_yaml(**kwargs)

Serialise this instance to a YAML string.

Fields excluded via metadata={"exclude": True} are omitted.

Parameters:

Name Type Description Default
**kwargs Any

Additional keyword arguments forwarded to :meth:~rn_forge.commons.fs.documents.YamlUtils.serialize (e.g. sort_keys, default_flow_style).

{}

Returns:

Type Description
str

A YAML string representation of this instance.

build_tool_app(source, *, cli_key='cli', lifecycle_key=LIFECYCLE_KEY, **typer_kwargs)

Build the application a repository's [cli] and [lifecycle] tables describe.

This is the entry point for an installable tool. It builds the generic application rn-forge-cli describes from [cli], then — when the document also has a lifecycle_key table — mounts this module's verbs on top of it, at the root or under LifecycleSurface.namespace.

Parameters:

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

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

required
cli_key str

The table the generic surface lives under.

'cli'
lifecycle_key str

The table the lifecycle verbs live under. A document without this table builds a plain application.

LIFECYCLE_KEY
**typer_kwargs Any

Forwarded to the :class:~rn_forge.cli.CliApp constructor.

{}

Raises:

Type Description
AppException

Either table is malformed, the namespace or a verb collides with a declared command name, or the product cannot be imported.

lifecycle_commands(product, verbs=VERBS)

Return a Typer app holding verbs as commands over product.

Parameters:

Name Type Description Default
product ToolProduct

The product the commands act on.

required
verbs Sequence[str]

Which of :data:VERBS to include.

VERBS

Raises:

Type Description
AppException

product is not a :class:ToolProduct, or a verb is not one of :data:VERBS.