Fix the reST field raises in docstrings

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: I0c35c6b4df840018534737bca2ca32dc977b0e05

swift/cli/info.py

@@ -303,7 +303,7 @@ def print_obj_metadata(metadata):
 
     :param metadata: dict of object metadata
 
-    :raises: ValueError
+    :raises ValueError:
     """
     user_metadata = {}
     sys_metadata = {}

swift/cli/ring_builder_analyzer.py

@@ -195,7 +195,7 @@ def parse_scenario(scenario_data):
     for feeding to run_scenario().
 
     :returns: scenario
-    :raises: ValueError on invalid scenario
+    :raises ValueError: on invalid scenario
     """
 
     parsed_scenario = {}

swift/common/constraints.py

@@ -277,7 +277,7 @@ def valid_timestamp(request):
     :param request: the swob request object
 
     :returns: a valid Timestamp instance
-    :raises: HTTPBadRequest on missing or invalid X-Timestamp
+    :raises HTTPBadRequest: on missing or invalid X-Timestamp
     """
     try:
         return request.timestamp
@@ -364,7 +364,7 @@ def check_name_format(req, name, target_type):
     :param name: header value to validate
     :param target_type: which header is being validated (Account or Container)
     :returns: A properly encoded account name or container name
-    :raise: HTTPPreconditionFailed if account header
+    :raise HTTPPreconditionFailed: if account header
             is not well formatted.
     """
     if not name:

swift/common/db.py

@@ -738,7 +738,7 @@ class DatabaseBroker(object):
         Validates that metadata falls within acceptable limits.
 
         :param metadata: to be validated
-        :raises: HTTPBadRequest if MAX_META_COUNT or MAX_META_OVERALL_SIZE
+        :raises HTTPBadRequest: if MAX_META_COUNT or MAX_META_OVERALL_SIZE
                  is exceeded, or if metadata contains non-UTF-8 data
         """
         meta_count = 0

swift/common/middleware/bulk.py

@@ -296,7 +296,7 @@ class Bulk(object):
         Checks if the container exists and if not try to create it.
         :params container_path: an unquoted path to a container to be created
         :returns: True if created container, False if container exists
-        :raises: CreateContainerError when unable to create container
+        :raises CreateContainerError: when unable to create container
         """
         new_env = req.environ.copy()
         new_env['PATH_INFO'] = container_path
@@ -324,7 +324,7 @@ class Bulk(object):
         Will populate objs_to_delete with data from request input.
         :params req: a Swob request
         :returns: a list of the contents of req.body when separated by newline.
-        :raises: HTTPException on failures
+        :raises HTTPException: on failures
         """
         line = ''
         data_remaining = True

swift/common/middleware/copy.py

@@ -156,7 +156,7 @@ def _check_path_header(req, name, length, error_msg):
     :param length: length of path segment check
     :param error_msg: error message for client
     :returns: A tuple with path parts according to length
-    :raise: HTTPPreconditionFailed if header value
+    :raise HTTPPreconditionFailed: if header value
             is not well formatted.
     """
     src_header = unquote(req.headers.get(name))
@@ -178,7 +178,7 @@ def _check_copy_from_header(req):
 
     :param req: HTTP request object
     :returns: A tuple with container name and object name
