openstack/deb-python-falcon
Code Issues Proposed changes

doc(reference): Standardize docstring syntax

Browse Source 
Unify the use of markup in docstrings, particulary relating to the use of
backticks and asterisks. Also clean up any remaining minor inconsistencies or
errors in the docstrings.

Closes #334
This commit is contained in:
Kurt Griffiths
2015-01-30 16:31:39 -06:00
parent 5886e6482a
commit da2bc234f8
21 changed files with 288 additions and 271 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
CONTRIBUTING.md
View File

@@ -14,6 +14,16 @@ $ tox -e py27,py33,pep8
* Docstrings are required for classes, attributes, methods, and functions.
* Docstrings should utilize the [napolean style][docstrings] in order to make them read well, regardless of whether they are viewed through `help()` or on [Read the Docs][rtd].
* Please try to be consistent with the way existing docstrings are formatted. In particular, note the use of single vs. double backticks as follows:
* Double backticks
* Inline code
* Variables
* Types
* Decorators
* Single backticks
* Methods
* Params
* Attributes
* Format non-trivial comments using your GitHub nick and one of these prefixes:
* TODO(riker): Damage report!
* NOTE(riker): Well, that's certainly good to know.

1
doc/api/api.rst
View File

@@ -14,7 +14,6 @@ standard-compliant WSGI server.
.. autoclass:: falcon.API
:members:
:undoc-members:
.. autoclass:: falcon.RequestOptions
:members:

18
doc/api/middleware.rst
View File

@@ -18,9 +18,9 @@ The middleware interface is defined as follows:
Args:
req: Request object that will eventually be
routed to an on_* responder method
routed to an on_* responder method.
resp: Response object that will be routed to
the on_* responder
the on_* responder.
"""
def process_resource(self, req, resp, resource):
@@ -28,23 +28,23 @@ The middleware interface is defined as follows:
Args:
req: Request object that will be passed to the
routed responder
routed responder.
resp: Response object that will be passed to the
responder
responder.
resource: Resource object to which the request was
routed. May be None if no route was found for
the request
the request.
"""
def process_response(self, req, resp, resource)
def process_response(self, req, resp, resource):
"""Post-processing of the response (after routing).
Args:
req: Request object
resp: Response object
req: Request object.
resp: Response object.
resource: Resource object to which the request was
routed. May be None if no route was found
for the request
for the request.
"""
Because middleware can execute before routing has occurred, if a

14
doc/user/install.rst
View File

@@ -3,14 +3,6 @@
Installation
============
Install from PyPI
-----------------
Falcon is super easy to install with pip. If you don't have pip yet,
please run—don't walk—to the
`pip website <http://www.pip-installer.org/en/latest/installing.html>`_
and get that happy little tool installed before you do anything else.
.. note::
This documentation targets the upcoming 0.2 release of Falcon,
@@ -18,6 +10,9 @@ and get that happy little tool installed before you do anything else.
``--pre`` flag with pip in order to install the Falcon 0.2 betas
and release candidates.
Install from PyPI
-----------------
If available, Falcon will compile itself with Cython for an extra
speed boost. The following will make sure Cython is installed first, and
that you always have the latest and greatest.
@@ -26,7 +21,8 @@ that you always have the latest and greatest.
$ pip install --upgrade cython falcon
If you are on PyPy, you won't need Cython, of course:
Note that if you are running on PyPy, you won't need Cython, so you can just
type:
.. code:: bash

51
falcon/api.py
View File

@@ -36,7 +36,7 @@ class API(object):
Args:
media_type (str, optional): Default media type to use as the value for
the Content-Type header on responses. (default 'application/json')
the Content-Type header on responses (default 'application/json').
middleware(object or list, optional): One or more objects
(instantiated classes) that implement the following middleware
component interface::
@@ -47,9 +47,9 @@ class API(object):
Args:
req: Request object that will eventually be
routed to an on_* responder method
routed to an on_* responder method.
resp: Response object that will be routed to
the on_* responder
the on_* responder.
\"""
def process_resource(self, req, resp, resource):
@@ -57,33 +57,36 @@ class API(object):
Args:
req: Request object that will be passed to the
routed responder
routed responder.
resp: Response object that will be passed to the
responder
responder.
resource: Resource object to which the request was
routed. May be None if no route was found for
the request
the request.
\"""
def process_response(self, req, resp, resource)
\"""Post-processing of the response (after routing).
Args:
req: Request object
resp: Response object
req: Request object.
resp: Response object.
resource: Resource object to which the request was
routed. May be None if no route was found
for the request
for the request.
\"""
See also :ref:`Middleware <middleware>`.
request_type (Request, optional): Request-like class to use instead
request_type (Request, optional): ``Request``-like class to use instead
of Falcon's default class. Among other things, this feature
affords inheriting from ``falcon.request.Request`` in order
to override the ``context_type`` class variable.
(default falcon.request.Request)
response_type (Response, optional): Response-like class to use
(default ``falcon.request.Request``)
response_type (Response, optional): ``Response``-like class to use
instead of Falcon's default class. (default
falcon.response.Response)
``falcon.response.Response``)
Attributes:
req_options (RequestOptions): A set of behavioral options related to
@@ -265,7 +268,7 @@ class API(object):
Args:
uri_template (str): A templatized URI. Care must be
taken to ensure the template does not mask any sink
patterns, if any are registered (see also ``add_sink``).
patterns, if any are registered (see also `add_sink`).
resource (instance): Object which represents a REST
resource. Falcon will pass "GET" requests to on_get,
"PUT" requests to on_put, etc. If any HTTP methods are not
@@ -311,7 +314,7 @@ class API(object):
Note:
If the prefix overlaps a registered route template,
the route will take precedence and mask the sink
(see also ``add_route``).
(see also `add_route`).
"""
@@ -349,7 +352,7 @@ class API(object):
raise falcon.HTTPError(falcon.HTTP_792)
Note:
A handler can either raise an instance of HTTPError
A handler can either raise an instance of ``HTTPError``
or modify resp manually in order to communicate
information about the issue to the client.
@@ -403,12 +406,12 @@ class API(object):
to override this behavior.
Args:
serializer (callable): A function of the form
serializer (callable): A function taking the form
``func(req, exception)``, where `req` is the request
object that was passed to the responder method, and
`exception` is an instance of falcon.HTTPError.
The function must return a tuple of the form
``(media_type, representation)``, or ``(None, None)``
`exception` is an instance of ``falcon.HTTPError``.
The function must return a ``tuple`` of the form
(*media_type*, *representation*), or (``None``, ``None``)
if the client does not support any of the
available media types.
@@ -428,7 +431,7 @@ class API(object):
Returns:
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
responder's resource instance.
@@ -583,11 +586,11 @@ class API(object):
when resp.stream is a file-like object (default None).
Returns:
* If resp.body is not *None*, returns [resp.body], encoded
* If resp.body is not ``None``, returns [resp.body], encoded
as UTF-8 if it is a Unicode string. Bytestrings are returned
as-is.
* If resp.data is not *None*, returns [resp.data]
* If resp.stream is not *None*, returns resp.stream
* If resp.data is not ``None``, returns [resp.data]
* If resp.stream is not ``None``, returns resp.stream
iterable using wsgi.file_wrapper, if possible.
* Otherwise, returns []

