зеркало из https://github.com/mozilla/gecko-dev.git
Bug 1561172 [wpt PR 17386] - [docs] Add detail on writing Python handlers, a=testonly
Automatic update from web-platform-tests [docs] Add detail on writing Python handlers (#17386) Extend the documentation on writing Python handlers to more completely describe the feature. Introduce a short example to concretely demonstrate its usage. Apply similar changes to the corresponding documentation in the `wptserve` directory for parity. -- wpt-commits: acbefd606a1b9284b96d21a4a332d0202e36d531 wpt-pr: 17386
This commit is contained in:
jugglinmike
James Graham
Родитель
4d9cb4b0b4
Коммит
5922407bda
|
|
@ -6,10 +6,29 @@ requests made to the corresponding URL. This is hooked up to a route like
|
|||
treated as a handler file (note that this makes it easy to write unsafe
|
||||
handlers, particularly when running the server in a web-exposed setting).
|
||||
|
||||
The Python files must define a single function `main` with the signature::
|
||||
The Python files must define a function named `main` with the signature:
|
||||
|
||||
main(request, response)
|
||||
|
||||
...where `request` is [a wptserve `Request`
|
||||
object](/tools/wptserve/docs/request) and `response` is [a wptserve `Response`
|
||||
object](/tools/wptserve/docs/response).
|
||||
|
||||
This function must return a value in one of the following four formats:
|
||||
|
||||
((status_code, reason), headers, content)
|
||||
(status_code, headers, content)
|
||||
(headers, content)
|
||||
content
|
||||
|
||||
Above, `headers` is a list of (field name, value) pairs, and `content` is a
|
||||
string or an iterable returning strings. The `main` 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 wptserver implements a number of Python APIs for controlling traffic.
|
||||
|
||||
```eval_rst
|
||||
|
|
@ -20,3 +39,40 @@ The wptserver implements a number of Python APIs for controlling traffic.
|
|||
/tools/wptserve/docs/response
|
||||
/tools/wptserve/docs/stash
|
||||
```
|
||||
|
||||
## Example: Dynamic HTTP headers
|
||||
|
||||
The following code defines a Python handler that allows the requester to
|
||||
control the value of the `Content-Type` HTTP response header:
|
||||
|
||||
```python
|
||||
def main(request, response):
|
||||
content_type = request.GET.first('content-type')
|
||||
headers = [('Content-Type', content_type)]
|
||||
|
||||
return (200, 'my status text'), headers, 'my response content'
|
||||
```
|
||||
|
||||
If saved to a file named `resources/control-content-type.py`, the WPT server
|
||||
will respond to requests for `resources/control-content-type.py` by executing
|
||||
that code.
|
||||
|
||||
This could be used from a [testharness.js test](../testharness) like so:
|
||||
|
||||
```html
|
||||
<!DOCTYPE html>
|
||||
<meta charset="utf-8">
|
||||
<title>Demonstrating the WPT server's Python handler feature</title>
|
||||
<script src="/resources/testharness.js"></script>
|
||||
<script src="/resources/testharnessreport.js"></script>
|
||||
<script>
|
||||
promise_test(function() {
|
||||
return fetch('resources/control-content-type.py?content-type=text/foobar')
|
||||
.then(function(response) {
|
||||
assert_equals(response.status, 200);
|
||||
assert_equals(response.statusText, 'my status text');
|
||||
assert_equals(response.headers.get('Content-Type'), 'text/foobar');
|
||||
});
|
||||
});
|
||||
</script>
|
||||
```
|
||||
|
|
|
|||
|
|
@ -22,22 +22,22 @@ 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
|
||||
the function to provide (part of) the response. There are four
|
||||
possible sets of values that may be returned::
|
||||
|
||||
|
||||
(status, headers, content)
|
||||
((status_code, reason), headers, content)
|
||||
(status_code, 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.
|
||||
Here `status_code` is an 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::
|
||||
|
|
|
|||
Загрузка…
Ссылка в новой задаче