Add dependency: flake8-docstrings

flake8-docstrings is "a simple module that adds an extension for the fantastic
pep257 tool to flake8." It helps ensure that docstrings comply with PEP 257.
See:

* https://gitlab.com/pycqa/flake8-docstrings
* http://pep257.readthedocs.org/en/latest/

The flake8-pep257 plug-in was also considered, but Robpol86/flake8-pydocstyle#4 was
encountered. In addition, flake8-docstrings appears to be compatible with a
greater variety of Python versions.

Targets #22.

pulp_smash/config.py

@@ -106,11 +106,12 @@ class ServerConfig(object):
         the server?
 
     """
+
     # Used to lock access to the configuration file when performing destructive
     # operations, such as saving.
     _file_lock = Lock()
 
-    def __init__(self, base_url=None, auth=None, verify=None):
+    def __init__(self, base_url=None, auth=None, verify=None):  # noqa
         self.base_url = base_url
         self.auth = auth
         self.verify = verify
@@ -122,7 +123,7 @@ def __init__(self, base_url=None, auth=None, verify=None):
         )
         self._xdg_config_dir = 'pulp_smash'
 
-    def __repr__(self):
+    def __repr__(self):  # noqa
         attrs = {attr: getattr(self, attr) for attr in _PUBLIC_ATTRS}
         return '{}({})'.format(
             type(self).__name__,

pulp_smash/tests/platform/api_v2/test_content_applicability.py

@@ -50,10 +50,7 @@ def test_body(self):
 
 
 class FailureTestCase(TestCase):
-    """Unsuccessfully generate content applicability for consumers and
-    repos.
-
-    """
+    """Fail to generate content applicability for consumers and repos."""
 
     @classmethod
     def setUpClass(cls):

pulp_smash/tests/platform/api_v2/test_login.py

@@ -12,8 +12,15 @@
 from unittest2 import TestCase
 
 
-LOGIN_KEYS = {'certificate', 'key'}
 LOGIN_PATH = '/pulp/api/v2/actions/login/'
+
+#: Upon successfully logging in, the response should contain these keys.
+LOGIN_KEYS = {'certificate', 'key'}
+
+#: Responses with a non-200 status code should contain these keys.
+#:
+#: See:
+#: https://pulp.readthedocs.org/en/latest/dev-guide/conventions/exceptions.html
 ERROR_KEYS = {
     '_href',
     'error',
@@ -42,8 +49,9 @@ def test_status_code(self):
         self.assertEqual(self.response.status_code, 200)
 
     def test_body(self):
-        """Assert that the response is valid JSON and has "key" and
-        "certificate" keys.
+        """Assert that the response is valid JSON and has correct keys.
+
+        The "correct keys" are defined in :data:`LOGIN_KEYS`.
 
         """
         self.assertEqual(set(self.response.json().keys()), LOGIN_KEYS)
@@ -67,8 +75,9 @@ def test_status_code(self):
         self.assertEqual(self.response.status_code, 401)
 
     def test_body(self):
-        """Assert that the response is valid JSON and does not have "key" and
-        "certificate" keys.
+        """Assert that the response is valid JSON and has correct keys.
+
+        The "correct keys" are defined in :data:`ERROR_KEYS`.
 
         """
         self.assertEqual(set(self.response.json().keys()), ERROR_KEYS)

pulp_smash/tests/platform/api_v2/test_user.py

@@ -37,7 +37,7 @@ def _search_logins(response):
 
 
 class CreateTestCase(TestCase):
-    """Can we create users? No prior assumptions are made."""
+    """Establish that we can create users. No prior assumptions are made."""
 
     @classmethod
     def setUpClass(cls):
@@ -98,7 +98,7 @@ def tearDownClass(cls):
 
 
 class ReadUpdateDeleteTestCase(TestCase):
-    """Can we read, update and delete users?
+    """Establish that we can read, update and delete users.
 
     This test case assumes that the assertions in :class:`CreateTestCase` are
     valid.
@@ -141,7 +141,7 @@ def setUpClass(cls):
         )
 
     def test_status_codes(self):
-        """Do the read, update and delete responses have 200 status codes?"""
+        """Ensure read, update and delete responses have 200 status codes."""
         for attr in ('read_response', 'update_response', 'delete_response'):
             with self.subTest(attr):
                 self.assertEqual(getattr(self, attr).status_code, 200)
@@ -212,7 +212,7 @@ def tearDownClass(cls):
 
 
 class SearchTestCase(TestCase):
-    """Can we search for users?
+    """Establish that we can search for users.
 
     This test case assumes that the assertions in
     :class:`ReadUpdateDeleteTestCase` are valid.

requirements-dev.txt

@@ -1,5 +1,6 @@
 # For `make lint`
 flake8
+flake8-docstrings
 flake8-quotes
 pylint