Address hacking check H405

Previously, there were a string of commits to keystone that addresed ignored
hacking checks. This commit does the same for H405 in keystoneauth. This
also modifies our tox.ini so that we no longer ignore H405 violations.

Change-Id: I0ac1165f309edd486639e2729c18330b1d062eb3
Closes-Bug: 1482773

keystoneauth1/access/access.py

@@ -96,7 +96,7 @@ class AccessInfo(object):
         return norm_expires < soon
 
     def has_service_catalog(self):
-        """Returns true if the authorization token has a service catalog.
+        """Returns true if the auth token has a service catalog.
 
         :returns: boolean
         """
@@ -104,8 +104,9 @@ class AccessInfo(object):
 
     @property
     def auth_token(self):
-        """Returns the token_id associated with the auth request, to be used
+        """Returns the token_id associated with the auth request.
-        in headers for authenticating OpenStack API requests.
+
+        To be used in headers for authenticating OpenStack API requests.
 
         :returns: str
         """
@@ -129,7 +130,8 @@ class AccessInfo(object):
 
     @property
     def username(self):
-        """Returns the username associated with the authentication request.
+        """Returns the username associated with the auth request.
+
         Follows the pattern defined in the V2 API of first looking for 'name',
         returning that if available, and falling back to 'username' if name
         is unavailable.
@@ -140,7 +142,7 @@ class AccessInfo(object):
 
     @property
     def user_id(self):
-        """Returns the user id associated with the authentication request.
+        """Returns the user id associated with the auth request.
 
         :returns: str
         """
@@ -148,8 +150,7 @@ class AccessInfo(object):
 
     @property
     def user_domain_id(self):
-        """Returns the domain id of the user associated with the authentication
+        """Returns the user's domain id associated with the auth request.
-        request.
 
         :returns: str
         """
@@ -157,8 +158,7 @@ class AccessInfo(object):
 
     @property
     def user_domain_name(self):
-        """Returns the domain name of the user associated with the
+        """Returns the user's  domain name associated with the auth request.
-        authentication request.
 
         :returns: str
         """
@@ -166,8 +166,7 @@ class AccessInfo(object):
 
     @property
     def role_ids(self):
-        """Returns a list of role ids of the user associated with the
+        """Returns a list of user's role ids associated with the auth request.
-        authentication request.
 
         :returns: a list of strings of role ids
         """
@@ -175,8 +174,7 @@ class AccessInfo(object):
 
     @property
     def role_names(self):
-        """Returns a list of role names of the user associated with the
+        """Returns a list of user's role names associated with the auth request.
-        authentication request.
 
         :returns: a list of strings of role names
         """
@@ -184,7 +182,7 @@ class AccessInfo(object):
 
     @property
     def domain_name(self):
-        """Returns the domain name associated with the authentication token.
+        """Returns the domain name associated with the auth request.
 
         :returns: str or None (if no domain associated with the token)
         """
@@ -192,7 +190,7 @@ class AccessInfo(object):
 
     @property
     def domain_id(self):
-        """Returns the domain id associated with the authentication token.
+        """Returns the domain id associated with the auth request.
 
         :returns: str or None (if no domain associated with the token)
         """
@@ -200,7 +198,7 @@ class AccessInfo(object):
 
     @property
     def project_name(self):
-        """Returns the project name associated with the authentication request.
+        """Returns the project name associated with the auth request.
 
         :returns: str or None (if no project associated with the token)
         """
@@ -213,10 +211,12 @@ class AccessInfo(object):
 
     @property
     def scoped(self):
-        """Returns true if the authorization token was scoped to a tenant
+        """Returns true if the auth token was scoped.
-           (project), and contains a populated service catalog.
 
-           This is deprecated, use project_scoped instead.
+        Returns true if scoped to a tenant(project) or domain,
+        and contains a populated service catalog.
+
+        This is deprecated, use project_scoped instead.
 
         :returns: bool
         """
@@ -224,8 +224,7 @@ class AccessInfo(object):
 
     @property
     def project_scoped(self):
-        """Returns true if the authorization token was scoped to a tenant
+        """Returns true if the auth token was scoped to a tenant(project).
-           (project).
 
         :returns: bool
         """
