Fix raise section in docstrings

The correct format is:
    :raises Exception: conditions

This patch fix all docstrings across the project and
add hacking rule to check it.

Change-Id: I40cc20f8d555082e284c1683522932aaa68f575c
Closes-Bug: 1470901

rally/api.py

@@ -277,9 +277,9 @@ class Task(object):
         :param task_uuid: The UUID of the task.
         :param force: If set to True, then delete the task despite to the
                       status.
-        :raises: :class:`rally.exceptions.TaskInvalidStatus` when the
-                 status of the task is not FINISHED and the force argument
-                 if not True
+        :raises TaskInvalidStatus: when the status of the task is not
+                                   FINISHED and the force argument
+                                   is not True
         """
         status = None if force else consts.TaskStatus.FINISHED
         objects.Task.delete_by_uuid(task_uuid, status=status)

rally/common/db/api.py

@@ -84,7 +84,7 @@ def task_get(uuid):
     """Returns task by uuid.
 
     :param uuid: UUID of the task.
-    :raises: :class:`rally.exceptions.TaskNotFound` if the task does not exist.
+    :raises TaskNotFound: if the task does not exist.
     :returns: task dict with data on the task.
     """
     return get_impl().task_get(uuid)
@@ -94,7 +94,7 @@ def task_get_status(uuid):
     """Returns task by uuid.
 
     :param uuid: UUID of the task.
-    :raises: :class:`rally.exceptions.TaskNotFound` if the task does not exist.
+    :raises TaskNotFound: if the task does not exist.
     :returns: task dict with data on the task.
     """
     return get_impl().task_get_status(uuid)
@@ -128,7 +128,7 @@ def task_update(uuid, values):
 
     :param uuid: UUID of the task.
     :param values: dict with record values.
-    :raises: :class:`rally.exceptions.TaskNotFound` if the task does not exist.
+    :raises TaskNotFound: if the task does not exist.
     :returns: new updated task dict with data on the task.
     """
     return get_impl().task_update(uuid, values)
@@ -140,8 +140,7 @@ def task_update_status(task_uuid, status, allowed_statuses):
     :param task_uuid: string with UUID of Task instance.
     :param status: new value to wrote into db instead of status.
     :param allowed_statuses: list of expected statuses to update in db.
-    :raises: :class: 'rally.exceptions.RallyException' if task not
-             found with specified status.
+    :raises RallyException: if task not found with specified status.
     :returns: the count of rows match as returned by the database's
               "row count" feature
     """
@@ -170,9 +169,9 @@ def task_delete(uuid, status=None):
     statuses are equal otherwise an exception is raised.
 
     :param uuid: UUID of the task.
-    :raises: :class:`rally.exceptions.TaskNotFound` if the task does not exist.
-    :raises: :class:`rally.exceptions.TaskInvalidStatus` if the status
-             of the task does not equal to the status argument.
+    :raises TaskNotFound: if the task does not exist.
+    :raises TaskInvalidStatus: if the status of the task does not
+                               equal to the status argument.
     """
     return get_impl().task_delete(uuid, status=status)
 
@@ -210,10 +209,8 @@ def deployment_delete(uuid):
     """Delete a deployment by UUID.
 
     :param uuid: UUID of the deployment.
-    :raises: :class:`rally.exceptions.DeploymentNotFound` if the deployment
-             does not exist.
-    :raises: :class:`rally.exceptions.DeploymentIsBusy` if the resource is
-             not enough.
+    :raises DeploymentNotFound: if the deployment does not exist.
+    :raises DeploymentIsBusy: if the resource is not enough.
     """
     return get_impl().deployment_delete(uuid)
 
@@ -222,8 +219,7 @@ def deployment_get(deployment):
     """Get a deployment by UUID.
 
     :param deployment: UUID or name of the deployment.
-    :raises: :class:`rally.exceptions.DeploymentNotFound` if the deployment
-             does not exist.
+    :raises DeploymentNotFound: if the deployment does not exist.
     :returns: a dict with data on the deployment.
     """
     return get_impl().deployment_get(deployment)
@@ -234,8 +230,7 @@ def deployment_update(uuid, values):
 
     :param uuid: UUID of the deployment.
     :param values: dict with items to update.
