docs/releases/v4.2.0.rst
Backwards-compatibility notes
* ``SSLIOStream.connect`` and `.IOStream.start_tls` now validate certificates
by default.
* Certificate validation will now use the system CA root certificates instead
of ``certifi`` when possible (i.e. Python 2.7.9+ or 3.4+). This includes
`.IOStream` and ``simple_httpclient``, but not ``curl_httpclient``.
* The default SSL configuration has become stricter, using
`ssl.create_default_context` where available on the client side.
(On the server side, applications are encouraged to migrate from the
``ssl_options`` dict-based API to pass an `ssl.SSLContext` instead).
* The deprecated classes in the `tornado.auth` module, ``GoogleMixin``,
``FacebookMixin``, and ``FriendFeedMixin`` have been removed.
New modules: `tornado.locks` and `tornado.queues`
These modules provide classes for coordinating coroutines, merged from
Toro <https://toro.readthedocs.io>_.
To port your code from Toro's queues to Tornado 4.2, import .Queue,
.PriorityQueue, or .LifoQueue from tornado.queues instead of from
toro.
Use .Queue instead of Toro's JoinableQueue. In Tornado the methods
~.Queue.join and ~.Queue.task_done are available on all queues, not on a
special JoinableQueue.
Tornado queues raise exceptions specific to Tornado instead of reusing
exceptions from the Python standard library.
Therefore instead of catching the standard queue.Empty exception from
.Queue.get_nowait, catch the special tornado.queues.QueueEmpty exception,
and instead of catching the standard queue.Full from .Queue.get_nowait,
catch tornado.queues.QueueFull.
To port from Toro's locks to Tornado 4.2, import .Condition, .Event,
.Semaphore, .BoundedSemaphore, or .Lock from tornado.locks
instead of from toro.
Toro's Semaphore.wait allowed a coroutine to wait for the semaphore to
be unlocked without acquiring it. This encouraged unorthodox patterns; in
Tornado, just use ~.Semaphore.acquire.
Toro's Event.wait raised a Timeout exception after a timeout. In
Tornado, .Event.wait raises tornado.gen.TimeoutError.
Toro's Condition.wait also raised Timeout, but in Tornado, the .Future
returned by .Condition.wait resolves to False after a timeout::
@gen.coroutine
def await_notification():
if not (yield condition.wait(timeout=timedelta(seconds=1))):
print('timed out')
else:
print('condition is true')
In lock and queue methods, wherever Toro accepted deadline as a keyword
argument, Tornado names the argument timeout instead.
Toro's AsyncResult is not merged into Tornado, nor its exceptions
NotReady and AlreadySet. Use a .Future instead. If you wrote code like
this::
from tornado import gen
import toro
result = toro.AsyncResult()
@gen.coroutine
def setter():
result.set(1)
@gen.coroutine
def getter():
value = yield result.get()
print(value) # Prints "1".
Then the Tornado equivalent is::
from tornado import gen
from tornado.concurrent import Future
result = Future()
@gen.coroutine
def setter():
result.set_result(1)
@gen.coroutine
def getter():
value = yield result
print(value) # Prints "1".
tornado.autoreload
* Improved compatibility with Windows.
* Fixed a bug in Python 3 if a module was imported during a reload check.
`tornado.concurrent`
.run_on_executor now accepts arguments to control which attributes
it uses to find the .IOLoop and executor.tornado.curl_httpclient
* Fixed a bug that would cause the client to stop processing requests
if an exception occurred in certain places while there is a queue.
`tornado.escape`
~~~~~~~~~~~~~~~~
* `.xhtml_escape` now supports numeric character references in hex
format (`` ``)
`tornado.gen`
~~~~~~~~~~~~~
* `.WaitIterator` no longer uses weak references, which fixes several
garbage-collection-related bugs.
* ``tornado.gen.Multi`` and `tornado.gen.multi_future` (which are used when
yielding a list or dict in a coroutine) now log any exceptions after the
first if more than one `.Future` fails (previously they would be logged
when the `.Future` was garbage-collected, but this is more reliable).
Both have a new keyword argument ``quiet_exceptions`` to suppress
logging of certain exception types; to use this argument you must
call ``Multi`` or ``multi_future`` directly instead of simply yielding
a list.
* `.multi_future` now works when given multiple copies of the same `.Future`.
* On Python 3, catching an exception in a coroutine no longer leads to
leaks via ``Exception.__context__``.
`tornado.httpclient`
~~~~~~~~~~~~~~~~~~~~
* The ``raise_error`` argument now works correctly with the synchronous
`.HTTPClient`.
* The synchronous `.HTTPClient` no longer interferes with `.IOLoop.current()`.
`tornado.httpserver`
~~~~~~~~~~~~~~~~~~~~
* `.HTTPServer` is now a subclass of `tornado.util.Configurable`.
`tornado.httputil`
~~~~~~~~~~~~~~~~~~
* `.HTTPHeaders` can now be copied with `copy.copy` and `copy.deepcopy`.
`tornado.ioloop`
~~~~~~~~~~~~~~~~
* The `.IOLoop` constructor now has a ``make_current`` keyword argument
to control whether the new `.IOLoop` becomes `.IOLoop.current()`.
* Third-party implementations of `.IOLoop` should accept ``**kwargs``
in their ``IOLoop.initialize`` methods and pass them to the superclass
implementation.
* `.PeriodicCallback` is now more efficient when the clock jumps forward
by a large amount.
`tornado.iostream`
~~~~~~~~~~~~~~~~~~
* ``SSLIOStream.connect`` and `.IOStream.start_tls` now validate certificates
by default.
* New method `.SSLIOStream.wait_for_handshake` allows server-side applications
to wait for the handshake to complete in order to verify client certificates
or use NPN/ALPN.
* The `.Future` returned by ``SSLIOStream.connect`` now resolves after the
handshake is complete instead of as soon as the TCP connection is
established.
* Reduced logging of SSL errors.
* `.BaseIOStream.read_until_close` now works correctly when a
``streaming_callback`` is given but ``callback`` is None (i.e. when
it returns a `.Future`)
`tornado.locale`
~~~~~~~~~~~~~~~~
* New method `.GettextLocale.pgettext` allows additional context to be
supplied for gettext translations.
`tornado.log`
~~~~~~~~~~~~~
* `.define_logging_options` now works correctly when given a non-default
``options`` object.
`tornado.process`
~~~~~~~~~~~~~~~~~
* New method `.Subprocess.wait_for_exit` is a coroutine-friendly
version of `.Subprocess.set_exit_callback`.
`tornado.simple_httpclient`
ssl.SSLContext.max_body_size controls the maximum response
size the client is willing to accept. It may be bigger than
max_buffer_size if streaming_callback is used.tornado.tcpserver
* `.TCPServer.handle_stream` may be a coroutine (so that any exceptions
it raises will be logged).
`tornado.util`
~~~~~~~~~~~~~~
* `.import_object` now supports unicode strings on Python 2.
* `.Configurable.initialize` now supports positional arguments.
`tornado.web`
~~~~~~~~~~~~~
* Key versioning support for cookie signing. ``cookie_secret`` application
setting can now contain a dict of valid keys with version as key. The
current signing key then must be specified via ``key_version`` setting.
* Parsing of the ``If-None-Match`` header now follows the RFC and supports
weak validators.
* Passing ``secure=False`` or ``httponly=False`` to
`.RequestHandler.set_cookie` now works as expected (previously only the
presence of the argument was considered and its value was ignored).
* `.RequestHandler.get_arguments` now requires that its ``strip`` argument
be of type bool. This helps prevent errors caused by the slightly dissimilar
interfaces between the singular and plural methods.
* Errors raised in ``_handle_request_exception`` are now logged more reliably.
* `.RequestHandler.redirect` now works correctly when called from a handler
whose path begins with two slashes.
* Passing messages containing ``%`` characters to `tornado.web.HTTPError`
no longer causes broken error messages.
`tornado.websocket`
on_close method will no longer be called more than once.