What’s new in Tornado 4.0¶
July 15, 2014¶
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
, including mostIOStream
methods andRequestHandler.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
andtornado.wsgi
modules, making support for features such as chunked and gzip encoding more consistent.HTTPServer
now uses new delegate interfaces defined intornado.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; useconcurrent.futures.Future
when thread-safety is needed.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
pip
oreasy_install
.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
WebSocketHandler.check_origin
.WebSocketHandler
no longer supports the olddraft 76
protocol (this mainly affects Safari 5.x browsers). Applications should use non-websocket workarounds for these browsers.Authors of alternative
IOLoop
implementations should see the changes toIOLoop.add_handler
in this release.The
RequestHandler.async_callback
andWebSocketHandler.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.Support for
RequestHandler.get_error_html
has been removed; overrideRequestHandler.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 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
¶
Fixed a bug in
.FacebookMixin
on Python 3.When using the
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 theconcurrent.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-safeconcurrent.futures.Future
.tornado.concurrent.Future
now includes all the functionality of the oldTracebackFuture
class.TracebackFuture
is now simply an alias forFuture
.
tornado.curl_httpclient
¶
curl_httpclient
now passes along the HTTP “reason” string inresponse.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 usingFutures
, at the expense of some performance degradation for the olderYieldPoint
interfaces.New function
with_timeout
wraps aFuture
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 aFuture
instead of aYieldPoint
subclass. This change should be transparent to application code, but allowsTask
to take advantage of the newly-optimizedFuture
handling.
tornado.http1connection
¶
New module contains the HTTP implementation shared by
tornado.httpserver
andtornado.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 existinguse_gzip
parameter; both names are accepted.
tornado.httpserver
¶
tornado.httpserver.HTTPRequest
has moved totornado.httputil.HTTPServerRequest
.HTTP implementation has been unified with
tornado.simple_httpclient
intornado.http1connection
.Now supports
Transfer-Encoding: chunked
for request bodies.Now supports
Content-Encoding: gzip
for request bodies ifdecompress_request=True
is passed to theHTTPServer
constructor.The
connection
attribute ofHTTPServerRequest
is now documented for public use; applications are expected to write their responses via theHTTPConnection
interface.The
HTTPServerRequest.write
andHTTPServerRequest.finish
methods are now deprecated. (RequestHandler.write
andRequestHandler.finish
are not deprecated; this only applies to the methods onHTTPServerRequest
)HTTPServer
now supportsHTTPServerConnectionDelegate
in addition to the oldrequest_callback
interface. The delegate interface supports streaming of request bodies.HTTPServer
now detects the error of an application sending aContent-Length
error that is inconsistent with the actual content.New constructor arguments
max_header_size
andmax_body_size
allow separate limits to be set for different parts of the request.max_body_size
is applied even in streaming mode.New constructor argument
chunk_size
can be used to limit the amount of data read into memory at one time per request.New constructor arguments
idle_connection_timeout
andbody_timeout
allow time limits to be placed on the reading of requests.Form-encoded message bodies are now parsed for all HTTP methods, not just
POST
,PUT
, andPATCH
.
tornado.httputil
¶
HTTPServerRequest
was moved to this module fromtornado.httpserver
.New base classes
HTTPConnection
,HTTPServerConnectionDelegate
, andHTTPMessageDelegate
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 aFuture
and thatFuture
has an exception, theIOLoop
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
andIOLoop.call_at
simplify the specification of relative or absolute timeouts (as opposed toadd_timeout
, which used the type of its argument).
tornado.iostream
¶
The
callback
argument to mostIOStream
methods is now optional. When called without a callback the method will return aFuture
for use with coroutines.New method
IOStream.start_tls
converts anIOStream
to anSSLIOStream
.No longer gets confused when an
IOError
orOSError
without anerrno
attribute is raised.BaseIOStream.read_bytes
now accepts apartial
keyword argument, which can be used to return before the full amount has been read. This is a more coroutine-friendly alternative tostreaming_callback
.BaseIOStream.read_until
andread_until_regex
now acept amax_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.The default
chunk_size
has been increased to 64KB (from 4KB)The
IOStream
constructor takes a new keyword argumentmax_write_buffer_size
(defaults to unlimited). Calls toBaseIOStream.write
will raiseStreamBufferFullError
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, examinestream.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
¶
It is now possible to disable the default logging configuration by setting
options.logging
toNone
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
intornado.http1connection
Streaming request bodies are now supported via the
body_producer
keyword argument totornado.httpclient.HTTPRequest
.The
expect_100_continue
keyword argument totornado.httpclient.HTTPRequest
allows the use of the HTTPExpect: 100-continue
feature.simple_httpclient
now raises the original exception (e.g. anIOError
) in more cases, instead of converting everything toHTTPError
.
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 newRequestHandler.data_received
method.RequestHandler.flush
now returns aFuture
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 theHTTPMessageDelegate
interface.HEAD
requests inStaticFileHandler
no longer read the entire file.StaticFileHandler
now streams response bodies to the client.New setting
compress_response
replaces the existinggzip
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
andWebSocketClientConnection.close
now supportcode
andreason
arguments to send a status code and message to the other side of the connection when closing. Both classes also haveclose_code
andclose_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 toRequestHandler.get
and similar methods.It is now allowed to override
prepare
in aWebSocketHandler
, 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 TornadoApplication
on a WSGI server in a way that is more compatible with Tornado’s non-WSGIHTTPServer
.WSGIApplication
is deprecated in favor of usingWSGIAdapter
with a regularApplication
.WSGIAdapter
now supports gzipped output.