docs/releases/v4.0.0.rst
Highlights
* The `tornado.web.stream_request_body` decorator allows large files to be
uploaded with limited memory usage.
* Coroutines are now faster and are used extensively throughout Tornado itself.
More methods now return `Futures <.Future>`, including most `.IOStream`
methods and `.RequestHandler.flush`.
* Many user-overridden methods are now allowed to return a `.Future`
for flow control.
* HTTP-related code is now shared between the `tornado.httpserver`,
``tornado.simple_httpclient`` and `tornado.wsgi` modules, making support
for features such as chunked and gzip encoding more consistent.
`.HTTPServer` now uses new delegate interfaces defined in `tornado.httputil`
in addition to its old single-callback interface.
* New module `tornado.tcpclient` creates TCP connections with non-blocking
DNS, SSL handshaking, and support for IPv6.
Backwards-compatibility notes
tornado.concurrent.Future is no longer thread-safe; use
concurrent.futures.Future when thread-safety is needed.certifi <https://pypi.python.org/pypi/certifi>_
package instead of bundling its own copy of the Mozilla CA list. This will
be installed automatically when using pip or easy_install.3.2.1 <v3.2.1>, and the xsrf token change
in version :doc:3.2.2 <v3.2.2>. If you are upgrading from an earlier
version, see those versions' release notes..WebSocketHandler.check_origin..WebSocketHandler no longer supports the old draft 76 protocol
(this mainly affects Safari 5.x browsers). Applications should use
non-websocket workarounds for these browsers..IOLoop implementations should see the changes
to .IOLoop.add_handler in this release.RequestHandler.async_callback and WebSocketHandler.async_callback
wrapper functions have been removed; they have been obsolete for a long
time due to stack contexts (and more recently coroutines).curl_httpclient now requires a minimum of libcurl version 7.21.1 and
pycurl 7.18.2.RequestHandler.get_error_html has been removed;
override .RequestHandler.write_error instead.Other notes
* The git repository has moved to https://github.com/tornadoweb/tornado.
All old links should be redirected to the new location.
* An `announcement mailing list
<http://groups.google.com/group/python-tornado-announce>`_ is now available.
* All Tornado modules are now importable on Google App Engine (although
the App Engine environment does not allow the system calls used
by `.IOLoop` so many modules are still unusable).
`tornado.auth`
.FacebookMixin on Python 3..Future interface, exceptions are more reliably delivered
to the caller.tornado.concurrent
* `tornado.concurrent.Future` is now always thread-unsafe (previously
it would be thread-safe if the `concurrent.futures` package was available).
This improves performance and provides more consistent semantics.
The parts of Tornado that accept Futures will accept both Tornado's
thread-unsafe Futures and the thread-safe `concurrent.futures.Future`.
* `tornado.concurrent.Future` now includes all the functionality
of the old ``TracebackFuture`` class. ``TracebackFuture`` is now
simply an alias for ``Future``.
``tornado.curl_httpclient``
curl_httpclient now passes along the HTTP "reason" string
in response.reason.tornado.gen
* Performance of coroutines has been improved.
* Coroutines no longer generate ``StackContexts`` by default, but they
will be created on demand when needed.
* The internals of the `tornado.gen` module have been rewritten to
improve performance when using ``Futures``, at the expense of some
performance degradation for the older ``YieldPoint`` interfaces.
* New function `.with_timeout` wraps a `.Future` and raises an exception
if it doesn't complete in a given amount of time.
* New object `.moment` can be yielded to allow the IOLoop to run for
one iteration before resuming.
* ``Task`` is now a function returning a `.Future` instead of a ``YieldPoint``
subclass. This change should be transparent to application code, but
allows ``Task`` to take advantage of the newly-optimized `.Future`
handling.
`tornado.http1connection`
tornado.httpserver
and tornado.simple_httpclient.tornado.httpclient
* The command-line HTTP client (``python -m tornado.httpclient $URL``)
now works on Python 3.
* Fixed a memory leak in `.AsyncHTTPClient` shutdown that affected
applications that created many HTTP clients and IOLoops.
* New client request parameter ``decompress_response`` replaces
the existing ``use_gzip`` parameter; both names are accepted.
`tornado.httpserver`
tornado.httpserver.HTTPRequest has moved to
tornado.httputil.HTTPServerRequest.tornado.simple_httpclient
in tornado.http1connection.Transfer-Encoding: chunked for request bodies.Content-Encoding: gzip for request bodies if
decompress_request=True is passed to the .HTTPServer constructor.connection attribute of .HTTPServerRequest is now documented
for public use; applications are expected to write their responses
via the .HTTPConnection interface.HTTPServerRequest.write and HTTPServerRequest.finish methods
are now deprecated. (.RequestHandler.write and .RequestHandler.finish
are not deprecated; this only applies to the methods on
.HTTPServerRequest).HTTPServer now supports .HTTPServerConnectionDelegate in addition to
the old request_callback interface. The delegate interface supports
streaming of request bodies..HTTPServer now detects the error of an application sending a
Content-Length error that is inconsistent with the actual content.max_header_size and max_body_size
allow separate limits to be set for different parts of the request.
max_body_size is applied even in streaming mode.chunk_size can be used to limit the amount
of data read into memory at one time per request.idle_connection_timeout and body_timeout
allow time limits to be placed on the reading of requests.POST, PUT, and PATCH.tornado.httputil
* `.HTTPServerRequest` was moved to this module from `tornado.httpserver`.
* New base classes `.HTTPConnection`, `.HTTPServerConnectionDelegate`,
and `.HTTPMessageDelegate` define the interaction between applications
and the HTTP implementation.
`tornado.ioloop`
~~~~~~~~~~~~~~~~
* `.IOLoop.add_handler` and related methods now accept file-like objects
in addition to raw file descriptors. Passing the objects is recommended
(when possible) to avoid a garbage-collection-related problem in unit tests.
* New method `.IOLoop.clear_instance` makes it possible to uninstall the
singleton instance.
* Timeout scheduling is now more robust against slow callbacks.
* `.IOLoop.add_timeout` is now a bit more efficient.
* When a function run by the `.IOLoop` returns a `.Future` and that `.Future`
has an exception, the `.IOLoop` will log the exception.
* New method `.IOLoop.spawn_callback` simplifies the process of launching
a fire-and-forget callback that is separated from the caller's stack context.
* New methods `.IOLoop.call_later` and `.IOLoop.call_at` simplify the
specification of relative or absolute timeouts (as opposed to
`~.IOLoop.add_timeout`, which used the type of its argument).
`tornado.iostream`
callback argument to most .IOStream methods is now optional.
When called without a callback the method will return a .Future
for use with coroutines..IOStream.start_tls converts an .IOStream to an
.SSLIOStream.IOError or OSError without
an errno attribute is raised..BaseIOStream.read_bytes now accepts a partial keyword argument,
which can be used to return before the full amount has been read.
This is a more coroutine-friendly alternative to streaming_callback..BaseIOStream.read_until and read_until_regex now acept a
max_bytes keyword argument which will cause the request to fail if
it cannot be satisfied from the given number of bytes..IOStream no longer reads from the socket into memory if it does not
need data to satisfy a pending read. As a side effect, the close callback
will not be run immediately if the other side closes the connection
while there is unconsumed data in the buffer.chunk_size has been increased to 64KB (from 4KB).IOStream constructor takes a new keyword argument
max_write_buffer_size (defaults to unlimited). Calls to
.BaseIOStream.write will raise .StreamBufferFullError if the amount
of unsent buffered data exceeds this limit.ETIMEDOUT errors are no longer logged. If you need to distinguish
timeouts from other forms of closed connections, examine stream.error
from a close callback.tornado.netutil
* When `.bind_sockets` chooses a port automatically, it will now use
the same port for IPv4 and IPv6.
* TLS compression is now disabled by default on Python 3.3 and higher
(it is not possible to change this option in older versions).
`tornado.options`
options.logging to None instead of the string "none".tornado.platform.asyncio
* Now works on Python 2.6.
* Now works with Trollius version 0.3.
`tornado.platform.twisted`
TwistedIOLoop now works on Python 3.3+ (with Twisted 14.0.0+).tornado.simple_httpclient
* ``simple_httpclient`` has better support for IPv6, which is now enabled
by default.
* Improved default cipher suite selection (Python 2.7+).
* HTTP implementation has been unified with ``tornado.httpserver``
in `tornado.http1connection`
* Streaming request bodies are now supported via the ``body_producer``
keyword argument to `tornado.httpclient.HTTPRequest`.
* The ``expect_100_continue`` keyword argument to
`tornado.httpclient.HTTPRequest` allows the use of the HTTP ``Expect:
100-continue`` feature.
* ``simple_httpclient`` now raises the original exception (e.g. an `IOError`)
in more cases, instead of converting everything to ``HTTPError``.
``tornado.stack_context``
~~~~~~~~~~~~~~~~~~~~~~~~~
* The stack context system now has less performance overhead when no
stack contexts are active.
`tornado.tcpclient`
~~~~~~~~~~~~~~~~~~~
* New module which creates TCP connections and IOStreams, including
name resolution, connecting, and SSL handshakes.
`tornado.testing`
~~~~~~~~~~~~~~~~~
* `.AsyncTestCase` now attempts to detect test methods that are generators
but were not run with ``@gen_test`` or any similar decorator (this would
previously result in the test silently being skipped).
* Better stack traces are now displayed when a test times out.
* The ``@gen_test`` decorator now passes along ``*args, **kwargs`` so it
can be used on functions with arguments.
* Fixed the test suite when ``unittest2`` is installed on Python 3.
`tornado.web`
~~~~~~~~~~~~~
* It is now possible to support streaming request bodies with the
`.stream_request_body` decorator and the new `.RequestHandler.data_received`
method.
* `.RequestHandler.flush` now returns a `.Future` if no callback is given.
* New exception `.Finish` may be raised to finish a request without
triggering error handling.
* When gzip support is enabled, all ``text/*`` mime types will be compressed,
not just those on a whitelist.
* `.Application` now implements the `.HTTPMessageDelegate` interface.
* ``HEAD`` requests in `.StaticFileHandler` no longer read the entire file.
* `.StaticFileHandler` now streams response bodies to the client.
* New setting ``compress_response`` replaces the existing ``gzip``
setting; both names are accepted.
* XSRF cookies that were not generated by this module (i.e. strings without
any particular formatting) are once again accepted (as long as the
cookie and body/header match). This pattern was common for
testing and non-browser clients but was broken by the changes in
Tornado 3.2.2.
`tornado.websocket`
~~~~~~~~~~~~~~~~~~~
* WebSocket connections from other origin sites are now rejected by default.
Browsers do not use the same-origin policy for WebSocket connections as they
do for most other browser-initiated communications. This can be surprising
and a security risk, so we disallow these connections on the server side
by default. To accept cross-origin websocket connections, override
the new method `.WebSocketHandler.check_origin`.
* `.WebSocketHandler.close` and `.WebSocketClientConnection.close` now
support ``code`` and ``reason`` arguments to send a status code and
message to the other side of the connection when closing. Both classes
also have ``close_code`` and ``close_reason`` attributes to receive these
values when the other side closes.
* The C speedup module now builds correctly with MSVC, and can support
messages larger than 2GB on 64-bit systems.
* The fallback mechanism for detecting a missing C compiler now
works correctly on Mac OS X.
* Arguments to `.WebSocketHandler.open` are now decoded in the same way
as arguments to `.RequestHandler.get` and similar methods.
* It is now allowed to override ``prepare`` in a `.WebSocketHandler`,
and this method may generate HTTP responses (error pages) in the usual
way. The HTTP response methods are still not allowed once the
WebSocket handshake has completed.
`tornado.wsgi`
~~~~~~~~~~~~~~
* New class ``WSGIAdapter`` supports running a Tornado `.Application` on
a WSGI server in a way that is more compatible with Tornado's non-WSGI
`.HTTPServer`. ``WSGIApplication`` is deprecated in favor of using
``WSGIAdapter`` with a regular `.Application`.
* ``WSGIAdapter`` now supports gzipped output.