From: Ben Darnell Date: Sat, 5 May 2018 18:56:47 +0000 (-0400) Subject: docs: Start release notes for 5.1 X-Git-Tag: v5.1.0b1~19^2~2 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=80f6a5172870f4d50643e4cf4ff525cf237ce6ca;p=thirdparty%2Ftornado.git docs: Start release notes for 5.1 --- diff --git a/docs/releases.rst b/docs/releases.rst index 6f87edc30..575253288 100644 --- a/docs/releases.rst +++ b/docs/releases.rst @@ -4,6 +4,7 @@ Release notes .. toctree:: :maxdepth: 2 + releases/v5.1.0 releases/v5.0.2 releases/v5.0.1 releases/v5.0.0 diff --git a/docs/releases/v5.1.0.rst b/docs/releases/v5.1.0.rst new file mode 100644 index 000000000..f29ab2114 --- /dev/null +++ b/docs/releases/v5.1.0.rst @@ -0,0 +1,152 @@ +What's new in Tornado 5.1 +========================= + +In progress +----------- + +Deprecation notice +~~~~~~~~~~~~~~~~~~ + +- Tornado 6.0 will drop support for Python 2.7 and 3.4. The minimum + supported Python version will be 3.5.2. +- The `tornado.stack_context` module is deprecated and will be removed + in Tornado 6.0. The reason for this is that it is not feasible to + provide this module's semantics in the presence of ``async def`` + native coroutines. `.ExceptionStackContext` is mainly obsolete + thanks to coroutines. `.StackContext` lacks a direct replacement + although the new ``contextvars`` package (in the Python standard + library beginning in Python 3.7) may be an alternative. +- Callback-oriented code often relies on `.ExceptionStackContext` to + handle errors and prevent leaked connections. In order to avoid the + risk of silently introducing subtle leaks (and to consolidate all of + Tornado's interfaces behind the coroutine pattern), ``callback`` + arguments throughout the package are deprecated and will be removed + in version 6.0. All functions that had a ``callback`` argument + removed now return a `.Future` which should be used instead. +- Where possible, deprecation warnings are emitted when any of these + deprecated interfaces is used. However, Python does not display + deprecation warnings by default. To prepare your application for + Tornado 6.0, run Python with the ``-Wd`` argument or set the + environment variable ``PYTHONWARNINGS`` to ``d``. If your + application runs on Python 3 without deprecation warnings, it should + be able to move to Tornado 6.0 without disruption. + +`tornado.auth` +~~~~~~~~~~~~~~ + +- `.OAuthMixin._oauth_get_user_future` may now be a native coroutine. +- All ``callback`` arguments in this package are deprecated and will + be removed in 6.0. Use the coroutine interfaces instead. +- The ``OAuthMixin._oauth_get_user`` method is deprecated and will be removed in + 6.0. Override `~.OAuthMixin._oauth_get_user_future` instead. + +`tornado.concurrent` +~~~~~~~~~~~~~~~~~~~~ + +- `.run_on_executor` now returns `.Future` objects that are compatible + with ``await``. +- The ``callback`` argument to `.run_on_executor` is deprecated and will + be removed in 6.0. +- `.return_future` is deprecated. The wrapped function will no longer + accept ``callback`` arguments in Tornado 6.0, although the decorator + itself will not be removed. + +`tornado.gen` +~~~~~~~~~~~~~ + +- Some older portions of this module are deprecated and will be removed + in 6.0. This includes `.engine`, `.YieldPoint`, `.Callback`, + `.Wait`, `.WaitAll`, `.MultiYieldPoint`, and `.Task`. +- Functions decorated with ``@gen.coroutine`` will no longer accept + ``callback`` arguments in 6.0. + +`tornado.httpclient` +~~~~~~~~~~~~~~~~~~~~ + +- The behavior of ``raise_error=False`` is changing in 6.0. Currently + it suppresses all errors; in 6.0 it will only suppress the errors + raised due to completed responses with non-200 status codes. +- The ``callback`` argument to `.AsyncHTTPClient.fetch` is deprecated + and will be removed in 6.0. +- `tornado.httpclient.HTTPError` has been renamed to + `.HTTPClientError` to avoid ambiguity in code that also has to deal + with `tornado.web.HTTPError`. The old name remains as an alias. + +`tornado.httputil` +~~~~~~~~~~~~~~~~~~ + +- `.HTTPServerRequest.write` is deprecated and will be removed in 6.0. Use + the methods of ``request.connection`` instead. +- Malformed HTTP headers are now logged less noisily. + +`tornado.ioloop` +~~~~~~~~~~~~~~~~ + +- `.PeriodicCallback` now supports a ``jitter`` argument to randomly + vary the timeout. +- `.IOLoop.set_blocking_signal_threshold`, + `~.IOLoop.set_blocking_log_threshold`, `~.IOLoop.log_stack`, + and `.IOLoop.handle_callback_exception` are deprecated and will + be removed in 6.0. + +`tornado.iostream` +~~~~~~~~~~~~~~~~~~ + +- All ``callback`` arguments in this module are deprecated except for + `.BaseIOStream.set_close_callback`. They will be removed in 6.0. +- ``streaming_callback`` arguments to `.BaseIOStream.read_bytes` and + `.BaseIOStream.read_until_close` are deprecated and will be removed + in 6.0. + +`tornado.platform.twisted` +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- `.TornadoReactor` and `.TwistedIOLoop` are deprecated and will be + removed in 6.0. Instead, Tornado will always use the asyncio event loop + and twisted can be configured to do so as well. + +`tornado.stack_context` +~~~~~~~~~~~~~~~~~~~~~~~ + +- The `tornado.stack_context` module is deprecated and will be removed + in 6.0. + +`tornado.testing` +~~~~~~~~~~~~~~~~~ + +- `.AsyncHTTPTestCase.fetch` now takes a ``raise_error`` argument. + This argument has the same semantics as `.AsyncHTTPClient.fetch`, + but defaults to false because tests often need to deal with non-200 + responses (and for backwards-compatibility). +- The `.AsyncTestCase.stop` and `.AsyncTestCase.wait` methods are + deprecated. + +`tornado.web` +~~~~~~~~~~~~~ + +- New method `.RequestHandler.detach` can be used from methods + that are not decorated with ``@asynchronous`` (the decorator + was required to use ``self.request.connection.detach()``. +- `.FallbackHandler` now calls ``on_finish`` for the benefit of + subclasses that may have overridden it. +- The `.asynchronous` decorator is deprecated and will be removed in 6.0. +- The ``callback`` argument to `.RequestHandler.flush` is deprecated + and will be removed in 6.0. + + +`tornado.websocket` +~~~~~~~~~~~~~~~~~~~ + +- The `.WebSocketHandler.select_subprotocol` method is now called only + when a subprotocol header is provided (previously it would be called + with a list containing an empty string). +- The ``data`` argument to `.WebSocketHandler.ping` is now optional. +- Client-side websocket connections no longer buffer more than one + message in memory at a time. +- Exception logging now uses `.RequestHandler.log_exception`. + +`tornado.wsgi` +~~~~~~~~~~~~~~ + +- `.WSGIApplication` and `.WSGIAdapter` are deprecated and will be removed + in Tornado 6.0. diff --git a/docs/web.rst b/docs/web.rst index 77f2fff4c..2442e37c5 100644 --- a/docs/web.rst +++ b/docs/web.rst @@ -125,6 +125,7 @@ .. automethod:: RequestHandler.compute_etag .. automethod:: RequestHandler.create_template_loader .. autoattribute:: RequestHandler.current_user + .. automethod:: RequestHandler.detach .. automethod:: RequestHandler.get_browser_locale .. automethod:: RequestHandler.get_current_user .. automethod:: RequestHandler.get_login_url