Docs and release notes for 4.4

docs/conf.py

@@ -93,7 +93,7 @@
     }
 
 intersphinx_mapping = {
-    'python': ('https://docs.python.org/3.4/', None),
+    'python': ('https://docs.python.org/3.5/', None),
     }
 
 on_rtd = os.environ.get('READTHEDOCS', None) == 'True'

docs/index.rst

@@ -97,11 +97,10 @@ the following optional packages may be useful:
 * `pycares <https://pypi.python.org/pypi/pycares>`_ is an alternative
   non-blocking DNS resolver that can be used when threads are not
   appropriate.
-* `Monotime <https://pypi.python.org/pypi/Monotime>`_ adds support for
-  a monotonic clock, which improves reliability in environments
-  where clock adjustments are frequent.  No longer needed in Python 3.3.
-* `monotonic <https://pypi.python.org/pypi/monotonic>`_ adds support for
-  a monotonic clock. Alternative to Monotime.  No longer needed in Python 3.3.
+* `monotonic <https://pypi.python.org/pypi/monotonic>`_ or `Monotime
+  <https://pypi.python.org/pypi/Monotime>`_ add support for a
+  monotonic clock, which improves reliability in environments where
+  clock adjustements are frequent. No longer needed in Python 3.3.
 
 **Platforms**: Tornado should run on any Unix-like platform, although
 for the best performance and scalability only Linux (with ``epoll``)

docs/releases.rst

@@ -4,6 +4,7 @@ Release notes
 .. toctree::
    :maxdepth: 2
 
+   releases/v4.4.0
    releases/v4.3.0
    releases/v4.2.1
    releases/v4.2.0

docs/releases/v4.4.0.rst

@@ -0,0 +1,95 @@
+What's new in Tornado 4.4
+=========================
+
+In progress
+-----------
+
+General
+~~~~~~~
+
+* Tornado now requires Python 2.7 or 3.3+; versions 2.6 and 3.2 are no
+  longer supported. Pypy3 is still supported even though its latest
+  release is mainly based on Python 3.2.
+* The `monotonic <https://pypi.python.org/pypi/monotonic>`_ package is
+  now supported as an alternative to `Monotime
+  <https://pypi.python.org/pypi/Monotime>`_ for monotonic clock support
+  on Python 2.
+
+``tornado.curl_httpclient``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+* Failures in ``_curl_setup_request`` no longer cause the
+  ``max_clients`` pool to be exhausted.
+* Non-ascii header values are now handled correctly.
+
+`tornado.gen`
+~~~~~~~~~~~~~
+
+* `.with_timeout` now accepts any yieldable object (except
+  `.YieldPoint`), not just `tornado.concurrent.Future`.
+
+`tornado.httpclient`
+~~~~~~~~~~~~~~~~~~~~
+
+* The errors raised by timeouts now indicate what state the request
+  was in; the error message is no longer simply "599 Timeout".
+* Calling `repr` on a `tornado.httpclient.HTTPError` no longer raises
+  an error.
+
+`tornado.httpserver`
+~~~~~~~~~~~~~~~~~~~~
+
+* Int-like enums (including `http.HTTPStatus`) can now be used as
+  status codes.
+* Responses with status code ``204 No Content`` no longer emit a
+  ``Content-Length: 0`` header.
+
+`tornado.ioloop`
+~~~~~~~~~~~~~~~~
+
+* Improved performance when there are large numbers of active timeouts.
+
+`tornado.netutil`
+~~~~~~~~~~~~~~~~~
+
+* All included `.Resolver` implementations raise `IOError` (or a
+  subclass) for any resolution failure.
+
+`tornado.options`
+~~~~~~~~~~~~~~~~~
+
+* Options can now be modified with subscript syntax in addition to
+  attribute syntax.
+* The special variable ``__file__`` is now available inside config files.
+
+``tornado.simple_httpclient``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+* HTTP/1.0 (not 1.1) responses without a ``Content-Length`` header now
+  work correctly.
+
+`tornado.tcpserver`
+~~~~~~~~~~~~~~~~~~~
+
+* `.TCPServer.bind` now accepts a ``reuse_port`` argument.
+
+`tornado.testing`
+~~~~~~~~~~~~~~~~~
+
+* Test sockets now always use ``127.0.0.1`` instead of ``localhost``.
+  This avoids conflicts when the automatically-assigned port is
+  available on IPv4 but not IPv6, or in unusual network configurations
+  when ``localhost`` has multiple IP addresses.
+
+`tornado.web`
+~~~~~~~~~~~~~
+
+* ``image/svg+xml`` is now on the list of compressible mime types.
+* Fixed an error on Python 3 when compression is used with multiple
+  ``Vary`` headers.
+
+`tornado.websocket`
+~~~~~~~~~~~~~~~~~~~
+
+* ``WebSocketHandler.__init__`` now uses `super`, which improves
+  support for multiple inheritance.

