openstack/deb-python-falcon
Code Issues Proposed changes

doc: Unindent additional Return lines to work around napolean bug (#892)

Browse Source 
In a google-style docstring, this is problematic:

    Returns:
        str: Some really long description that requires more
            than one line

Since the additional text (i.e., "than one line") is indented,
napolean gets confused and incorrectly formats the description. The
fix is to align subsequent lines with the first:

    Returns:
        str: Some really long description that requires more
        than one line.

Along the way I also added missing return types as needed.
This commit is contained in:
Kurt Griffiths
2016-09-08 13:55:47 -06:00
committed by GitHub
parent dd5a5291f7
commit c2cb7091e2
8 changed files with 48 additions and 47 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
falcon/api.py
View File

@@ -482,7 +482,7 @@ class API(object):
req: The request object.
Returns:
A 3-member tuple consisting of a responder callable,
tuple: A 3-member tuple consisting of a responder callable,
a ``dict`` containing parsed path fields (if any were specified in
the matching route's URI template), and a reference to the
responder's resource instance.
@@ -578,7 +578,7 @@ class API(object):
Returns:
bool: ``True`` if a handler was found and called for the
exception, ``False`` otherwise.
exception, ``False`` otherwise.
"""
for err_type, err_handler in self._error_handlers:
@@ -611,7 +611,7 @@ class API(object):
when resp.stream is a file-like object (default None).
Returns:
A two-member tuple of the form (iterable, content_length).
tuple: A two-member tuple of the form (iterable, content_length).
The length is returned as ``None`` when unknown. The
iterable is determined as follows:

2
falcon/api_helpers.py
View File

@@ -24,7 +24,7 @@ def prepare_middleware(middleware=None):
middleware: list (or object) of input middleware
Returns:
A middleware list
list: A list of prepared middleware tuples
"""
# PERF(kgriffs): do getattr calls once, in advance, so we don't

7
falcon/http_error.py
View File

@@ -131,7 +131,8 @@ class HTTPError(Exception):
error information (default ``dict``).
Returns:
A dictionary populated with the error's title, description, etc.
dict: A dictionary populated with the error's title,
description, etc.
"""
@@ -154,7 +155,7 @@ class HTTPError(Exception):
"""Returns a pretty-printed JSON representation of the error.
Returns:
A JSON document for the error.
str: A JSON document for the error.
"""
@@ -166,7 +167,7 @@ class HTTPError(Exception):
"""Returns an XML-encoded representation of the error.
Returns:
An XML document for the error.
str: An XML document for the error.
"""

40
falcon/request.py
View File

@@ -617,8 +617,8 @@ class Request(object):
Returns:
bool: ``True`` if the client has indicated in the Accept header
that it accepts the specified media type. Otherwise, returns
``False``.
that it accepts the specified media type. Otherwise, returns
``False``.
"""
accept = self.accept
@@ -644,8 +644,8 @@ class Request(object):
Returns:
str: The client's preferred media type, based on the Accept
header. Returns ``None`` if the client does not accept any
of the given types.
header. Returns ``None`` if the client does not accept any
of the given types.
"""
try:
@@ -668,7 +668,7 @@ class Request(object):
Returns:
str: The value of the specified header if it exists, or ``None`` if
the header is not found and is not required.
the header is not found and is not required.
Raises:
HTTPBadRequest: The header was not found in the request, but
@@ -715,7 +715,7 @@ class Request(object):
Returns:
datetime: The value of the specified header if it exists,
or ``None`` if the header is not found and is not required.
or ``None`` if the header is not found and is not required.
Raises:
HTTPBadRequest: The header was not found in the request, but
@@ -766,7 +766,7 @@ class Request(object):
Returns:
str: The value of the param as a string, or ``None`` if param is
not found and is not required.
not found and is not required.
Raises:
HTTPBadRequest: A required param is missing from the request.
@@ -817,8 +817,8 @@ class Request(object):
Returns:
int: The value of the param if it is found and can be converted to
an integer. If the param is not found, returns ``None``, unless
`required` is ``True``.
an integer. If the param is not found, returns ``None``, unless
`required` is ``True``.
Raises
HTTPBadRequest: The param was not found in the request, even though
@@ -888,8 +888,8 @@ class Request(object):
Returns:
bool: The value of the param if it is found and can be converted
to a ``bool``. If the param is not found, returns ``None``
unless required is ``True``.
to a ``bool``. If the param is not found, returns ``None``
unless required is ``True``.
Raises:
HTTPBadRequest: A required param is missing from the request.
@@ -949,12 +949,12 @@ class Request(object):
Returns:
list: The value of the param if it is found. Otherwise, returns
``None`` unless required is True. Empty list elements will be
discarded. For example, the following query strings would
both result in `['1', '3']`::
``None`` unless required is True. Empty list elements will be
discarded. For example, the following query strings would
both result in `['1', '3']`::
things=1,,3
things=1&things=&things=3
things=1,,3
things=1&things=&things=3
Raises:
HTTPBadRequest: A required param is missing from the request.
@@ -1015,9 +1015,9 @@ class Request(object):
``None``).
Returns:
datetime.date: The value of the param if it is found and can be
converted to a ``date`` according to the supplied format
string. If the param is not found, returns ``None`` unless
required is ``True``.
converted to a ``date`` according to the supplied format
string. If the param is not found, returns ``None`` unless
required is ``True``.
Raises:
HTTPBadRequest: A required param is missing from the request.
@@ -1057,7 +1057,7 @@ class Request(object):
Returns:
dict: The value of the param if it is found. Otherwise, returns
``None`` unless required is ``True``.
``None`` unless required is ``True``.
Raises:
HTTPBadRequest: A required param is missing from the request.

8
falcon/request_helpers.py
View File

@@ -83,7 +83,7 @@ class Body(object):
will be called to actually do the work.
Returns:
Data read from the stream, as returned by `target`.
bytes: Data read from the stream, as returned by `target`.
"""
@@ -104,7 +104,7 @@ class Body(object):
Defaults to reading until EOF.
Returns:
Data read from the stream.
bytes: Data read from the stream.
"""
@@ -118,7 +118,7 @@ class Body(object):
Defaults to reading until EOF.
Returns:
Data read from the stream.
bytes: Data read from the stream.
"""
@@ -132,7 +132,7 @@ class Body(object):
Defaults to reading until EOF.
Returns:
Data read from the stream.
bytes: Data read from the stream.
"""

12
falcon/util/misc.py
View File

@@ -95,7 +95,7 @@ def http_now():
Returns:
str: The current UTC time as an IMF-fixdate,
e.g., 'Tue, 15 Nov 1994 12:45:26 GMT'.
e.g., 'Tue, 15 Nov 1994 12:45:26 GMT'.
"""
return dt_to_http(utcnow())
@@ -128,7 +128,7 @@ def http_date_to_dt(http_date, obs_date=False):
Returns:
datetime: A UTC datetime instance corresponding to the given
HTTP date.
HTTP date.
Raises:
ValueError: http_date doesn't match any of the available time formats
@@ -180,8 +180,8 @@ def to_query_str(params, comma_delimited_lists=True, prefix=True):
Returns:
str: A URI query string, including the '?' prefix (unless
`prefix` is ``False``), or an empty string if no params are
given (the ``dict`` is empty).
`prefix` is ``False``), or an empty string if no params are
given (the ``dict`` is empty).
"""
if not params:
@@ -226,8 +226,8 @@ def get_bound_method(obj, method_name):
method_name: Name of the method to retrieve.
Returns:
Bound method, or ``None`` if the method does not exist on
the object.
Bound method, or ``None`` if the method does not exist on
the object.
Raises:
AttributeError: The method exists, but it isn't

2
falcon/util/time.py
View File

@@ -26,7 +26,7 @@ class TimezoneGMT(datetime.tzinfo):
Returns:
datetime.timedelta: GMT offset, which is equivalent to UTC and
so is aways 0.
so is aways 0.
"""
return self.GMT_ZERO

18
falcon/util/uri.py
View File

@@ -128,7 +128,7 @@ Args:
Returns:
str: An escaped version of `uri`, where all disallowed characters
have been percent-encoded.
have been percent-encoded.
"""
@@ -160,7 +160,7 @@ Args:
Returns:
str: An escaped version of `uri`, where all disallowed characters
have been percent-encoded.
have been percent-encoded.
"""
@@ -183,8 +183,8 @@ if six.PY2:
Returns:
str: A decoded URL. Will be of type ``unicode`` on Python 2 IFF the
URL contained escaped non-ASCII characters, in which case
UTF-8 is assumed per RFC 3986.
URL contained escaped non-ASCII characters, in which case
UTF-8 is assumed per RFC 3986.
"""
@@ -318,8 +318,8 @@ def parse_query_string(query_string, keep_blank_qs_values=False,
Returns:
dict: A dictionary of (*name*, *value*) pairs, one per query
parameter. Note that *value* may be a single ``str``, or a
``list`` of ``str``.
parameter. Note that *value* may be a single ``str``, or a
``list`` of ``str``.
Raises:
TypeError: `query_string` was not a ``str``.
@@ -390,9 +390,9 @@ def parse_host(host, default_port=None):
Returns:
tuple: A parsed (*host*, *port*) tuple from the given
host string, with the port converted to an ``int``.
If the host string does not specify a port, `default_port` is
used instead.
host string, with the port converted to an ``int``.
If the host string does not specify a port, `default_port` is
used instead.
"""