doc(API): Improve req, resp param descriptions and related docs (#1003)
This commit is contained in:

committed by
John Vrbanac

parent
ee89b7c9ff
commit
d43d295c6e
@@ -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:
|
||||
|
@@ -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
|
||||
|
@@ -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
|
||||
|
@@ -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
|
||||
|
Reference in New Issue
Block a user