mirror of
https://codeberg.org/privacy1st/exec-notify
synced 2024-12-22 23:16:04 +01:00
158 lines
4.0 KiB
Markdown
158 lines
4.0 KiB
Markdown
# 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
|
|
|
|
### Installation - global
|
|
|
|
Requires `pip` (e.g. `pacman -S --needed python-pip`).
|
|
|
|
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)
|
|
```
|
|
|
|
Then install with one of the following options:
|
|
|
|
```shell
|
|
sudo python3 -m pip install --upgrade git+https://codeberg.org/privacy1st/execNotify
|
|
sudo python3 -m pip install --upgrade .
|
|
sudo python3 -m pip install --upgrade --index-url https://test.pypi.org/simple/ --no-deps de.p1st.exec-notify
|
|
```
|
|
|
|
### 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}"
|
|
```
|
|
|
|
And choose one source of installation:
|
|
|
|
```shell
|
|
# Install from git URL
|
|
python3 -m pip install git+https://codeberg.org/privacy1st/execNotify
|
|
|
|
# Install from local directory
|
|
python3 -m pip install ~/Downloads/git/execNotify/
|
|
|
|
# Install the module from TestPyPI
|
|
python3 -m pip install --index-url https://test.pypi.org/simple/ --no-deps --upgrade de.p1st.exec-notify
|
|
```
|
|
|
|
Note about usage of TestPyPI and `--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.
|
|
|
|
(Optionally) list installed modules:
|
|
|
|
```shell
|
|
pip list
|
|
```
|
|
|
|
## 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/)
|