From c2cb7091e28680671cb9092bf5f8a1840f6e6308 Mon Sep 17 00:00:00 2001 From: Kurt Griffiths Date: Thu, 8 Sep 2016 13:55:47 -0600 Subject: [PATCH] doc: Unindent additional Return lines to work around napolean bug (#892) 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. --- falcon/api.py | 6 +++--- falcon/api_helpers.py | 2 +- falcon/http_error.py | 7 ++++--- falcon/request.py | 40 +++++++++++++++++++-------------------- falcon/request_helpers.py | 8 ++++---- falcon/util/misc.py | 12 ++++++------ falcon/util/time.py | 2 +- falcon/util/uri.py | 18 +++++++++--------- 8 files changed, 48 insertions(+), 47 deletions(-) diff --git a/falcon/api.py b/falcon/api.py index 2f1e455..853abb1 100644 --- a/falcon/api.py +++ b/falcon/api.py @@ -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: diff --git a/falcon/api_helpers.py b/falcon/api_helpers.py index a6a1b6c..9f91608 100644 --- a/falcon/api_helpers.py +++ b/falcon/api_helpers.py @@ -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 diff --git a/falcon/http_error.py b/falcon/http_error.py index dc4ebfe..9f7ee34 100644 --- a/falcon/http_error.py +++ b/falcon/http_error.py @@ -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. """ diff --git a/falcon/request.py b/falcon/request.py index dd49159..b063321 100644 --- a/falcon/request.py +++ b/falcon/request.py @@ -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. diff --git a/falcon/request_helpers.py b/falcon/request_helpers.py index 545dbe5..dda7837 100644 --- a/falcon/request_helpers.py +++ b/falcon/request_helpers.py @@ -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. """ diff --git a/falcon/util/misc.py b/falcon/util/misc.py index a31d598..03f3510 100644 --- a/falcon/util/misc.py +++ b/falcon/util/misc.py @@ -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 diff --git a/falcon/util/time.py b/falcon/util/time.py index 53809c2..4d19c3c 100644 --- a/falcon/util/time.py +++ b/falcon/util/time.py @@ -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 diff --git a/falcon/util/uri.py b/falcon/util/uri.py index 47726da..959b2c9 100644 --- a/falcon/util/uri.py +++ b/falcon/util/uri.py @@ -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. """