8
falcon/api_helpers.py
View File

@@ -86,12 +86,12 @@ def default_serialize_error(req, exception):
override this one.
Args:
req: Instance of falcon.Request
exception: Instance of falcon.HTTPError
req: Instance of ``falcon.Request``
exception: Instance of ``falcon.HTTPError``
Returns:
A tuple of the form ``(media_type, representation)``, or
``(None, None)`` if the client does not support any of the
A ``tuple`` of the form (*media_type*, *representation*), or
(``None``, ``None``) if the client does not support any of the
available media types.
"""

16
falcon/errors.py
View File

@@ -50,7 +50,7 @@ class HTTPUnauthorized(HTTPError):
description (str): Human-friendly description of the error, along with
a helpful suggestion or two.
scheme (str): Authentication scheme to use as the value of the
WWW-Authenticate header in the response (default *None*).
WWW-Authenticate header in the response (default ``None``).
kwargs (optional): Same as for ``HTTPError``.
"""
@@ -111,7 +111,7 @@ class HTTPMethodNotAllowed(OptionalRepresentation, HTTPError):
Args:
allowed_methods (list of str): Allowed HTTP methods for this
resource (e.g., ['GET', 'POST', 'HEAD']).
resource (e.g., ``['GET', 'POST', 'HEAD']``).
"""
@@ -243,9 +243,9 @@ class HTTPRequestEntityTooLarge(HTTPError):
description (str): Human-friendly description of the error, along with
a helpful suggestion or two.
retry_after (datetime or int, optional): Value for the Retry-After
header. If a datetime object, will serialize as an HTTP date.
Otherwise, a non-negative int is expected, representing the number
of seconds to wait. See also: http://goo.gl/DIrWr .
header. If a ``datetime`` object, will serialize as an HTTP date.
Otherwise, a non-negative ``int`` is expected, representing the
number of seconds to wait. See also: http://goo.gl/DIrWr .
kwargs (optional): Same as for ``HTTPError``.
"""
@@ -337,9 +337,9 @@ class HTTPServiceUnavailable(HTTPError):
description (str): Human-friendly description of the error, along with
a helpful suggestion or two.
retry_after (datetime or int): Value for the Retry-After header. If a
datetime object, will serialize as an HTTP date. Otherwise,
a non-negative int is expected, representing the number of seconds
to wait. See also: http://goo.gl/DIrWr .
``datetime`` object, will serialize as an HTTP date. Otherwise,
a non-negative ``int`` is expected, representing the number of
seconds to wait. See also: http://goo.gl/DIrWr .
kwargs (optional): Same as for ``HTTPError``.
"""

24
falcon/hooks.py
View File

@@ -29,7 +29,7 @@ def before(action):
reference to the resource class instance associated with the
request, and `params` is a dict of URI Template field names,
if any, that will be passed into the resource responder as
*kwargs*.
kwargs.
Note:
Hooks may inject extra params as needed. For example::
@@ -161,8 +161,8 @@ def _has_self(spec):
Warning:
If a method's spec lists "self", that doesn't necessarily mean
that it should be called with a "self" param; if the method
instance is bound, the caller must omit "self" on invocation.
that it should be called with a `self` param; if the method
instance is bound, the caller must omit `self` on invocation.
"""
@@ -174,13 +174,13 @@ def _wrap_with_after(action, responder, resource=None, is_method=False):
Args:
action: A function with a signature similar to a resource responder
method, taking (req, resp, resource).
method, taking the form ``func(req, resp, resource)``.
responder: The responder method to wrap.
resource: The resource affected by `action` (default None). If None,
`is_method` MUST BE True, so that the resource can be
derived from the `self` param that is passed into the wrapper
resource: The resource affected by `action` (default ``None``). If
``None``, `is_method` MUST BE True, so that the resource can be
derived from the `self` param that is passed into the wrapper.
is_method: Whether or not `responder` is an unbound method
(default False)
(default ``False``).
"""
@@ -223,13 +223,13 @@ def _wrap_with_before(action, responder, resource=None, is_method=False):
Args:
action: A function with a similar signature to a resource responder
method, taking (req, resp, resource, params)
method, taking the form ``func(req, resp, resource, params)``.
responder: The responder method to wrap
resource: The resource affected by `action` (default None). If None,
`is_method` MUST BE True, so that the resource can be
resource: The resource affected by `action` (default ``None``). If
``None``, `is_method` MUST BE True, so that the resource can be
derived from the `self` param that is passed into the wrapper
is_method: Whether or not `responder` is an unbound method
(default False)
(default ``False``)
"""

