Metadata-Version: 2.0
Name: cmdinter
Version: 1.0.9
Summary: A "command interface" for functions.
Home-page: https://github.com/feluxe/cmdinter
Author: Felix Meyer-Wolters
Author-email: felix@meyerwolters.de
License: unlicensed
Download-URL: https://github.com/feluxe/cmdinter/tarball/1.0.9
Description-Content-Type: UNKNOWN
Keywords: command,interface,decorator
Platform: 

# 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(
    silent=True, 
    return_stdout=True,
    catch_err=False,
)(
    func=my_func,
    args=my_args,
    kwargs=my_kwargs,
)
```

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.




