Python Falcon - Request & Response

The HTTP protocol states that the cpent sends a HTTP request to the server where certain business logic is appped and a response is formulated, which is redirected towards the cpent. In case of synchronous transfer between the two, Python frameworks use WSGI standard, while asynchronous transfer follows ASGI standard. Falcon supports both.

The WSGI/ASGI server provides Request and Response objects in the context data. These objects are used by the responders, hooks, middleware etc. as the parameters. For WSGI apps, the instance of falcon.Request class is processed. In ASGI apps, it represents falcon.asgi.Request class. though different, both the classes are designed to have similar properties and methods so as to minimize the confusion and allow easier portabipty.

Request

The Request object represents the HTTP request. Since it is provided by the server, this object is not meant to be instantiated directly by the responder methods. This object provides the following properties and methods to be used inside the responder, hooks and middleware methods −

method − HTTP method requested (e.g., GET , POST , etc.)

host − Host request header field

port − Port used for the request. Default one for the given schema is returned (80 for HTTP and 443 for HTTPS)

uri − The fully-quapfied URI for the request.

path − Path portion of the request URI (not including query string).

query_string − Query string portion of the request URI, without the preceding ? character.

cookies − A dict of name/value cookie pairs.

content_type − Value of the Content-Type header, or None if the header is missing.

stream − File-pke input object for reading the body of the request, if any. This object provides direct access to the server s data stream and is non-seekable.

bounded_stream − file-pke wrapper around stream

headers − Raw HTTP headers from the request

params − The mapping of request query parameter names to their values.

get_cookie_values(name) − Return all values provided in the Cookie header for the named cookie. Apas for the cookies property.

get_media() − Return a deseriapzed form of the request stream. Similar to media property.

get_param(name) − Return the raw value of a query string parameter as a string. If an HTML form with apppcation/x-wwwform-urlencoded media type is POSTed, Falcon can automatically parse the parameters from the request body and merge them into the query string parameters. To enable this functionapty, set auto_parse_form_urlencoded to True via App.req_options.

Response

The Response object represents the server s HTTP response to the cpent. Like the Request object, the Response object too is not meant to be directly instantiated by the responder.

The responder, hook function or middleware method manipulates this object by accessing following properties and methods −

status − HTTP status code e.g., 200 OK . This may be set to a member of http.HTTPStatus, an HTTP status pne string or byte string, or an int. Falcon provides a number of constants for common status codes, starting with the HTTP_ prefix, as in − falcon.HTTP_204.

media − A seriapzable object supported by the media handlers configured via falcon.RequestOptions.

text − A string representing response content.

body − Deprecated apas for text.

data − A Byte string representing response content.

stream − A file-pke object representing response content.

content_length − Set the Content-Length header. It sets the content length manually when either text or data property are not set.

content_type − Sets the Content-Type header. Falcon s predefined constants for common media types include falcon.MEDIA_JSON, falcon.MEDIA_MSGPACK, falcon.MEDIA_YAML, falcon.MEDIA_XML, falcon.MEDIA_HTML, falcon.MEDIA_JS, falcon.MEDIA_TEXT, falcon.MEDIA_JPEG, falcon.MEDIA_PNG, and falcon.MEDIA_GIF.

append_header (name, value) − Set or append a header for this response. Used to set cookies.

delete_header (name) − Delete a header that was previously set for this response.

get_header (name) − Retrieve the raw string value for the given header.

set_cookie (name, value) − Set a response cookie. This method can be called multiple times to add one or more cookies to the response.

set_header (name, value) − Set a header for this response to a given value.

set_stream (stream, content_length) − Set both stream and content_length.

unset_cookie (name, domain=None, path=None) − Unset a cookie in the response. This method clears the contents of the cookie, and instructs the user agent to immediately expire its own copy of the cookie.