exec-notify/README.md
Daniel Langbein 19d4188205 v0.1.5
add usage and improve doc; lazy config loading;
2021-11-23 19:18:38 +01:00

139 lines
3.5 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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 doesnt have the same packages as the live PyPI, its possible that attempting
> to install dependencies may fail or install something unexpected. While this package
> doesnt have any dependencies, its 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
```
## Instalation - global
```shell
sudo python3 -m pip install --upgrade --index-url https://test.pypi.org/simple/ --no-deps de.p1st.exec-notify
```
## 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/)