Merge branch 'branch2.0'

bdarnell · bdarnell · commit ef788bce6d1c · 2011-09-11T20:42:22.000-07:00
diff --git a/tornado/auth.py b/tornado/auth.py
@@ -43,6 +43,9 @@ def _on_auth(self, user):
                 raise tornado.web.HTTPError(500, "Google auth failed")
             # Save the user with, e.g., set_secure_cookie()
 
+.. note::
+
+   The ``tornado.auth`` module is not yet compatible with Python 3.
 """
 
 import base64
diff --git a/tornado/httpserver.py b/tornado/httpserver.py
@@ -397,6 +397,8 @@ def _on_request_body(self, data):
 class HTTPRequest(object):
     """A single HTTP request.
 
+    All attributes are type `str` unless otherwise noted.
+
     .. attribute:: method
 
        HTTP request method, e.g. "GET" or "POST"
@@ -425,7 +427,7 @@ class HTTPRequest(object):
 
     .. attribute:: body
 
-       Request body, if present.
+       Request body, if present, as a byte string.
 
     .. attribute:: remote_ip
 
@@ -447,7 +449,10 @@ class HTTPRequest(object):
 
        GET/POST arguments are available in the arguments property, which
        maps arguments names to lists of values (to support multiple values
-       for individual names). Names and values are both unicode always.
+       for individual names). Names are of type `str`, while arguments
+       are byte strings.  Note that this is different from 
+       `RequestHandler.get_argument`, which returns argument values as 
+       unicode strings.
 
     .. attribute:: files
 
diff --git a/website/sphinx/overview.rst b/website/sphinx/overview.rst
@@ -353,6 +353,14 @@ replacing ``{{ ... }}`` with ``{% raw ...%}``. Additionally, in each of
 these places the name of an alternative escaping function may be used
 instead of ``None``.
 
+Note that while Tornado's automatic escaping is helpful in avoiding
+XSS vulnerabilities, it is not sufficient in all cases.  Expressions
+that appear in certain locations, such as in Javascript or CSS, may need
+additional escaping.  Additionally, either care must be taken to always
+use double quotes and ``xhtml_escape`` in HTML attributes that may contain
+untrusted content, or a separate escaping function must be used for
+attributes (see e.g. http://wonko.com/post/html-escaping)
+
 Cookies and secure cookies
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
diff --git a/website/sphinx/releases/v2.0.0.rst b/website/sphinx/releases/v2.0.0.rst
@@ -17,6 +17,8 @@ Jun 21, 2011
       a previous release of Tornado must either disable autoescaping or adapt
       their templates to work with it.  For most applications, the simplest
       way to do this is to pass autoescape=None to the Application constructor.
+      Note that this affects certain built-in methods, e.g. xsrf_form_html
+      and linkify, which must now be called with {% raw %} instead of {}
     * Applications that wish to continue using curl_httpclient instead of
       simple_httpclient may do so by calling
         AsyncHTTPClient.configure("tornado.curl_httpclient.CurlAsyncHTTPClient")
diff --git a/website/templates/index.html b/website/templates/index.html
@@ -55,7 +55,7 @@ <h2>Installation</h2>
   <ul>
     <li>On Python 2.6 and 2.7, there are no dependencies outside the Python standard library, although <a href="http://pycurl.sourceforge.net/">PycURL</a> (version 7.18.2 or higher required; version 7.21.1 or higher recommended) may be used if desired.</li>
     <li>On Python 2.5, PycURL is required, along with <a href="http://pypi.python.org/pypi/simplejson/">simplejson</a> and the Python development headers (typically obtained by installing a package named something like <code>python-dev</code> from your operating system).</li>
-    <li>On Python 3.2, the <a href="http://pypi.python.org/pypi/distribute">distribute</a> package is required.</li>
+    <li>On Python 3.2, the <a href="http://pypi.python.org/pypi/distribute">distribute</a> package is required.  Note that Python 3 support is new and may have bugs; in particular the <code>tornado.auth</code> module is known not to work on Python 3.</li>
   </ul></p>
 
   <p><b>Platforms:</b> Tornado should run on any Unix-like platform, although