tornado/gen.py

@@ -833,7 +833,7 @@ def maybe_future(x):
 
 
 def with_timeout(timeout, future, io_loop=None, quiet_exceptions=()):
-    """Wraps a `.Future` in a timeout.
+    """Wraps a `.Future` (or other yieldable object) in a timeout.
 
     Raises `TimeoutError` if the input future does not complete before
     ``timeout``, which may be specified in any form allowed by
@@ -844,13 +844,16 @@ def with_timeout(timeout, future, io_loop=None, quiet_exceptions=()):
     will be logged unless it is of a type contained in ``quiet_exceptions``
     (which may be an exception type or a sequence of types).
 
-    Currently only supports Futures, not other `YieldPoint` classes.
+    Does not support `YieldPoint` subclasses.
 
     .. versionadded:: 4.0
 
     .. versionchanged:: 4.1
        Added the ``quiet_exceptions`` argument and the logging of unhandled
        exceptions.
+
+    .. versionchanged:: 4.4
+       Added support for yieldable objects other than `.Future`.
     """
     # TODO: allow YieldPoints in addition to other yieldables?
     # Tricky to do with stack_context semantics.

tornado/tcpserver.py

@@ -147,7 +147,8 @@ def add_socket(self, socket):
         """Singular version of `add_sockets`.  Takes a single socket object."""
         self.add_sockets([socket])
 
-    def bind(self, port, address=None, family=socket.AF_UNSPEC, backlog=128, reuse_port=False):
+    def bind(self, port, address=None, family=socket.AF_UNSPEC, backlog=128,
+             reuse_port=False):
         """Binds this server to the given port on the given address.
 
         To start the server, call `start`. If you want to run this server
@@ -162,10 +163,14 @@ def bind(self, port, address=None, family=socket.AF_UNSPEC, backlog=128, reuse_p
         both will be used if available.
 
         The ``backlog`` argument has the same meaning as for
-        `socket.listen <socket.socket.listen>`.
+        `socket.listen <socket.socket.listen>`. The ``reuse_port`` argument
+        has the same meaning as for `.bind_sockets`.
 
         This method may be called multiple times prior to `start` to listen
         on multiple ports or interfaces.
+
+        .. versionchanged:: 4.4
+           Added the ``reuse_port`` argument.
         """
         sockets = bind_sockets(port, address=address, family=family,
                                backlog=backlog, reuse_port=reuse_port)

tornado/testing.py

@@ -96,6 +96,10 @@ def bind_unused_port(reuse_port=False):
     """Binds a server socket to an available port on localhost.
 
     Returns a tuple (socket, port).
+
+    .. versionchanged:: 4.4
+       Always binds to ``127.0.0.1`` without resolving the name
+       ``localhost``.
     """
     sock = netutil.bind_sockets(None, '127.0.0.1', family=socket.AF_INET,
                                 reuse_port=reuse_port)[0]