doc

docker/controller.py

@@ -88,6 +88,13 @@ def docker_warning(msg, *k, ignore=None):
 
 @contextlib.contextmanager
 def report_error(fmt, *k):
+    """Context manager for logging exceptions
+
+    This function logs exceptions (when leaving the context) with log.error()
+    (if the exception inherit from Error) or log.exception() otherwise.
+
+    The log message is prepended with the string generated by: fmt % k
+    """
     try:
         yield
     except Exception as e:
@@ -775,7 +782,14 @@ EOF
             log.debug("done    sandbox %d", webapp_id)
 
 class DockerWatcher:
-    def __init__(self, client):
+    """A class for monitoring docker events from an asyncio loop
+
+    Currently only the "die" events (container termination) are supported.
+
+    The watcher is run in a separate thread (calling docker.Client.events())
+    """
+
+    def __init__(self, client: docker.Client):
         self._client = client
 
         # {container_id: future}
@@ -814,6 +828,11 @@ class DockerWatcher:
                 fut.set_result(None)
 
     def shutdown(self):
+        """Shutdown the watcher
+
+        -> all pending .wait() are inturrepted with ShuttingDown
+        -> all future .wait() calls will immediately raise ShuttingDown
+        """
         if not self._shutdown:
             self._shutdown = True
             for fut in self._futures.values():
@@ -823,7 +842,13 @@ class DockerWatcher:
 
     @asyncio.coroutine
     def wait(self, container_id):
-        log.debug("container id %s", container_id)
+        """Wait for the termination of a container
+
+        Notes:
+         - `container_id` *must* be the full container id (64 digits)
+         - the class support only one concurrent waiter for each container id
+
+        """
         assert re.match(r"[0-9a-f]{64}\Z", container_id), "bad container id"
 
         if container_id in self._futures: