Misc doc updates.

diff --git a/tornado/curl_httpclient.py b/tornado/curl_httpclient.py
index 5a3e624836de4f9ee9dbc9310bea7928d14c8f76..b8fd40527a81e4638fe14e77fdec46c3e6a3935d 100644 (file)
--- a/tornado/curl_httpclient.py
+++ b/tornado/curl_httpclient.py
@@ -351,7 +351,7 @@ def _curl_setup_request(curl, request, buffer, headers):
         # (but see version check in _process_queue above)
         curl.setopt(pycurl.IPRESOLVE, pycurl.IPRESOLVE_V4)
 
-    # Set the request method through curl's retarded interface which makes
+    # Set the request method through curl's irritating interface which makes
     # up names for almost every single method
     curl_options = {
         "GET": pycurl.HTTPGET,

diff --git a/tornado/httpclient.py b/tornado/httpclient.py
index b8f97c6295c35fe78d995b661dfec90a1ab28988..443657c038609b0ea4fbf8ee13a7e49ea1330dec 100644 (file)
--- a/tornado/httpclient.py
+++ b/tornado/httpclient.py
@@ -10,6 +10,10 @@ The default implementation is `simple_httpclient`, and this is expected
 to be suitable for most users' needs.  However, some applications may wish
 to switch to `curl_httpclient` for reasons such as the following:
 
+* `curl_httpclient` has some features not found in `simple_httpclient`,
+  including support for HTTP proxies and the ability to use a specified
+  network interface.
+
 * `curl_httpclient` is more likely to be compatible with sites that are
   not-quite-compliant with the HTTP spec, or sites that use little-exercised
   features of HTTP.

diff --git a/tornado/stack_context.py b/tornado/stack_context.py
index d64e3cfd37ec0a3676eb6e82fd97fd90b224cc3d..1ba3730c3d212176eda7012cf849026a7040b179 100644 (file)
--- a/tornado/stack_context.py
+++ b/tornado/stack_context.py
@@ -45,6 +45,25 @@ Example usage::
         # in the ioloop.
         http_client.fetch(url, callback)
     ioloop.start()
+
+Most applications shouln't have to work with `StackContext` directly.
+Here are a few rules of thumb for when it's necessary:
+
+* If you're writing an asynchronous library that doesn't rely on a
+  stack_context-aware library like `tornado.ioloop` or `tornado.iostream`
+  (for example, if you're writing a thread pool), use
+  `stack_context.wrap()` before any asynchronous operations to capture the
+  stack context from where the operation was started.
+
+* If you're writing an asynchronous library that has some shared
+  resources (such as a connection pool), create those shared resources
+  within a ``with stack_context.NullContext():`` block.  This will prevent
+  ``StackContexts`` from leaking from one request to another.
+
+* If you want to write something like an exception handler that will
+  persist across asynchronous calls, create a new `StackContext` (or
+  `ExceptionStackContext`), and make your asynchronous calls in a ``with``
+  block that references your `StackContext`.
 '''
 
 from __future__ import with_statement

diff --git a/tornado/testing.py b/tornado/testing.py
index 1cbabe5998f59b53427cc535a6c30a957cfe2525..b2b983dd0dcff2e7dce9a15be11456e89164b8f8 100644 (file)
--- a/tornado/testing.py
+++ b/tornado/testing.py
@@ -80,16 +80,23 @@ class AsyncTestCase(unittest.TestCase):
                 # Test contents of response (failures and exceptions here
                 # will cause self.wait() to throw an exception and end the
                 # test).
+                # Exceptions thrown here are magically propagated to
+                # self.wait() in test_http_fetch() via stack_context.
+                self.assertIn("FriendFeed", response.body)
                 self.stop()
 
         # This test uses the argument passing between self.stop and self.wait
-        # for a simpler, more synchronous style
+        # for a simpler, more synchronous style.
+        # This style is recommended over the preceding example because it
+        # keeps the assertions in the test method itself, and is therefore
+        # less sensitive to the subtleties of stack_context.
         class MyTestCase2(AsyncTestCase):
             def test_http_fetch(self):
                 client = AsyncHTTPClient(self.io_loop)
                 client.fetch("http://www.tornadoweb.org/", self.stop)
                 response = self.wait()
                 # Test contents of response
+                self.assertIn("FriendFeed", response.body)
     """
     def __init__(self, *args, **kwargs):
         super(AsyncTestCase, self).__init__(*args, **kwargs)

diff --git a/website/sphinx/releases/next.rst b/website/sphinx/releases/next.rst
index f63d9f6f43fa00a781dce15b384ab4564f23f8b3..130c9b8fca2fb3bda4033397fb6389501160b270 100644 (file)
--- a/website/sphinx/releases/next.rst
+++ b/website/sphinx/releases/next.rst
@@ -18,8 +18,8 @@ Other modules
 
 * `tornado.iostream.IOStream.write` now works correctly when given an
   empty string.
-* `tornado.simple_httpclient` no longer hangs on ``HEAD`` requests
-  and responses with no content.
+* `tornado.simple_httpclient` no longer hangs on ``HEAD`` requests,
+  responses with no content, or empty ``POST``/``PUT`` response bodies.
 * `tornado.websocket` has been updated to support the latest protocol
   (as finalized in RFC 6455).
 * `tornado.platform.twisted` compatibility has been improved.  However,