Fix some reST field lists in docstrings

remove the redundant ":"

Probably the most common format for documenting arguments is reST field
lists [1]. This change updates some docstrings to comply with the field
lists syntax.

[1] http://sphinx-doc.org/domains.html#info-field-lists

Change-Id: Ie85c045be45bbc540bc45224c93f51a58053a991

HACKING.rst

@@ -118,7 +118,8 @@ Example::
     keep things ordered
   :returns: return_type -- description of the return value
   :returns: description of the return value
-  :raises: AttributeError, KeyError
+  :raises ValueError: if the message_body exceeds 160 characters
+  :raises TypeError: if the message_body is not a basestring
   """
 
 **DO NOT** leave an extra newline before the closing triple-double-quote.

zaqar/common/api/api.py

@@ -38,8 +38,7 @@ class Api(object):
         :returns: Action's schema
         :rtype: dict
 
-        :raises: `errors.InvalidAction` if the action
+        :raises InvalidAction: if the action does not exist
-            does not exist
         """
 
         try:
@@ -63,8 +62,7 @@ class Api(object):
         :type body: dict
 
         :returns: True if the schema is valid, False otherwise
-        :raises: `errors.InvalidAction` if the action
+        :raises InvalidAction: if the action does not exist
-            does not exist
         """
 
         if action not in self.validators:

zaqar/common/api/utils.py

@@ -42,7 +42,9 @@ def sanitize(document, spec=None, doctype=dict):
         If spec is None, the incoming documents will not be validated.
     :param doctype: type of document to expect; must be either
         JSONObject or JSONArray.
-    :raises: DocumentTypeNotSupported, TypeError
+    :raises DocumentTypeNotSupported: if document type is not supported
+    :raises TypeError: if document type is neither a JSONObject
+        nor JSONArray
     :returns: A sanitized, filtered version of the document. If the
         document is a list of objects, each object will be filtered
         and returned in a new list. If, on the other hand, the document
@@ -80,7 +82,7 @@ def filter_fields(document, spec):
         tuples with the form of: (field_name, value_type). Note that
         value_type may either be a Python type, or the special
         string '*' to accept any type.
-    :raises: BadRequest if any field is missing or not an
+    :raises BadRequest: if any field is missing or not an
         instance of the specified type
     :returns: A filtered dict containing only the fields
         listed in the spec
@@ -106,7 +108,7 @@ def get_checked_field(document, name, value_type, default_value):
     :param value_type: expected value type, or '*' to accept any type
     :param default_value: Default value to use if the value is missing,
         or None to make the value required.
-    :raises: BadRequest if the field is missing or not an
+    :raises BadRequest: if the field is missing or not an
         instance of value_type
     :returns: value obtained from doc[name]
     """
@@ -134,7 +136,7 @@ def get_client_uuid(req):
     """Read a required Client-ID from a request.
 
     :param req: Request object
-    :raises: BadRequest if the Client-ID header is missing or
+    :raises BadRequest: if the Client-ID header is missing or
         does not represent a valid UUID
     :returns: A UUID object
     """

zaqar/common/pipeline.py

@@ -75,7 +75,7 @@ class Pipeline(object):
             :param args: Positional arguments to pass to the call.
             :param kwargs: Keyword arguments to pass to the call.
 
-            :raises: AttributeError if none of the stages implement `method`
+            :raises AttributeError: if none of the stages implement `method`
             """
             # NOTE(flaper87): Used as a way to verify
             # the requested method exists in at least

zaqar/common/transport/wsgi/helpers.py

@@ -65,7 +65,7 @@ def get_client_uuid(req):
     """Read a required Client-ID from a request.
 
     :param req: A falcon.Request object
