Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 149 lines (115 sloc) 6.264 kb
e17f68c @GrahamDumpleton Initial page structure.
authored
1 Amendments to WSGI 1.0
2 ======================
646e963 @masklinn Initial port of the WSGI 1.0 Amendments document
masklinn authored
3
4 This page is intended to collect any ideas related to amendments to
5 the original `WSGI 1.0 <http://www.python.org/dev/peps/pep-0333/>`_ so
6 that it can be marked as 'Final'.
7
8 The purpose of the amendments is to address any mistakes or
9 ambiguities in the 1.0 specification or to change any requirements
10 that in practice could not be implemented for one reason or
11 another. The amendments would also address any differences in how the
12 1.0 specification should be interpreted for Python 3. See
13 :doc:`python3` for details.
14
15 Note that this isn't about changing the 1.0 specification drastically
16 in any way, that is what :doc:`proposals-2.0` specification will be
17 about. You should though not construe anything in here as an
18 indication that said change will be made. This is especially the case
19 with Python 3 support as there is a measure of disagreement as to how
20 WSGI should work for Python 3. In other words, you would be unwise to
21 implement any WSGI application or WSGI adapter with information in
22 here as a basis as it could change or simply never be adopted.
23
24 The page has been created in response to `a discussion on the Python
25 WEB-SIG
26 <http://groups.google.com/group/python-web-sig/browse_frm/thread/ae4bf2f41ed10350>`_.
27
28 In addition, Graham Dumpleton gives `details and clarifications on
29 WSGI 1.0 amendments
30 <http://blog.dscpl.com.au/2009/10/details-on-wsgi-10-amendmentsclarificat.html>`_
31 on his blog.
32
33 readline(size)
34 --------------
35
36 Currently the specification does not require servers to provide
37 ``environ['wsgi.input'].readline(size)`` (the ``size`` argument in
38 particular). But :py:class:`cgi.FieldStorage` calls readline this way,
39 so in effect it is required.
40
41 Python 3
42 --------
43
f24138d @masklinn Editor fixes to amendment document: improve markup and wording in a bunc...
masklinn authored
44 :doc:`python3` default string type is now unicode and existing python2
45 strings correspond to bytes. This changes how terms need to be
46 interpreted. From `WSGI, Python 3 and Unicode
646e963 @masklinn Initial port of the WSGI 1.0 Amendments document
masklinn authored
47 <http://groups.google.com/group/python-web-sig/browse_frm/thread/f8f54fe99485312a/046841da888eac1e#046841da888eac1e>`_,
48 the following suggested amendments were proposed for Python 3.
49
f24138d @masklinn Editor fixes to amendment document: improve markup and wording in a bunc...
masklinn authored
50 * When running under Python 3, applications **SHOULD** produce bytes
646e963 @masklinn Initial port of the WSGI 1.0 Amendments document
masklinn authored
51 output, status line and headers
f24138d @masklinn Editor fixes to amendment document: improve markup and wording in a bunc...
masklinn authored
52 * When running under Python 3, servers and gateways **MUST** accept
646e963 @masklinn Initial port of the WSGI 1.0 Amendments document
masklinn authored
53 strings as application output, status line or headers, under the
f24138d @masklinn Editor fixes to amendment document: improve markup and wording in a bunc...
masklinn authored
54 existing rules (i.e., ``s.encode('latin-1')`` must convert the
55 string to bytes without an exception)
56 * When running under Python 3, servers **MUST** provide CGI HTTP
646e963 @masklinn Initial port of the WSGI 1.0 Amendments document
masklinn authored
57 variables and as strings, decoded from the headers using HTTP
f24138d @masklinn Editor fixes to amendment document: improve markup and wording in a bunc...
masklinn authored
58 standard encodings (i.e. latin-1 + :rfc:`2047`) (Open question: are
646e963 @masklinn Initial port of the WSGI 1.0 Amendments document
masklinn authored
59 there any CGI or WSGI variables that should NOT be strings?)
6e853bc @masklinn Add a definitions page to store e.g. the various WSGI environ keys
masklinn authored
60 * When running under Python 3, servers **MUST** make
61 :envvar:`wsgi.input` a binary (byte) stream
f24138d @masklinn Editor fixes to amendment document: improve markup and wording in a bunc...
masklinn authored
62 * When running under Python 3, servers **MUST** provide a text stream
6e853bc @masklinn Add a definitions page to store e.g. the various WSGI environ keys
masklinn authored
63 for :envvar:`wsgi.errors`
646e963 @masklinn Initial port of the WSGI 1.0 Amendments document
masklinn authored
64
65 See the mailing list archive for the full discussion of issues.
66
67 Note that this doesn't address any clarifications that may be required
6e853bc @masklinn Add a definitions page to store e.g. the various WSGI environ keys
masklinn authored
68 around :envvar:`wsgi.file_wrapper` optional extension.
646e963 @masklinn Initial port of the WSGI 1.0 Amendments document
masklinn authored
69
70 Note that current thinking is that the WSGI adaptor should not worry
e20ed00 @masklinn Fix RFC 2047 link
masklinn authored
71 about :rfc:`2047`.
646e963 @masklinn Initial port of the WSGI 1.0 Amendments document
masklinn authored
72
73 Errata 1
74 --------
75
76 In the "Specification Details" chapter there is this note:
77
78 .. note::
f24138d @masklinn Editor fixes to amendment document: improve markup and wording in a bunc...
masklinn authored
79 the application must invoke the ``start_response()`` callable
80 before the iterable yields its first body string, so that the
81 server can send the headers before any body content. However, this
82 invocation may be performed by the iterable's first iteration, so
83 servers must not assume that ``start_response()`` has been called
84 before they begin iterating over the iterable.) What's wrong is
85 that the invocation of start_response may be performed at any
86 iteration of the iterable, as long as the application yields empty
87 strings.
646e963 @masklinn Initial port of the WSGI 1.0 Amendments document
masklinn authored
88
89 See http://mail.python.org/pipermail/web-sig/2007-December/003064.html
90 for more info.
91
92 * I don't really think that this is a good assumption to make. I
93 could see how some implementations could allow for this, but
94 strictly speaking, I wouldn't assume that most implementations
95 would do that. Besides that, what purpose does yielding an empty
96 string serve? For those reasons, I think this is better of left as
97 an undefined behavior. --JasonBaker July 1, 2008
98
99 When HTTP response headers can be sent
100 --------------------------------------
101
102 The WSGI spec explicitly states that HTTP response headers must be
103 sent when the application yields the first non empty strings.
104
105 However if a WSGI implementation is allowed to send headers early
106 (*not* when ``start_response`` is called, but when the first
107 string is yielded by the WSGI application, even if empty), then in
108 case of an ``HEAD`` request no content generation is required
109 (assuming, of course, that the WSGI application returns a generator).
110
111 See http://mail.python.org/pipermail/web-sig/2007-October/002881.html,
112 http://mail.python.org/pipermail/web-sig/2007-October/002799.html,
113 http://mail.python.org/pipermail/web-sig/2007-October/002803.html and
114 http://mail.python.org/pipermail/web-sig/2007-October/002879.html
115
116 That thread is a bit confused.
117
118 start_response and error checks
119 -------------------------------
120
121 The WSGI spec says that start_response callable **must not** actually
122 transmit the response headers. Instead, it must store them.
123
124 The problem is that it says nothing about errors checking.
125
126 See
127 http://mail.python.org/pipermail/web-sig/2007-September/002771.html
128
129 Clarification about start_response
130 ----------------------------------
131
f24138d @masklinn Editor fixes to amendment document: improve markup and wording in a bunc...
masklinn authored
132 What happens if an application calls ``start_response`` with an
133 incorrect status line or headers?
646e963 @masklinn Initial port of the WSGI 1.0 Amendments document
masklinn authored
134
135 Should an implementation consider the function *called*, so that an
136 application can call it a second time, *without* the exc_info
137 parameter?
138
139 See http://mail.python.org/pipermail/web-sig/2007-October/002887.html
140
141 Specify the type of ``SERVER_PORT``
142 -----------------------------------
143
144 Some implementations currently expect it to be an integer, some a
145 string. Can we please specify one or the other or either? The "URL
f24138d @masklinn Editor fixes to amendment document: improve markup and wording in a bunc...
masklinn authored
146 reconstruction" code snippet in :pep:`333` presumes it's a string, the
646e963 @masklinn Initial port of the WSGI 1.0 Amendments document
masklinn authored
147 reference to the (defunct) CGI spec would seem to imply it should be a
148 string, but it should be explicit.
Something went wrong with that request. Please try again.