mirror of
https://github.com/servo/servo.git
synced 2025-06-24 00:54:32 +01:00
111 lines
3.9 KiB
ReStructuredText
111 lines
3.9 KiB
ReStructuredText
Handlers
|
|
========
|
|
|
|
Handlers are functions that have the general signature::
|
|
|
|
handler(request, response)
|
|
|
|
It is expected that the handler will use information from
|
|
the request (e.g. the path) either to populate the response
|
|
object with the data to send, or to directly write to the
|
|
output stream via the ResponseWriter instance associated with
|
|
the request. If a handler writes to the output stream then the
|
|
server will not attempt additional writes, i.e. the choice to write
|
|
directly in the handler or not is all-or-nothing.
|
|
|
|
A number of general-purpose handler functions are provided by default:
|
|
|
|
.. _handlers.Python:
|
|
|
|
Python Handlers
|
|
---------------
|
|
|
|
Python handlers are functions which provide a higher-level API over
|
|
manually updating the response object, by causing the return value of
|
|
the function to provide (part of) the response. There are three
|
|
possible sets of values that may be returned::
|
|
|
|
|
|
(status, headers, content)
|
|
(headers, content)
|
|
content
|
|
|
|
Here `status` is either a tuple (status code, message) or simply a
|
|
integer status code, `headers` is a list of (field name, value) pairs,
|
|
and `content` is a string or an iterable returning strings. Such a
|
|
function may also update the response manually. For example one may
|
|
use `response.headers.set` to set a response header, and only return
|
|
the content. One may even use this kind of handler, but manipulate
|
|
the output socket directly, in which case the return value of the
|
|
function, and the properties of the response object, will be ignored.
|
|
|
|
The most common way to make a user function into a python handler is
|
|
to use the provided `wptserve.handlers.handler` decorator::
|
|
|
|
from wptserve.handlers import handler
|
|
|
|
@handler
|
|
def test(request, response):
|
|
return [("X-Test": "PASS"), ("Content-Type", "text/plain")], "test"
|
|
|
|
#Later, assuming we have a Router object called 'router'
|
|
|
|
router.register("GET", "/test", test)
|
|
|
|
JSON Handlers
|
|
-------------
|
|
|
|
This is a specialisation of the python handler type specifically
|
|
designed to facilitate providing JSON responses. The API is largely
|
|
the same as for a normal python handler, but the `content` part of the
|
|
return value is JSON encoded, and a default Content-Type header of
|
|
`application/json` is added. Again this handler is usually used as a
|
|
decorator::
|
|
|
|
from wptserve.handlers import json_handler
|
|
|
|
@json_handler
|
|
def test(request, response):
|
|
return {"test": "PASS"}
|
|
|
|
Python File Handlers
|
|
--------------------
|
|
|
|
Python file handlers are designed to provide a vaguely PHP-like interface
|
|
where each resource corresponds to a particular python file on the
|
|
filesystem. Typically this is hooked up to a route like ``("*",
|
|
"*.py", python_file_handler)``, meaning that any .py file will be
|
|
treated as a handler file (note that this makes python files unsafe in
|
|
much the same way that .php files are when using PHP).
|
|
|
|
Unlike PHP, the python files don't work by outputting text to stdout
|
|
from the global scope. Instead they must define a single function
|
|
`main` with the signature::
|
|
|
|
main(request, response)
|
|
|
|
This function then behaves just like those described in
|
|
:ref:`handlers.Python` above.
|
|
|
|
asis Handlers
|
|
-------------
|
|
|
|
These are used to serve files as literal byte streams including the
|
|
HTTP status line, headers and body. In the default configuration this
|
|
handler is invoked for all files with a .asis extension.
|
|
|
|
File Handlers
|
|
-------------
|
|
|
|
File handlers are used to serve static files. By default the content
|
|
type of these files is set by examining the file extension. However
|
|
this can be overridden, or additional headers supplied, by providing a
|
|
file with the same name as the file being served but an additional
|
|
.headers suffix, i.e. test.html has its headers set from
|
|
test.html.headers. The format of the .headers file is plaintext, with
|
|
each line containing::
|
|
|
|
Header-Name: header_value
|
|
|
|
In addition headers can be set for a whole directory of files (but not
|
|
subdirectories), using a file called `__dir__.headers`.
|