What’s new in Tornado 4.0¶
July 15, 2014¶
tornado.web.stream_request_bodydecorator allows large files to be uploaded with limited memory usage.
Many user-overridden methods are now allowed to return a
Futurefor flow control.
HTTP-related code is now shared between the
tornado.wsgimodules, making support for features such as chunked and gzip encoding more consistent.
HTTPServernow uses new delegate interfaces defined in
tornado.httputilin addition to its old single-callback interface.
tornado.tcpclientcreates TCP connections with non-blocking DNS, SSL handshaking, and support for IPv6.
Tornado now depends on the certifi package instead of bundling its own copy of the Mozilla CA list. This will be installed automatically when using
This version includes the changes to the secure cookie format first introduced in version 3.2.1, and the xsrf token change in version 3.2.2. If you are upgrading from an earlier version, see those versions’ release notes.
WebSocket connections from other origin sites are now rejected by default. To accept cross-origin websocket connections, override the new method
WebSocketHandlerno longer supports the old
draft 76protocol (this mainly affects Safari 5.x browsers). Applications should use non-websocket workarounds for these browsers.
WebSocketHandler.async_callbackwrapper functions have been removed; they have been obsolete for a long time due to stack contexts (and more recently coroutines).
curl_httpclientnow requires a minimum of libcurl version 7.21.1 and pycurl 7.18.2.
RequestHandler.get_error_htmlhas been removed; override
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 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
IOLoopso many modules are still unusable).
Fixed a bug in
.FacebookMixinon Python 3.
When using the
Futureinterface, exceptions are more reliably delivered to the caller.
tornado.concurrent.Futureis now always thread-unsafe (previously it would be thread-safe if the
concurrent.futurespackage 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
tornado.concurrent.Futurenow includes all the functionality of the old
TracebackFutureis now simply an alias for
curl_httpclientnow passes along the HTTP “reason” string in
Performance of coroutines has been improved.
Coroutines no longer generate
StackContextsby default, but they will be created on demand when needed.
The internals of the
tornado.genmodule have been rewritten to improve performance when using
Futures, at the expense of some performance degradation for the older
momentcan be yielded to allow the IOLoop to run for one iteration before resuming.
Taskis now a function returning a
Futureinstead of a
YieldPointsubclass. This change should be transparent to application code, but allows
Taskto take advantage of the newly-optimized
New module contains the HTTP implementation shared by
The command-line HTTP client (
python -m tornado.httpclient $URL) now works on Python 3.
Fixed a memory leak in
AsyncHTTPClientshutdown that affected applications that created many HTTP clients and IOLoops.
New client request parameter
decompress_responsereplaces the existing
use_gzipparameter; both names are accepted.
tornado.httpserver.HTTPRequesthas moved to
HTTP implementation has been unified with
Transfer-Encoding: chunkedfor request bodies.
Content-Encoding: gzipfor request bodies if
decompress_request=Trueis passed to the
HTTPServerRequest.finishmethods are now deprecated. (
RequestHandler.finishare not deprecated; this only applies to the methods on
HTTPServernow detects the error of an application sending a
Content-Lengtherror that is inconsistent with the actual content.
New constructor arguments
max_body_sizeallow separate limits to be set for different parts of the request.
max_body_sizeis applied even in streaming mode.
New constructor argument
chunk_sizecan be used to limit the amount of data read into memory at one time per request.
New constructor arguments
body_timeoutallow time limits to be placed on the reading of requests.
Form-encoded message bodies are now parsed for all HTTP methods, not just
IOLoop.add_handlerand 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.
IOLoop.clear_instancemakes it possible to uninstall the singleton instance.
Timeout scheduling is now more robust against slow callbacks.
IOLoop.add_timeoutis now a bit more efficient.
IOLoop.spawn_callbacksimplifies the process of launching a fire-and-forget callback that is separated from the caller’s stack context.
No longer gets confused when an
errnoattribute is raised.
BaseIOStream.read_bytesnow accepts a
partialkeyword argument, which can be used to return before the full amount has been read. This is a more coroutine-friendly alternative to
read_until_regexnow acept a
max_byteskeyword argument which will cause the request to fail if it cannot be satisfied from the given number of bytes.
IOStreamno 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_sizehas been increased to 64KB (from 4KB)
IOStreamconstructor takes a new keyword argument
max_write_buffer_size(defaults to unlimited). Calls to
StreamBufferFullErrorif the amount of unsent buffered data exceeds this limit.
ETIMEDOUTerrors are no longer logged. If you need to distinguish timeouts from other forms of closed connections, examine
stream.errorfrom a close callback.
bind_socketschooses 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).
It is now possible to disable the default logging configuration by setting
Noneinstead of the string
Now works on Python 2.6.
Now works with Trollius version 0.3.
TwistedIOLoopnow works on Python 3.3+ (with Twisted 14.0.0+).
simple_httpclienthas better support for IPv6, which is now enabled by default.
Improved default cipher suite selection (Python 2.7+).
HTTP implementation has been unified with
Streaming request bodies are now supported via the
body_producerkeyword argument to
expect_100_continuekeyword argument to
tornado.httpclient.HTTPRequestallows the use of the HTTP
simple_httpclientnow raises the original exception (e.g. an
IOError) in more cases, instead of converting everything to
The stack context system now has less performance overhead when no stack contexts are active.
New module which creates TCP connections and IOStreams, including name resolution, connecting, and SSL handshakes.
AsyncTestCasenow attempts to detect test methods that are generators but were not run with
@gen_testor any similar decorator (this would previously result in the test silently being skipped).
Better stack traces are now displayed when a test times out.
@gen_testdecorator now passes along
*args, **kwargsso it can be used on functions with arguments.
Fixed the test suite when
unittest2is installed on Python 3.
Finishmay 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.
StaticFileHandlerno longer read the entire file.
StaticFileHandlernow streams response bodies to the client.
compress_responsereplaces the existing
gzipsetting; 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.
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
reasonarguments to send a status code and message to the other side of the connection when closing. Both classes also have
close_reasonattributes 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.
It is now allowed to override
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.