Add docs to Node Manager's base compute node driver.

This adds a docstring or comment description to every method in the class.

diff --git a/services/nodemanager/arvnodeman/computenode/driver/__init__.py b/services/nodemanager/arvnodeman/computenode/driver/__init__.py
index b703e0d14456706fbadcb71e74f51a8d5aa7688d..042f6a57cd95eff95e9c931ec96680d57d978488 100644 (file)
--- a/services/nodemanager/arvnodeman/computenode/driver/__init__.py
+++ b/services/nodemanager/arvnodeman/computenode/driver/__init__.py
@@ -2,6 +2,8 @@
 
 from __future__ import absolute_import, print_function
 
+from operator import attrgetter
+
 import libcloud.common.types as cloud_types
 from libcloud.compute.base import NodeDriver
 
@@ -10,22 +12,40 @@ from ...config import NETWORK_ERRORS
 class BaseComputeNodeDriver(object):
     """Abstract base class for compute node drivers.
 
-    libcloud abstracts away many of the differences between cloud providers,
-    but managing compute nodes requires some cloud-specific features (e.g.,
-    on EC2 we use tags to identify compute nodes).  Compute node drivers
-    are responsible for translating the node manager's cloud requests to a
-    specific cloud's vocabulary.
+    libcloud drivers abstract away many of the differences between
+    cloud providers, but managing compute nodes requires some
+    cloud-specific features (e.g., keeping track of node FQDNs and
+    boot times).  Compute node drivers are responsible for translating
+    the node manager's cloud requests to a specific cloud's
+    vocabulary.
 
-    Subclasses must implement arvados_create_kwargs (to update node
-    creation kwargs with information about the specific Arvados node
-    record), sync_node, and node_start_time.
+    Subclasses must implement arvados_create_kwargs, sync_node,
+    node_fqdn, and node_start_time.
     """
     CLOUD_ERRORS = NETWORK_ERRORS + (cloud_types.LibcloudError,)
 
     def __init__(self, auth_kwargs, list_kwargs, create_kwargs, driver_class):
+        """Base initializer for compute node drivers.
+
+        Arguments:
+        * auth_kwargs: A dictionary of arguments that are passed into the
+          driver_class constructor to instantiate a libcloud driver.
+        * list_kwargs: A dictionary of arguments that are passed to the
+          libcloud driver's list_nodes method to return the list of compute
+          nodes.
+        * create_kwargs: A dictionary of arguments that are passed to the
+          libcloud driver's create_node method to create a new compute node.
+        * driver_class: The class of a libcloud driver to use.
+        """
         self.real = driver_class(**auth_kwargs)
         self.list_kwargs = list_kwargs
         self.create_kwargs = create_kwargs
+        # Transform entries in create_kwargs.  For each key K, if this class
+        # has an _init_K method, remove the entry and call _init_K with the
+        # corresponding value.  If _init_K returns None, the entry stays out
+        # of the dictionary (we expect we're holding the value somewhere
+        # else, like an instance variable).  Otherwise, _init_K returns a
+        # key-value tuple pair, and we add that entry to create_kwargs.
         for key in self.create_kwargs.keys():
             init_method = getattr(self, '_init_' + key, None)
             if init_method is not None:
@@ -36,7 +56,19 @@ class BaseComputeNodeDriver(object):
     def _init_ping_host(self, ping_host):
         self.ping_host = ping_host
 
-    def search_for(self, term, list_method, key=lambda item: item.id):
+    def search_for(self, term, list_method, key=attrgetter('id')):
+        """Return one matching item from a list of cloud objects.
+
+        Raises ValueError if the number of matching objects is not exactly 1.
+
+        Arguments:
+        * term: The value that identifies a matching item.
+        * list_method: A string that names the method to call on this
+          instance's libcloud driver for a list of objects.
+        * key: A function that accepts a cloud object and returns a
+          value search for a `term` match on each item.  Returns the
+          object's 'id' attribute by default.
+        """
         cache_key = (list_method, term)
         if cache_key not in self.SEARCH_CACHE:
             results = [item for item in getattr(self.real, list_method)()
@@ -52,6 +84,17 @@ class BaseComputeNodeDriver(object):
         return self.real.list_nodes(**self.list_kwargs)
 
     def arvados_create_kwargs(self, arvados_node):
+        """Return dynamic keyword arguments for create_node.
+
+        Subclasses must override this method.  It should return a dictionary
+        of keyword arguments to pass to the libcloud driver's create_node
+        method.  These arguments will extend the static arguments in
+        create_kwargs.
+
+        Arguments:
+        * arvados_node: The Arvados node record that will be associated
+          with this cloud node, as returned from the API server.
+        """
         raise NotImplementedError("BaseComputeNodeDriver.arvados_create_kwargs")
 
     def _make_ping_url(self, arvados_node):
@@ -86,6 +129,8 @@ class BaseComputeNodeDriver(object):
 
     @classmethod
     def node_start_time(cls, node):
+        # This method should return the time the node was started, in
+        # seconds since the epoch UTC.
         raise NotImplementedError("BaseComputeNodeDriver.node_start_time")
 
     @classmethod
@@ -94,7 +139,7 @@ class BaseComputeNodeDriver(object):
         # represent API errors.  Return True for any exception that is
         # exactly an Exception, or a better-known higher-level exception.
         return (isinstance(exception, cls.CLOUD_ERRORS) or
-                getattr(exception, '__class__', None) is Exception)
+                type(exception) is Exception)
 
     # Now that we've defined all our own methods, delegate generic, public
     # attributes of libcloud drivers that we haven't defined ourselves.