Update contrib docstrings to match guidelines

Per http://docs.openstack.org/developer/hacking/
and http://www.python.org/dev/peps/pep-0257/

Without extra blank line in multi-line docstrings
based on http://lists.openstack.org/pipermail/openstack-dev/2014-February/028156.html

Blueprint: reduce-flake8-ignored-rules

Change-Id: I0050d382369d3013280f3d90df87fb530bc6c939

contrib/heat_keystoneclient_v2/heat_keystoneclient_v2/client.py

@@ -13,6 +13,8 @@
 #    License for the specific language governing permissions and limitations
 #    under the License.
 
+"""Client Library for Keystone Resources."""
+
 from keystoneclient.v2_0 import client as kc
 from oslo.config import cfg
 
@@ -26,13 +28,14 @@ logger.info(_("Keystone V2 loaded"))
 
 
 class KeystoneClientV2(object):
-    """
+
-    Wrap keystone client so we can encapsulate logic used in resources
+    """Wrap keystone client so we can encapsulate logic used in resources.
+
     Note this is intended to be initialized from a resource on a per-session
     basis, so the session context is passed in on initialization
     Also note that a copy of this is created every resource as self.keystone()
     via the code in engine/client.py, so there should not be any need to
-    directly instantiate instances of this class inside resources themselves
+    directly instantiate instances of this class inside resources themselves.
     """
     def __init__(self, context):
         # If a trust_id is specified in the context, we immediately

contrib/marconi/marconi/clients.py

@@ -11,6 +11,8 @@
 #    License for the specific language governing permissions and limitations
 #    under the License.
 
+"""Client Library for Marconi Resources."""
+
 from heat.engine import clients
 from heat.openstack.common import log as logging
 
@@ -24,9 +26,9 @@ except ImportError:
 
 
 class Clients(clients.OpenStackClients):
-    '''
+
-    Convenience class to create and cache client instances.
+    """Convenience class to create and cache client instances."""
-    '''
+
     def __init__(self, context):
         super(Clients, self).__init__(context)
         self._marconi = None

contrib/marconi/marconi/resources/queue.py

@@ -70,9 +70,7 @@ class MarconiQueue(resource.Resource):
         return self.properties[self.NAME]
 
     def handle_create(self):
-        '''
+        """Create a marconi message queue."""
-        Create a marconi message queue.
-        '''
         queue_name = self.physical_resource_name()
         queue = self.marconi().queue(queue_name, auto_create=False)
         # Marconi client doesn't report an error if an queue with the same
@@ -85,7 +83,7 @@ class MarconiQueue(resource.Resource):
         return queue
 
     def check_create_complete(self, queue):
-        # set metadata of the newly created queue
+        """Set metadata of the newly created queue."""
         if queue.exists():
             metadata = self.properties.get('metadata')
             if metadata:
@@ -97,18 +95,14 @@ class MarconiQueue(resource.Resource):
                               % queue_name)
 
     def handle_update(self, json_snippet, tmpl_diff, prop_diff):
-        '''
+        """Update queue metadata."""
-        Update queue metadata.
-        '''
         if 'metadata' in prop_diff:
             queue = self.marconi().queue(self.resource_id, auto_create=False)
             metadata = prop_diff['metadata']
             queue.metadata(new_meta=metadata)
 
     def handle_delete(self):
-        '''
+        """Delete a marconi message queue."""
-        Delete a marconi message queue.
-        '''
         if not self.resource_id:
             return
 

contrib/rackspace/rackspace/clients.py

@@ -12,6 +12,8 @@
 #    License for the specific language governing permissions and limitations
 #    under the License.
 
+"""Client Libraries for Rackspace Resources."""
+
 from oslo.config import cfg
 
 from heat.common import exception
@@ -46,9 +48,9 @@ cfg.CONF.register_opts(cloud_opts)
 
 
 class Clients(clients.OpenStackClients):
-    '''
+
-    Convenience class to create and cache client instances.
+    """Convenience class to create and cache client instances."""
-    '''
+
     def __init__(self, context):
         super(Clients, self).__init__(context)
         self.pyrax = None
@@ -63,32 +65,34 @@ class Clients(clients.OpenStackClients):
         return self._get_client("autoscale")
 
     def cloud_db(self):
-        '''Rackspace cloud database client.'''
+        """Rackspace cloud database client."""
         return self._get_client("database")
 
     def cloud_lb(self):
-        '''Rackspace cloud loadbalancer client.'''
+        """Rackspace cloud loadbalancer client."""
         return self._get_client("load_balancer")
 
     def cloud_dns(self):
-        '''Rackspace cloud dns client.'''
+        """Rackspace cloud dns client."""
         return self._get_client("dns")
 
     def nova(self, service_type="compute"):
-        '''Rackspace cloudservers client. Specifying the service type is to
+        """Rackspace cloudservers client.
+
+        Specifying the service type is to
         maintain compatibility with clients.OpenStackClients. It is not
         actually a valid option to change within pyrax.
