| Name | dwatch JSON |
| Version |
0.4.1
JSON |
| download |
| home_page | None |
| Summary | A tool to watch command output for differences and send notifications. |
| upload_time | 2025-08-28 14:49:24 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.9 |
| license | Copyright 2022 Forschungszentrum Jülich GmbH
Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the "Software"), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
the Software, and to permit persons to whom the Software is furnished to do so,
subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
| keywords |
administration
monitoring
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# dwatch
## Overview
dwatch (*diff watch*) is a tool to monitor the output of a given command and notify the user on changes by sending an
email with a diff view.
## Installation
dwatch is available on PyPI and can be installed with `pip`:
```bash
python3 -m pip install dwatch
```
At least Python 3.9 is required.
If you run an Arch-based system, you can also install `dwatch` from the
[AUR](https://aur.archlinux.org/packages/dwatch/):
```bash
yay -S dwatch
```
You can also download self-contained executables (no Python installation required) for Linux x64, macOS x64 and macOS
ARM64 from the [releases page](https://github.com/IngoMeyer441/dwatch/releases).
## Usage
By default, dwatch runs a commmand passed on the command line every 60 seconds and notifies the user on any changes. You
can run a first test with:
```bash
dwatch -i 2 --stdout "date"
```
This runs the `date` command every 2 seconds and prints the output differences to stdout.
Pass the `--run-once` option to run one check, print a diff if necessary and exit. The diff is created against the
output from the previous run (command outputs are stored in the file `~/.dwatch_command_output.json`). This is
especially useful in cron jobs.
Without `--stdout` the diff output is sent as an HTML email. By default, dwatch uses the `sendmail` tool for this, which
is available if a local email server like Postfix or Exim is installed or if a simple mail forwarder like
[ssmtp](https://packages.debian.org/stable/ssmtp) is present. As an alternative, dwatch supports direct communication
with a mail server with Python's builtin [smtplib](https://docs.python.org/3/library/smtplib.html). This can be used if
no email server is installed locally. In either case, run
```bash
dwatch --write-default-config
```
to create a default configuration file at `~/.dwatchrc`. Open the file with a text editor and configure a sender
`from_address` and receiver `to_address` in the `[mail]` section:
```text
[mail]
backend = sendmail
server = mail.example.com
login_user = jane.doe
login_password = xxx
encryption = starttls
from_address = dwatch-report@example.com
to_addresses = admin@example.com
```
Change `sendmail` to `smtplib` to use an arbitrary email provider and set the server address, the login credentials and
the encryption (`none`, `starttls` or `ssl`). If `none` is chosen, no login credentials are sent for security reasons.
This can only be used for very simple mail server setups.
Use the `--description` command line option with a text argument to add a description to the diff report and the subject
field of emails. This can be useful to distinguish different commands.
## Configuration
These options can be configured in the file `~/.dwatchrc`:
- `[general]` section:
- `verbosity`: The logging level of the application. Can be one of `quiet`, `error`, `warn`, `verbose` or `debug`.
- `[mail]` section:
- `backend`: `sendmail` to use the local `sendmail` command or `smtplib` to connect to an arbitrary email server with
the smtp protocol.
- `server`: The mail server to use. This field is ignored if the `sendmail` backend is chosen.
- `login_user`: The login name for the mail server. This field is ignored if the `sendmail` backend is chosen.
- `login_password`: The login password for the mail server. This field is ignored if the `sendmail` backend is chosen.
- `encryption`: The encryption to use to connect to the mail server, can be `none` (not recommended!), `starttls` or
`ssl`. This field is ignored if the `sendmail` backend is chosen. If `none` is chosen, no login credentials are sent
for security reasons.
- `from_address`: The from address in the email envelope. Many providers do not support to change the from address and
overwrite this with your actual mail address.
- `to_address`: The recipient address.
- `[watch]` section:
- `abort_on_error`: If set to `True`, the program will abort if the given command exits with a non-zero exit code.
- `capture`: The streams to capture from, as comma-separated list of "stdout" and "stderr".
- `ignore_output_on_error`: Ignore the output of the executed command if it exits with a non-zero exit code.
- `interval`: The time interval in seconds between runs of the given command.
- `run_once`: If set to `True`, the command will only be run once the program exits. This is intended to be used with
cron jobs.
- `shell`: Run the given command in a subshell. This is useful to allow shell patterns in a command like pipes (for
example `command | grep pattern`).
## Command line options
```text
usage: dwatch [-h] [-a | -A] [-c CAPTURE] [-d DESCRIPTION] [-i INTERVAL] [-l |
-L] [-o | -O] [-s | -S] [--stdout] [-V] [-w] [-x | -X] [-q |
--error | --warn | -v | --debug]
[command]
dwatch is a tool for watching command output for changes and notifiying the
user. Default values for command line options are taken from the config file
at "~/.dwatchrc"
positional arguments:
command the command to watch
options:
-h, --help show this help message and exit
-a, --abort-on-error abort if the executed command exits with a non-zero
exit code (default: "False")
-A, --no-abort-on-error
don't abort if the executed command exits with a non-
zero exit code (default: "True")
-c, --capture CAPTURE
set the streams to capture from, as comma-separated
list of "stdout" and "stderr" (default:
"stdout,stderr")
-d, --description DESCRIPTION
add a description which is added to the diff output
and used in the e-mail subject
-i, --interval INTERVAL
set the interval for the watched command (default:
"60.0")
-l, --wait-for-lock block until other instances of dwatch are done
(default: "True")
-L, --no-wait-for-lock
don't block until other instances of dwatch are done
(default: "False")
-o, --run-once run the given command once and exit (default: "False")
-O, --no-run-once don't run the given command once and exit (default:
"True")
-s, --shell run the given command in a shell subprocess (default:
"False")
-S, --no-shell don't run the given command in a shell subprocess
(default: "True")
--stdout print the diff on stdout, do not send a mail
-V, --version print the version number and exit
-w, --write-default-config
create a configuration file with default values
(config filepath: "~/.dwatchrc")
-x, --ignore-output-on-error
ignore the output of the executed command if it exits
with a non-zero exit code (default: "False")
-X, --no-ignore-output-on-error
don't ignore the output of the executed command if it
exits with a non-zero exit code (default: "True")
-q, --quiet be quiet (default: "False")
--error print error messages (default: "False")
--warn print warning and error messages (default: "False")
-v, --verbose be verbose (default: "True")
--debug print debug messages (default: "False")
```
Raw data
{
"_id": null,
"home_page": null,
"name": "dwatch",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "Ingo Meyer <i.meyer@fz-juelich.de>",
"keywords": "administration, monitoring",
"author": null,
"author_email": "Ingo Meyer <i.meyer@fz-juelich.de>",
"download_url": "https://files.pythonhosted.org/packages/ad/f6/6cb19793589dc68bdee89a07667fc7abf401e981253bf914644d22ce3072/dwatch-0.4.1.tar.gz",
"platform": null,
"description": "# dwatch\n\n## Overview\n\n\n\ndwatch (*diff watch*) is a tool to monitor the output of a given command and notify the user on changes by sending an\nemail with a diff view.\n\n## Installation\n\ndwatch is available on PyPI and can be installed with `pip`:\n\n```bash\npython3 -m pip install dwatch\n```\n\nAt least Python 3.9 is required.\n\nIf you run an Arch-based system, you can also install `dwatch` from the\n[AUR](https://aur.archlinux.org/packages/dwatch/):\n\n```bash\nyay -S dwatch\n```\n\nYou can also download self-contained executables (no Python installation required) for Linux x64, macOS x64 and macOS\nARM64 from the [releases page](https://github.com/IngoMeyer441/dwatch/releases).\n\n## Usage\n\nBy default, dwatch runs a commmand passed on the command line every 60 seconds and notifies the user on any changes. You\ncan run a first test with:\n\n```bash\ndwatch -i 2 --stdout \"date\"\n```\n\nThis runs the `date` command every 2 seconds and prints the output differences to stdout.\n\nPass the `--run-once` option to run one check, print a diff if necessary and exit. The diff is created against the\noutput from the previous run (command outputs are stored in the file `~/.dwatch_command_output.json`). This is\nespecially useful in cron jobs.\n\nWithout `--stdout` the diff output is sent as an HTML email. By default, dwatch uses the `sendmail` tool for this, which\nis available if a local email server like Postfix or Exim is installed or if a simple mail forwarder like\n[ssmtp](https://packages.debian.org/stable/ssmtp) is present. As an alternative, dwatch supports direct communication\nwith a mail server with Python's builtin [smtplib](https://docs.python.org/3/library/smtplib.html). This can be used if\nno email server is installed locally. In either case, run\n\n```bash\ndwatch --write-default-config\n```\n\nto create a default configuration file at `~/.dwatchrc`. Open the file with a text editor and configure a sender\n`from_address` and receiver `to_address` in the `[mail]` section:\n\n```text\n[mail]\nbackend = sendmail\nserver = mail.example.com\nlogin_user = jane.doe\nlogin_password = xxx\nencryption = starttls\nfrom_address = dwatch-report@example.com\nto_addresses = admin@example.com\n```\n\nChange `sendmail` to `smtplib` to use an arbitrary email provider and set the server address, the login credentials and\nthe encryption (`none`, `starttls` or `ssl`). If `none` is chosen, no login credentials are sent for security reasons.\nThis can only be used for very simple mail server setups.\n\nUse the `--description` command line option with a text argument to add a description to the diff report and the subject\nfield of emails. This can be useful to distinguish different commands.\n\n## Configuration\n\nThese options can be configured in the file `~/.dwatchrc`:\n\n- `[general]` section:\n\n - `verbosity`: The logging level of the application. Can be one of `quiet`, `error`, `warn`, `verbose` or `debug`.\n\n- `[mail]` section:\n\n - `backend`: `sendmail` to use the local `sendmail` command or `smtplib` to connect to an arbitrary email server with\n the smtp protocol.\n - `server`: The mail server to use. This field is ignored if the `sendmail` backend is chosen.\n - `login_user`: The login name for the mail server. This field is ignored if the `sendmail` backend is chosen.\n - `login_password`: The login password for the mail server. This field is ignored if the `sendmail` backend is chosen.\n - `encryption`: The encryption to use to connect to the mail server, can be `none` (not recommended!), `starttls` or\n `ssl`. This field is ignored if the `sendmail` backend is chosen. If `none` is chosen, no login credentials are sent\n for security reasons.\n - `from_address`: The from address in the email envelope. Many providers do not support to change the from address and\n overwrite this with your actual mail address.\n - `to_address`: The recipient address.\n\n- `[watch]` section:\n\n - `abort_on_error`: If set to `True`, the program will abort if the given command exits with a non-zero exit code.\n - `capture`: The streams to capture from, as comma-separated list of \"stdout\" and \"stderr\".\n - `ignore_output_on_error`: Ignore the output of the executed command if it exits with a non-zero exit code.\n - `interval`: The time interval in seconds between runs of the given command.\n - `run_once`: If set to `True`, the command will only be run once the program exits. This is intended to be used with\n cron jobs.\n - `shell`: Run the given command in a subshell. This is useful to allow shell patterns in a command like pipes (for\n example `command | grep pattern`).\n\n## Command line options\n\n```text\nusage: dwatch [-h] [-a | -A] [-c CAPTURE] [-d DESCRIPTION] [-i INTERVAL] [-l |\n -L] [-o | -O] [-s | -S] [--stdout] [-V] [-w] [-x | -X] [-q |\n --error | --warn | -v | --debug]\n [command]\n\ndwatch is a tool for watching command output for changes and notifiying the\nuser. Default values for command line options are taken from the config file\nat \"~/.dwatchrc\"\n\npositional arguments:\n command the command to watch\n\noptions:\n -h, --help show this help message and exit\n -a, --abort-on-error abort if the executed command exits with a non-zero\n exit code (default: \"False\")\n -A, --no-abort-on-error\n don't abort if the executed command exits with a non-\n zero exit code (default: \"True\")\n -c, --capture CAPTURE\n set the streams to capture from, as comma-separated\n list of \"stdout\" and \"stderr\" (default:\n \"stdout,stderr\")\n -d, --description DESCRIPTION\n add a description which is added to the diff output\n and used in the e-mail subject\n -i, --interval INTERVAL\n set the interval for the watched command (default:\n \"60.0\")\n -l, --wait-for-lock block until other instances of dwatch are done\n (default: \"True\")\n -L, --no-wait-for-lock\n don't block until other instances of dwatch are done\n (default: \"False\")\n -o, --run-once run the given command once and exit (default: \"False\")\n -O, --no-run-once don't run the given command once and exit (default:\n \"True\")\n -s, --shell run the given command in a shell subprocess (default:\n \"False\")\n -S, --no-shell don't run the given command in a shell subprocess\n (default: \"True\")\n --stdout print the diff on stdout, do not send a mail\n -V, --version print the version number and exit\n -w, --write-default-config\n create a configuration file with default values\n (config filepath: \"~/.dwatchrc\")\n -x, --ignore-output-on-error\n ignore the output of the executed command if it exits\n with a non-zero exit code (default: \"False\")\n -X, --no-ignore-output-on-error\n don't ignore the output of the executed command if it\n exits with a non-zero exit code (default: \"True\")\n -q, --quiet be quiet (default: \"False\")\n --error print error messages (default: \"False\")\n --warn print warning and error messages (default: \"False\")\n -v, --verbose be verbose (default: \"True\")\n --debug print debug messages (default: \"False\")\n```\n",
"bugtrack_url": null,
"license": "Copyright 2022 Forschungszentrum J\u00fclich GmbH\n \n Permission is hereby granted, free of charge, to any person obtaining a copy of\n this software and associated documentation files (the \"Software\"), to deal in\n the Software without restriction, including without limitation the rights to\n use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of\n the Software, and to permit persons to whom the Software is furnished to do so,\n subject to the following conditions:\n \n The above copyright notice and this permission notice shall be included in all\n copies or substantial portions of the Software.\n \n THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS\n FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR\n COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER\n IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN\n CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\n ",
"summary": "A tool to watch command output for differences and send notifications.",
"version": "0.4.1",
"project_urls": {
"Homepage": "https://github.com/IngoMeyer441/dwatch"
},
"split_keywords": [
"administration",
" monitoring"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "9b4164ea1e627b46c1efeb4317a9cc158310f5c8f6175fc8fd3fa3db1b208cf8",
"md5": "2999b6f4d0d9cdda2cf9c037ee76e757",
"sha256": "05f529104d146eb578b15ec71b05f616cbc7d2ddca4e6e3682e559c0e67084bc"
},
"downloads": -1,
"filename": "dwatch-0.4.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2999b6f4d0d9cdda2cf9c037ee76e757",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 16024,
"upload_time": "2025-08-28T14:49:23",
"upload_time_iso_8601": "2025-08-28T14:49:23.281189Z",
"url": "https://files.pythonhosted.org/packages/9b/41/64ea1e627b46c1efeb4317a9cc158310f5c8f6175fc8fd3fa3db1b208cf8/dwatch-0.4.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "adf66cb19793589dc68bdee89a07667fc7abf401e981253bf914644d22ce3072",
"md5": "86aba80db6661cfdfe5e83a55081d259",
"sha256": "50b39cbec436127db488ee5f76f5cacf5f5af814ae3ae024e2a4663e63708e3e"
},
"downloads": -1,
"filename": "dwatch-0.4.1.tar.gz",
"has_sig": false,
"md5_digest": "86aba80db6661cfdfe5e83a55081d259",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 16741,
"upload_time": "2025-08-28T14:49:24",
"upload_time_iso_8601": "2025-08-28T14:49:24.351757Z",
"url": "https://files.pythonhosted.org/packages/ad/f6/6cb19793589dc68bdee89a07667fc7abf401e981253bf914644d22ce3072/dwatch-0.4.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-28 14:49:24",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "IngoMeyer441",
"github_project": "dwatch",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "dwatch"
}
