Skip to main content

A "command interface" for functions.

Project description

# 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.


Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, size & hash SHA256 hash help File type Python version Upload date
cmdinter-1.0.11-py3-none-any.whl (7.6 kB) Copy SHA256 hash SHA256 Wheel 3.6

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page