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: |
required |
verbs
|
tuple[str, ...]
|
Which of :data: |
(lambda: VERBS)()
|
namespace
|
str | None
|
Sub-command group the verbs are mounted under, e.g.
|
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 |
__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
|
Returns:
| Type | Description |
|---|---|
dict[str, Any]
|
A dict mapping field names to their current values. Nested |
dict[str, Any]
|
dataclasses are recursively converted, respecting |
dict[str, Any]
|
metadata at every level. |
Raises:
| Type | Description |
|---|---|
TypeError
|
If the subclass was not decorated with
|
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 |
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 |
TypeError
|
If the subclass was not decorated with
|
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: |
None
|
**kwargs
|
Any
|
Additional keyword arguments forwarded to
:func: |
{}
|
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: |
{}
|
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: |
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: |
{}
|
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
|
Raises:
| Type | Description |
|---|---|
AppException
|
product is not a :class: |