exec-notify/README.md

# execNotify

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

## Installation - venv

More detailed instructions about _venv_ can be found at [https://docs.python.org/3/library/venv.html](https://docs.python.org/3/library/venv.html)

Create a _venv_:

```shell
python3 -m venv ~/execNotify/venv
```

Activate the venv:

```shell
source ~/execNotify/venv/bin/activate
# echo "VIRTUAL_ENV=${VIRTUAL_ENV}"
```

Option A: Install the module from TestPyPI:

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

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.

Option B: Install from local directory

```shell
python3 -m pip install ~/Downloads/git/execNotify/
```

(Optionally) list installed modules:

```shell
pip list
```

## Installation - global

Requires `pip` (e.g. `pacman -S --needed python-pip`):

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

Note: Make sure that pip is up-to-date and matches your python version:

```shell
python --version
#=> Python 3.10.1

pip --version
#=> pip 20.3.4 from /usr/lib/python3.10/site-packages/pip (python 3.10)
```

## Configuration

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

```shell
install -Dm0600 /etc/execNotify/cfg.ini << 'EOF'
[DEFAULT]

[mail]
host = smtp.example.com
port = 465
password = examplePassword

from = noreply@example.com
to = me@example.com

[file]
maildir = /home/exampleUser/mail/
EOF
```

See also: [./etc/execNotify/cfg.ini.example](etc/execNotify/cfg.ini.example)


## Usage

### Usage of execNotify

Add `de-p1st-execNotify` in front of your command to execute.

**Example:**

`de-p1st-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!" | de-p1st-notify`

Send stdout and stderr via mail:

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

Send stdout and specify an optional email subject:

`echo "Hello world!" | de-p1st-notify "someSubject"`

Send message without using a pipe:

`de-p1st-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).

### Testing

See heading "Installation" above with steps to locally install this module.

### Uploading to TestPyPI

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

1) Set up a _venv_
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.exec_notify/](https://test.pypi.org/project/de.p1st.exec_notify/)