docs: Start release notes for 5.1

diff --git a/docs/releases.rst b/docs/releases.rst
index 6f87edc30ba41d216bc364130b10b2d618de921f..5752532886b9347e4123d32f4d476b488dbc59d3 100644 (file)
--- 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 (file)
index 0000000..f29ab21
--- /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 77f2fff4c6ab6275ec4e26c284bb277917238605..2442e37c5e9eb3983049596c4fa646cb28be06c3 100644 (file)
--- 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