doc(API): Improve req, resp param descriptions and related docs (#1003)

This commit is contained in:
Kurt Griffiths
2017-02-21 14:27:22 -07:00
committed by John Vrbanac
parent ee89b7c9ff
commit d43d295c6e
4 changed files with 50 additions and 17 deletions

View File

@@ -1,7 +1,7 @@
.. _api:
API Class
=========
The API Class
=============
Falcon's API class is a WSGI "application" that you can host with any
standard-compliant WSGI server.
@@ -10,7 +10,7 @@ standard-compliant WSGI server.
import falcon
api = application = falcon.API()
app = falcon.API()
.. autoclass:: falcon.API
:members:

View File

@@ -7,6 +7,10 @@ The *falcon.routing* module contains utilities used internally by
:py:meth:`falcon.API` to route requests. They are exposed here for use by
custom routing engines.
Custom routers may derive from the default :py:class:`~.CompiledRouter`
engine, or implement a completely different routing strategy (such as
object-based routing).
A custom router is any class that implements the following interface:
.. code:: python

View File

@@ -291,28 +291,47 @@ class API(object):
which HTTP method they handle, as in `on_get`, `on_post`, `on_put`,
etc.
If your resource does not support a particular
HTTP method, simply omit the corresponding responder and
Falcon will reply with "405 Method not allowed" if that
method is ever requested.
Note:
If your resource does not support a particular
HTTP method, simply omit the corresponding responder and
Falcon will reply with "405 Method not allowed" if that
method is ever requested.
Responders must always define at least two arguments to receive
request and response objects, respectively. For example::
:class:`~.Request` and :class:`~.Response` objects, respectively.
For example::
def on_post(self, req, resp):
pass
In addition, if the route's template contains field
expressions, any responder that desires to receive requests
for that route must accept arguments named after the respective
field names defined in the template. A field expression consists
of a bracketed field name.
The :class:`~.Request` object represents the incoming HTTP
request. It exposes properties and methods for examining headers,
query string parameters, and other metadata associated with
the request. A file-like stream is also provided for reading
any data that was included in the body of the request.
The :class:`~.Response` object represents the application's
HTTP response to the above request. It provides properties
and methods for setting status, header and body data. The
:class:`~.Response` object also exposes a dict-like
:attr:`~.Response.context` property for passing arbitrary
data to hooks and middleware methods. This property could be
used, for example, to provide a resource representation to a
middleware component that would then serialize the
representation according to the client's preferred media type.
Note:
Since field names correspond to argument names in responder
methods, they must be valid Python identifiers.
Rather than directly manipulate the :class:`~.Response`
object, a responder may raise an instance of either
:class:`~.HTTPError` or :class:`~.HTTPStatus`.
For example, given the following template::
In addition to the standard `req` and `resp` parameters, if the
route's template contains field expressions, any responder that
desires to receive requests for that route must accept arguments
named after the respective field names defined in the template.
A field expression consists of a bracketed field name. For
example, given the following template::
/user/{name}
@@ -326,6 +345,10 @@ class API(object):
/repos/{org}/{repo}/compare/{usr0}:{branch0}...{usr1}:{branch1}
Note:
Because field names correspond to argument names in responder
methods, they must be valid Python identifiers.
Args:
uri_template (str): A templatized URI. Care must be
taken to ensure the template does not mask any sink

View File

@@ -185,7 +185,13 @@ class Request(object):
content_length (int): Value of the Content-Length header converted
to an ``int``, or ``None`` if the header is missing.
stream: File-like input object for reading the body of the
request, if any. Since this object is provided by the WSGI
request, if any. This object provides direct access to the
server's data stream and is non-seekable. In order to
avoid unintended side effects, and to provide maximum
flexibility to the application, Falcon itself does not
buffer or spool the data in any way.
Since this object is provided by the WSGI
server itself, rather than by Falcon, it may behave
differently depending on how you host your app. For example,
attempting to read more bytes than are expected (as