cmdinter 1.0.11

A "command interface" for functions.

# cmdinter

## Description

This is a library that can be used to apply a *command interface* to functions.
It's main purpose is to apply the *returncode* convention to python functions
and to give you some control on how to run these functions. E.g. if you need to
run a function silently (no stdout), if you need to return the stdout that a
function produces or if you need to prevent a function from throwing errors.

`cmdinter` was created for the [buildlib](https://pypi.python.org/pypi/buildlib)
package.

## API

### CmdFuncResult

A *cmd function* should return a `CmdFuncResult` object.

```python
class CmdFuncResult(NamedTuple):
returncode: int
returnvalue: Any
summary: str
```

`returncode` Unix returncode convention...

`returnvalue` The value the function returns. That would be what you usually
return via the `return` keyword.

`summary`, contains a cmd summary with a Status flag (see Status below). E.g.:

```
[OK] Run apt-get install.
[Error] pip install package x.
[Skip] Mount hard drive. Drive alrady mounted.
```


### Status

Status flags that can be used as `summary` prefix.

```python
class Status(object):
ok: str = '[OK]'
error: str = '[ERROR]'
skip: str = '[SKIP]'
```

### run_cmd()

This function can be used in case you want to run a child function as a command.
You run it like this

```python
result: CmdResult = run_cmd(
func=my_func,
args=my_args,
kwargs=my_kwargs,
silent=True,
return_stdout=True,
catch_err=False,
)
```

This is from the source code:

```python
def run_cmd(
silent: bool = False,
return_stdout: bool = False,
catch_err: bool = False,
) -> Callable:
"""
This function works in combination with functions that return a
'CmdFuncResult' object. With `run_cmd()` you get a some more control over
these functions.

Call it like this:

run_cmd(silent=True, return_stdout=True)(my_func, args, kwargs)

The curried function returns a `CmdResult` object.

@silent: Mute child output of child function if set to True.
@return_stdout: Return stdout of child function.
@catch_err: Catch errors that are raised by child functions and return error
message with 'CmdResult' object.
"""
# ...
```


### CmdResult

A function that is run via the `run_cmd()` function returns a `CmdResult`
object.

```python
class CmdResult(NamedTuple):
returnvalue: Any
returncode: int
summary: str
stdout: Optional[str]
stderr: Optional[str]
traceback: Optional[str]
```

The `CmdResult` object is an extended version of `CmdFuncResult`.

`stdout` In case you return stdout from a child function, it's stored here.

`stderr` In case use the `catch_err` option to catch errors from a child function, it's stored here.

`traceback` Error traceback is stored here.