16
falcon/http_error.py
View File

@@ -54,11 +54,11 @@ class HTTPError(Exception):
title (str): Human-friendly error title (default ``None``).
description (str): Human-friendly description of the error, along with
a helpful suggestion or two (default ``None``).
headers (dict or list): A dictionary of header names and values
to set, or list of (name, value) tuples. Both names and
values must be of type str or StringType, and only character
values 0x00 through 0xFF may be used on platforms that use
wide characters.
headers (dict or list): A ``dict`` of header names and values
to set, or a ``list`` of (*name*, *value*) tuples. Both *name* and
*value* must be of type ``str`` or ``StringType``, and only
character values 0x00 through 0xFF may be used on platforms that
use wide characters.
Note:
The Content-Type header, if present, will be overridden. If
@@ -68,8 +68,8 @@ class HTTPError(Exception):
client
Note:
Falcon can process a list of tuples slightly faster
than a dict.
Falcon can process a list of ``tuple`` slightly faster
than a ``dict``.
headers (dict): Extra headers to return in the
response to the client (default ``None``).
@@ -120,7 +120,7 @@ class HTTPError(Exception):
Args:
obj_type: A dict-like type that will be used to store the
error information (default *dict*).
error information (default ``dict``).
Returns:
A dictionary populated with the error's title, description, etc.

171
falcon/request.py
View File

