exec-notify/README.md

# execNotify

* Send email notification if command fails with [execNotify](src/de/p1st/exec_notify/execNotify).
* Send unconditional notifications with [notify](src/de/p1st/exec_notify/notify).

## Installation

Create a _venv_ and install the module from TestPyPI:

```shell
python3 -m pip install --index-url https://test.pypi.org/simple/ --no-deps de-p1st-execNotify
```

The above command uses the parameter `--no-deps`:

> Since TestPyPI doesn’t have the same packages as the live PyPI, it’s possible that attempting
> to install dependencies may fail or install something unexpected. While this package
> doesn’t have any dependencies, it’s a good practice to avoid installing dependencies when
> using TestPyPI.

## Configuration

Create configuration file `/etc/execNotify/cfg.ini`.

For the required fields, see [./etc/execNotify/cfg.ini.example](etc/execNotify/cfg.ini.example)


## Usage

### Usage of execNotify

Add `execNotify` in front of your command to execute.

You can pipe into `execNotify` but **not** from `execNotify`
 as the output gets modified.

**Example:**

`execNotify ls /non/existent/file` will mail you the exit code, stdout and stderr of `ls /non/existent/file`

### Usage of notify

Send stdout via mail:

`echo "Hello world!" | notify`

Send stdout and stderr via mail:

`echo "Hello world!" 2>&1 | notify`

Send stdout and specify an optional email subject:

`echo "Hello world!" | notify "someSubject"`

Send message without using a pipe:

`notify "someSubject" "Hello World! What's up?"`


## Development

When started with environment variable `DE_P1ST_EXEC_NOTIFY` set,
then the configuration file is read from [./etc/execNotify/cfg.ini](etc/execNotify/cfg.ini).

### Uploading to TestPyPI

More detailed instructions can be found at https://packaging.python.org/tutorials/packaging-projects/

0) Set up a _venv_
1) Develop and test locally
2) Increase/Adjust `[metadata][version]` in [setup.cfg](setup.cfg)
3) Install the `build` and `twine` modules to your _venv_.
4) Next generate a [distribution archive](https://packaging.python.org/tutorials/packaging-projects/#generating-distribution-archives):

```shell
python3 -m build
```

5) Upload the distribution packages with twine. For the username, use `__token__`. For the password, use a 
[test.pypi.org API token](https://test.pypi.org/manage/account/#api-tokens):

```shell
python3 -m twine upload --repository testpypi dist/*
```

6) Congratulations! You can view the uploaded module under:

* [https://test.pypi.org/project/de-p1st-execNotify/](https://test.pypi.org/project/de-p1st-execNotify/)