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
This commit is contained in:
parent
66e90d3b25
commit
007f073e41
@ -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.
|
||||
|
@ -38,8 +38,7 @@ class Api(object):
|
||||
:returns: Action's schema
|
||||
:rtype: dict
|
||||
|
||||
:raises: `errors.InvalidAction` if the action
|
||||
does not exist
|
||||
:raises InvalidAction: if the action 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
|
||||
does not exist
|
||||
:raises InvalidAction: if the action does not exist
|
||||
"""
|
||||
|
||||
if action not in self.validators:
|
||||
|
@ -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
|
||||
"""
|
||||
|
@ -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
|
||||
|
@ -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
|
||||
|
@ -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: SubscriptionAlreadyExists on attempt to update in a way to
|
||||
:raises SubscriptionDoesNotExist: if not found
|
||||
: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
|
||||
|
@ -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
|
||||
|
@ -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()
|
||||
|
||||
|
@ -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)
|
||||
|
@ -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
|
||||
|
||||
"""
|
||||
|
||||
|
@ -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,
|
||||
pop AND id params are present together
|
||||
neither pop or id params are present
|
||||
message count to be popped > maximum allowed
|
||||
:raises ValidationFailed: if,
|
||||
pop AND id params are present together
|
||||
neither pop or id params are present
|
||||
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
|
||||
|
@ -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)
|
||||
|
Loading…
Reference in New Issue
Block a user