Shell¶

class nutcli.shell.Shell(cwd=None, env=None, clear_env=False, shell=None, default_effect=<Effect.SideEffect: 2>, logger=None)¶

Bases: object

Run commands in closed shell environment.

Example usage¶

sh = Shell()
sh('echo "Hello World!"')
sh(['/bin/bash', '-c', 'echo "Hello World!"'])
she('echo $HELLO', env={'HELLO': 'World!'})

Parameters

cwd (str, optional) – Default working directory, defaults to None (= current working directory)
env (dict of str:str, optional) – Additional environment values, defaults to None
clear_env (bool, optional) – If True, current shell environment is ignored, defaults to False
shell (list of str, optional) – Shell that will be used to execute commands, defaults to None (= [‘/bin/bash’, ‘-c’])
default_effect (Effect, optional) – Default execution effect, defaults to Effect.SideEffect
logger (logger, optional) – Logger, defaults to None (= nutcli.message)

class Effect¶

Bases: enum.Enum

Sometimes, it is desirable to produce some additional effect such as a log message when the command is run. These values control the effect.

Blank = 0¶: Nothing is done when the command is executed.

LogExecution = 1¶: Each call is logged into the information log if it is enabled in nutcli.decorators.LogExecution.

SideEffect = 2¶: Each call is logged into the information log if it is enabled in nutcli.decorators.LogExecution. And the command is not run at all if dry run is enabled in nutcli.decorators.SideEffect.

__call__(command, env=None, effect=None, dry_run_result=None, execution_message=None, **kwargs)¶

Execute shell command.

Parameters

command (str or list of str) – Command to execute
env (dict of str:str, optional) – Additional environment variables, defaults to None
effect (Effect, optional) – Execution effect, defaults to None (= value provided in constructor)
dry_run_result (any, optional) – Result for dry run call if effect is set to SideEffect, defaults to None
execution_message (str, optional) – Log execution message if effect is set to LogExecution or SideEffect, defaults to None

Raises

ShellCommandError – Command returned non-zero status code
ShellTimeoutError – Command did not finish in time

Returns

Shell result object.

Return type

ShellResult

Command may be either a list of command and its arguments or a string representing a full command line. If it is a list it is run as is via subproccess.run(), if it is a string it is run inside a shell as:

[shell, command], e.g. ['/bin/bash', '-c', command]

Additional keyword arguments can be specified to be forwarded to subprocess.run() call. By default text mode is set to true, therefore if you capture output via capture_output or other means, it is considered to be a text and is decoded as utf-8 text.

Common subprocess.run() arguments:

capture_output {bool} – Capture stdout and stderr.

cwd {string} – Change working directory.

timeout – timeout in seconds

Note

See python documentation for more:

https://docs.python.org/3/library/subprocess.html

clone()¶

Create a deep copy of self.

Returns:: ShellEnvironment – Self deep copy.

class nutcli.shell.ShellResult(rc, stdout=None, stderr=None)¶

Bases: object

Result of successful shell command execution.

Parameters

rc (Int) – Command return code
stdout (bytes or str) – Captured command standard output stream
stderr (bytes or str) – Captured command standard error stream.

class nutcli.shell.ShellEnvironment(clear_env=False)¶

Bases: object

Manage copy of shell environment.

Parameters: clear_env (bool, optional) – If True, current shell environment is ignored, defaults to False

set(env)¶

Add values to the environment.

Parameters: env (dict of str:str) – Additional environment.
Returns: self
Return type: ShellEnvironment

get()¶

Get new copy of this environment as a dictionary.

Returns: This environment as a dictionary
Return type: dict of str:str

get_overrides()¶

Get only values that were added to the original environment.

Returns: Additional environment as a dictionary
Return type: dict of str:str

clone()¶

Get a deep copy of this object.

Returns: Deep copy of self.
Return type: ShellEnvironment

exception nutcli.shell.ShellError(message, cmd, cwd, env, stdout, stderr)¶

Bases: Exception

Provide information about shell error.

Parameters

message (str) – Error message
cmd (str or list of str) – Failed command
cwd (str) – Command working directory
env (ShellEnvironment) – Command environment
stdout (bytes or str) – Captured command standard output stream
stderr (bytes or str) – Captured command standard error stream.

property pretty_message¶

Get formatted error message. It is returned as list of string where each item represents one line of the message.

Returns: Error message lines.
Return type: list of str

exception nutcli.shell.ShellCommandError(rc, cmd, cwd, env, stdout, stderr)¶

Bases: nutcli.shell.ShellError

Provide information about failed command.

Parameters

rc (int) – Command return code
cmd (str or list of str) – Failed command
cwd (str) – Command working directory
env (ShellEnvironment) – Command environment
stdout (bytes or str) – Captured command standard output stream
stderr (bytes or str) – Captured command standard error stream.

property pretty_message¶

Get formatted error message. It is returned as list of string where each item represents one line of the message.

Returns: Error message lines.
Return type: list of str

exception nutcli.shell.ShellTimeoutError(timeout, cmd, cwd, env, stdout, stderr)¶

Bases: nutcli.shell.ShellError

Provide information about command that did not end in set time.

Parameters

timeout (int) – Timeout value in seconds
cmd (str or list of str) – Failed command
cwd (str) – Command working directory
env (ShellEnvironment) – Command environment
stdout (bytes or str) – Captured command standard output stream
stderr (bytes or str) – Captured command standard error stream.

property pretty_message¶

Get formatted error message. It is returned as list of string where each item represents one line of the message.

Returns: Error message lines.
Return type: list of str