Python Falcon 简明教程

Python Falcon - Request & Response

HTTP 协议指出，客户端向服务器发送一个 HTTP 请求，该请求中应用了某些业务逻辑，然后生成响应并将其重定向到客户端。如果在这两个之间进行同步传输，Python 框架会使用 WSGI 标准，而异步传输遵循 ASGI 标准。Falcon 支持这两种标准。

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

WSGI/ASGI 服务器在上下文数据中提供 Request 和 Response 对象。这些对象被响应者、钩子、中间件等用作参数。对于 WSGI 应用程序，它处理 falcon.Request 类的实例。在 ASGI 应用程序中，它表示 falcon.asgi.Request 类。虽然这两类不同，但它们被设计为具有相似的属性和方法，以便最大限度地减少混淆并实现更简单的移植。

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 portability.

Request

Request 对象表示 HTTP 请求。由于它是由服务器提供的，因此该对象不应由响应者方法直接实例化。此对象提供了以下属性和方法，供响应者、钩子和中间件方法在其中使用 -

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 −

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

  2. host − Host request header field

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

  4. uri − The fully-qualified URI for the request.

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

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

  7. cookies − A dict of name/value cookie pairs.

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

  9. stream − File-like 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.

  10. bounded_stream − file-like wrapper around stream

  11. headers − Raw HTTP headers from the request

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

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

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

  15. get_param(name) − Return the raw value of a query string parameter as a string. If an HTML form with application/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 functionality, set auto_parse_form_urlencoded to True via App.req_options.

Response

Response 对象表示服务器对客户端的 HTTP 响应。与 Request 对象一样，Response 对象也不应该由应答者直接实例化。

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

应答者、hook 函数或中间件方法通过访问以下属性和方法来操作该对象−

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

  1. status − HTTP status code e.g., '200 OK'. This may be set to a member of http.HTTPStatus, an HTTP status line 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.

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

  3. text − A string representing response content.

  4. body − Deprecated alias for text.

  5. data − A Byte string representing response content.

  6. stream − A file-like object representing response content.

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

  8. 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.

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

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

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

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

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

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

  15. 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.