@@ -233,7 +232,7 @@ class AccessInfo(object):
 
     @property
     def domain_scoped(self):
-        """Returns true if the authorization token was scoped to a domain.
+        """Returns true if the auth token was scoped to a domain.
 
         :returns: bool
         """
@@ -241,7 +240,7 @@ class AccessInfo(object):
 
     @property
     def trust_id(self):
-        """Returns the trust id associated with the authentication token.
+        """Returns the trust id associated with the auth request.
 
         :returns: str or None (if no trust associated with the token)
         """
@@ -249,8 +248,9 @@ class AccessInfo(object):
 
     @property
     def trust_scoped(self):
-        """Returns true if the authorization token was scoped as delegated in a
+        """Returns true if the auth token was scoped from a delegated trust.
-        trust, via the OS-TRUST v3 extension.
+
+        The trust delegation is via the OS-TRUST v3 extension.
 
         :returns: bool
         """
@@ -274,9 +274,9 @@ class AccessInfo(object):
 
     @property
     def project_id(self):
-        """Returns the project ID associated with the authentication
+        """Returns the project ID associated with the auth request.
-        request, or None if the authentication request wasn't scoped to a
+
-        project.
+        This returns None if the auth token wasn't scoped to a project.
 
         :returns: str or None (if no project associated with the token)
         """
@@ -289,8 +289,7 @@ class AccessInfo(object):
 
     @property
     def project_domain_id(self):
-        """Returns the domain id of the project associated with the
+        """Returns the project's domain id associated with the auth request.
-        authentication request.
 
         :returns: str
         """
@@ -298,8 +297,7 @@ class AccessInfo(object):
 
     @property
     def project_domain_name(self):
-        """Returns the domain name of the project associated with the
+        """Returns the project's domain name associated with the auth request.
-        authentication request.
 
         :returns: str
         """
@@ -387,9 +385,7 @@ class AccessInfo(object):
 
 
 class AccessInfoV2(AccessInfo):
-    """An object for encapsulating a raw v2 auth token from identity
+    """An object for encapsulating raw v2 auth token from identity service."""
-       service.
-    """
 
     version = 'v2.0'
     _service_catalog_class = service_catalog.ServiceCatalogV2
@@ -566,9 +562,7 @@ class AccessInfoV2(AccessInfo):
 
 
 class AccessInfoV3(AccessInfo):
-    """An object for encapsulating a raw v3 auth token from identity
+    """An object encapsulating raw v3 auth token from identity service."""
-       service.
-    """
 
     version = 'v3'
     _service_catalog_class = service_catalog.ServiceCatalogV3

keystoneauth1/access/service_catalog.py

@@ -229,8 +229,9 @@ class ServiceCatalog(object):
 
 
 class ServiceCatalogV2(ServiceCatalog):
-    """An object for encapsulating the service catalog using raw v2 auth token
+    """An object for encapsulating the v2 service catalog.
-    from Keystone.
+
+    The object is created using raw v2 auth token from Keystone.
     """
 
     @classmethod
@@ -267,8 +268,9 @@ class ServiceCatalogV2(ServiceCatalog):
 
 
 class ServiceCatalogV3(ServiceCatalog):
-    """An object for encapsulating the service catalog using raw v3 auth token
+    """An object for encapsulating the v3 service catalog.
-    from Keystone.
+
+    The object is created using raw v3 auth token from Keystone.
     """
 
     @classmethod

keystoneauth1/discover.py

@@ -102,8 +102,7 @@ def normalize_version_number(version):
 
 
 def version_match(required, candidate):
-    """Test that an available version is a suitable match for a required
+    """Test that an available version satisfies the required version.
-    version.
 
     To be suitable a version must be of the same major version as required
     and be at least a match in minor/patch level.

