From: Ben Darnell Date: Sat, 7 Jul 2018 22:53:49 +0000 (-0400) Subject: docs: Doc and lint updates X-Git-Tag: v6.0.0b1~48^2~4 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=432473e32186c2674a72d5aeffa03c334d77befb;p=thirdparty%2Ftornado.git docs: Doc and lint updates Just enough to unbreak the build for now. --- diff --git a/docs/gen.rst b/docs/gen.rst index 0f0bfdeef..320d29c51 100644 --- a/docs/gen.rst +++ b/docs/gen.rst @@ -13,8 +13,6 @@ .. autofunction:: coroutine - .. autofunction:: engine - Utility functions ----------------- @@ -39,38 +37,3 @@ .. autofunction:: maybe_future .. autofunction:: is_coroutine_function - - Legacy interface - ---------------- - - Before support for `Futures <.Future>` was introduced in Tornado 3.0, - coroutines used subclasses of `YieldPoint` in their ``yield`` expressions. - These classes are still supported but should generally not be used - except for compatibility with older interfaces. None of these classes - are compatible with native (``await``-based) coroutines. - - .. autoclass:: YieldPoint - :members: - - .. autoclass:: Callback - - .. autoclass:: Wait - - .. autoclass:: WaitAll - - .. autoclass:: MultiYieldPoint - - .. autofunction:: Task - - .. class:: Arguments - - The result of a `Task` or `Wait` whose callback had more than one - argument (or keyword arguments). - - The `Arguments` object is a `collections.namedtuple` and can be - used either as a tuple ``(args, kwargs)`` or an object with attributes - ``args`` and ``kwargs``. - - .. deprecated:: 5.1 - - This class will be removed in 6.0. diff --git a/docs/guide/intro.rst b/docs/guide/intro.rst index f5d918701..778573bbb 100644 --- a/docs/guide/intro.rst +++ b/docs/guide/intro.rst @@ -26,8 +26,7 @@ Tornado can be roughly divided into four major components: The Tornado web framework and HTTP server together offer a full-stack alternative to `WSGI `_. -While it is possible to use the Tornado web framework in a WSGI -container (`.WSGIAdapter`), or use the Tornado HTTP server as a -container for other WSGI frameworks (`.WSGIContainer`), each of these -combinations has limitations and to take full advantage of Tornado you -will need to use the Tornado's web framework and HTTP server together. +While it is possible to use the Tornado HTTP server as a container for +other WSGI frameworks (`.WSGIContainer`), this combination has +limitations and to take full advantage of Tornado you will need to use +the Tornado's web framework and HTTP server together. diff --git a/docs/guide/running.rst b/docs/guide/running.rst index e7c5b3494..edf469a96 100644 --- a/docs/guide/running.rst +++ b/docs/guide/running.rst @@ -273,41 +273,3 @@ On some platforms (including Windows and Mac OSX prior to 10.6), the process cannot be updated "in-place", so when a code change is detected the old server exits and a new one starts. This has been known to confuse some IDEs. - - -WSGI and Google App Engine -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Tornado is normally intended to be run on its own, without a WSGI -container. However, in some environments (such as Google App Engine), -only WSGI is allowed and applications cannot run their own servers. -In this case Tornado supports a limited mode of operation that does -not support asynchronous operation but allows a subset of Tornado's -functionality in a WSGI-only environment. The features that are -not allowed in WSGI mode include coroutines, the ``@asynchronous`` -decorator, `.AsyncHTTPClient`, the ``auth`` module, and WebSockets. - -You can convert a Tornado `.Application` to a WSGI application -with `tornado.wsgi.WSGIAdapter`. In this example, configure -your WSGI container to find the ``application`` object: - -.. testcode:: - - import tornado.web - import tornado.wsgi - - class MainHandler(tornado.web.RequestHandler): - def get(self): - self.write("Hello, world") - - tornado_app = tornado.web.Application([ - (r"/", MainHandler), - ]) - application = tornado.wsgi.WSGIAdapter(tornado_app) - -.. testoutput:: - :hide: - -See the `appengine example application -`_ for a -full-featured AppEngine app built on Tornado. diff --git a/docs/guide/structure.rst b/docs/guide/structure.rst index 99370d971..8e8dc026a 100644 --- a/docs/guide/structure.rst +++ b/docs/guide/structure.rst @@ -193,9 +193,8 @@ place: etc. If the URL regular expression contains capturing groups, they are passed as arguments to this method. 5. When the request is finished, `~.RequestHandler.on_finish()` is - called. For most handlers this is immediately after ``get()`` (etc) - return; for handlers using the `tornado.web.asynchronous` decorator - it is after the call to `~.RequestHandler.finish()`. + called. This is generally after ``get()`` or another HTTP method + returns. All methods designed to be overridden are noted as such in the `.RequestHandler` documentation. Some of the most commonly @@ -299,11 +298,6 @@ Certain handler methods (including ``prepare()`` and the HTTP verb methods ``get()``/``post()``/etc) may be overridden as coroutines to make the handler asynchronous. -Tornado also supports a callback-based style of asynchronous handler -with the `tornado.web.asynchronous` decorator, but this style is -deprecated and will be removed in Tornado 6.0. New applications should -use coroutines instead. - For example, here is a simple handler using a coroutine: .. testcode:: diff --git a/docs/ioloop.rst b/docs/ioloop.rst index 2c5fdc2cd..55096e187 100644 --- a/docs/ioloop.rst +++ b/docs/ioloop.rst @@ -46,14 +46,6 @@ .. autoclass:: PeriodicCallback :members: - Debugging and error handling - ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - - .. automethod:: IOLoop.handle_callback_exception - .. automethod:: IOLoop.set_blocking_signal_threshold - .. automethod:: IOLoop.set_blocking_log_threshold - .. automethod:: IOLoop.log_stack - Methods for subclasses ^^^^^^^^^^^^^^^^^^^^^^ diff --git a/docs/releases/v2.3.0.rst b/docs/releases/v2.3.0.rst index d24f46c54..5be231d03 100644 --- a/docs/releases/v2.3.0.rst +++ b/docs/releases/v2.3.0.rst @@ -102,9 +102,9 @@ Other modules function is called repeatedly. * `tornado.locale.get_supported_locales` no longer takes a meaningless ``cls`` argument. -* `.StackContext` instances now have a deactivation callback that can be +* ``StackContext`` instances now have a deactivation callback that can be used to prevent further propagation. * `tornado.testing.AsyncTestCase.wait` now resets its timeout on each call. -* `tornado.wsgi.WSGIApplication` now parses arguments correctly on Python 3. +* ``tornado.wsgi.WSGIApplication`` now parses arguments correctly on Python 3. * Exception handling on Python 3 has been improved; previously some exceptions such as `UnicodeDecodeError` would generate ``TypeErrors`` diff --git a/docs/releases/v2.4.0.rst b/docs/releases/v2.4.0.rst index bbf07bf82..5bbff30bc 100644 --- a/docs/releases/v2.4.0.rst +++ b/docs/releases/v2.4.0.rst @@ -57,7 +57,7 @@ HTTP clients * New method `.RequestHandler.get_template_namespace` can be overridden to add additional variables without modifying keyword arguments to ``render_string``. -* `.RequestHandler.add_header` now works with `.WSGIApplication`. +* `.RequestHandler.add_header` now works with ``WSGIApplication``. * `.RequestHandler.get_secure_cookie` now handles a potential error case. * ``RequestHandler.__init__`` now calls ``super().__init__`` to ensure that all constructors are called when multiple inheritance is used. diff --git a/docs/releases/v2.4.1.rst b/docs/releases/v2.4.1.rst index 22b09ca42..82eabc94e 100644 --- a/docs/releases/v2.4.1.rst +++ b/docs/releases/v2.4.1.rst @@ -7,7 +7,7 @@ Nov 24, 2012 Bug fixes ~~~~~~~~~ -* Fixed a memory leak in `tornado.stack_context` that was especially likely +* Fixed a memory leak in ``tornado.stack_context`` that was especially likely with long-running ``@gen.engine`` functions. * `tornado.auth.TwitterMixin` now works on Python 3. * Fixed a bug in which ``IOStream.read_until_close`` with a streaming callback diff --git a/docs/releases/v3.0.0.rst b/docs/releases/v3.0.0.rst index a1d34e12f..53c9771f3 100644 --- a/docs/releases/v3.0.0.rst +++ b/docs/releases/v3.0.0.rst @@ -10,7 +10,7 @@ Highlights * The ``callback`` argument to many asynchronous methods is now optional, and these methods return a `.Future`. The `tornado.gen` module now understands ``Futures``, and these methods can be used - directly without a `.gen.Task` wrapper. + directly without a ``gen.Task`` wrapper. * New function `.IOLoop.current` returns the `.IOLoop` that is running on the current thread (as opposed to `.IOLoop.instance`, which returns a specific thread's (usually the main thread's) IOLoop. @@ -136,7 +136,7 @@ Multiple modules calling a callback you return a value with ``raise gen.Return(value)`` (or simply ``return value`` in Python 3.3). * Generators may now yield `.Future` objects. -* Callbacks produced by `.gen.Callback` and `.gen.Task` are now automatically +* Callbacks produced by ``gen.Callback`` and ``gen.Task`` are now automatically stack-context-wrapped, to minimize the risk of context leaks when used with asynchronous functions that don't do their own wrapping. * Fixed a memory leak involving generators, `.RequestHandler.flush`, @@ -167,7 +167,7 @@ Multiple modules when instantiating an implementation subclass directly. * Secondary `.AsyncHTTPClient` callbacks (``streaming_callback``, ``header_callback``, and ``prepare_curl_callback``) now respect - `.StackContext`. + ``StackContext``. `tornado.httpserver` ~~~~~~~~~~~~~~~~~~~~ @@ -311,9 +311,9 @@ Multiple modules `tornado.platform.twisted` ~~~~~~~~~~~~~~~~~~~~~~~~~~ -* New class `tornado.platform.twisted.TwistedIOLoop` allows Tornado +* New class ``tornado.platform.twisted.TwistedIOLoop`` allows Tornado code to be run on the Twisted reactor (as opposed to the existing - `.TornadoReactor`, which bridges the gap in the other direction). + ``TornadoReactor``, which bridges the gap in the other direction). * New class `tornado.platform.twisted.TwistedResolver` is an asynchronous implementation of the `.Resolver` interface. @@ -343,10 +343,10 @@ Multiple modules * Fixed a bug in which ``SimpleAsyncHTTPClient`` callbacks were being run in the client's ``stack_context``. -`tornado.stack_context` -~~~~~~~~~~~~~~~~~~~~~~~ +``tornado.stack_context`` +~~~~~~~~~~~~~~~~~~~~~~~~~ -* `.stack_context.wrap` now runs the wrapped callback in a more consistent +* ``stack_context.wrap`` now runs the wrapped callback in a more consistent environment by recreating contexts even if they already exist on the stack. * Fixed a bug in which stack contexts could leak from one callback diff --git a/docs/releases/v3.0.2.rst b/docs/releases/v3.0.2.rst index 7eac09dba..70e7d52b3 100644 --- a/docs/releases/v3.0.2.rst +++ b/docs/releases/v3.0.2.rst @@ -9,4 +9,4 @@ Jun 2, 2013 June 11 `_. It also now uses HTTPS when talking to Twitter. * Fixed a potential memory leak with a long chain of `.gen.coroutine` - or `.gen.engine` functions. + or ``gen.engine`` functions. diff --git a/docs/releases/v3.1.0.rst b/docs/releases/v3.1.0.rst index edbf39dba..b4ae0e12e 100644 --- a/docs/releases/v3.1.0.rst +++ b/docs/releases/v3.1.0.rst @@ -28,7 +28,7 @@ Multiple modules are asynchronous in `.OAuthMixin` and derived classes, although they do not take a callback. The `.Future` these methods return must be yielded if they are called from a function decorated with `.gen.coroutine` - (but not `.gen.engine`). + (but not ``gen.engine``). * `.TwitterMixin` now uses ``/account/verify_credentials`` to get information about the logged-in user, which is more robust against changing screen names. @@ -147,11 +147,11 @@ Multiple modules * `.Subprocess.set_exit_callback` now works for subprocesses created without an explicit ``io_loop`` parameter. -`tornado.stack_context` -~~~~~~~~~~~~~~~~~~~~~~~ +``tornado.stack_context`` +~~~~~~~~~~~~~~~~~~~~~~~~~ -* `tornado.stack_context` has been rewritten and is now much faster. -* New function `.run_with_stack_context` facilitates the use of stack +* ``tornado.stack_context`` has been rewritten and is now much faster. +* New function ``run_with_stack_context`` facilitates the use of stack contexts with coroutines. `tornado.tcpserver` @@ -170,7 +170,7 @@ Multiple modules ~~~~~~~~~~~~~~~~~ * `tornado.testing.AsyncTestCase.wait` now raises the correct exception - when it has been modified by `tornado.stack_context`. + when it has been modified by ``tornado.stack_context``. * `tornado.testing.gen_test` can now be called as ``@gen_test(timeout=60)`` to give some tests a longer timeout than others. * The environment variable ``ASYNC_TEST_TIMEOUT`` can now be set to @@ -210,11 +210,11 @@ Multiple modules instead of being turned into spaces. * `.RequestHandler.send_error` will now only be called once per request, even if multiple exceptions are caught by the stack context. -* The `tornado.web.asynchronous` decorator is no longer necessary for +* The ``tornado.web.asynchronous`` decorator is no longer necessary for methods that return a `.Future` (i.e. those that use the `.gen.coroutine` - or `.return_future` decorators) + or ``return_future`` decorators) * `.RequestHandler.prepare` may now be asynchronous if it returns a - `.Future`. The `~tornado.web.asynchronous` decorator is not used with + `.Future`. The ``tornado.web.asynchronous`` decorator is not used with ``prepare``; one of the `.Future`-related decorators should be used instead. * ``RequestHandler.current_user`` may now be assigned to normally. * `.RequestHandler.redirect` no longer silently strips control characters diff --git a/docs/releases/v3.2.0.rst b/docs/releases/v3.2.0.rst index 09057030a..f0be99961 100644 --- a/docs/releases/v3.2.0.rst +++ b/docs/releases/v3.2.0.rst @@ -79,7 +79,7 @@ New modules `tornado.ioloop` ~~~~~~~~~~~~~~~~ -* `.IOLoop` now uses `~.IOLoop.handle_callback_exception` consistently for +* `.IOLoop` now uses ``IOLoop.handle_callback_exception`` consistently for error logging. * `.IOLoop` now frees callback objects earlier, reducing memory usage while idle. diff --git a/docs/releases/v4.0.0.rst b/docs/releases/v4.0.0.rst index dd60ea8c3..6b470d3bc 100644 --- a/docs/releases/v4.0.0.rst +++ b/docs/releases/v4.0.0.rst @@ -96,14 +96,14 @@ Other notes will be created on demand when needed. * The internals of the `tornado.gen` module have been rewritten to improve performance when using ``Futures``, at the expense of some - performance degradation for the older `.YieldPoint` interfaces. + performance degradation for the older ``YieldPoint`` interfaces. * New function `.with_timeout` wraps a `.Future` 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 a `.Future` instead of a `.YieldPoint` +* ``Task`` is now a function returning a `.Future` instead of a ``YieldPoint`` subclass. This change should be transparent to application code, but - allows `.Task` to take advantage of the newly-optimized `.Future` + allows ``Task`` to take advantage of the newly-optimized `.Future` handling. `tornado.http1connection` @@ -135,7 +135,7 @@ Other notes * The ``connection`` attribute of `.HTTPServerRequest` is now documented for public use; applications are expected to write their responses via the `.HTTPConnection` interface. -* The `.HTTPServerRequest.write` and `.HTTPServerRequest.finish` methods +* The ``HTTPServerRequest.write`` and ``HTTPServerRequest.finish`` methods are now deprecated. (`.RequestHandler.write` and `.RequestHandler.finish` are *not* deprecated; this only applies to the methods on `.HTTPServerRequest`) @@ -233,7 +233,7 @@ Other notes `tornado.platform.twisted` ~~~~~~~~~~~~~~~~~~~~~~~~~~ -* `.TwistedIOLoop` now works on Python 3.3+ (with Twisted 14.0.0+). +* ``TwistedIOLoop`` now works on Python 3.3+ (with Twisted 14.0.0+). ``tornado.simple_httpclient`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -251,8 +251,8 @@ Other notes * ``simple_httpclient`` now raises the original exception (e.g. an `IOError`) in more cases, instead of converting everything to ``HTTPError``. -`tornado.stack_context` -~~~~~~~~~~~~~~~~~~~~~~~ +``tornado.stack_context`` +~~~~~~~~~~~~~~~~~~~~~~~~~ * The stack context system now has less performance overhead when no stack contexts are active. @@ -324,8 +324,8 @@ Other notes `tornado.wsgi` ~~~~~~~~~~~~~~ -* New class `.WSGIAdapter` supports running a Tornado `.Application` on +* New class ``WSGIAdapter`` supports running a Tornado `.Application` on a WSGI server in a way that is more compatible with Tornado's non-WSGI - `.HTTPServer`. `.WSGIApplication` is deprecated in favor of using - `.WSGIAdapter` with a regular `.Application`. -* `.WSGIAdapter` now supports gzipped output. + `.HTTPServer`. ``WSGIApplication`` is deprecated in favor of using + ``WSGIAdapter`` with a regular `.Application`. +* ``WSGIAdapter`` now supports gzipped output. diff --git a/docs/releases/v4.1.0.rst b/docs/releases/v4.1.0.rst index 29ad19146..74cd30a49 100644 --- a/docs/releases/v4.1.0.rst +++ b/docs/releases/v4.1.0.rst @@ -60,7 +60,7 @@ Backwards-compatibility notes yieldable in coroutines. * New function `tornado.gen.sleep` is a coroutine-friendly analogue to `time.sleep`. -* `.gen.engine` now correctly captures the stack context for its callbacks. +* ``gen.engine`` now correctly captures the stack context for its callbacks. `tornado.httpclient` ~~~~~~~~~~~~~~~~~~~~ @@ -167,7 +167,7 @@ Backwards-compatibility notes `tornado.web` ~~~~~~~~~~~~~ -* The `.asynchronous` decorator now understands `concurrent.futures.Future` +* The ``asynchronous`` decorator now understands `concurrent.futures.Future` in addition to `tornado.concurrent.Future`. * `.StaticFileHandler` no longer logs a stack trace if the connection is closed while sending the file. diff --git a/docs/releases/v4.3.0.rst b/docs/releases/v4.3.0.rst index e6ea1589c..b19b297c1 100644 --- a/docs/releases/v4.3.0.rst +++ b/docs/releases/v4.3.0.rst @@ -12,7 +12,7 @@ Highlights Inside a function defined with ``async def``, use ``await`` instead of ``yield`` to wait on an asynchronous operation. Coroutines defined with async/await will be faster than those defined with ``@gen.coroutine`` and - ``yield``, but do not support some features including `.Callback`/`.Wait` or + ``yield``, but do not support some features including ``Callback``/``Wait`` or the ability to yield a Twisted ``Deferred``. See :ref:`the users' guide ` for more. * The async/await keywords are also available when compiling with Cython in diff --git a/docs/releases/v4.4.0.rst b/docs/releases/v4.4.0.rst index fa7c81702..5ac3018b9 100644 --- a/docs/releases/v4.4.0.rst +++ b/docs/releases/v4.4.0.rst @@ -26,7 +26,7 @@ General ~~~~~~~~~~~~~ * `.with_timeout` now accepts any yieldable object (except - `.YieldPoint`), not just `tornado.concurrent.Future`. + ``YieldPoint``), not just `tornado.concurrent.Future`. `tornado.httpclient` ~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/releases/v4.5.0.rst b/docs/releases/v4.5.0.rst index 9cdf0ad5c..5a4ce9e25 100644 --- a/docs/releases/v4.5.0.rst +++ b/docs/releases/v4.5.0.rst @@ -58,7 +58,7 @@ General changes - Fixed an issue in which a generator object could be garbage collected prematurely (most often when weak references are used. - New function `.is_coroutine_function` identifies functions wrapped - by `.coroutine` or `.engine`. + by `.coroutine` or ``engine``. ``tornado.http1connection`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/releases/v5.0.0.rst b/docs/releases/v5.0.0.rst index 7f1325b8d..dd0bd0243 100644 --- a/docs/releases/v5.0.0.rst +++ b/docs/releases/v5.0.0.rst @@ -193,8 +193,8 @@ Other notes - The ``io_loop`` argument to `.PeriodicCallback` 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` and - `.IOLoop.set_blocking_log_threshold` methods are deprecated because +- The ``IOLoop.set_blocking_signal_threshold`` and + ``IOLoop.set_blocking_log_threshold`` methods are deprecated because they are not implemented for the `asyncio` event loop`. Use the ``PYTHONASYNCIODEBUG=1`` environment variable instead. - `.IOLoop.clear_current` now works if it is called before any @@ -257,8 +257,8 @@ Other notes `tornado.platform.twisted` ~~~~~~~~~~~~~~~~~~~~~~~~~~ -- The ``io_loop`` arguments to `.TornadoReactor`, `.TwistedResolver`, - and `tornado.platform.twisted.install` have been removed. +- The ``io_loop`` arguments to ``TornadoReactor``, `.TwistedResolver`, + and ``tornado.platform.twisted.install`` have been removed. `tornado.process` ~~~~~~~~~~~~~~~~~ diff --git a/docs/releases/v5.1.0.rst b/docs/releases/v5.1.0.rst index 09c5d80e1..00def8f38 100644 --- a/docs/releases/v5.1.0.rst +++ b/docs/releases/v5.1.0.rst @@ -9,14 +9,14 @@ 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 +- 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 + 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 +- 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`` @@ -55,14 +55,14 @@ Deprecation notice with ``await``. - The ``callback`` argument to `.run_on_executor` is deprecated and will be removed in 6.0. -- `.return_future` is deprecated and will be removed in 6.0. +- ``return_future`` is deprecated and will be removed in 6.0. `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`. + 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. @@ -94,7 +94,7 @@ Deprecation notice - `.parse_multipart_form_data` now recognizes non-ASCII filenames in RFC 2231/5987 (``filename*=``) format. -- `.HTTPServerRequest.write` is deprecated and will be removed in 6.0. Use +- ``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. @@ -103,9 +103,9 @@ Deprecation notice - `.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 +- ``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. - Fixed a `KeyError` in `.IOLoop.close` when `.IOLoop` objects are being opened and closed in multiple threads. @@ -135,14 +135,14 @@ Deprecation notice `tornado.platform.twisted` ~~~~~~~~~~~~~~~~~~~~~~~~~~ -- `.TornadoReactor` and `.TwistedIOLoop` are deprecated and will be +- ``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` -~~~~~~~~~~~~~~~~~~~~~~~ +``tornado.stack_context`` +~~~~~~~~~~~~~~~~~~~~~~~~~ -- The `tornado.stack_context` module is deprecated and will be removed +- The ``tornado.stack_context`` module is deprecated and will be removed in 6.0. `tornado.testing` @@ -166,7 +166,7 @@ Deprecation notice response to be sent to the client. - `.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 ``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. @@ -191,5 +191,5 @@ Deprecation notice `tornado.wsgi` ~~~~~~~~~~~~~~ -- `.WSGIApplication` and `.WSGIAdapter` are deprecated and will be removed +- ``WSGIApplication`` and ``WSGIAdapter`` are deprecated and will be removed in Tornado 6.0. diff --git a/docs/stack_context.rst b/docs/stack_context.rst deleted file mode 100644 index 489a37fdc..000000000 --- a/docs/stack_context.rst +++ /dev/null @@ -1,5 +0,0 @@ -``tornado.stack_context`` --- Exception handling across asynchronous callbacks -============================================================================== - -.. automodule:: tornado.stack_context - :members: diff --git a/docs/twisted.rst b/docs/twisted.rst index a6e1946f1..a5d971a04 100644 --- a/docs/twisted.rst +++ b/docs/twisted.rst @@ -3,20 +3,6 @@ .. automodule:: tornado.platform.twisted - Twisted on Tornado - ------------------ - - .. autoclass:: TornadoReactor - :members: - - .. autofunction:: install - - Tornado on Twisted - ------------------ - - .. autoclass:: TwistedIOLoop - :members: - Twisted DNS resolver -------------------- diff --git a/docs/utilities.rst b/docs/utilities.rst index 55536626e..4c6edf586 100644 --- a/docs/utilities.rst +++ b/docs/utilities.rst @@ -7,6 +7,5 @@ Utilities concurrent log options - stack_context testing util diff --git a/docs/web.rst b/docs/web.rst index 2442e37c5..ed9a3f1c1 100644 --- a/docs/web.rst +++ b/docs/web.rst @@ -21,9 +21,9 @@ .. _verbs: Implement any of the following methods (collectively known as the - HTTP verb methods) to handle the corresponding HTTP method. - These methods can be made asynchronous with one of the following - decorators: `.gen.coroutine`, `.return_future`, or `asynchronous`. + HTTP verb methods) to handle the corresponding HTTP method. These + methods can be made asynchronous with the ``async def`` keyword or + `.gen.coroutine` decorator. The arguments to these methods come from the `.URLSpec`: Any capturing groups in the regular expression become arguments to the @@ -272,7 +272,6 @@ Decorators ---------- - .. autofunction:: asynchronous .. autofunction:: authenticated .. autofunction:: addslash .. autofunction:: removeslash diff --git a/docs/wsgi.rst b/docs/wsgi.rst index a54b7aaae..75d544aad 100644 --- a/docs/wsgi.rst +++ b/docs/wsgi.rst @@ -3,17 +3,5 @@ .. automodule:: tornado.wsgi - Running Tornado apps on WSGI servers - ------------------------------------ - - .. autoclass:: WSGIAdapter - :members: - - .. autoclass:: WSGIApplication - :members: - - Running WSGI apps on Tornado servers - ------------------------------------ - .. autoclass:: WSGIContainer :members: diff --git a/tornado/auth.py b/tornado/auth.py index 07a3f5d70..a3fd7943c 100644 --- a/tornado/auth.py +++ b/tornado/auth.py @@ -66,7 +66,6 @@ import time import urllib.parse import uuid -from tornado import gen from tornado import httpclient from tornado import escape from tornado.httputil import url_concat @@ -404,7 +403,6 @@ class OAuthMixin(object): args["oauth_signature"] = signature return url + "?" + urllib.parse.urlencode(args) - def _oauth_consumer_token(self): """Subclasses must override this to return their OAuth consumer keys. @@ -815,7 +813,7 @@ class FacebookGraphMixin(OAuth2Mixin): _FACEBOOK_BASE_URL = "https://graph.facebook.com" async def get_authenticated_user(self, redirect_uri, client_id, client_secret, - code, extra_fields=None): + code, extra_fields=None): """Handles the login for the Facebook user, returning a user object. Example usage: diff --git a/tornado/gen.py b/tornado/gen.py index 8b17568b1..e5ff49832 100644 --- a/tornado/gen.py +++ b/tornado/gen.py @@ -17,25 +17,7 @@ environment than chaining callbacks. Code using coroutines is technically asynchronous, but it is written as a single generator instead of a collection of separate functions. -For example, the following callback-based asynchronous handler: - -.. testcode:: - - class AsyncHandler(RequestHandler): - @asynchronous - def get(self): - http_client = AsyncHTTPClient() - http_client.fetch("http://example.com", - callback=self.on_fetch) - - def on_fetch(self, response): - do_something_with_response(response) - self.render("template.html") - -.. testoutput:: - :hide: - -could be written with ``gen`` as: +For example, here's a coroutine-based handler: .. testcode:: @@ -160,7 +142,8 @@ def coroutine(func): """Decorator for asynchronous generators. Any generator that yields objects from this module must be wrapped - in either this decorator or `engine`. + in this decorator (or use ``async def`` and ``await`` for similar + functionality). Coroutines may "return" by raising the special exception `Return(value) `. In Python 3.3+, it is also possible for @@ -169,13 +152,7 @@ def coroutine(func): In all versions of Python a coroutine that simply wishes to exit early may use the ``return`` statement without a value. - Functions with this decorator return a `.Future`. Additionally, - they may be called with a ``callback`` keyword argument, which - will be invoked with the future's result when it resolves. If the - coroutine fails, the callback will not be run and an exception - will be raised into the surrounding `.StackContext`. The - ``callback`` argument is not visible inside the decorated - function; it is handled by the decorator itself. + Functions with this decorator return a `.Future`. .. warning:: @@ -191,6 +168,7 @@ def coroutine(func): The ``callback`` argument was removed. Use the returned awaitable object instead. + """ @functools.wraps(func) def wrapper(*args, **kwargs): @@ -426,11 +404,6 @@ def multi(children, quiet_exceptions=()): one. All others will be logged, unless they are of types contained in the ``quiet_exceptions`` argument. - If any of the inputs are `YieldPoints `, the returned - yieldable object is a `YieldPoint`. Otherwise, returns a `.Future`. - This means that the result of `multi` can be used in a native - coroutine if and only if all of its children can be. - In a ``yield``-based coroutine, it is not normally necessary to call this function directly, since the coroutine runner will do it automatically when a list or dict is yielded. However, @@ -452,7 +425,7 @@ def multi(children, quiet_exceptions=()): .. versionchanged:: 4.3 Replaced the class ``Multi`` and the function ``multi_future`` with a unified function ``multi``. Added support for yieldables - other than `YieldPoint` and `.Future`. + other than ``YieldPoint`` and `.Future`. """ return multi_future(children, quiet_exceptions=quiet_exceptions) @@ -464,8 +437,7 @@ Multi = multi def multi_future(children, quiet_exceptions=()): """Wait for multiple asynchronous futures in parallel. - This function is similar to `multi`, but does not support - `YieldPoints `. + Since Tornado 6.0, this function is exactly the same as `multi`. .. versionadded:: 4.0 @@ -553,8 +525,6 @@ def with_timeout(timeout, future, quiet_exceptions=()): will be logged unless it is of a type contained in ``quiet_exceptions`` (which may be an exception type or a sequence of types). - Does not support `YieldPoint` subclasses. - The wrapped `.Future` is not canceled when the timeout expires, permitting it to be reused. `asyncio.wait_for` is similar to this function but it does cancel the wrapped `.Future` on timeout. @@ -665,7 +635,7 @@ Usage: ``yield gen.moment`` class Runner(object): - """Internal implementation of `tornado.gen.engine`. + """Internal implementation of `tornado.gen.coroutine`. Maintains information about pending callbacks and their results. diff --git a/tornado/httpclient.py b/tornado/httpclient.py index e3c933058..7c2f2568a 100644 --- a/tornado/httpclient.py +++ b/tornado/httpclient.py @@ -42,7 +42,6 @@ from __future__ import absolute_import, division, print_function import functools import time -import warnings import weakref from tornado.concurrent import Future, future_set_result_unless_cancelled diff --git a/tornado/iostream.py b/tornado/iostream.py index 0df21bc62..da6817349 100644 --- a/tornado/iostream.py +++ b/tornado/iostream.py @@ -37,7 +37,7 @@ import re from tornado.concurrent import Future from tornado import ioloop -from tornado.log import gen_log, app_log +from tornado.log import gen_log from tornado.netutil import ssl_wrap_socket, _client_ssl_defaults, _server_ssl_defaults from tornado.util import errno_from_exception diff --git a/tornado/platform/twisted.py b/tornado/platform/twisted.py index 8c7b217a8..a5f41ab6b 100644 --- a/tornado/platform/twisted.py +++ b/tornado/platform/twisted.py @@ -39,7 +39,6 @@ import twisted.names.resolve # type: ignore from tornado.concurrent import Future, future_set_exc_info from tornado.escape import utf8 from tornado import gen -import tornado.ioloop from tornado.netutil import Resolver diff --git a/tornado/test/concurrent_test.py b/tornado/test/concurrent_test.py index 05a419c4d..4cda31271 100644 --- a/tornado/test/concurrent_test.py +++ b/tornado/test/concurrent_test.py @@ -17,7 +17,6 @@ from __future__ import absolute_import, division, print_function import logging import re import socket -import warnings from tornado.concurrent import Future, run_on_executor, future_set_result_unless_cancelled from tornado.escape import utf8, to_unicode diff --git a/tornado/test/gen_test.py b/tornado/test/gen_test.py index 5ea5e0b79..89753b229 100644 --- a/tornado/test/gen_test.py +++ b/tornado/test/gen_test.py @@ -14,7 +14,7 @@ from tornado.concurrent import Future from tornado.ioloop import IOLoop from tornado.log import app_log from tornado.testing import AsyncHTTPTestCase, AsyncTestCase, ExpectLog, gen_test -from tornado.test.util import unittest, skipOnTravis, skipBefore33, skipBefore35, skipNotCPython, exec_test +from tornado.test.util import unittest, skipOnTravis, skipBefore33, skipBefore35, skipNotCPython, exec_test # noqa: E501 from tornado.web import Application, RequestHandler, HTTPError from tornado import gen diff --git a/tornado/testing.py b/tornado/testing.py index 018374fc6..444b62f24 100644 --- a/tornado/testing.py +++ b/tornado/testing.py @@ -30,7 +30,7 @@ from tornado import netutil from tornado.platform.asyncio import AsyncIOMainLoop from tornado.process import Subprocess from tornado.log import app_log -from tornado.util import raise_exc_info, basestring_type, PY3 +from tornado.util import raise_exc_info, basestring_type _NON_OWNED_IOLOOPS = AsyncIOMainLoop diff --git a/tornado/web.py b/tornado/web.py index 49639b415..a490ea9a9 100644 --- a/tornado/web.py +++ b/tornado/web.py @@ -245,8 +245,7 @@ class RequestHandler(object): of the request method. Asynchronous support: Decorate this method with `.gen.coroutine` - or use ``async def`` to make it asynchronous (the - `asynchronous` decorator cannot be used on `prepare`). + or use ``async def`` to make it asynchronous. If this method returns a `.Future` execution will not proceed until the `.Future` is done. diff --git a/tornado/wsgi.py b/tornado/wsgi.py index 0e7067604..3f31ddb8a 100644 --- a/tornado/wsgi.py +++ b/tornado/wsgi.py @@ -16,16 +16,15 @@ """WSGI support for the Tornado web framework. WSGI is the Python standard for web servers, and allows for interoperability -between Tornado and other Python web frameworks and servers. This module -provides WSGI support in two ways: - -* `WSGIAdapter` converts a `tornado.web.Application` to the WSGI application - interface. This is useful for running a Tornado app on another - HTTP server, such as Google App Engine. See the `WSGIAdapter` class - documentation for limitations that apply. -* `WSGIContainer` lets you run other WSGI applications and frameworks on the - Tornado HTTP server. For example, with this class you can mix Django - and Tornado handlers in a single server. +between Tornado and other Python web frameworks and servers. + +This module provides WSGI support via the `WSGIContainer` class, which +makes it possible to run applications using other WSGI frameworks on +the Tornado HTTP server. The reverse is not supported; the Tornado +`.Application` and `.RequestHandler` classes are designed for use with +the Tornado `.HTTPServer` and cannot be used in a generic WSGI +container. + """ from __future__ import absolute_import, division, print_function