sdnotify.py documentation

sshuttle/sdnotify.py

@@ -1,3 +1,13 @@
+"""When sshuttle is run via a systemd service file, we can communicate
+to systemd about the status of the sshuttle process. In particular, we
+can send READY status to tell systemd that sshuttle has completed
+startup and send STOPPING to indicate that sshuttle is beginning
+shutdown.
+
+For details, see:
+https://www.freedesktop.org/software/systemd/man/sd_notify.html
+"""
+
 import socket
 import os
 
@@ -5,6 +15,7 @@ from sshuttle.helpers import debug1
 
 
 def _notify(message):
+    """Send a notification message to systemd."""
     addr = os.environ.get("NOTIFY_SOCKET", None)
 
     if not addr or len(addr) == 1 or addr[0] not in ('/', '@'):
@@ -31,16 +42,22 @@ def _notify(message):
 
 
 def send(*messages):
+    """Send multiple messages to systemd."""
     return _notify(b'\n'.join(messages))
 
 
 def ready():
+    """Constructs a message that is appropriate to send upon completion of
+sshuttle startup."""
     return b"READY=1"
 
 
 def stop():
+    """Constructs a message that is appropriate to send when sshuttle is
+beginning to shutdown."""
     return b"STOPPING=1"
 
 
 def status(message):
+    """Constructs a status message to be sent to systemd."""
     return b"STATUS=%s" % message.encode('utf8')