-    :raises: HTTPBadRequest if the Client-ID header is missing or
+    :raises HTTPBadRequest: if the Client-ID header is missing or
         does not represent a valid UUID
     :returns: A UUID object
     """
@@ -182,7 +182,7 @@ def require_accepts_json(req, resp, params):
     :param params: additional parameters passed to responders
     :type params: dict
     :rtype: None
-    :raises: falcon.HTTPNotAcceptable
+    :raises HTTPNotAcceptable: if the request does not accept JSON
     """
     if not req.client_accepts('application/json'):
         raise falcon.HTTPNotAcceptable(
@@ -212,8 +212,8 @@ def require_content_type_be_non_urlencoded(req, resp, params):
     :param params: additional parameters passed to responders
     :type params: dict
     :rtype: None
-    :raises: falcon.HTTPBadRequest
+    :raises HTTPBadRequest: if request has body and "Content-Type" header has
-
+        "application/x-www-form-urlencoded" value
     """
     if req.content_length is None:
         return

zaqar/storage/base.py

@@ -332,7 +332,7 @@ class Queue(ControllerBase):
         :param project: Project id
 
         :returns: Dictionary containing queue metadata
-        :raises: DoesNotExist
+        :raises DoesNotExist: if queue metadata does not exist
         """
         return self._get(name, project)
 
@@ -345,7 +345,7 @@ class Queue(ControllerBase):
         :param project: Project id
 
         :returns: Dictionary containing queue metadata
-        :raises: DoesNotExist
+        :raises DoesNotExist: if queue metadata does not exist
         """
         raise NotImplementedError
 
@@ -355,7 +355,7 @@ class Queue(ControllerBase):
         :param name: The queue name
         :param metadata: Queue metadata as a dict
         :param project: Project id
-        :raises: DoesNotExist
+        :raises DoesNotExist: if queue metadata can not be updated
         """
         raise NotImplementedError
 
@@ -458,7 +458,7 @@ class Message(ControllerBase):
         :param message_id: Message ID
 
         :returns: Dictionary containing message data
-        :raises: DoesNotExist
+        :raises DoesNotExist: if message data can not be got
         """
         raise NotImplementedError
 
@@ -547,7 +547,7 @@ class Claim(ControllerBase):
         :param project: Project id
 
         :returns: (Claim's metadata, claimed messages)
-        :raises: DoesNotExist
+        :raises DoesNotExist: if claimed messages can not be got
         """
         raise NotImplementedError
 
@@ -630,7 +630,7 @@ class Subscription(ControllerBase):
         :type project: six.text_type
         :returns: Dictionary containing subscription data
         :rtype: {}
-        :raises: SubscriptionDoesNotExist if not found
+        :raises SubscriptionDoesNotExist: if not found
         """
         raise NotImplementedError
 
@@ -664,8 +664,8 @@ class Subscription(ControllerBase):
         :type name: text
         :param kwargs: one of: `source`, `subscriber`, `ttl`, `options`
         :type kwargs: dict
-        :raises: SubscriptionDoesNotExist if not found
+        :raises SubscriptionDoesNotExist: if not found
-        :raises: SubscriptionAlreadyExists on attempt to update in a way to
+        :raises SubscriptionAlreadyExists: if attempt to update in a way to
             create duplicate subscription
         """
 
@@ -823,7 +823,7 @@ class PoolsBase(ControllerBase):
         :type detailed: bool
         :returns: weight, uri, and options for this pool
         :rtype: {}
-        :raises: PoolDoesNotExist if not found
+        :raises PoolDoesNotExist: if not found
         """
         return self._get_pools_by_group(group, detailed)
 
@@ -838,7 +838,7 @@ class PoolsBase(ControllerBase):
         :type detailed: bool
         :returns: weight, uri, and options for this pool
         :rtype: {}
-        :raises: PoolDoesNotExist if not found
+        :raises PoolDoesNotExist: if not found
         """
         return self._get(name, detailed)
 
@@ -874,7 +874,7 @@ class PoolsBase(ControllerBase):
         :type name: text
         :param kwargs: one of: `uri`, `weight`, `options`
         :type kwargs: dict
-        :raises: PoolDoesNotExist
+        :raises PoolDoesNotExist: if not found
         """
         uri = kwargs.get('uri')
         if uri and not self._check_capabilities(uri, name=name):
@@ -922,7 +922,7 @@ class CatalogueBase(ControllerBase):
         :type queue: six.text_type
         :returns: {'pool': ...}
         :rtype: dict
-        :raises: QueueNotMapped
+        :raises QueueNotMapped: if queue is not mapped
         """
 
         raise NotImplementedError
@@ -975,7 +975,7 @@ class CatalogueBase(ControllerBase):
         :type queue: six.text_type
         :param pools: The name of the pool where this project/queue lives.
         :type pools: six.text_type
-        :raises: QueueNotMapped
+        :raises QueueNotMapped: if queue is not mapped
         """
 
         raise NotImplementedError
@@ -1032,7 +1032,7 @@ class FlavorsBase(ControllerBase):
         :param project: Project this flavor belongs to.
         :type project: six.text_type
         :rtype: {}
-        :raises: FlavorDoesNotExist if not found
+        :raises FlavorDoesNotExist: if not found
         """
 
         raise NotImplementedError
@@ -1074,7 +1074,7 @@ class FlavorsBase(ControllerBase):
         :type project: six.text_type
         :param kwargs: one of: `uri`, `weight`, `options`
         :type kwargs: dict
-        :raises: FlavorDoesNotExist
+        :raises FlavorDoesNotExist: if not found
         """
 
         raise NotImplementedError

zaqar/storage/mongodb/messages.py

@@ -414,7 +414,7 @@ class MessageController(storage.Message):
             was specified, and the counter has already been updated
             within the specified time period.
 
-        :raises: storage.errors.QueueDoesNotExist
+        :raises QueueDoesNotExist: if not found
         """
 
         # NOTE(flaper87): If this `if` is True, it means we're

zaqar/storage/mongodb/queues.py

@@ -144,7 +144,7 @@ class QueueController(storage.Queue):
             was specified, and the counter has already been updated
             within the specified time period.
 
-        :raises: storage.errors.QueueDoesNotExist
+        :raises QueueDoesNotExist: if not found
         """
         now = timeutils.utcnow_ts()
 

zaqar/storage/mongodb/utils.py

@@ -82,7 +82,7 @@ def calculate_backoff(attempt, max_attempts, max_sleep, max_jitter=0):
     :param max_jitter: maximum jitter value to add to the baseline sleep
         time. Actual value will be chosen randomly.
 
-    :raises: ValueError
+    :raises ValueError: if the parameter is not invalid
     :returns: float representing the number of seconds to sleep, within
         the interval [0, max_sleep), determined linearly according to
         the ratio attempt / max_attempts, with optional jitter.
@@ -122,7 +122,7 @@ def to_oid(obj):
 def oid_ts(oid):
     """Converts an ObjectId to a UNIX timestamp.
 
-    :raises: TypeError if oid isn't an ObjectId
+    :raises TypeError: if oid isn't an ObjectId
     """
     try:
         return timeutils.delta_seconds(EPOCH, oid.generation_time)

zaqar/storage/pooling.py

@@ -488,7 +488,7 @@ class Catalog(object):
 
         :returns: pool id
 
-        :raises: `errors.QueueNotMapped`
+        :raises QueueNotMapped: if queue is not mapped
         """
         return self._catalogue_ctrl.get(project, queue)['pool']
 
@@ -512,7 +512,7 @@ class Catalog(object):
         :param flavor: Flavor for the queue (OPTIONAL)
         :type flavor: six.text_type
 
-        :raises: NoPoolFound
+        :raises NoPoolFound: if not found
 
         """
 

zaqar/transport/validation.py

@@ -121,7 +121,7 @@ class Validator(object):
 
         :param queue: Name of the queue
         :param project: Project id
-        :raises: ValidationFailed if the `name` is longer than 64
+        :raises ValidationFailed: if the `name` is longer than 64
             characters or contains anything other than ASCII digits and
             letters, underscores, and dashes.  Also raises if `project`
             is not None but longer than 256 characters.
@@ -271,7 +271,7 @@ class Validator(object):
 
         :param limit: The expected number of queues in the list
         :param kwargs: Ignored arguments passed to storage API
-        :raises: ValidationFailed if the limit is exceeded
+        :raises ValidationFailed: if the limit is exceeded
         """
 
         uplimit = self._limits_conf.max_queues_per_page
@@ -283,7 +283,7 @@ class Validator(object):
         """Restrictions on queue's length.
 
         :param content_length: Queue request's length.
-        :raises: ValidationFailed if the metadata is oversize.
+        :raises ValidationFailed: if the metadata is oversize.
         """
         if content_length is None:
             return
@@ -295,7 +295,7 @@ class Validator(object):
         """Checking if the reserved attributes of the queue are valid.
 
         :param queue_metadata: Queue's metadata.
-        :raises: ValidationFailed if any reserved attribute is invalid.
+        :raises ValidationFailed: if any reserved attribute is invalid.
         """
         if not queue_metadata:
             return
@@ -331,7 +331,7 @@ class Validator(object):
         """Restrictions the resource types to be purged for a queue.
 
         :param resource_types: Type list of all resource under a queue
-        :raises: ValidationFailed if the resource types are invalid
+        :raises ValidationFailed: if the resource types are invalid
         """
 
         if 'resource_types' not in document:
@@ -347,7 +347,7 @@ class Validator(object):
         """Restrictions on a list of messages.
 
         :param messages: A list of messages
-        :raises: ValidationFailed if any message has a out-of-range
+        :raises ValidationFailed: if any message has a out-of-range
             TTL.
         """
 
@@ -361,7 +361,7 @@ class Validator(object):
         """Restrictions on message post length.
 
         :param content_length: Queue request's length.
-        :raises: ValidationFailed if the metadata is oversize.
+        :raises ValidationFailed: if the metadata is oversize.
         """
         if content_length is None:
             return
@@ -407,7 +407,7 @@ class Validator(object):
 
         :param limit: The expected number of messages in the list
         :param kwargs: Ignored arguments passed to storage API
-        :raises: ValidationFailed if the limit is exceeded
+        :raises ValidationFailed: if the limit is exceeded
         """
 
         uplimit = self._limits_conf.max_messages_per_page
@@ -423,10 +423,10 @@ class Validator(object):
 
         :param ids: message ids passed in by the delete request
         :param pop: count of messages to be POPped
-        :raises: ValidationFailed if,
+        :raises ValidationFailed: if,
-                 pop AND id params are present together
+            pop AND id params are present together
-                 neither pop or id params are present
+            neither pop or id params are present
-                 message count to be popped > maximum allowed
+            message count to be popped > maximum allowed
         """
 
         if pop is not None and ids is not None:
@@ -460,7 +460,7 @@ class Validator(object):
 
         :param metadata: The claim metadata
         :param limit: The number of messages to claim
-        :raises: ValidationFailed if either TTL or grace is out of range,
+        :raises ValidationFailed: if either TTL or grace is out of range,
             or the expected number of messages exceed the limit.
         """
 
@@ -487,7 +487,7 @@ class Validator(object):
         """Restrictions on the claim TTL.
 
         :param metadata: The claim metadata
-        :raises: ValidationFailed if the TTL is out of range
+        :raises ValidationFailed: if the TTL is out of range
         """
 
         ttl = metadata['ttl']
@@ -503,7 +503,7 @@ class Validator(object):
         """Restrictions on a creation of subscription.
 
         :param subscription: dict of subscription
-        :raises: ValidationFailed if the subscription is invalid.
+        :raises ValidationFailed: if the subscription is invalid.
         """
         for p in ('subscriber',):
             if p not in subscription.keys():
@@ -515,7 +515,7 @@ class Validator(object):
         """Restrictions on an update of subscription.
 
         :param subscription: dict of subscription
-        :raises: ValidationFailed if the subscription is invalid.
+        :raises ValidationFailed: if the subscription is invalid.
         """
 
         if not subscription:
@@ -578,7 +578,7 @@ class Validator(object):
 
         :param limit: The expected number of subscriptions in the list
         :param kwargs: Ignored arguments passed to storage API
-        :raises: ValidationFailed if the limit is exceeded
+        :raises ValidationFailed: if the limit is exceeded
         """
 
         uplimit = self._limits_conf.max_subscriptions_per_page
@@ -601,7 +601,7 @@ class Validator(object):
 
         :param limit: The expected number of flavors in the list
         :param kwargs: Ignored arguments passed to storage API
-        :raises: ValidationFailed if the limit is exceeded
+        :raises ValidationFailed: if the limit is exceeded
         """
 
         uplimit = self._limits_conf.max_flavors_per_page
@@ -614,7 +614,7 @@ class Validator(object):
 
         :param limit: The expected number of flavors in the list
         :param kwargs: Ignored arguments passed to storage API
-        :raises: ValidationFailed if the limit is exceeded
+        :raises ValidationFailed: if the limit is exceeded
         """
 
         uplimit = self._limits_conf.max_pools_per_page

zaqar/transport/wsgi/utils.py

@@ -43,7 +43,8 @@ def deserialize(stream, len):
     :param stream: file-like object from which to read an object or
         array of objects.
     :param len: number of bytes to read from stream
-    :raises: HTTPBadRequest, HTTPServiceUnavailable
+    :raises HTTPBadRequest: if the request is invalid
+    :raises HTTPServiceUnavailable: if the http service is unavailable
     """
 
     if len is None:
@@ -90,7 +91,7 @@ def sanitize(document, spec=None, doctype=JSONObject):
         If spec is None, the incoming documents will not be validated.
     :param doctype: type of document to expect; must be either
         JSONObject or JSONArray.
-    :raises: HTTPBadRequestBody
+    :raises HTTPBadRequestBody: if the request is invalid
     :returns: A sanitized, filtered version of the document. If the
         document is a list of objects, each object will be filtered
         and returned in a new list. If, on the other hand, the document
@@ -128,7 +129,7 @@ def filter(document, spec):
         tuples with the form of: (field_name, value_type). Note that
         value_type may either be a Python type, or the special
         string '*' to accept any type.
-    :raises: HTTPBadRequest if any field is missing or not an
+    :raises HTTPBadRequest: if any field is missing or not an
         instance of the specified type
     :returns: A filtered dict containing only the fields
         listed in the spec
@@ -154,7 +155,7 @@ def get_checked_field(document, name, value_type, default_value):
     :param value_type: expected value type, or '*' to accept any type
     :param default_value: Default value to use if the value is missing,
         or None to make the value required.
-    :raises: HTTPBadRequest if the field is missing or not an
+    :raises HTTPBadRequest: if the field is missing or not an
         instance of value_type
     :returns: value obtained from doc[name]
     """
@@ -185,7 +186,7 @@ def load(req):
     :type req: falcon.Request
     :return: a dictionary decoded from the JSON stream
     :rtype: dict
-    :raises: errors.HTTPBadRequestBody
+    :raises HTTPBadRequestBody: if JSON could not be parsed
     """
     try:
         return utils.read_json(req.stream, req.content_length)
@@ -204,7 +205,7 @@ def validate(validator, document):
     :type validator: jsonschema.Draft4Validator
     :param document: document to check
     :type document: dict
-    :raises: errors.HTTPBadRequestBody
+    :raises HTTPBadRequestBody: if the request is invalid
     """
     try:
         validator.validate(document)