-        '''
+        """
         if service_type is not "compute":
             raise ValueError(_("service_type should be compute."))
         return self._get_client(service_type)
 
     def cloud_networks(self):
-        '''Rackspace cloud networks client.'''
+        """Rackspace cloud networks client."""
         return self._get_client("network")
 
     def trove(self):
-        '''Rackspace trove client.'''
+        """Rackspace trove client."""
         if not self._trove:
             super(Clients, self).trove(service_type='rax:database')
             management_url = self.url_for(service_type='rax:database',

contrib/rackspace/rackspace/resources/auto_scale.py

@@ -11,9 +11,7 @@
 #    License for the specific language governing permissions and limitations
 #    under the License.
 
-"""
+"""Resources for Rackspace Auto Scale."""
-Resources for Rackspace Auto Scale.
-"""
 
 import copy
 
@@ -38,6 +36,7 @@ except ImportError:
 
 
 class Group(resource.Resource):
+
     """Represents a scaling group."""
 
     # pyrax differs drastically from the actual Auto Scale API. We'll prefer
@@ -302,18 +301,16 @@ class Group(resource.Resource):
         return args
 
     def handle_create(self):
-        """
+        """Create the autoscaling group and set resource_id.
-        Create the autoscaling group and set the resulting group's ID as the
+
-        resource_id.
+        The resource_id is set to the resulting group's ID.
         """
         asclient = self.stack.clients.auto_scale()
         group = asclient.create(**self._get_create_args())
         self.resource_id_set(str(group.id))
 
     def handle_update(self, json_snippet, tmpl_diff, prop_diff):
-        """
+        """Update the group configuration and the launch configuration."""
-        Update the group configuration and the launch configuration.
-        """
         asclient = self.stack.clients.auto_scale()
         if self.GROUP_CONFIGURATION in prop_diff:
             args = self._get_group_config_args(
@@ -325,8 +322,7 @@ class Group(resource.Resource):
             asclient.replace_launch_config(self.resource_id, **args)
 
     def handle_delete(self):
-        """
+        """Delete the scaling group.
-        Delete the scaling group.
 
         Since Auto Scale doesn't allow deleting a group until all its servers
         are gone, we must set the minEntities and maxEntities of the group to 0
@@ -360,6 +356,7 @@ class Group(resource.Resource):
 
 
 class ScalingPolicy(resource.Resource):
+
     """Represents a Rackspace Auto Scale scaling policy."""
 
     PROPERTIES = (
@@ -444,9 +441,9 @@ class ScalingPolicy(resource.Resource):
         return args
 
     def handle_create(self):
-        """
+        """Create the scaling policy and initialize the resource ID.
-        Create the scaling policy, and initialize the resource ID to
+
-        {group_id}:{policy_id}.
+        The resource ID is initialized to {group_id}:{policy_id}.
         """
         asclient = self.stack.clients.auto_scale()
         args = self._get_args(self.properties)
@@ -476,11 +473,12 @@ class ScalingPolicy(resource.Resource):
 
 
 class WebHook(resource.Resource):
-    """
+
-    Represents a Rackspace AutoScale webhook.
+    """Represents a Rackspace AutoScale webhook.
 
     Exposes the URLs of the webhook as attributes.
     """
+
     PROPERTIES = (
         POLICY, NAME, METADATA,
     ) = (

contrib/rackspace/rackspace/resources/cloud_dns.py

@@ -10,6 +10,8 @@
 #    License for the specific language governing permissions and limitations
 #    under the License.
 
+"""Resources for Rackspace DNS."""
+
 from heat.common import exception
 from heat.engine import constraints
 from heat.engine import properties
@@ -32,6 +34,8 @@ logger = logging.getLogger(__name__)
 
 class CloudDns(resource.Resource):
 
+    """Represents a DNS resource."""
+
     PROPERTIES = (
         NAME, EMAIL_ADDRESS, TTL, COMMENT, RECORDS,
     ) = (
@@ -147,9 +151,7 @@ class CloudDns(resource.Resource):
         return self.stack.clients.cloud_dns()
 
     def handle_create(self):
-        """
+        """Create a Rackspace CloudDns Instance."""
-        Create a Rackspace CloudDns Instance.
-        """
         # There is no check_create_complete as the pyrax create for DNS is
         # synchronous.
         logger.debug(_("CloudDns handle_create called."))
@@ -163,9 +165,7 @@ class CloudDns(resource.Resource):
         self.resource_id_set(dom.id)
 
     def handle_update(self, json_snippet, tmpl_diff, prop_diff):
-        """
+        """Update a Rackspace CloudDns Instance."""
-        Update a Rackspace CloudDns Instance.
-        """
         logger.debug(_("CloudDns handle_update called."))
         if not self.resource_id:
             raise exception.Error(_('Update called on a non-existent domain'))
@@ -188,9 +188,7 @@ class CloudDns(resource.Resource):
             dom.add_records(records)
 
     def handle_delete(self):
-        """
+        """Delete a Rackspace CloudDns Instance."""
-        Delete a Rackspace CloudDns Instance.
-        """
         logger.debug(_("CloudDns handle_delete called."))
         if self.resource_id:
             try:

contrib/rackspace/rackspace/resources/cloud_loadbalancer.py

@@ -10,6 +10,9 @@
 #    WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
 #    License for the specific language governing permissions and limitations
 #    under the License.
+
+"""Resources for Rackspace Cloud Loadbalancers."""
+
 try:
     from pyrax.exceptions import NotFound
     PYRAX_INSTALLED = True
@@ -41,6 +44,8 @@ class LoadbalancerBuildError(exception.HeatException):
 
 class CloudLoadBalancer(resource.Resource):
 
+    """Represents a Rackspace Cloud Loadbalancer."""
+
     PROPERTIES = (
         NAME, NODES, PROTOCOL, ACCESS_LIST, HALF_CLOSED, ALGORITHM,
         CONNECTION_LOGGING, METADATA, PORT, TIMEOUT,
@@ -378,7 +383,9 @@ class CloudLoadBalancer(resource.Resource):
             return [function()]
 
     def _alter_properties_for_api(self):
-        """The following properties have usless key/value pairs which must
+        """Set up required, but useless, key/value pairs.
+
+        The following properties have useless key/value pairs which must
         be passed into the api. Set them up to make template definition easier.
         """
         session_persistence = None
@@ -405,8 +412,9 @@ class CloudLoadBalancer(resource.Resource):
             return False
 
     def _configure_post_creation(self, loadbalancer):
-        """Configure all load balancer properties that must be done post
+        """Configure all load balancer properties post creation.
-        creation.
+
+        These properties can only be set after the load balancer is created.
         """
         if self.properties[self.ACCESS_LIST]:
             while not self._check_status(loadbalancer, ['ACTIVE']):
@@ -492,9 +500,7 @@ class CloudLoadBalancer(resource.Resource):
         return self._check_status(loadbalancer, ['ACTIVE'])
 
     def handle_update(self, json_snippet, tmpl_diff, prop_diff):
-        """
+        """Add and remove nodes specified in the prop_diff."""
-        Add and remove nodes specified in the prop_diff.
-        """
         loadbalancer = self.clb.get(self.resource_id)
         if self.NODES in prop_diff:
             current_nodes = loadbalancer.nodes
@@ -556,18 +562,16 @@ class CloudLoadBalancer(resource.Resource):
                 self.resource_id_set(None)
 
     def _remove_none(self, property_dict):
-        '''
+        """Remove None values that would cause schema validation problems.
-        Remove values that may be initialized to None and would cause problems
+
-        during schema validation.
+        These are values that may be initialized to None.
-        '''
+        """
         return dict((key, value)
                     for (key, value) in property_dict.iteritems()
                     if value)
 
     def validate(self):
-        """
+        """Validate any of the provided params."""
-        Validate any of the provided params
-        """
         res = super(CloudLoadBalancer, self).validate()
         if res:
             return res