keystoneauth1/exceptions/auth_plugins.py

@@ -30,8 +30,7 @@ class MissingAuthPlugin(AuthPluginException):
 
 
 class NoMatchingPlugin(AuthPluginException):
-    """There were no auth plugins that could be created from the parameters
+    """No auth plugins could be created from the parameters provided.
-    provided.
 
     :param str name: The name of the plugin that was attempted to load.
 

keystoneauth1/exceptions/http.py

@@ -63,8 +63,7 @@ __all__ = ('HttpError',
 
 
 class HttpError(base.ClientException):
-    """The base exception class for all HTTP exceptions.
+    """The base exception class for all HTTP exceptions."""
-    """
     http_status = 0
     message = "HTTP Error"
 

keystoneauth1/identity/v3/base.py

@@ -223,8 +223,10 @@ class AuthMethod(object):
 
 @six.add_metaclass(abc.ABCMeta)
 class AuthConstructor(Auth):
-    """AuthConstructor is a means of creating an Auth Plugin that contains
+    """Abstract base class for creating an Auth Plugin.
-    only one authentication method. This is generally the required usage.
+
+    The Auth Plugin created contains only one authentication method. This
+    is generally the required usage.
 
     An AuthConstructor creates an AuthMethod based on the method's
     arguments and the auth_method_class defined by the plugin. It then

keystoneauth1/identity/v3/oidc.py

@@ -137,6 +137,7 @@ class OidcPassword(_OidcBase):
                  grant_type='password', access_token_type='access_token',
                  username=None, password=None, scope='profile'):
         """The OpenID Password plugin expects the following:
+
         :param username: Username used to authenticate
         :type username: string
 
@@ -209,6 +210,7 @@ class OidcAuthorizationCode(_OidcBase):
                  access_token_type='access_token',
                  redirect_uri=None, code=None):
         """The OpenID Authorization Code plugin expects the following:
+
         :param redirect_uri: OpenID Connect Client Redirect URL
         :type redirect_uri: string
 

keystoneauth1/loading/session.py

@@ -125,8 +125,7 @@ class Session(base.BaseLoader):
         return self.load_from_options(**kwargs)
 
     def get_conf_options(self, deprecated_opts=None):
-        """Get the oslo_config options that are needed for a
+        """Get oslo_config options that are needed for a :py:class:`.Session`.
-        :py:class:`.Session`.
 
         These may be useful without being registered for config file generation
         or to manipulate the options before registering them yourself.

keystoneauth1/tests/unit/keystoneauth_fixtures.py

@@ -15,8 +15,9 @@ import fixtures
 
 
 class HackingCode(fixtures.Fixture):
-    """A fixture to house the various code examples for the keystoneclient
+    """A fixture to house the various code examples.
-    hacking style checks.
+
+    Examples contains various keystoneauth hacking style checks.
     """
 
     oslo_namespace_imports = {

keystoneauth1/tests/unit/utils.py

@@ -113,8 +113,9 @@ class TestCase(testtools.TestCase):
 
 
 class TestResponse(requests.Response):
-    """Class used to wrap requests.Response and provide some
+    """Class used to wrap requests.Response.
-       convenience to initialize with a dict.
+
+    This provides some convenience to initialize with a dict.
     """
 
     def __init__(self, data):

tox.ini

@@ -32,8 +32,12 @@ downloadcache = ~/cache/pip
 commands = oslo_debug_helper -t keystoneauth1/tests {posargs}
 
 [flake8]
-# H405: multi line docstring summary not separated with an empty line
+# NOTE(lhcheng): Even though we aren't ignoring any hacking checks, we have
-ignore = H405
+# to leave it assigned in the environment specification otherwise some error
+# checks will be ignored by default. If we need to ignore a specific hacking
+# check in the future, we will have to remove '___' from the ignore line.
+# See: http://flake8.readthedocs.org/en/latest/config.html#default
+ignore = ___
 show-source = True
 exclude = .venv,.tox,dist,doc,*egg,build,*openstack/common*