Skip to content
Newer
Older
100644 53 lines (43 sloc) 2.47 KB
4b6e737 @mcdonc Support the WSGI ``wsgi.file_wrapper`` protocol as per
mcdonc authored Jan 16, 2012
1 Support for ``wsgi.file_wrapper``
2 ---------------------------------
3
4 Waitress supports the `WSGI file_wrapper protocol
5 <http://www.python.org/dev/peps/pep-0333/#optional-platform-specific-file-handling>`_
6 . Here's a usage example::
7
8 import os
9
10 here = os.path.dirname(os.path.abspath(__file__))
11
12 def myapp(environ, start_response):
13 f = open(os.path.join(here, 'myphoto.jpg'), 'rb')
14 headers = [('Content-Type', 'image/jpeg')]
15 start_response(
16 '200 OK',
17 headers
18 )
19 return environ['wsgi.file_wrapper'](f, 32768)
20
21 The file wrapper constructor is accessed via
22 ``environ['wsgi.file_wrapper']``. The signature of the file wrapper
23 constructor is ``(filelike_object, block_size)``. Both arguments must be
24 passed as positional (not keyword) arguments. The result of creating a file
25 wrapper should be **returned** as the ``app_iter`` from a WSGI application.
26
27 The object passed as ``filelike_object`` to the wrapper must be a file-like
28 object which supports *at least* the ``read()`` method, and the ``read()``
29 method must support an optional size hint argument and the ``read()`` method
30 *must* return **bytes** objects (never unicode). It *should* support the
31 ``seek()`` and ``tell()`` methods. If it does not, normal iteration over the
32 filelike object using the provided block_size is used (and copying is done,
33 negating any benefit of the file wrapper). It *should* support a ``close()``
34 method.
35
36 The specified ``block_size`` argument to the file wrapper constructor will be
37 used only when the ``filelike_object`` doesn't support ``seek`` and/or
38 ``tell`` methods. Waitress needs to use normal iteration to serve the file
39 in this degenerate case (as per the WSGI pec), and this block size will be
40 used as the iteration chunk size. The ``block_size`` argument is optional;
41 if it is not passed, a default value``32768`` is used.
42
43 Waitress will set a ``Content-Length`` header on the behalf of an application
44 when a file wrapper with a sufficiently filelike object is used if the
45 application hasn't already set one.
46
47 The machinery which handles a file wrapper currently doesn't do anything
48 particularly special using fancy system calls (it doesn't use ``sendfile``
49 for example); using it currently just prevents the system from needing to
50 copy data to a temporary buffer in order to send it to the client. No
51 copying of data is done when a WSGI app returns a file wrapper that wraps a
52 sufficiently filelike object. It may do something fancier in the future.
Something went wrong with that request. Please try again.