-    :raise: HTTPPreconditionFailed if x-copy-from value
+    :raise HTTPPreconditionFailed: if x-copy-from value
             is not well formatted.
     """
     return _check_path_header(req, 'X-Copy-From', 2,
@@ -194,7 +194,7 @@ def _check_destination_header(req):
 
     :param req: HTTP request object
     :returns: A tuple with container name and object name
-    :raise: HTTPPreconditionFailed if destination value
+    :raise HTTPPreconditionFailed: if destination value
             is not well formatted.
     """
     return _check_path_header(req, 'Destination', 2,

swift/common/middleware/crypto/crypto_utils.py

@@ -53,7 +53,7 @@ class Crypto(object):
 
         :param key: 256-bit key
         :param iv: 128-bit iv or nonce used for encryption
-        :raises: ValueError on invalid key or iv
+        :raises ValueError: on invalid key or iv
         :returns: an instance of an encryptor
         """
         self.check_key(key)

swift/common/middleware/list_endpoints.py

@@ -151,7 +151,7 @@ class ListEndpointsMiddleware(object):
 
         :returns: parsed path parts as a tuple with version filled in as
                   configured default response version if not specified.
-        :raises: ValueError if path is invalid, message will say why.
+        :raises ValueError: if path is invalid, message will say why.
         """
         clean_path = request.path[len(self.endpoints_path) - 1:]
         # try to peel off version

swift/common/middleware/ratelimit.py

@@ -189,7 +189,7 @@ class RateLimitMiddleware(object):
 
         :param key: a memcache key
         :param max_rate: maximum rate allowed in requests per second
-        :raises: MaxSleepTimeHitError if max sleep time is exceeded.
+        :raises MaxSleepTimeHitError: if max sleep time is exceeded.
         """
         try:
             now_m = int(round(time.time() * self.clock_accuracy))

swift/common/middleware/slo.py

@@ -311,7 +311,7 @@ def parse_and_validate_input(req_body, req_path):
         corresponding swob.Range object. If d_in does not have a key
         'range', neither will d_out.
 
-    :raises: HTTPException on parse errors or semantic errors (e.g. bogus
+    :raises HTTPException: on parse errors or semantic errors (e.g. bogus
         JSON structure, syntactically invalid ranges)
 
     :returns: a list of dictionaries on success
@@ -899,7 +899,7 @@ class StaticLargeObject(object):
         concatenation of the segments.
 
         :params req: a swob.Request with a path referencing an object
-        :raises: HttpException on errors
+        :raises HttpException: on errors
         """
         return SloGetContext(self).handle_slo_get_or_head(req, start_response)
 
@@ -911,7 +911,7 @@ class StaticLargeObject(object):
         call self and start_response and returns a WSGI iterator.
 
         :params req: a swob.Request with an obj in path
-        :raises: HttpException on errors
+        :raises HttpException: on errors
         """
         try:
             vrs, account, container, obj = req.split_path(1, 4, True)

swift/common/request_helpers.py

@@ -57,7 +57,7 @@ def get_param(req, name, default=None):
     :param default: result to return if the parameter is not found
     :returns: HTTP request parameter value
               (as UTF-8 encoded str, not unicode object)
-    :raises: HTTPBadRequest if param not valid UTF-8 byte sequence
+    :raises HTTPBadRequest: if param not valid UTF-8 byte sequence
     """
     value = req.params.get(name, default)
     if value and not isinstance(value, six.text_type):
@@ -77,8 +77,8 @@ def get_listing_content_type(req):
 
     :param req: request object
     :returns: content type as a string (e.g. text/plain, application/json)
-    :raises: HTTPNotAcceptable if the requested content type is not acceptable
+    :raises HTTPNotAcceptable: if the requested content type is not acceptable
-    :raises: HTTPBadRequest if the 'format' query param is provided and
+    :raises HTTPBadRequest: if the 'format' query param is provided and
              not valid UTF-8
     """
     query_format = get_param(req, 'format')
@@ -103,7 +103,7 @@ def get_name_and_placement(request, minsegs=1, maxsegs=None,
 
     :returns: a list, result of :meth:`split_and_validate_path` with
               the BaseStoragePolicy instance appended on the end
-    :raises: HTTPServiceUnavailable if the path is invalid or no policy exists
+    :raises HTTPServiceUnavailable: if the path is invalid or no policy exists
              with the extracted policy_index.
     """
     policy_index = request.headers.get('X-Backend-Storage-Policy-Index')
@@ -126,7 +126,7 @@ def split_and_validate_path(request, minsegs=1, maxsegs=None,
 
     :returns: result of :meth:`~swift.common.utils.split_path` if
               everything's okay
-    :raises: HTTPBadRequest if something's not okay
+    :raises HTTPBadRequest: if something's not okay
     """
     try:
         segs = split_path(unquote(request.path),

swift/common/ring/ring.py

@@ -167,7 +167,7 @@ class Ring(object):
     :param ring_name: ring name string (basically specified from policy)
     :param validation_hook: hook point to validate ring configuration ontime
 
-    :raises: RingLoadError if the loaded ring data violates its constraint
+    :raises RingLoadError: if the loaded ring data violates its constraint
     """
 
     def __init__(self, serialized_path, reload_time=15, ring_name=None,

swift/common/ring/utils.py

@@ -426,7 +426,7 @@ def parse_add_value(add_value):
 
     :returns: dictionary with keys 'region', 'zone', 'ip', 'port', 'device',
         'replication_ip', 'replication_port', 'meta'
-    :raises: ValueError if add_value is malformed
+    :raises ValueError: if add_value is malformed
     """
     region = None
     rest = add_value

swift/common/storage_policy.py

@@ -111,7 +111,7 @@ def get_policy_string(base, policy_or_index):
                             storage Policy-0 is assumed.
 
     :returns: base name with policy index added
-    :raises: PolicyError if no policy exists with the given policy_index
+    :raises PolicyError: if no policy exists with the given policy_index
     """
     if isinstance(policy_or_index, BaseStoragePolicy):
         policy = policy_or_index
@@ -130,7 +130,7 @@ def split_policy_string(policy_string):
 
     :param policy_string: base name with policy index added
 
-    :raises: PolicyError if given index does not map to a valid policy
+    :raises PolicyError: if given index does not map to a valid policy
     :returns: a tuple, in the form (base, policy) where base is the base
               string and policy is the StoragePolicy instance for the
               index encoded in the policy_string.
@@ -288,7 +288,7 @@ class BaseStoragePolicy(object):
         to check policy names before setting them.
 
         :param name: a name string for a single policy name.
-        :raises: PolicyError if the policy name is invalid.
+        :raises PolicyError: if the policy name is invalid.
         """
         if not name:
             raise PolicyError('Invalid name %r' % name, self.idx)

swift/common/swob.py

@@ -1029,7 +1029,7 @@ class Request(object):
                                trailing data, raises ValueError.
         :returns: list of segments with a length of maxsegs (non-existent
                   segments will return as None)
-        :raises: ValueError if given an invalid path
+        :raises ValueError: if given an invalid path
         """
         return split_path(
             self.environ.get('SCRIPT_NAME', '') + self.environ['PATH_INFO'],

swift/common/utils.py

@@ -1276,7 +1276,7 @@ def split_path(path, minsegs=1, maxsegs=None, rest_with_last=False):
                            trailing data, raises ValueError.
     :returns: list of segments with a length of maxsegs (non-existent
               segments will return as None)
-    :raises: ValueError if given an invalid path
+    :raises ValueError: if given an invalid path
     """
     if not maxsegs:
         maxsegs = minsegs
@@ -1311,7 +1311,7 @@ def validate_device_partition(device, partition):
 
     :param device: device to validate
     :param partition: partition to validate
-    :raises: ValueError if given an invalid device or partition
+    :raises ValueError: if given an invalid device or partition
     """
     if not device or '/' in device or device in ['.', '..']:
         raise ValueError('Invalid device: %s' % quote(device or ''))
@@ -2943,7 +2943,7 @@ def affinity_key_function(affinity_str):
     :param affinity_str: affinity config value, e.g. "r1z2=3"
                          or "r1=1, r2z1=2, r2z2=2"
     :returns: single-argument function
-    :raises: ValueError if argument invalid
+    :raises ValueError: if argument invalid
     """
     affinity_str = affinity_str.strip()
 
@@ -2996,7 +2996,7 @@ def affinity_locality_predicate(write_affinity_str):
     :param write_affinity_str: affinity config value, e.g. "r1z2"
         or "r1, r2z1, r2z2"
     :returns: single-argument function, or None if affinity_str is empty
-    :raises: ValueError if argument invalid
+    :raises ValueError: if argument invalid
     """
     affinity_str = write_affinity_str.strip()
 
@@ -3634,7 +3634,7 @@ def parse_content_range(content_range):
     :param content_range: Content-Range header value to parse,
         e.g. "bytes 100-1249/49004"
     :returns: 3-tuple (start, end, total)
-    :raises: ValueError if malformed
+    :raises ValueError: if malformed
     """
     found = re.search(_content_range_pattern, content_range)
     if not found:
@@ -3816,7 +3816,7 @@ def iter_multipart_mime_documents(wsgi_input, boundary, read_chunk_size=4096):
     :param boundary: The mime boundary to separate new file-like
                      objects on.
     :returns: A generator of file-like objects for each part.
-    :raises: MimeInvalid if the document is malformed
+    :raises MimeInvalid: if the document is malformed
     """
     boundary = '--' + boundary
     blen = len(boundary) + 2  # \r\n

swift/container/server.py

@@ -140,7 +140,7 @@ class ContainerController(BaseStorageServer):
         Validate that the index supplied maps to a policy.
 
         :returns: policy index from request, or None if not present
-        :raises: HTTPBadRequest if the supplied index is bogus
+        :raises HTTPBadRequest: if the supplied index is bogus
         """
 
         policy_index = req.headers.get('X-Backend-Storage-Policy-Index', None)

swift/proxy/controllers/obj.py

@@ -950,7 +950,7 @@ class ECAppIter(object):
         can also use it in the body.
 
         :returns: None
-        :raises: HTTPException on error
+        :raises HTTPException: on error
         """
         self.mime_boundary = resp.boundary
 
@@ -1468,7 +1468,7 @@ class Putter(object):
         :param informational: if True then try to get a 100-continue response,
                               otherwise try to get a final response.
         :returns: HTTPResponse
-        :raises: Timeout if the response took too long
+        :raises Timeout: if the response took too long
         """
         # don't do this update of self.resp if the Expect response during
         # connect() was actually a final response
@@ -1587,10 +1587,10 @@ class Putter(object):
 
         :returns: Putter instance
 
-        :raises: ConnectionTimeout if initial connection timed out
+        :raises ConnectionTimeout: if initial connection timed out
-        :raises: ResponseTimeout if header retrieval timed out
+        :raises ResponseTimeout: if header retrieval timed out
-        :raises: InsufficientStorage on 507 response from node
+        :raises InsufficientStorage: on 507 response from node
-        :raises: PutterConnectError on non-507 server error response from node
+        :raises PutterConnectError: on non-507 server error response from node
         """
         conn, expect_resp, final_resp, connect_duration = cls._make_connection(
             node, part, path, headers, conn_timeout, node_timeout)
@@ -1700,9 +1700,9 @@ class MIMEPutter(Putter):
 
         :param need_multiphase: if True then multiphase support is required of
                                 the object server
-        :raises: FooterNotSupported if need_metadata_footer is set but
+        :raises FooterNotSupported: if need_metadata_footer is set but
                  backend node can't process footers
-        :raises: MultiphasePUTNotSupported if need_multiphase is set but
+        :raises MultiphasePUTNotSupported: if need_multiphase is set but
                  backend node can't handle multiphase PUT
         """
         mime_boundary = "%.64x" % random.randint(0, 16 ** 64)

swift/proxy/server.py

@@ -363,7 +363,7 @@ class Application(object):
         :param req: the request
         :returns: tuple of (controller class, path dictionary)
 
-        :raises: ValueError (thrown by split_path) if given invalid path
+        :raises ValueError: (thrown by split_path) if given invalid path
         """
         if req.path == '/info':
             d = dict(version=None,