@@ -59,35 +59,35 @@ class Request(object):
Attributes:
protocol (str): Either 'http' or 'https'.
method (str): HTTP method requested (e.g., GET, POST, etc.)
method (str): HTTP method requested (e.g., 'GET', 'POST', etc.)
host (str): Hostname requested by the client
subdomain (str): Leftmost (i.e., most specific) subdomain from the
hostname. If only a single domain name is given, `subdomain`
will be *None*.
will be ``None``.
Note:
If the hostname in the request is an IP address, the value
for `subdomain` is undefined.
user_agent (str): Value of the User-Agent header, or *None* if the
user_agent (str): Value of the User-Agent header, or ``None`` if the
header is missing.
app (str): Name of the WSGI app (if using WSGI's notion of virtual
hosting).
env (dict): Reference to the WSGI *environ* dict passed in from the
env (dict): Reference to the WSGI environ ``dict`` passed in from the
server. See also PEP-3333.
context (dict): Dictionary to hold any data about the request which is
specific to your app (e.g. session object). Falcon itself will
not interact with this attribute after it has been initialized.
context_type (class): Class variable that determines the
factory or type to use for initializing the
``context`` attribute. By default, the framework will
`context` attribute. By default, the framework will
instantiate standard
``dict`` objects. However, You may override this behavior
by creating a custom child class of ``falcon.Request``, and
then passing that new class to ``falcon.API()`` by way of the
then passing that new class to `falcon.API()` by way of the
latter's `request_type` parameter.
uri (str): The fully-qualified URI for the request.
url (str): alias for ``uri``.
url (str): alias for `uri`.
relative_uri (str): The path + query string portion of the full URI.
path (str): Path portion of the request URL (not including query
string).
@@ -95,18 +95,19 @@ class Request(object):
the preceding '?' character.
accept (str): Value of the Accept header, or '*/*' if the header is
missing.
auth (str): Value of the Authorization header, or *None* if the header
is missing.
client_accepts_json (bool): True if the Accept header indicates that
the client is willing to receive JSON, otherwise False.
client_accepts_msgpack (bool): True if the Accept header indicates
that the client is willing to receive MessagePack, otherwise False.
client_accepts_xml (bool): True if the Accept header indicates that
the client is willing to receive XML, otherwise False.
content_type (str): Value of the Content-Type header, or *None* if
auth (str): Value of the Authorization header, or ``None`` if the
header is missing.
client_accepts_json (bool): ``True`` if the Accept header indicates
that the client is willing to receive JSON, otherwise ``False``.
client_accepts_msgpack (bool): ``True`` if the Accept header indicates
that the client is willing to receive MessagePack, otherwise
``False``.
client_accepts_xml (bool): ``True`` if the Accept header indicates that
the client is willing to receive XML, otherwise ``False``.
content_type (str): Value of the Content-Type header, or ``None`` if
the header is missing.
content_length (int): Value of the Content-Length header converted
to an int, or *None* if the header is missing.
to an ``int``, or ``None`` if the header is missing.
stream: File-like object for reading the body of the request, if any.
Note:
@@ -118,18 +119,18 @@ class Request(object):
Note also that the character encoding for fields, before
percent-encoding non-ASCII bytes, is assumed to be
UTF-8. The special "_charset_" field is ignored if present.
UTF-8. The special `_charset_` field is ignored if present.
Falcon expects form-encoded request bodies to be
encoded according to the standard W3C algorithm (see
also http://goo.gl/6rlcux).
date (datetime): Value of the Date header, converted to a
`datetime.datetime` instance. The header value is assumed to
``datetime`` instance. The header value is assumed to
conform to RFC 1123.
expect (str): Value of the Expect header, or *None* if the
expect (str): Value of the Expect header, or ``None`` if the
header is missing.
range (tuple of int): A 2-member tuple parsed from the value of the
range (tuple of int): A 2-member ``tuple`` parsed from the value of the
Range header.
The two members correspond to the first and last byte
@@ -141,15 +142,15 @@ class Request(object):
Only continous ranges are supported (e.g., "bytes=0-0,-1" would
result in an HTTPBadRequest exception when the attribute is
accessed.)
if_match (str): Value of the If-Match header, or *None* if the
if_match (str): Value of the If-Match header, or ``None`` if the
header is missing.
if_none_match (str): Value of the If-None-Match header, or *None*
if_none_match (str): Value of the If-None-Match header, or ``None``
if the header is missing.
if_modified_since (str): Value of the If-Modified-Since header, or
None if the header is missing.
``None`` if the header is missing.
if_unmodified_since (str): Value of the If-Unmodified-Sinc header,
or *None* if the header is missing.
if_range (str): Value of the If-Range header, or *None* if the
or ``None`` if the header is missing.
if_range (str): Value of the If-Range header, or ``None`` if the
header is missing.
headers (dict): Raw HTTP headers from the request with
@@ -157,7 +158,7 @@ class Request(object):
to create this dict is done the first time this attribute
is accessed. This parsing can be costly, so unless you
need all the headers in this format, you should use the
``get_header`` method or one of the convenience attributes
`get_header` method or one of the convenience attributes
instead, to get a value for a specific header.
params (dict): The mapping of request query parameter names to their
@@ -488,9 +489,9 @@ class Request(object):
media_type (str): An Internet media type to check.
Returns:
bool: True if the client has indicated in the Accept header that
it accepts the specified media type. Otherwise, returns
False.
bool: ``True`` if the client has indicated in the Accept header
that it accepts the specified media type. Otherwise, returns
``False``.
"""
accept = self.accept
@@ -516,7 +517,7 @@ 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
header. Returns ``None`` if the client does not accept any
of the given types.
"""
@@ -534,12 +535,12 @@ class Request(object):
Args:
name (str): Header name, case-insensitive (e.g., 'Content-Type')
required (bool, optional): Set to True to raise HttpBadRequest
instead of returning gracefully when the header is not found
(default False).
required (bool, optional): Set to ``True`` to raise
``HTTPBadRequest`` instead of returning gracefully when the
header is not found (default ``False``).
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.
Raises:
@@ -589,20 +590,20 @@ class Request(object):
Note:
Similar to the way multiple keys in form data is handled,
if a query parameter is assigned a comma-separated list of
values (e.g., foo=a,b,c), only one of those values will be
values (e.g., 'foo=a,b,c'), only one of those values will be
returned, and it is undefined which one. Use
`req.get_param_as_list()` to retrieve all the values.
Args:
name (str): Parameter name, case-sensitive (e.g., 'sort')
required (bool, optional): Set to True to raise HTTPBadRequest
instead of returning gracefully when the parameter is not
found (default False)
store (dict, optional): A dict-like object in which to place the
value of the param, but only if the param is present.
name (str): Parameter name, case-sensitive (e.g., 'sort').
required (bool, optional): Set to ``True`` to raise
``HTTPBadRequest`` instead of returning ``None`` when the
parameter is not found (default ``False``).
store (dict, optional): A ``dict``-like object in which to place
the value of the param, but only if the param is present.
Returns:
string: 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.
Raises:
@@ -637,24 +638,25 @@ class Request(object):
"""Return the value of a query string parameter as an int.
Args:
name (str): Parameter name, case-sensitive (e.g., 'limit')
required (bool, optional): Set to True to raise HTTPBadRequest
instead of returning gracefully when the parameter is not
found or is not an integer (default False).
name (str): Parameter name, case-sensitive (e.g., 'limit').
required (bool, optional): Set to ``True`` to raise
``HTTPBadRequest`` instead of returning ``None`` when the
parameter is not found or is not an integer (default
``False``).
min (int, optional): Set to the minimum value allowed for this
param. If the param is found and it is less than min, an
HTTPError is raised.
``HTTPError`` is raised.
max (int, optional): Set to the maximum value allowed for this
param. If the param is found and its value is greater than
max, an HTTPError is raised.
store (dict, optional): A dict-like object in which to place the
value of the param, but only if the param is found (default
*None*).
max, an ``HTTPError`` is raised.
store (dict, optional): A ``dict``-like object in which to place
the value of the param, but only if the param is found
(default ``None``).
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
@@ -701,27 +703,31 @@ class Request(object):
blank_as_true=False):
"""Return the value of a query string parameter as a boolean
The following bool-like strings are supported::
The following boolean strings are supported::
TRUE_STRINGS = ('true', 'True', 'yes')
FALSE_STRINGS = ('false', 'False', 'no')
Args:
name (str): Parameter name, case-sensitive (e.g., 'limit')
required (bool, optional): Set to True to raise HTTPBadRequest
instead of returning gracefully when the parameter is not
found or is not a recognized bool-ish string (default False).
store (dict, optional): A dict-like object in which to place the
value of the param, but only if the param is found (default
*None*).
blank_as_true (bool): If True, empty strings will be treated as
True. keep_blank_qs_values must be set on the Request (or API
object and inherited) for empty strings to not be filtered.
name (str): Parameter name, case-sensitive (e.g., 'detailed').
required (bool, optional): Set to ``True`` to raise
``HTTPBadRequest`` instead of returning ``None`` when the
parameter is not found or is not a recognized boolean
string (default ``False``).
store (dict, optional): A ``dict``-like object in which to place
the value of the param, but only if the param is found (default
``None``).
blank_as_true (bool): If ``True``, an empty string value will be
treated as ``True``. Normally empty strings are ignored, so
if you would like to recognize them, you must set the
`keep_blank_qs_values` request option to ``True``. Request
options are set globally for each instance of
``falcon.API`` through that instance's `req_options` attribute.
Returns:
bool: The value of the param if it is found and can be converted
to a boolean. 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.
@@ -766,22 +772,22 @@ class Request(object):
ala *application/x-www-form-urlencoded*.
Args:
name (str): Parameter name, case-sensitive (e.g., 'limit')
name (str): Parameter name, case-sensitive (e.g., 'ids').
transform (callable, optional): An optional transform function
that takes as input each element in the list as a string and
that takes as input each element in the list as a ``str`` and
outputs a transformed element for inclusion in the list that
will be returned. For example, passing the int function will
will be returned. For example, passing ``int`` will
transform list items into numbers.
required (bool, optional): Set to True to raise HTTPBadRequest
instead of returning gracefully when the parameter is not
found or is not an integer (default False)
store (dict, optional): A dict-like object in which to place the
value of the param, but only if the param is found (default
*None*).
required (bool, optional): Set to ``True`` to raise
``HTTPBadRequest`` instead of returning ``None`` when the
parameter is not found (default ``False``).
store (dict, optional): A ``dict``-like object in which to place
the value of the param, but only if the param is found (default
``None``).
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 a query string containing this::
things=1,,3
@@ -796,6 +802,8 @@ class Request(object):
Raises:
HTTPBadRequest: A required param is missing from the request.
HTTPInvalidParam: A tranform function raised an instance of
``ValueError``.
"""
@@ -841,9 +849,8 @@ class Request(object):
result out to the WSGI server's error stream (`wsgi.error`).
Args:
message (str): A string describing the problem. If a byte-string,
it is simply written out as-is. Unicode strings will be
converted to UTF-8.
message (str or unicode): Description of the problem. On Python 2,
instances of ``unicode`` will be converted to UTF-8.
"""
@@ -917,11 +924,11 @@ class Request(object):
# PERF: To avoid typos and improve storage space and speed over a dict.
class RequestOptions(object):
"""This class is a container for Request options.
"""This class is a container for ``Request`` options.
Attributes:
keep_blank_qs_values (bool): Set to ``True`` in order to retain
blank values in query string parameters (default ``False``.)
blank values in query string parameters (default ``False``).
"""
__slots__ = (

15
falcon/request_helpers.py
View File

@@ -18,7 +18,7 @@ def header_property(wsgi_name):
Args:
wsgi_name (str): Case-sensitive name of the header as it would
appear in the WSGI environ dict (i.e., 'HTTP_*')
appear in the WSGI environ ``dict`` (i.e., 'HTTP_*')
Returns:
A property instance than can be assigned to a class variable.
@@ -35,20 +35,21 @@ def header_property(wsgi_name):
class Body(object):
"""Wrap wsgi.input streams to make them more robust.
"""Wrap *wsgi.input* streams to make them more robust.
The socket._fileobject and io.BufferedReader are sometimes used
to implement wsgi.input. However, app developers are often burned
by the fact that the read() method for these objects block
``socket._fileobject`` and ``io.BufferedReader`` are sometimes used
to implement *wsgi.input*. However, app developers are often burned
by the fact that the `read()` method for these objects block
indefinitely if either no size is passed, or a size greater than
the request's content length is passed to the method.
This class normalizes wsgi.input behavior between WSGI servers
This class normalizes *wsgi.input* behavior between WSGI servers
by implementing non-blocking behavior for the cases mentioned
above.
Args:
stream: Instance of socket._fileobject from environ['wsgi.input']
stream: Instance of ``socket._fileobject`` from
``environ['wsgi.input']``
stream_len: Expected content length of the stream.
"""

80
falcon/response.py
View File

@@ -50,28 +50,28 @@ class Response(object):
simply ``bytes`` in Python 3). See also the note below.
Note:
Under Python 2.x, if your content is of type *str*, using
Under Python 2.x, if your content is of type ``str``, using
the `data` attribute instead of `body` is the most
efficient approach. However, if
your text is of type *unicode*, you will need to use the
*body* attribute instead.
your text is of type ``unicode``, you will need to use the
`body` attribute instead.
Under Python 3.x, on the other hand, the 2.x *str* type can
Under Python 3.x, on the other hand, the 2.x ``str`` type can
be thought of as
having been replaced by what was once the *unicode* type,
having been replaced by what was once the ``unicode`` type,
and so you will need to always use the `body` attribute for
strings to
ensure Unicode characters are properly encoded in the
HTTP response.
stream: Either a file-like object with a *read()* method that takes
stream: Either a file-like object with a `read()` method that takes
an optional size argument and returns a block of bytes, or an
iterable object, representing response content, and yielding
blocks as byte strings. Falcon will use wsgi.file_wrapper, if
blocks as byte strings. Falcon will use *wsgi.file_wrapper*, if
provided by the WSGI server, in order to efficiently serve
file-like objects.
stream_len (int): Expected length of *stream* (e.g., file size).
stream_len (int): Expected length of `stream` (e.g., file size).
"""
__slots__ = (
@@ -125,10 +125,10 @@ class Response(object):
return self._body_encoded
def set_stream(self, stream, stream_len):
"""Convenience method for setting both stream and stream_len.
"""Convenience method for setting both `stream` and `stream_len`.
Although the stream and stream_len properties may be set
directly, using this method ensures stream_len is not
Although the `stream` and `stream_len` properties may be set
directly, using this method ensures `stream_len` is not
accidentally neglected.
"""
@@ -144,11 +144,11 @@ class Response(object):
Args:
name (str): Header name to set (case-insensitive). Must be of
type str or StringType, and only character values 0x00
type ``str`` or ``StringType``, and only character values 0x00
through 0xFF may be used on platforms that use wide
characters.
value (str): Value for the header. Must be of type str or
StringType, and only character values 0x00 through 0xFF
value (str): Value for the header. Must be of type ``str`` or
``StringType``, and only character values 0x00 through 0xFF
may be used on platforms that use wide characters.
"""
@@ -166,11 +166,11 @@ class Response(object):
Args:
name (str): Header name to set (case-insensitive). Must be of
type str or StringType, and only character values 0x00
type ``str`` or ``StringType``, and only character values 0x00
through 0xFF may be used on platforms that use wide
characters.
value (str): Value for the header. Must be of type str or
StringType, and only character values 0x00 through 0xFF
value (str): Value for the header. Must be of type ``str`` or
``StringType``, and only character values 0x00 through 0xFF
may be used on platforms that use wide characters.
"""
@@ -188,17 +188,17 @@ class Response(object):
Args:
headers (dict or list): A dictionary of header names and values
to set, or list of (name, value) tuples. Both names and
values must be of type str or StringType, and only character
values 0x00 through 0xFF may be used on platforms that use
wide characters.
to set, or ``list`` of (*name*, *value*) tuples. Both *name*
and *value* must be of type ``str`` or ``StringType``, and
only character values 0x00 through 0xFF may be used on
platforms that use wide characters.
Note:
Falcon can process a list of tuples slightly faster
than a dict.
Raises:
ValueError: headers was not a dictionary or list of tuples.
ValueError: `headers` was not a ``dict`` or ``list`` of ``tuple``.
"""
@@ -236,12 +236,12 @@ class Response(object):
Kwargs:
title (str): Human-readable label for the destination of
the link (default None). If the title includes non-ASCII
the link (default ``None``). If the title includes non-ASCII
characters, you will need to use `title_star` instead, or
provide both a US-ASCII version using `title` and a
Unicode version using `title_star`.
title_star (tuple of str): Localized title describing the
destination of the link (default None). The value must be a
destination of the link (default ``None``). The value must be a
two-member tuple in the form of (*language-tag*, *text*),
where *language-tag* is a standard language identifier as
defined in RFC 5646, Section 2.1, and *text* is a Unicode
@@ -255,7 +255,7 @@ class Response(object):
Note:
*text* will always be encoded as UTF-8. If the string
contains non-ASCII characters, it should be passed as
a "unicode" type string (requires the 'u' prefix in
a ``unicode`` type string (requires the 'u' prefix in
Python 2).
anchor (str): Override the context IRI with a different URI
@@ -263,13 +263,13 @@ class Response(object):
simply the IRI of the requested resource. The value
provided may be a relative URI.
hreflang (str or iterable): Either a single *language-tag*, or
a list or tuple of such tags to provide a hint to the client
as to the language of the result of following the link. A
list of tags may be given in order to indicate to the
a ``list`` or ``tuple`` of such tags to provide a hint to the
client as to the language of the result of following the link.
A list of tags may be given in order to indicate to the
client that the target resource is available in multiple
languages.
type_hint(str): Provides a hint as to the media type of the
result of dereferencing the link (default None). As noted
result of dereferencing the link (default ``None``). As noted
in RFC 5988, this is only a hint and does not override the
Content-Type header returned when the link is followed.
@@ -344,15 +344,15 @@ class Response(object):
'Content-Range',
"""A tuple to use in constructing a value for the Content-Range header.
The tuple has the form ``(start, end, length)``, where *start* and
The tuple has the form (*start*, *end*, *length*), where *start* and
*end* designate the byte range (inclusive), and *length* is the
total number of bytes, or '*' if unknown. You may use *int*'s for
these numbers (no need to convert to a *str* first).
total number of bytes, or '*' if unknown. You may pass ``int``'s for
these numbers (no need to convert to ``str`` beforehand).
Note:
You only need to use the alternate form, "bytes */1234", for
responses that use the status "416 Range Not Satisfiable". In this
case, raising falcon.HTTPRangeNotSatisfiable will do the right
You only need to use the alternate form, 'bytes */1234', for
responses that use the status '416 Range Not Satisfiable'. In this
case, raising ``falcon.HTTPRangeNotSatisfiable`` will do the right
thing.
See also: http://goo.gl/Iglhp
@@ -369,10 +369,10 @@ class Response(object):
last_modified = header_property(
'Last-Modified',
"""Sets the Last-Modified header. Set to a datetime (UTC) instance.
"""Sets the Last-Modified header. Set to a ``datetime`` (UTC) instance.
Note:
Falcon will format the datetime as an HTTP date.
Falcon will format the ``datetime`` as an HTTP date string.
""",
dt_to_http)
@@ -395,8 +395,8 @@ class Response(object):
"""Value to use for the Vary header.
Set this property to an iterable of header names. For a single
asterisk or field value, simply pass a single-element list or
tuple.
asterisk or field value, simply pass a single-element ``list`` or
``tuple``.
"Tells downstream proxies how to match future request headers
to decide whether the cached response can be used rather than
@@ -414,7 +414,7 @@ class Response(object):
Args:
media_type: Default media type to use for the Content-Type
header if the header was not set explicitly (default None).
header if the header was not set explicitly (default ``None``).
"""

4
falcon/response_helpers.py
View File

@@ -22,7 +22,7 @@ def header_property(name, doc, transform=None):
transform: Transformation function to use when setting the
property. The value will be passed to the function, and
the function should return the transformed value to use
as the value of the header (default None)
as the value of the header (default ``None``).
"""
normalized_name = name.lower()
@@ -50,7 +50,7 @@ def format_range(value):
"""Formats a range header tuple per the HTTP spec.
Args:
value: Tuple passed to req.range
value: ``tuple`` passed to `req.range`
"""

6
falcon/routing.py
View File

@@ -67,7 +67,7 @@ def compile_uri_template(template):
# NOTE(kgriffs): Published method; take care to avoid breaking changes.
def create_http_method_map(resource, uri_fields, before, after):
"""Maps HTTP methods (e.g., GET, POST) to methods of a resource object.
"""Maps HTTP methods (e.g., 'GET', 'POST') to methods of a resource object.
Args:
resource: An object with *responder* methods, following the naming
@@ -78,9 +78,9 @@ def create_http_method_map(resource, uri_fields, before, after):
uri_fields: A set of field names from the route's URI template
that a responder must support in order to avoid "method not
allowed".
before: An action hook or list of hooks to be called before each
before: An action hook or ``list`` of hooks to be called before each
*on_\** responder defined by the resource.
after: An action hook or list of hooks to be called after each
after: An action hook or ``list`` of hooks to be called after each
*on_\** responder defined by the resource.
Returns:

10
falcon/testing/base.py
View File

@@ -26,20 +26,20 @@ from falcon.testing.helpers import create_environ
class TestBase(unittest.TestCase):
"""Extends *testtools.TestCase* to support WSGI integration testing.
"""Extends ``testtools.TestCase`` to support WSGI integration testing.
`TestBase` provides a base class that provides some extra plumbing to
``TestBase`` provides a base class that provides some extra plumbing to
help simulate WSGI calls without having to actually host your API
in a server.
Note:
If *testtools* is not available, *unittest* is used instead.
If ``testtools`` is not available, ``unittest`` is used instead.
Attributes:
api (falcon.API): An API instance to target when simulating
requests. Defaults to ``falcon.API()``.
srmock (falcon.testing.StartResponseMock): Provides a callable
that simulates the behavior of the *start_response* argument
that simulates the behavior of the `start_response` argument
that the server would normally pass into the WSGI app. The
mock object captures various information from the app's
response to the simulated request.
@@ -84,7 +84,7 @@ class TestBase(unittest.TestCase):
Args:
path (str): The path to request.
decode (str, optional): If this is set to a character encoding,
such as "utf-8", `simulate_request` will assume the
such as 'utf-8', `simulate_request` will assume the
response is a single byte string, and will decode it as the
result of the request, rather than simply returning the
standard WSGI iterable.

15
falcon/testing/helpers.py
View File

@@ -57,32 +57,33 @@ def create_environ(path='/', query_string='', protocol='HTTP/1.1',
headers=None, app='', body='', method='GET',
wsgierrors=None, file_wrapper=None):
"""Creates a mock PEP-3333 environ dict for simulating WSGI requests.
"""Creates a mock PEP-3333 environ ``dict`` for simulating WSGI requests.
Args:
path (str, optional): The path for the request (default '/')
query_string (str, optional): The query string to simulate, without a
leading '?' (default '')
protocol (str, optional): The HTTP protocol to simulate
(default 'HTTP/1.1'). If set 'HTTP/1.0', the Host header
(default 'HTTP/1.1'). If set to 'HTTP/1.0', the Host header
will not be added to the environment.
scheme (str): URL scheme, either 'http' or 'https' (default 'http')
host(str): Hostname for the request (default 'falconframework.org')
port (str or int, optional): The TCP port to simulate. Defaults to
the standard port used by the given scheme (i.e., 80 for 'http'
and 443 for 'https').
headers (dict or list, optional): Headers as a dict or an
iterable collection of ``(key, value)`` tuples
app (str): Value for the SCRIPT_NAME environ variable, described in
headers (dict or list, optional): Headers as a ``dict`` or an
iterable collection of (*key*, *value*) ``tuple``'s
app (str): Value for the ``SCRIPT_NAME`` environ variable, described in
PEP-333: 'The initial portion of the request URL's "path" that
corresponds to the application object, so that the application
knows its virtual "location". This may be an empty string, if the
application corresponds to the "root" of the server.' (default '')
body (str or unicode): The body of the request (default '')
method (str): The HTTP method to use (default 'GET')
wsgierrors (io): The stream to use as wsgierrors (default sys.stderr)
wsgierrors (io): The stream to use as *wsgierrors*
(default ``sys.stderr``)
file_wrapper: Callable that returns an iterable, to be used as
the value for 'wsgi.file_wrapper' in the environ.
the value for *wsgi.file_wrapper* in the environ.
"""

25
falcon/testing/resource.py
View File

@@ -19,7 +19,7 @@ from .helpers import rand_string
class TestResource:
"""Mock resource for integration testing.
This class implements the *on_get* responder, captures
This class implements the `on_get` responder, captures
request data, and sets response body and headers.
Child classes may add additional methods and attributes as
@@ -30,13 +30,14 @@ class TestResource:
sample_body (str): Random body string to set in the response
resp_headers (dict): Sample headers to use in the response
req (falcon.Request): Request object passed into the *on_get*
responder
resp (falcon.Response): Response object passed into the *on_get*
responder
kwargs (dict): Keyword arguments passed into the *on_get*
responder, if any
called (bool): True if *on_get* was ever called; False otherwise
req (falcon.Request): Request object passed into the `on_get`
responder.
resp (falcon.Response): Response object passed into the `on_get`
responder.
kwargs (dict): Keyword arguments passed into the `on_get`
responder, if any.
called (bool): ``True`` if `on_get` was ever called; ``False``
otherwise.
"""
@@ -57,13 +58,13 @@ class TestResource:
def on_get(self, req, resp, **kwargs):
"""GET responder.
Captures req, resp, and kwargs. Also sets up a sample response.
Captures `req`, `resp`, and `kwargs`. Also sets up a sample response.
Args:
req: Falcon `Request` instance
resp: Falcon `Response` instance
req: Falcon ``Request`` instance.
resp: Falcon ``Response`` instance.
kwargs: URI template *name=value* pairs, if any, along with
any extra args injected by middleware
any extra args injected by middleware.
"""

10
falcon/testing/srmock.py
View File

@@ -16,16 +16,16 @@ from falcon import util
class StartResponseMock:
"""Mock object that represents a WSGI "start_response" callable.
"""Mock object representing a WSGI `start_response` callable.
Attributes:
call_count (int): Number of times start_response was called.
status (str): HTTP status line, e.g. "785 TPS Cover Sheet
not attached".
call_count (int): Number of times `start_response` was called.
status (str): HTTP status line, e.g. '785 TPS Cover Sheet
not attached'.
headers (list): Raw headers list passed to `start_response`,
per PEP-333.
headers_dict (dict): Headers as a case-insensitive
dictionary, instead of a list.
``dict``-like object, instead of a ``list``.
"""

25
falcon/util/misc.py
View File

@@ -45,7 +45,7 @@ def deprecated(instructions):
Args:
instructions (str): Specific guidance for the developer, e.g.:
"Please migrate to add_proxy(...)"
'Please migrate to add_proxy(...)''
"""
def decorator(func):
@@ -70,14 +70,13 @@ def deprecated(instructions):
def dt_to_http(dt):
"""Converts a datetime instance to an HTTP date string.
"""Converts a ``datetime`` instance to an HTTP date string.
Args:
dt (datetime): A *datetime.datetime* instance, assumed to be UTC.
dt (datetime): A ``datetime`` instance to convert, assumed to be UTC.
Returns:
str: An RFC 1123 date string, e.g.:
"Tue, 15 Nov 1994 12:45:26 GMT".
str: An RFC 1123 date string, e.g.: "Tue, 15 Nov 1994 12:45:26 GMT".
"""
@@ -102,18 +101,18 @@ def http_date_to_dt(http_date):
def to_query_str(params):
"""Converts a dict of params to a query string.
"""Converts a dictionary of params to a query string.
Args:
params (dict): A dictionary of parameters, where each key is a
parameter name, and each value is either a string or
something that can be converted into a string. If `params`
is a list, it will be converted to a comma-delimited string
of values (e.g., "thing=1,2,3")
parameter name, and each value is either a ``str`` or
something that can be converted into a ``str``. If `params`
is a ``list``, it will be converted to a comma-delimited string
of values (e.g., 'thing=1,2,3')
Returns:
str: A URI query string including the "?" prefix, or an empty string
if no params are given (the dict is empty).
str: A URI query string including the '?' prefix, or an empty string
if no params are given (the ``dict`` is empty).
"""
if not params:
@@ -145,7 +144,7 @@ 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
Bound method, or ``None`` if the method does not exist on
the object.
Raises:

4
falcon/util/structures.py
View File

@@ -24,8 +24,8 @@ class CaseInsensitiveDict(collections.MutableMapping): # pragma: no cover
A case-insensitive ``dict``-like object.
Implements all methods and operations of
``collections.MutableMapping`` as well as dict's ``copy``. Also
provides ``lower_items``.
``collections.MutableMapping`` as well as dict's `copy`. Also
provides `lower_items`.
All keys are expected to be strings. The structure remembers the
case of the last key to be set, and ``iter(instance)``,

36
falcon/util/uri.py
View File

@@ -82,12 +82,12 @@ all other "disallowed" characters by percent-encoding them.
Note:
This utility is faster in the average case than the similar
`quote` function found in urlib. It also strives to be easier
`quote` function found in ``urlib``. It also strives to be easier
to use by assuming a sensible default of allowed characters.
Args:
uri (str): URI or part of a URI to encode. If this is a wide
string (i.e., *six.text_type*), it will be encoded to
string (i.e., ``six.text_type``), it will be encoded to
a UTF-8 byte array and any multibyte sequences will
be percent-encoded as-is.
@@ -119,7 +119,7 @@ Args:
uri (str): URI fragment to encode. It is assumed not to cross delimiter
boundaries, and so any reserved URI delimiter characters
included in it will be escaped. If `value` is a wide
string (i.e., *six.text_type*), it will be encoded to
string (i.e., ``six.text_type``), it will be encoded to
a UTF-8 byte array and any multibyte sequences will
be percent-encoded as-is.
@@ -140,7 +140,7 @@ if six.PY2: # pragma: no cover
def decode(encoded_uri):
"""Decodes percent-encoded characters in a URI or query string.
This function models the behavior of urllib.parse.unquote_plus, but
This function models the behavior of `urllib.parse.unquote_plus`, but
is faster. It is also more robust, in that it will decode escaped
UTF-8 mutibyte sequences.
@@ -148,7 +148,7 @@ if six.PY2: # pragma: no cover
encoded_uri (str): An encoded URI (full or partial).
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
UTF-8 is assumed per RFC 3986.
@@ -249,31 +249,31 @@ def parse_query_string(query_string, keep_blank_qs_values=False):
"""Parse a query string into a dict.
Query string parameters are assumed to use standard form-encoding. Only
parameters with values are parsed. for example, given "foo=bar&flag",
this function would ignore "flag" unless the keep_blank_qs_values option
parameters with values are parsed. for example, given 'foo=bar&flag',
this function would ignore 'flag' unless the `keep_blank_qs_values` option
is set.
Note:
In addition to the standard HTML form-based method for specifying
lists by repeating a given param multiple times, Falcon supports
a more compact form in which the param may be given a single time
but set to a list of comma-separated elements (e.g., 'foo=a,b,c').
but set to a ``list`` of comma-separated elements (e.g., 'foo=a,b,c').
The two different ways of specifying lists may not be mixed in
a single query string for the same parameter.
Args:
query_string (str): The query string to parse
keep_blank_qs_values (bool): If set to True, preserves boolean fields
and fields with no content as blank strings.
query_string (str): The query string to parse.
keep_blank_qs_values (bool): If set to ``True``, preserves boolean
fields and fields with no content as blank strings.
Returns:
dict: A dict containing ``(name, value)`` tuples, one per query
parameter. Note that *value* will be a string or list of
strings.
dict: A dictionary of (*name*, *value*) pairs, one per query
parameter. Note that *value* may be a single ``str``, or a
``list`` of ``str``.
Raises:
TypeError: query_string was not a string or buffer
TypeError: `query_string` was not a ``str``.
"""
@@ -317,7 +317,7 @@ def parse_query_string(query_string, keep_blank_qs_values=False):
def parse_host(host, default_port=None):
"""Parse a canonical host:port string into parts.
"""Parse a canonical 'host:port' string into parts.
Parse a host string (which may or may not contain a port) into
parts, taking into account that the string may contain
@@ -331,9 +331,9 @@ def parse_host(host, default_port=None):
the host string does not contain one (default ``None``).
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``.
If the string does not specify a port, `default_port` is
If the host string does not specify a port, `default_port` is
used instead.
"""