# systemd_watchdog
sd_notify(3) and sd_watchdog_enabled(3) client functionality implemented in Python 3 for writing Python daemons
## Install
```
$ pip install systemd-watchdog
```
or
```
$ git clone ...
$ make install
```
## Usage
### `example.py`
```python
import systemd_watchdog
import time
wd = systemd_watchdog.WatchDog()
if not wd.is_enabled:
# Then it's probably not running is systemd with watchdog enabled
raise Exception("Watchdog not enabled")
# Report a status message
wd.status("Starting my service...")
time.sleep(3)
# Report that the program init is complete
wd.ready()
wd.status("Init is complete...")
wd.notify()
time.sleep(3)
# Compute time between notifications
timeout_half_sec = int(float(wd.timeout) / 2e6) # Convert us->s and half that
wd.status("Sleeping and then notify x 3")
time.sleep(timeout_half_sec)
wd.notify()
time.sleep(timeout_half_sec)
wd.notify()
time.sleep(timeout_half_sec)
wd.notify()
wd.status("Spamming loop - should only see 2-3 notifications")
t = float(0)
while t <= 4*timeout_half_sec:
time.sleep(0.05)
wd.ping()
t += 0.05
# Report an error to the service manager
wd.notify_error("An irrecoverable error occured!")
# The service manager will probably kill the program here
time.sleep(3)
```
### Quick Example
In one terminal:
`socat unix-recv:/tmp/tempo.sock -`
In another terminal:
`NOTIFY_SOCKET=/tmp/tempo.sock WATCHDOG_USEC=5000000 python example.py`
Expected output (in first terminal):
```
STATUS=Starting my service...
READY=1
STATUS=Init is complete...
WATCHDOG=1
STATUS=Sleeping and then notify x 3
WATCHDOG=1
WATCHDOG=1
WATCHDOG=1
STATUS=Spamming loop - should only see 2-3 notifications
WATCHDOG=1
WATCHDOG=1
WATCHDOG=1
STATUS=An irrecoverable error occured!
WATCHDOG=trigger
```
## Public Interface
### `systemd_watchdog.WatchDog` - commonly used properties and methods
#### `ping`
The only method required for the simplest implementation; combines `notify_due` with `notify()` to _only_ send "alive" notifications at reasonable intervals.
Returns boolean indicating if a message was sent or not.
#### `beat`
Alias for `ping()` if you prefer heartbeat terminology.
#### `ready()`
Report ready service state, _i.e._ completed init (only needed with `Type=notify`).
#### `status(msg)`
Send a service status message.
### `systemd_watchdog.WatchDog` - less-used properties and methods
#### `is_enabled`
Boolean property stating whether watchdog capability is enabled.
#### `timeout`
Property reporting the number of microseconds (int) before process will be killed.
It is recommended that you call `notify()` once roughly half of this interval has passed (see `notify_due`).
#### `timeout_td`
Property that is the same as `timeout` but presented as `datetime.timedelta` for easier manipulation.
#### `notify_due`
Boolean property indicating more than half of the watchdog interval has passed since last update.
#### `notify()`
Report a healthy service state. Other calls, _e.g._ `status()` do *not* reset the watchdog.
#### `notify_error(msg=None)`
Report an error to the watchdog manager. This program will likely be killed upon receipt.
If `msg` is provided, it will be reported as a status message prior to the error.
## History
Aaron D. Marasco Aug 2025 (1.0.0)
* Added typing
* Modernized build (pyproject.toml, poetry, etc)
* Renamed watchdog => WatchDog
Aaron D. Marasco May 2020 (0.9.0)
* Forked from the sd-notify project <https://github.com/stigok/sd-notify>
* Additional contributors can be found in GitHub repository history
## License
See `LICENSE` file
Raw data
{
"_id": null,
"home_page": "http://github.com/AaronDMarasco/systemd-watchdog/",
"name": "systemd-watchdog",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "sd_notify, sd_watchdog_enabled, systemd, watchdog",
"author": "AaronDMarasco",
"author_email": "systemd-watchdog@marascos.net",
"download_url": "https://files.pythonhosted.org/packages/3b/50/18c422ff2f946eb0cb9e17a894b320f56478bd5bee93d99d44ab32ad91da/systemd_watchdog-1.0.0.tar.gz",
"platform": null,
"description": "# systemd_watchdog\n\n\n\n\n\n\n\nsd_notify(3) and sd_watchdog_enabled(3) client functionality implemented in Python 3 for writing Python daemons\n\n## Install\n```\n$ pip install systemd-watchdog\n```\nor\n```\n$ git clone ...\n$ make install\n```\n\n## Usage\n### `example.py`\n```python\nimport systemd_watchdog\nimport time\n\nwd = systemd_watchdog.WatchDog()\nif not wd.is_enabled:\n # Then it's probably not running is systemd with watchdog enabled\n raise Exception(\"Watchdog not enabled\")\n\n# Report a status message\nwd.status(\"Starting my service...\")\ntime.sleep(3)\n\n# Report that the program init is complete\nwd.ready()\nwd.status(\"Init is complete...\")\nwd.notify()\ntime.sleep(3)\n\n# Compute time between notifications\ntimeout_half_sec = int(float(wd.timeout) / 2e6) # Convert us->s and half that\nwd.status(\"Sleeping and then notify x 3\")\ntime.sleep(timeout_half_sec)\nwd.notify()\ntime.sleep(timeout_half_sec)\nwd.notify()\ntime.sleep(timeout_half_sec)\nwd.notify()\nwd.status(\"Spamming loop - should only see 2-3 notifications\")\nt = float(0)\nwhile t <= 4*timeout_half_sec:\n time.sleep(0.05)\n wd.ping()\n t += 0.05\n\n# Report an error to the service manager\nwd.notify_error(\"An irrecoverable error occured!\")\n# The service manager will probably kill the program here\ntime.sleep(3)\n```\n### Quick Example\nIn one terminal:\n`socat unix-recv:/tmp/tempo.sock -`\n\nIn another terminal:\n`NOTIFY_SOCKET=/tmp/tempo.sock WATCHDOG_USEC=5000000 python example.py`\n\nExpected output (in first terminal):\n```\nSTATUS=Starting my service...\nREADY=1\nSTATUS=Init is complete...\nWATCHDOG=1\nSTATUS=Sleeping and then notify x 3\nWATCHDOG=1\nWATCHDOG=1\nWATCHDOG=1\nSTATUS=Spamming loop - should only see 2-3 notifications\nWATCHDOG=1\nWATCHDOG=1\nWATCHDOG=1\nSTATUS=An irrecoverable error occured!\nWATCHDOG=trigger\n```\n\n## Public Interface\n### `systemd_watchdog.WatchDog` - commonly used properties and methods\n#### `ping`\nThe only method required for the simplest implementation; combines `notify_due` with `notify()` to _only_ send \"alive\" notifications at reasonable intervals.\n\nReturns boolean indicating if a message was sent or not.\n\n#### `beat`\nAlias for `ping()` if you prefer heartbeat terminology.\n\n#### `ready()`\nReport ready service state, _i.e._ completed init (only needed with `Type=notify`).\n\n#### `status(msg)`\nSend a service status message.\n\n### `systemd_watchdog.WatchDog` - less-used properties and methods\n#### `is_enabled`\nBoolean property stating whether watchdog capability is enabled.\n\n#### `timeout`\nProperty reporting the number of microseconds (int) before process will be killed.\n\nIt is recommended that you call `notify()` once roughly half of this interval has passed (see `notify_due`).\n\n#### `timeout_td`\nProperty that is the same as `timeout` but presented as `datetime.timedelta` for easier manipulation.\n\n#### `notify_due`\nBoolean property indicating more than half of the watchdog interval has passed since last update.\n\n#### `notify()`\nReport a healthy service state. Other calls, _e.g._ `status()` do *not* reset the watchdog.\n\n#### `notify_error(msg=None)`\nReport an error to the watchdog manager. This program will likely be killed upon receipt.\n\nIf `msg` is provided, it will be reported as a status message prior to the error.\n\n\n## History\nAaron D. Marasco Aug 2025 (1.0.0)\n * Added typing\n * Modernized build (pyproject.toml, poetry, etc)\n * Renamed watchdog => WatchDog\n\nAaron D. Marasco May 2020 (0.9.0)\n * Forked from the sd-notify project <https://github.com/stigok/sd-notify>\n * Additional contributors can be found in GitHub repository history\n\n## License\n\nSee `LICENSE` file\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "sd_notify and sd_watchdog_enabled functionality for writing Python daemons under systemd",
"version": "1.0.0",
"project_urls": {
"Homepage": "http://github.com/AaronDMarasco/systemd-watchdog/",
"Issues": "http://github.com/AaronDMarasco/systemd-watchdog/issues"
},
"split_keywords": [
"sd_notify",
" sd_watchdog_enabled",
" systemd",
" watchdog"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "65ac02cf21226bfdec6c032ae60a43c5826a962f1ddc894014f14d1e587eb6ac",
"md5": "85178fae8ffb32b76d1e352bca443db6",
"sha256": "335d06aabb0d9cc96b1825208be03170f52d293e3d9fa8f0c968a73c210a8e8b"
},
"downloads": -1,
"filename": "systemd_watchdog-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "85178fae8ffb32b76d1e352bca443db6",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 5008,
"upload_time": "2025-08-22T00:47:35",
"upload_time_iso_8601": "2025-08-22T00:47:35.925943Z",
"url": "https://files.pythonhosted.org/packages/65/ac/02cf21226bfdec6c032ae60a43c5826a962f1ddc894014f14d1e587eb6ac/systemd_watchdog-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "3b5018c422ff2f946eb0cb9e17a894b320f56478bd5bee93d99d44ab32ad91da",
"md5": "bd2231b03bc464aefcd830fa37d0873b",
"sha256": "4388150ea67f341b550400819cdb7b59bcea0f7a47bde3791b28764f04e157b7"
},
"downloads": -1,
"filename": "systemd_watchdog-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "bd2231b03bc464aefcd830fa37d0873b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 4314,
"upload_time": "2025-08-22T00:47:36",
"upload_time_iso_8601": "2025-08-22T00:47:36.961960Z",
"url": "https://files.pythonhosted.org/packages/3b/50/18c422ff2f946eb0cb9e17a894b320f56478bd5bee93d99d44ab32ad91da/systemd_watchdog-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-22 00:47:36",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "AaronDMarasco",
"github_project": "systemd-watchdog",
"travis_ci": true,
"coveralls": false,
"github_actions": false,
"lcname": "systemd-watchdog"
}
JSON
