Subprocess¶
rn_forge.commons.runtime.subprocess
¶
Subprocess execution with structured result capture.
Typical usage::
from rn_forge.commons.runtime.subprocess import Process
result = Process.execute("list-files", "ls", "-la", "/tmp")
if result.succeeded:
print(result.stdout)
Process(name, args, return_code, stdout, stderr, kwargs=dict[str, Any](), error=None, completed_process=None)
dataclass
¶
Bases: DataclassMixin
Immutable record of a subprocess execution.
Construct via :meth:execute or the named shortcuts (:meth:python,
:meth:mvn, :meth:npm, :meth:az, :meth:pwsh). Instances are
frozen dataclasses, so all fields are set at construction time.
Fields kwargs, error, and completed_process are excluded
from serialisation (they carry metadata={"exclude": True}).
Attributes:
| Name | Type | Description |
|---|---|---|
name |
str
|
Human-readable label for the process used in log messages and
:exc: |
args |
list[str]
|
The exact argument list forwarded to :func: |
return_code |
int
|
Exit code of the process ( |
stdout |
str | None
|
Decoded standard output, or |
stderr |
str | None
|
Decoded standard error, or |
kwargs |
dict[str, Any]
|
Extra keyword arguments that were passed to
:func: |
error |
Exception | None
|
The exception raised during execution, if any. Excluded from serialisation. |
completed_process |
CompletedProcess[Any] | None
|
The raw :class: |
Example::
result = Process.execute("ping", "ping", "-c", "1", "localhost")
assert result.succeeded
assert "localhost" in (result.stdout or "")
Process.python("scripts/build_report.py", "--date", "2026-04-23")
succeeded
property
¶
Whether the process exited successfully.
Returns:
| Type | Description |
|---|---|
bool
|
|
__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
|
az(cmd, *args, **kwargs)
classmethod
¶
Run an Azure CLI (az) command.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
cmd
|
str
|
The |
required |
*args
|
str
|
Additional arguments appended after cmd. |
()
|
**kwargs
|
Any
|
Forwarded to :meth: |
{}
|
Returns:
| Name | Type | Description |
|---|---|---|
A |
Self
|
class: |
Raises:
| Type | Description |
|---|---|
AppException
|
If cmd is empty or |
execute(name, *args, fail_on_error=True, capture_output=True, **kwargs)
classmethod
¶
Run a subprocess and return an immutable :class:Process result.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
name
|
str
|
Human-readable label for this process (used in log messages and exception messages). |
required |
*args
|
str
|
Command and arguments forwarded to :func: |
()
|
fail_on_error
|
bool
|
When |
True
|
capture_output
|
bool
|
When |
True
|
**kwargs
|
Any
|
Additional keyword arguments forwarded verbatim to
:func: |
{}
|
Returns:
| Name | Type | Description |
|---|---|---|
A |
Self
|
class: |
Self
|
stderr, and the raw :class: |
Example::
result = Process.execute(
"list-files",
"ls",
"-la",
cwd=".",
fail_on_error=False,
)
Raises:
| Type | Description |
|---|---|
AppException
|
If args is empty or contains an empty string. |
AppException
|
If |
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. |
mvn(pom, *args, **kwargs)
classmethod
¶
Run a Maven command against a POM file.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
pom
|
str | Path
|
Path to the |
required |
*args
|
str
|
Maven goals and arguments (e.g. |
()
|
**kwargs
|
Any
|
Forwarded to :meth: |
{}
|
Returns:
| Name | Type | Description |
|---|---|---|
A |
Self
|
class: |
Raises:
| Type | Description |
|---|---|
AppException
|
If pom does not exist or |
npm(project, *args, **kwargs)
classmethod
¶
Run an npm command in project directory.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
project
|
str | Path
|
Path to the directory containing |
required |
*args
|
str
|
npm arguments (e.g. |
()
|
**kwargs
|
Any
|
Forwarded to :meth: |
{}
|
Returns:
| Name | Type | Description |
|---|---|---|
A |
Self
|
class: |
Raises:
| Type | Description |
|---|---|
AppException
|
If |
pwsh(cmd_or_script, *args, mode='command', **kwargs)
classmethod
¶
Run a PowerShell (pwsh) command or script.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
cmd_or_script
|
str | Path
|
A PowerShell command string or a path to a |
required |
*args
|
str
|
Additional arguments appended to the |
()
|
mode
|
str
|
|
'command'
|
**kwargs
|
Any
|
Forwarded to :meth: |
{}
|
Returns:
| Name | Type | Description |
|---|---|---|
A |
Self
|
class: |
Raises:
| Type | Description |
|---|---|
AppException
|
If cmd_or_script is empty, |
python(file, *args, **kwargs)
classmethod
¶
Run a Python script using the active Python interpreter.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
file
|
str | Path
|
Path to the |
required |
*args
|
str
|
Additional arguments passed to the script. |
()
|
**kwargs
|
Any
|
Forwarded to :meth: |
{}
|
Returns:
| Name | Type | Description |
|---|---|---|
A |
Self
|
class: |
Example::
Process.python("scripts/build_report.py", "--date", "2026-04-23")
Raises:
| Type | Description |
|---|---|
AppException
|
If file does not exist. |
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. |