From 064474d89c3088e189975b56fae1207d0f7b9f33 Mon Sep 17 00:00:00 2001 From: kgriffs Date: Mon, 7 Apr 2014 19:01:22 -0500 Subject: [PATCH] doc(API): Cleaned up API docstrings Brought docstrings up to date, added type annotations, and clarified some confusing text. --- doc/api/api.rst | 2 +- falcon/api.py | 138 +++++++++++++++++++++++++----------------------- 2 files changed, 72 insertions(+), 68 deletions(-) diff --git a/doc/api/api.rst b/doc/api/api.rst index 214db0a..4b42a4b 100644 --- a/doc/api/api.rst +++ b/doc/api/api.rst @@ -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 diff --git a/falcon/api.py b/falcon/api.py index 8d310f1..992e579 100644 --- a/falcon/api.py +++ b/falcon/api.py @@ -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)