What’s new in Tornado 5.0¶
Mar 5, 2018¶
Highlights¶
The focus of this release is improving integration with
asyncio
. On Python 3, theIOLoop
is always a wrapper around theasyncio
event loop, andasyncio.Future
andasyncio.Task
are used instead of their Tornado counterparts. This means that libraries based onasyncio
can be mixed relatively seamlessly with those using Tornado. While care has been taken to minimize the disruption from this change, code changes may be required for compatibility with Tornado 5.0, as detailed in the following section.Tornado 5.0 supports Python 2.7.9+ and 3.4+. Python 2.7 and 3.4 are deprecated and support for them will be removed in Tornado 6.0, which will require Python 3.5+.
Backwards-compatibility notes¶
Python 3.3 is no longer supported.
Versions of Python 2.7 that predate the
ssl
module update are no longer supported. (Thessl
module was updated in version 2.7.9, although in some distributions the updates are present in builds with a lower version number. Tornado requiresssl.SSLContext
,ssl.create_default_context
, andssl.match_hostname
)Versions of Python 3.5 prior to 3.5.2 are no longer supported due to a change in the async iterator protocol in that version.
The
trollius
project (asyncio
backported to Python 2) is no longer supported.tornado.concurrent.Future
is now an alias forasyncio.Future
when running on Python 3. This results in a number of minor behavioral changes:Future
objects can only be created while there is a currentIOLoop
The timing of callbacks scheduled with
Future.add_done_callback
has changed.tornado.concurrent.future_add_done_callback
can be used to make the behavior more like older versions of Tornado (but not identical). Some of these changes are also present in the Python 2 version oftornado.concurrent.Future
to minimize the difference between Python 2 and 3.Cancellation is now partially supported, via
asyncio.Future.cancel
. A canceledFuture
can no longer have its result set. Applications that handleFuture
objects directly may want to usetornado.concurrent.future_set_result_unless_cancelled
. In native coroutines, cancellation will cause an exception to be raised in the coroutine.The
exc_info
andset_exc_info
methods are no longer present. Usetornado.concurrent.future_set_exc_info
to replace the latter, and raise the exception withresult
to replace the former.
io_loop
arguments to many Tornado functions have been removed. UseIOLoop.current()
instead of passingIOLoop
objects explicitly.On Python 3,
IOLoop
is always a wrapper around theasyncio
event loop.IOLoop.configure
is effectively removed on Python 3 (for compatibility, it may be called to redundantly specify theasyncio
-backedIOLoop
)IOLoop.instance
is now a deprecated alias forIOLoop.current
. Applications that need the cross-thread communication behavior facilitated byIOLoop.instance
should use their own global variable instead.
Other notes¶
The
futures
(concurrent.futures
backport) package is now required on Python 2.7.The
certifi
andbackports.ssl-match-hostname
packages are no longer required on Python 2.7.Python 3.6 or higher is recommended, because it features more efficient garbage collection of
asyncio.Future
objects.
tornado.auth
¶
GoogleOAuth2Mixin
now uses a newer set of URLs.
tornado.autoreload
¶
On Python 3, uses
__main__.__spec
to more reliably reconstruct the original command line and avoid modifyingPYTHONPATH
.The
io_loop
argument totornado.autoreload.start
has been removed.
tornado.concurrent
¶
tornado.concurrent.Future
is now an alias forasyncio.Future
when running on Python 3. See “Backwards-compatibility notes” for more.Setting the result of a
Future
no longer blocks while callbacks are being run. Instead, the callbacks are scheduled on the nextIOLoop
iteration.The deprecated alias
tornado.concurrent.TracebackFuture
has been removed.tornado.concurrent.chain_future
now works with all three kinds ofFutures
(Tornado,asyncio
, andconcurrent.futures
)The
io_loop
argument totornado.concurrent.run_on_executor
has been removed.New functions
future_set_result_unless_cancelled
,future_set_exc_info
, andfuture_add_done_callback
help mask the difference betweenasyncio.Future
and Tornado’s previousFuture
implementation.
tornado.curl_httpclient
¶
Improved debug logging on Python 3.
The
time_info
response attribute now includesappconnect
in addition to other measurements.Closing a
CurlAsyncHTTPClient
now breaks circular references that could delay garbage collection.The
io_loop
argument to theCurlAsyncHTTPClient
constructor has been removed.
tornado.gen
¶
tornado.gen.TimeoutError
is now an alias fortornado.util.TimeoutError
.Leak detection for
Futures
created by this module now attributes them to their proper caller instead of the coroutine machinery.Several circular references that could delay garbage collection have been broken up.
On Python 3,
asyncio.Task
is used instead of the Tornado coroutine runner. This improves compatibility with someasyncio
libraries and adds support for cancellation.The
io_loop
arguments toYieldFuture
andwith_timeout
have been removed.
tornado.httpclient
¶
The
io_loop
argument to allAsyncHTTPClient
constructors has been removed.
tornado.httpserver
¶
It is now possible for a client to reuse a connection after sending a chunked request.
If a client sends a malformed request, the server now responds with a 400 error instead of simply closing the connection.
Content-Length
andTransfer-Encoding
headers are no longer sent with 1xx or 204 responses (this was already true of 304 responses).When closing a connection to a HTTP/1.1 client, the
Connection: close
header is sent with the response.The
io_loop
argument to theHTTPServer
constructor has been removed.If more than one
X-Scheme
orX-Forwarded-Proto
header is present, only the last is used.
tornado.httputil
¶
The string representation of
HTTPServerRequest
objects (which are sometimes used in log messages) no longer includes the request headers.New function
qs_to_qsl
converts the result ofurllib.parse.parse_qs
to name-value pairs.
tornado.ioloop
¶
tornado.ioloop.TimeoutError
is now an alias fortornado.util.TimeoutError
.IOLoop.instance
is now a deprecated alias forIOLoop.current
.IOLoop.install
andIOLoop.clear_instance
are deprecated.The
IOLoop.initialized
method has been removed.On Python 3, the
asyncio
-backedIOLoop
is always used and alternativeIOLoop
implementations cannot be configured.IOLoop.current
and related methods pass through toasyncio.get_event_loop
.run_sync
cancels its argument on a timeout. This results in better stack traces (and avoids log messages about leaks) in native coroutines.New methods
IOLoop.run_in_executor
andIOLoop.set_default_executor
make it easier to run functions in other threads from native coroutines (sinceconcurrent.futures.Future
does not supportawait
).PollIOLoop
(the default on Python 2) attempts to detect misuse ofIOLoop
instances acrossos.fork
.The
io_loop
argument toPeriodicCallback
has been removed.It is now possible to create a
PeriodicCallback
in one thread and start it in another without passing an explicit event loop.The
IOLoop.set_blocking_signal_threshold
andIOLoop.set_blocking_log_threshold
methods are deprecated because they are not implemented for theasyncio
event loop`. Use thePYTHONASYNCIODEBUG=1
environment variable instead.IOLoop.clear_current
now works if it is called before any current loop is established.
tornado.iostream
¶
The
io_loop
argument to theIOStream
constructor has been removed.New method
BaseIOStream.read_into
provides a minimal-copy alternative toBaseIOStream.read_bytes
.BaseIOStream.write
is now much more efficient for very large amounts of data.Fixed some cases in which
IOStream.error
could be inaccurate.Writing a
memoryview
can no longer result in “BufferError: Existing exports of data: object cannot be re-sized”.
tornado.locks
¶
As a side effect of the
Future
changes, waiters are always notified asynchronously with respect toCondition.notify
.
tornado.netutil
¶
The default
Resolver
now usesIOLoop.run_in_executor
.ExecutorResolver
,BlockingResolver
, andThreadedResolver
are deprecated.The
io_loop
arguments toadd_accept_handler
,ExecutorResolver
, andThreadedResolver
have been removed.add_accept_handler
returns a callable which can be used to remove all handlers that were added.OverrideResolver
now accepts per-family overrides.
tornado.options
¶
Duplicate option names are now detected properly whether they use hyphens or underscores.
tornado.platform.asyncio
¶
AsyncIOLoop
andAsyncIOMainLoop
are now used automatically when appropriate; referencing them explicitly is no longer recommended.Starting an
IOLoop
or making it current now also sets theasyncio
event loop for the current thread. Closing anIOLoop
closes the correspondingasyncio
event loop.to_tornado_future
andto_asyncio_future
are deprecated since they are now no-ops.AnyThreadEventLoopPolicy
can now be used to easily allow the creation of event loops on any thread (similar to Tornado’s prior policy).
tornado.platform.caresresolver
¶
The
io_loop
argument toCaresResolver
has been removed.
tornado.platform.twisted
¶
The
io_loop
arguments toTornadoReactor
,TwistedResolver
, andtornado.platform.twisted.install
have been removed.
tornado.process
¶
The
io_loop
argument to theSubprocess
constructor andSubprocess.initialize
has been removed.
tornado.routing
¶
A default 404 response is now generated if no delegate is found for a request.
tornado.simple_httpclient
¶
The
io_loop
argument toSimpleAsyncHTTPClient
has been removed.TLS is now configured according to
ssl.create_default_context
by default.
tornado.tcpclient
¶
The
io_loop
argument to theTCPClient
constructor has been removed.TCPClient.connect
has a newtimeout
argument.
tornado.tcpserver
¶
tornado.testing
¶
The deprecated
tornado.testing.get_unused_port
andtornado.testing.LogTrapTestCase
have been removed.AsyncHTTPTestCase.fetch
now supports absolute URLs.AsyncHTTPTestCase.fetch
now connects to127.0.0.1
instead oflocalhost
to be more robust against faulty ipv6 configurations.
tornado.util
¶
tornado.util.TimeoutError
replacestornado.gen.TimeoutError
andtornado.ioloop.TimeoutError
.Configurable
now supports configuration at multiple levels of an inheritance hierarchy.
tornado.web
¶
RequestHandler.set_status
no longer requires that the given status code appear inhttp.client.responses
.It is no longer allowed to send a body with 1xx or 204 responses.
Exception handling now breaks up reference cycles that could delay garbage collection.
RedirectHandler
now copies any query arguments from the request to the redirect location.If both
If-None-Match
andIf-Modified-Since
headers are present in a request toStaticFileHandler
, the latter is now ignored.
tornado.websocket
¶
The C accelerator now operates on multiple bytes at a time to improve performance.
Requests with invalid websocket headers now get a response with status code 400 instead of a closed connection.
WebSocketHandler.write_message
now raisesWebSocketClosedError
if the connection closes while the write is in progress.The
io_loop
argument towebsocket_connect
has been removed.