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. req: The request object.
Returns: 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 a ``dict`` containing parsed path fields (if any were specified in
the matching route's URI template), and a reference to the the matching route's URI template), and a reference to the
responder's resource instance. responder's resource instance.
@@ -578,7 +578,7 @@ class API(object):
Returns: Returns:
bool: ``True`` if a handler was found and called for the 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: 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). when resp.stream is a file-like object (default None).
Returns: 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 The length is returned as ``None`` when unknown. The
iterable is determined as follows: 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 middleware: list (or object) of input middleware
Returns: Returns:
A middleware list list: A list of prepared middleware tuples
""" """
# PERF(kgriffs): do getattr calls once, in advance, so we don't # 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``). error information (default ``dict``).
Returns: 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 pretty-printed JSON representation of the error.
Returns: 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-encoded representation of the error.
Returns: 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: Returns:
bool: ``True`` if the client has indicated in the Accept header bool: ``True`` if the client has indicated in the Accept header
that it accepts the specified media type. Otherwise, returns that it accepts the specified media type. Otherwise, returns
``False``. ``False``.
""" """
accept = self.accept accept = self.accept
@@ -644,8 +644,8 @@ class Request(object):
Returns: Returns:
str: The client's preferred media type, based on the Accept str: The client's preferred media type, based on the Accept
header. Returns ``None`` if the client does not accept any header. Returns ``None`` if the client does not accept any
of the given types. of the given types.
""" """
try: try:
@@ -668,7 +668,7 @@ class Request(object):
Returns: Returns:
str: The value of the specified header if it exists, or ``None`` if 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: Raises:
HTTPBadRequest: The header was not found in the request, but HTTPBadRequest: The header was not found in the request, but
@@ -715,7 +715,7 @@ class Request(object):
Returns: Returns:
datetime: The value of the specified header if it exists, 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: Raises:
HTTPBadRequest: The header was not found in the request, but HTTPBadRequest: The header was not found in the request, but
@@ -766,7 +766,7 @@ class Request(object):
Returns: Returns:
str: The value of the param as a string, or ``None`` if param is 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: Raises:
HTTPBadRequest: A required param is missing from the request. HTTPBadRequest: A required param is missing from the request.
@@ -817,8 +817,8 @@ class Request(object):
Returns: Returns:
int: The value of the param if it is found and can be converted to 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 an integer. If the param is not found, returns ``None``, unless
`required` is ``True``. `required` is ``True``.
Raises Raises
HTTPBadRequest: The param was not found in the request, even though HTTPBadRequest: The param was not found in the request, even though
@@ -888,8 +888,8 @@ class Request(object):
Returns: Returns:
bool: The value of the param if it is found and can be converted 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`` to a ``bool``. If the param is not found, returns ``None``
unless required is ``True``. unless required is ``True``.
Raises: Raises:
HTTPBadRequest: A required param is missing from the request. HTTPBadRequest: A required param is missing from the request.
@@ -949,12 +949,12 @@ class Request(object):
Returns: Returns:
list: The value of the param if it is found. Otherwise, returns list: The value of the param if it is found. Otherwise, returns
``None`` unless required is True. Empty list elements will be ``None`` unless required is True. Empty list elements will be
discarded. For example, the following query strings would discarded. For example, the following query strings would
both result in `['1', '3']`:: both result in `['1', '3']`::
things=1,,3 things=1,,3
things=1&things=&things=3 things=1&things=&things=3
Raises: Raises:
HTTPBadRequest: A required param is missing from the request. HTTPBadRequest: A required param is missing from the request.
@@ -1015,9 +1015,9 @@ class Request(object):
``None``). ``None``).
Returns: Returns:
datetime.date: The value of the param if it is found and can be datetime.date: The value of the param if it is found and can be
converted to a ``date`` according to the supplied format converted to a ``date`` according to the supplied format
string. If the param is not found, returns ``None`` unless string. If the param is not found, returns ``None`` unless
required is ``True``. required is ``True``.
Raises: Raises:
HTTPBadRequest: A required param is missing from the request. HTTPBadRequest: A required param is missing from the request.
@@ -1057,7 +1057,7 @@ class Request(object):
Returns: Returns:
dict: The value of the param if it is found. Otherwise, returns dict: The value of the param if it is found. Otherwise, returns
``None`` unless required is ``True``. ``None`` unless required is ``True``.
Raises: Raises:
HTTPBadRequest: A required param is missing from the request. 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. will be called to actually do the work.
Returns: 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. Defaults to reading until EOF.
Returns: Returns:
Data read from the stream. bytes: Data read from the stream.
""" """
@@ -118,7 +118,7 @@ class Body(object):
Defaults to reading until EOF. Defaults to reading until EOF.
Returns: Returns:
Data read from the stream. bytes: Data read from the stream.
""" """
@@ -132,7 +132,7 @@ class Body(object):
Defaults to reading until EOF. Defaults to reading until EOF.
Returns: 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: Returns:
str: The current UTC time as an IMF-fixdate, 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()) return dt_to_http(utcnow())
@@ -128,7 +128,7 @@ def http_date_to_dt(http_date, obs_date=False):
Returns: Returns:
datetime: A UTC datetime instance corresponding to the given datetime: A UTC datetime instance corresponding to the given
HTTP date. HTTP date.
Raises: Raises:
ValueError: http_date doesn't match any of the available time formats 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: Returns:
str: A URI query string, including the '?' prefix (unless str: A URI query string, including the '?' prefix (unless
`prefix` is ``False``), or an empty string if no params are `prefix` is ``False``), or an empty string if no params are
given (the ``dict`` is empty). given (the ``dict`` is empty).
""" """
if not params: if not params:
@@ -226,8 +226,8 @@ def get_bound_method(obj, method_name):
method_name: Name of the method to retrieve. method_name: Name of the method to retrieve.
Returns: Returns:
Bound method, or ``None`` if the method does not exist on Bound method, or ``None`` if the method does not exist on
the object. the object.
Raises: Raises:
AttributeError: The method exists, but it isn't AttributeError: The method exists, but it isn't

2
falcon/util/time.py
View File

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

18
falcon/util/uri.py
View File

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