From c8f7ca7ce43324f676ef740ffd3a3ee10ae4338d Mon Sep 17 00:00:00 2001 From: Ben Darnell Date: Sun, 1 Nov 2020 21:09:08 -0500 Subject: [PATCH] docs: Stop using autodoc for t.p.twisted This way we don't have to install twisted into the docs build environment. Add some more detail while I'm here. --- docs/requirements.in | 1 - docs/requirements.txt | 8 ------ docs/twisted.rst | 57 ++++++++++++++++++++++++++++++++++++++----- 3 files changed, 51 insertions(+), 15 deletions(-) diff --git a/docs/requirements.in b/docs/requirements.in index 03e5a6923..334534d73 100644 --- a/docs/requirements.in +++ b/docs/requirements.in @@ -1,4 +1,3 @@ sphinx sphinxcontrib-asyncio sphinx_rtd_theme -Twisted diff --git a/docs/requirements.txt b/docs/requirements.txt index 101946c54..871d82a85 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,21 +1,15 @@ alabaster==0.7.12 -attrs==20.2.0 -Automat==20.2.0 Babel==2.8.0 certifi==2020.6.20 chardet==3.0.4 colorama==0.4.4 -constantly==15.1.0 docutils==0.16 -hyperlink==20.0.1 idna==2.10 imagesize==1.2.0 -incremental==17.5.0 Jinja2==2.11.2 MarkupSafe==1.1.1 packaging==20.4 Pygments==2.7.2 -PyHamcrest==2.0.2 pyparsing==2.4.7 pytz==2020.1 requests==2.24.0 @@ -30,6 +24,4 @@ sphinxcontrib-htmlhelp==1.0.3 sphinxcontrib-jsmath==1.0.1 sphinxcontrib-qthelp==1.0.3 sphinxcontrib-serializinghtml==1.1.4 -Twisted==20.3.0 urllib3==1.25.11 -zope.interface==5.1.2 diff --git a/docs/twisted.rst b/docs/twisted.rst index a5d971a04..f834eb55b 100644 --- a/docs/twisted.rst +++ b/docs/twisted.rst @@ -1,10 +1,55 @@ ``tornado.platform.twisted`` --- Bridges between Twisted and Tornado -======================================================================== +==================================================================== -.. automodule:: tornado.platform.twisted +.. module:: tornado.platform.twisted - Twisted DNS resolver - -------------------- +.. deprecated:: 6.0 - .. autoclass:: TwistedResolver - :members: + This module is no longer recommended for new code. Instead of using + direct integration between Tornado and Twisted, new applications should + rely on the integration with ``asyncio`` provided by both packages. + +Importing this module has the side effect of registering Twisted's ``Deferred`` +class with Tornado's ``@gen.coroutine`` so that ``Deferred`` objects can be +used with ``yield`` in coroutines using this decorator (importing this module has +no effect on native coroutines using ``async def``). + +.. function:: install() + + Install ``AsyncioSelectorReactor`` as the default Twisted reactor. + + .. deprecated:: 5.1 + + This function is provided for backwards compatibility; code + that does not require compatibility with older versions of + Tornado should use + ``twisted.internet.asyncioreactor.install()`` directly. + + .. versionchanged:: 6.0.3 + + In Tornado 5.x and before, this function installed a reactor + based on the Tornado ``IOLoop``. When that reactor + implementation was removed in Tornado 6.0.0, this function was + removed as well. It was restored in Tornado 6.0.3 using the + ``asyncio`` reactor instead. + +Twisted DNS resolver +-------------------- + +.. class:: TwistedResolver + + Twisted-based asynchronous resolver. + + This is a non-blocking and non-threaded resolver. It is + recommended only when threads cannot be used, since it has + limitations compared to the standard ``getaddrinfo``-based + `~tornado.netutil.Resolver` and + `~tornado.netutil.DefaultExecutorResolver`. Specifically, it returns at + most one result, and arguments other than ``host`` and ``family`` + are ignored. It may fail to resolve when ``family`` is not + ``socket.AF_UNSPEC``. + + Requires Twisted 12.1 or newer. + + .. versionchanged:: 5.0 + The ``io_loop`` argument (deprecated since version 4.1) has been removed. -- 2.47.2