openstack
/
zaqar
Code Issues Proposed changes

Merge "Fix some reST field lists in docstrings"

This commit is contained in:
Jenkins 2017-07-04 12:11:12 +00:00 committed by Gerrit Code Review
parent 6f2675e676 007f073e41
commit ecef4663de
12 changed files with 62 additions and 60 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
HACKING.rst
View File

@ -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.

6
zaqar/common/api/api.py
View File

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

10
zaqar/common/api/utils.py
View File

@ -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
"""

2
zaqar/common/pipeline.py
View File

@ -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

8
zaqar/common/transport/wsgi/helpers.py
View File

@ -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

30
zaqar/storage/base.py
View File

@ -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

2
zaqar/storage/mongodb/messages.py
View File

@ -413,7 +413,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

2
zaqar/storage/mongodb/queues.py
View File

@ -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()

4
zaqar/storage/mongodb/utils.py
View File

@ -80,7 +80,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.
@ -120,7 +120,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)

4
zaqar/storage/pooling.py
View File

@ -474,7 +474,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']
@ -498,7 +498,7 @@ class Catalog(object):
:param flavor: Flavor for the queue (OPTIONAL)
:type flavor: six.text_type
:raises: NoPoolFound
:raises NoPoolFound: if not found
"""

38
zaqar/transport/validation.py
View File

@ -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

13
zaqar/transport/wsgi/utils.py
View File

@ -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)