-    :raises: :class:`rally.exceptions.DeploymentNotFound` if the deployment
-             does not exist.
+    :raises DeploymentNotFound: if the deployment does not exist.
     :returns: a dict with data on the deployment.
     """
     return get_impl().deployment_update(uuid, values)
@@ -281,8 +276,7 @@ def resource_delete(id):
     """Delete a resource.
 
     :param id: ID of a resource.
-    :raises: :class:`rally.exceptions.ResourceNotFound` if the resource
-             does not exist.
+    :raises ResourceNotFound: if the resource does not exist.
     """
     return get_impl().resource_delete(id)
 
@@ -300,8 +294,7 @@ def verification_get(verification_uuid):
     """Returns verification by UUID.
 
     :param id: UUID of the verification.
-    :raises: :class:`rally.exceptions.NotFoundException` if verification
-             does not exist.
+    :raises NotFoundException: if verification does not exist.
     :returns: a dict with verification data.
     """
     return get_impl().verification_get(verification_uuid)
@@ -311,8 +304,7 @@ def verification_delete(verification_uuid):
     """Delete verification.
 
     :param verification_uuid: UUID of the verification.
-    :raises: :class:`rally.exceptions.NotFoundException` if verification
-             does not exist.
+    :raises NotFoundException: if verification does not exist.
     """
     return get_impl().verification_delete(verification_uuid)
 
@@ -322,8 +314,7 @@ def verification_update(uuid, values):
 
     :param uuid: UUID of the verification.
     :param values: dict with record values.
-    :raises: :class:`rally.exceptions.NotFoundException` if verification
-             does not exist.
+    :raises NotFoundException: if verification does not exist.
     :returns: new updated task dict with data on the task.
     """
     return get_impl().verification_update(uuid, values)
@@ -366,7 +357,7 @@ def register_worker(values):
                                 this worker service.
                    }
     :returns: A worker.
-    :raises: WorkerAlreadyRegistered
+    :raises WorkerAlreadyRegistered: if worker already registered
     """
     return get_impl().register_worker(values)
 
@@ -376,7 +367,7 @@ def get_worker(hostname):
 
     :param hostname: The hostname of the worker service.
     :returns: A worker.
-    :raises: WorkerNotFound
+    :raises WorkerNotFound: if worker not found
     """
     return get_impl().get_worker(hostname)
 
@@ -385,7 +376,7 @@ def unregister_worker(hostname):
     """Unregister this worker with the service registry.
 
     :param hostname: The hostname of the worker service.
-    :raises: WorkerNotFound
+    :raises WorkerNotFound: if worker not found
     """
     get_impl().unregister_worker(hostname)
 
@@ -394,6 +385,6 @@ def update_worker(hostname):
     """Mark a worker as active by updating its "updated_at" property.
 
     :param hostname: The hostname of this worker service.
-    :raises: WorkerNotFound
+    :raises WorkerNotFound: if worker not found
     """
     get_impl().update_worker(hostname)

rally/common/db/sqlalchemy/api.py

@@ -80,7 +80,7 @@ class Connection(object):
         :param session: Reuse the session object or get new one if it is
                         None.
         :returns: The query object.
-        :raises: :class:`Exception` when the model is not a sublcass of
+        :raises Exception: when the model is not a sublcass of
                  :class:`rally.common.db.sqlalchemy.models.RallyBase`.
         """
         session = session or get_session()

rally/common/utils.py

@@ -296,7 +296,7 @@ def retry(times, func, *args, **kwargs):
     :param args: *args that are passed to func
     :param kwargs: **kwargs that are passed to func
 
-    :raises: Raise any exception that can raise func
+    :raises Exception: Raise any exception that can raise func
     :returns: Result of func(*args, **kwargs)
     """
 

rally/plugins/common/scenarios/dummy/dummy.py

@@ -52,7 +52,7 @@ class Dummy(scenario.Scenario):
 
         :param size_of_message: int size of the exception message
         :param sleep: idle time of method (in seconds).
-        :raises: DummyScenarioException
+        :raises DummyScenarioException: raise exception for test
         """
         if sleep:
             time.sleep(sleep)
@@ -98,7 +98,7 @@ class Dummy(scenario.Scenario):
     def _random_fail_emitter(self, exception_probability):
         """Throw an exception with given probability.
 
