ship some documentation
authorHelmut Grohne <helmut@subdivi.de>
Mon, 17 Jun 2013 21:10:29 +0000 (23:10 +0200)
committerHelmut Grohne <helmut@subdivi.de>
Mon, 17 Jun 2013 21:10:29 +0000 (23:10 +0200)
dbus_client.py
dbus_service.py
mpd_watcher.py
onoff/command.py
onoff/common.py
onoff/gobject.py
onoff/process.py

index 691d86b..d24f151 100755 (executable)
@@ -1,4 +1,10 @@
 #!/usr/bin/env python
+"""
+A simpe client for an onoff device. If no parameters are given, the device
+is activated for 10 seconds. When a command is given, the device is activated,
+then the command is run. 10 seconds after the command finishes, the device is
+released.
+"""
 
 import os
 import sys
index 89acc3a..d7b5231 100755 (executable)
@@ -1,4 +1,9 @@
 #!/usr/bin/env python
+"""
+A dbus service example currently providing a device called redshift, that runs
+redshift whenever it is not activated. This could be useful to temporarily
+disable redshift e.g. while watching a movie.
+"""
 
 import logging
 import socket
index 9d8f25c..490312a 100755 (executable)
@@ -1,4 +1,8 @@
 #!/usr/bin/python
+"""
+A client to a device given on the commnd line, that is activated whenever the
+local mpd plays music.
+"""
 
 import os
 import sys
index f6b6c9b..87b9b26 100644 (file)
@@ -6,7 +6,28 @@ from .gobject import spawn_child
 logger = logging.getLogger("onoff.command")
 
 class OnoffCommand(OnoffDevice):
+    """A device that is enabled and disabled by executing separate commands.
+    The transition period is the duration of the commands.
+    @type pid: int or None
+    @ivar pid: is either None or the pid of a transition command as long as
+            it lives.
+    @ivar watch: is either None or a GObject event source id of the
+            callback waiting for the termination of the spawned process.
+    @type desired_state: bool
+    @ivar desired_state: is the state that should be transitioned to
+    @type target_state: bool
+    @ivar target_state: is the state that we are currently transitioning to
+    """
     def __init__(self, oncommand, offcommand):
+        """
+
+        @type oncommand: [str]
+        @param command: an argument vector to be executed for activation.
+        @type offcommand: [str]
+        @param command: an argument vector to be executed for deactivation.
+        @note: For both commands the first element is used as executable and
+                looked up in $PATH.
+        """
         OnoffDevice.__init__(self)
         self.oncommand = oncommand
         self.offcommand = offcommand
index 0120e8f..8db16a7 100644 (file)
@@ -10,7 +10,10 @@ ST_ACTIVE = 1
 ST_TRANSITION = 2
 
 class OnoffDevice(object):
-    """
+    """A device is a thing with two states, that can be asked to transition
+    from either state to the other. It can signal state changes to interested
+    parties.
+
     @type notify: {int -> None}
     @ivar notify: A set of functions taking a changed state.
 
@@ -39,6 +42,7 @@ class OnoffDevice(object):
         pass
 
 class InvertedDevice(OnoffDevice):
+    """A device that swaps active and inactive states of a give device."""
     def __init__(self, device):
         OnoffDevice.__init__(self)
         self.device = device
index ea98019..8c52221 100644 (file)
@@ -1,7 +1,9 @@
 from gi.repository import GObject
 
 def spawn_child(command, callback):
-    """
+    """Spawn a child process with GObject and attach a callback to the
+    termination of the spawned process.
+
     @type command: [str]
     @param command: an argument vector. First element is used as argv[0] and
             used as executable to look up in $PATH.
index d888842..68deb97 100644 (file)
@@ -10,7 +10,31 @@ from .gobject import spawn_child
 logger = logging.getLogger("onoff.process")
 
 class OnoffProcess(OnoffDevice):
+    """A device that in activated by starting a process and deactivated by
+    killing the process.
+
+    @type pid: int or None
+    @ivar pid: is either None if there is no process or the pid of the
+            spawned process
+    @ivar starting: is either None or a GObject event source id of the
+            callback sigalling the end of the activation transition.
+    @ivar watch: is either None or a GObject event source id of the
+            callback waiting for the termination of the spawned process.
+    @type killed: bool
+    @ivar killed: indicates whether the termination signal has been sent
+            to the spawned process.
+    """
     def __init__(self, command, start_wait=0, termsig=signal.SIGTERM):
+        """
+        @type command: [str]
+        @param command: an argument vector to be executed. The first element
+                is used as executable and looked up in $PATH.
+        @param start_wait: duration of the transition period from inactive to
+                active in seconds.
+        @param termsig: termination signal to be sent to the process to
+                deactivate it. The process must exit in response to this
+                signal.
+        """
         OnoffDevice.__init__(self)
         self.command = command
         self.start_wait = start_wait