openstack/deb-python-falcon
Code Issues Proposed changes

doc(API): Cleaned up API docstrings

Browse Source 
Brought docstrings up to date, added type annotations, and clarified some
confusing text.
This commit is contained in:
kgriffs
2014-04-07 19:01:22 -05:00
parent 016843ab58
commit 064474d89c
2 changed files with 72 additions and 68 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
doc/api/api.rst
View File

@@ -4,7 +4,7 @@ API Class
=========
Falcon's API class is a WSGI callable "application" that you can host with any
of a number of WSGI servers.
standard-compliant WSGI server.
.. code:: python

138
falcon/api.py
View File

@@ -26,10 +26,22 @@ from falcon import DEFAULT_MEDIA_TYPE
class API(object):
"""Provides routing and such for building a web service application
"""This class is the main entry point into a Falcon-based app.
This class is the main entry point into a Falcon-based app. It provides a
callable WSGI interface and a simple routing engine based on URI templates.
Each API instance provides a callable WSGI interface and a simple routing
engine based on URI Templates (RFC 6570).
Args:
media_type (str, optional): Default media type to use as the value for
the Content-Type header on responses. (default 'application/json')
before (callable, optional): A global action hook (or list of hooks)
to call before each on_* responder, for all resources. Similar to
the ``falcon.before`` decorator, but applies to the entire API.
When more than one hook is given, they will be executed
in natural order (starting with the first in the list).
after (callable, optional): A global action hook (or list of hooks)
to call after each on_* responder, for all resources. Similar to
the ``after`` decorator, but applies to the entire API.
"""
@@ -37,22 +49,6 @@ class API(object):
'_routes', '_default_route', '_sinks')
def __init__(self, media_type=DEFAULT_MEDIA_TYPE, before=None, after=None):
"""Initialize a new Falcon API instances
Args:
media_type: Default media type to use as the value for the
Content-Type header on responses. (default 'application/json')
before: A global action hook (or list of hooks) to call before
each on_* responder, for all resources. Similar to the
'falcon.before' decorator, but applies to the entire API. When
more than one action function is given, they will be executed
in natural order (starting with the first in the list).
after: A global action hook (or list of hooks) to call after each
on_* responder, for all resources. Similar to the 'after'
decorator, but applies to the entire API.
"""
self._routes = []
self._sinks = []
self._default_route = None
@@ -64,14 +60,18 @@ class API(object):
self._error_handlers = []
def __call__(self, env, start_response):
"""WSGI "app" method
"""WSGI `app` method.
Makes instances of API callable by any WSGI server. See also PEP 333.
Makes instances of API callable from a WSGI server. May be used to
host an API or called directly in order to simulate requests when
testing the API.
See also PEP 3333.
Args:
env: A WSGI environment dictionary
start_response: A WSGI helper method for setting status and
headers on a response.
env (dict): A WSGI environment dictionary
start_response (callable): A WSGI helper function for setting
status and headers on a response.
"""
@@ -142,7 +142,7 @@ class API(object):
return body
def add_route(self, uri_template, resource):
"""Associate a URI path with a resource
"""Associates a URI path with a resource.
A resource is an instance of a class that defines various on_*
"responder" methods, one for each HTTP method the resource
@@ -151,7 +151,7 @@ class API(object):
will respond with "405 Method not allowed".
Responders must always define at least two arguments to receive
request and response objects, respectively. For example:
request and response objects, respectively. For example::
def on_post(self, req, resp):
pass
@@ -160,30 +160,26 @@ class API(object):
expressions, any responder that desires to receive requests
for that route must accept arguments named after the respective
field names defined in the template. For example, given the
following uri template:
following uri template::
/das/{thing}
A PUT request to "/das/code" would be routed to:
A PUT request to "/das/code" would be routed to::
def on_put(self, req, resp, thing):
pass
If, on the other hand, the responder had been defined thus:
def on_put(self, req, resp):
pass
Args:
uri_template: Relative URI template. Currently only Level 1
uri_template (str): Relative URI template. Currently only Level 1
templates are supported. See also RFC 6570. Care must be
taken to ensure the template does not mask any sink
patterns (see also add_sink).
resource: Object which represents an HTTP/REST "resource". Falcon
will pass "GET" requests to on_get, "PUT" requests to on_put,
etc. If any HTTP methods are not supported by your resource,
simply don't define the corresponding request handlers, and
Falcon will do the right thing.
patterns (see also ``add_sink``).
resource (instance): Object which represents an HTTP/REST
"resource". Falcon will pass "GET" requests to on_get,
"PUT" requests to on_put, etc. If any HTTP methods are not
supported by your resource, simply don't define the
corresponding request handlers, and Falcon will do the right
thing.
"""
@@ -196,28 +192,28 @@ class API(object):
self._routes.insert(0, (path_template, method_map))
def add_sink(self, sink, prefix=r'/'):
"""Add a "sink" responder to the API.
"""Adds a "sink" responder to the API.
If no route matches a request, but the path in the requested URI
matches the specified prefix, Falcon will pass control to the
given sink, regardless of the HTTP method requested.
Args:
sink: A callable of the form:
sink (callable): A callable taking the form ``func(req, resp)``.
func(req, resp)
prefix: A regex string, typically starting with '/', which
prefix (str): A regex string, typically starting with '/', which
will trigger the sink if it matches the path portion of the
request's URI. Both strings and precompiled regex objects
may be specified. Characters are matched starting at the
beginning of the URI path.
Named groups are converted to kwargs and passed to
the sink as such.
Note:
Named groups are converted to kwargs and passed to
the sink as such.
If the route collides with a route's URI template, the
route will mask the sink (see also add_route).
Note:
If the route collides with a route's URI template, the
route will mask the sink (see also ``add_route``).
"""
@@ -233,16 +229,18 @@ class API(object):
# TODO(kgriffs): Remove this functionality in Falcon version 0.2.0
@util.deprecated('Please migrate to add_sink(...) ASAP.')
def set_default_route(self, default_resource):
"""DEPRECATED: Route all the unrouted requests to a default resource
"""DEPRECATED: Route all the unrouted requests to a default resource.
NOTE: If a default route is defined, all sinks are ignored.
Args:
default_resource: Object which works like an HTTP/REST resource.
Falcon will pass "GET" requests to on_get, "PUT" requests to
on_put, etc. If you want to exclude some HTTP method from the
default routing, just simply don't define the corresponding
request handlers.
default_resource (instance): Object which works like a RESTful
resource. Falcon will pass "GET" requests to on_get, "PUT"
requests to on_put, etc. If you want to exclude any HTTP
methods from the routing, simply do not define the
corresponding request handlers, and Falcon will respond
with "405 Method Not Allowed" when those methods are
requested.
"""
@@ -250,22 +248,28 @@ class API(object):
default_resource, set(), self._before, self._after)
def add_error_handler(self, exception, handler=None):
"""Adds a handler for a given exception type
"""Adds a handler for a given exception type.
Args:
exception: Whenever an exception occurs when handling a request
exception (type): Whenever an error occurs when handling a request
that is an instance of this exception class, the given
handler callable will be used to handle the exception.
handler: Callable that gets called with (ex, req, resp, params)
when there is a matching exception when handling a
request. If not specified, the handler will default to
exception.handle, in which case the method is expected to
be static (i.e., decorated with @staticmethod) and take
the same params described above.
handler (callable): A callable taking the form
``func(ex, req, resp, params)``, called
when there is a matching exception raised when handling a
request.
Note: A handler can either raise an instance of HTTPError
or modify resp manually in order to communicate information
about the issue to the client.
Note:
If not specified, the handler will default to
``exception.handle``, where ``exception`` is the error
type specified above, and ``handle`` is a static method
(i.e., decorated with @staticmethod) that accepts
the same params just described.
Note:
A handler can either raise an instance of HTTPError
or modify resp manually in order to communicate information
about the issue to the client.
"""
@@ -287,7 +291,7 @@ class API(object):
# ------------------------------------------------------------------------
def _get_responder(self, path, method):
"""Searches routes for a matching responder
"""Searches routes for a matching responder.
Args:
path: URI path to search (without query string)