-        :raises: KeyError
+        :raises KeyError: when exception_probability is bigger
         """
         if random.random() < exception_probability:
             raise KeyError("Dummy test exception")

rally/plugins/common/scenarios/requests/utils.py

@@ -28,8 +28,8 @@ class RequestScenario(scenario.Scenario):
         :param url: Uniform resource locator
         :param method: Type of request method (GET | POST ..)
         :param kwargs: Optional additional request parameters
-        :raises: ValueError if return http status code
-        not equal to expected status code
+        :raises ValueError: if return http status code
+                            not equal to expected status code
         """
 
         resp = requests.request(method, url, **kwargs)

rally/plugins/openstack/scenarios/heat/utils.py

@@ -331,7 +331,7 @@ class HeatScenario(scenario.OpenStackScenario):
 
         :param stack: stack to call a webhook on
         :param output_key: The name of the output to get the URL from
-        :raises: InvalidConfigException if the output key is not found
+        :raises InvalidConfigException: if the output key is not found
         """
         url = None
         for output in stack.outputs:

rally/verification/tempest/tempest.py

@@ -327,8 +327,8 @@ class Tempest(object):
         :param tempest_conf: User specified tempest.conf location
         :type tempest_conf: str
 
-        :raises: :class:`subprocess.CalledProcessError` if tests has been
-                 finished with error.
+        :raises subprocess.CalledProcessError: if tests has been finished
+                                               with error.
         """
 
         if tempest_conf and os.path.isfile(tempest_conf):

tests/hacking/README.rst

@@ -27,3 +27,4 @@ Rally Specific Commandments
 * [N351] - Ensure that data structs (i.e Lists and Dicts) are declared literally rather than using constructors
 * [N352] - Ensure that string formatting only uses a mapping if multiple mapping keys are used.
 * [N353] - Ensure that unicode() function is not uset because of absence in py3
+* [N354] - Ensure that ``:raises: Exception`` is not used

tests/hacking/checks.py

@@ -59,6 +59,8 @@ re_str_format = re.compile(r"""
 [hLl]?       # optional length modifier
 [A-z%]       # conversion modifier
 """, re.X)
+re_raises = re.compile(
+    r"\s:raise[^s] *.*$|\s:raises *:.*$|\s:raises *[^:]+$")
 
 
 def skip_ignored_lines(func):
@@ -441,6 +443,20 @@ def check_using_unicode(logical_line, filename):
                   "use 'six.text_type' instead.")
 
 
+def check_raises(physical_line, filename):
+    """Check raises usage
+
+    N354
+    """
+
+    ignored_files = ["./tests/unit/test_hacking.py",
+                     "./tests/hacking/checks.py"]
+    if filename not in ignored_files:
+        if re_raises.search(physical_line):
+            return (0, "N354 ':Please use ':raises Exception: conditions' "
+                       "in docstrings.")
+
+
 def factory(register):
     register(check_assert_methods_from_mock)
     register(check_import_of_logging)
@@ -457,3 +473,4 @@ def factory(register):
     register(check_no_constructor_data_struct)
     register(check_dict_formatting_in_string)
     register(check_using_unicode)
+    register(check_raises)

tests/unit/fakes.py

@@ -68,7 +68,7 @@ def setup_dict(data, required=None, defaults=None):
     :param required: list, mandatory keys to check
     :param defaults: dict, default data
     :returns: dict, with all keys set
-    :raises: IndexError, ValueError
+    :raises IndexError, ValueError: If input data is incorrect
     """
     required = required or []
     for i in set(required) - set(data):

tests/unit/test_hacking.py

@@ -319,3 +319,12 @@ class HackingTestCase(test.TestCase):
             "text = process(unicode('sometext'))", "fakefile")
         self.assertIsNotNone(next(checkres))
         self.assertEqual([], list(checkres))
+
+    def test_check_raises(self):
+        checkres = checks.check_raises(
+            "text = :raises: Exception if conditions", "fakefile")
+        self.assertIsNotNone(checkres)
+
+        checkres = checks.check_raises(
+            "text = :raises Exception: if conditions", "fakefile")
+        self.assertIsNone(checkres)