mirror of
https://codeberg.org/privacy1st/exec-notify
synced 2024-12-22 23:16:04 +01:00
156 lines
4.0 KiB
Markdown
156 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 - 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
|
||
```
|
||
|
||
## 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 ~/Downloads/git/execNotify/
|
||
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/)
|