From 8a911d639f9cb3528dbb49fbdef63974b86cd46c Mon Sep 17 00:00:00 2001 From: Ben Darnell Date: Sun, 27 Sep 2015 16:52:04 -0400 Subject: [PATCH] Use autodoc for asyncio and twisted docs. --- docs/asyncio.rst | 58 +---------------------- docs/requirements.txt | 1 + docs/twisted.rst | 73 ++++++---------------------- tornado/platform/asyncio.py | 53 +++++++++++++++++---- tornado/platform/twisted.py | 94 +++++++++++++++---------------------- 5 files changed, 101 insertions(+), 178 deletions(-) create mode 100644 docs/requirements.txt diff --git a/docs/asyncio.rst b/docs/asyncio.rst index a6803503..fc737451 100644 --- a/docs/asyncio.rst +++ b/docs/asyncio.rst @@ -1,59 +1,5 @@ ``tornado.platform.asyncio`` --- Bridge between ``asyncio`` and Tornado ======================================================================= -.. module:: tornado.platform.asyncio - -.. versionadded:: 3.2 - -This module integrates Tornado with the ``asyncio`` module introduced -in Python 3.4 (and available `as a separate download -`_ for Python 3.3). This makes -it possible to combine the two libraries on the same event loop. - -Most applications should use `AsyncIOMainLoop` to run Tornado on the -default ``asyncio`` event loop. Applications that need to run event -loops on multiple threads may use `AsyncIOLoop` to create multiple -loops. - -.. note:: - - Tornado requires the `~asyncio.BaseEventLoop.add_reader` family of methods, - so it is not compatible with the `~asyncio.ProactorEventLoop` on Windows. - Use the `~asyncio.SelectorEventLoop` instead. - -.. py:class:: AsyncIOMainLoop - - ``AsyncIOMainLoop`` creates an `.IOLoop` that corresponds to the - current ``asyncio`` event loop (i.e. the one returned by - ``asyncio.get_event_loop()``). Recommended usage:: - - from tornado.platform.asyncio import AsyncIOMainLoop - import asyncio - AsyncIOMainLoop().install() - asyncio.get_event_loop().run_forever() - -.. py:class:: AsyncIOLoop - - ``AsyncIOLoop`` is an `.IOLoop` that runs on an ``asyncio`` event loop. - This class follows the usual Tornado semantics for creating new - ``IOLoops``; these loops are not necessarily related to the - ``asyncio`` default event loop. Recommended usage:: - - from tornado.ioloop import IOLoop - IOLoop.configure('tornado.platform.asyncio.AsyncIOLoop') - IOLoop.current().start() - - Each ``AsyncIOLoop`` creates a new ``asyncio.EventLoop``; this object - can be accessed with the ``asyncio_loop`` attribute. - -.. py:function:: to_tornado_future - - Convert an ``asyncio.Future`` to a `tornado.concurrent.Future`. - - .. versionadded:: 4.1 - -.. py:function:: to_asyncio_future - - Convert a `tornado.concurrent.Future` to an ``asyncio.Future``. - - .. versionadded:: 4.1 +.. automodule:: tornado.platform.asyncio + :members: diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 00000000..082785c9 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1 @@ +Twisted diff --git a/docs/twisted.rst b/docs/twisted.rst index f60d08e5..a6e1946f 100644 --- a/docs/twisted.rst +++ b/docs/twisted.rst @@ -1,69 +1,24 @@ ``tornado.platform.twisted`` --- Bridges between Twisted and Tornado ======================================================================== -.. module:: tornado.platform.twisted +.. automodule:: tornado.platform.twisted -This module lets you run applications and libraries written for -Twisted in a Tornado application. It can be used in two modes, -depending on which library's underlying event loop you want to use. + Twisted on Tornado + ------------------ -This module has been tested with Twisted versions 11.0.0 and newer. + .. autoclass:: TornadoReactor + :members: -Twisted on Tornado ------------------- + .. autofunction:: install -.. py:class:: TornadoReactor + Tornado on Twisted + ------------------ - ``TornadoReactor`` implements the Twisted reactor interface on top of - the Tornado IOLoop. To use it, simply call ``install`` at the beginning - of the application:: + .. autoclass:: TwistedIOLoop + :members: - import tornado.platform.twisted - tornado.platform.twisted.install() - from twisted.internet import reactor + Twisted DNS resolver + -------------------- - When the app is ready to start, call ``IOLoop.current().start()`` - instead of ``reactor.run()``. - - It is also possible to create a non-global reactor by calling - ``tornado.platform.twisted.TornadoReactor(io_loop)``. However, if - the `.IOLoop` and reactor are to be short-lived (such as those used in - unit tests), additional cleanup may be required. Specifically, it is - recommended to call:: - - reactor.fireSystemEvent('shutdown') - reactor.disconnectAll() - - before closing the `.IOLoop`. - -Tornado on Twisted ------------------- - -.. py:class:: TwistedIOLoop - - ``TwistedIOLoop`` implements the Tornado IOLoop interface on top - of the Twisted reactor. Recommended usage:: - - from tornado.platform.twisted import TwistedIOLoop - from twisted.internet import reactor - TwistedIOLoop().install() - # Set up your tornado application as usual using `IOLoop.instance` - reactor.run() - - ``TwistedIOLoop`` always uses the global Twisted reactor. - -Twisted DNS resolver --------------------- - -.. py:class:: TwistedResolver - - 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.ThreadedResolver`. 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. + .. autoclass:: TwistedResolver + :members: diff --git a/tornado/platform/asyncio.py b/tornado/platform/asyncio.py index cfeadc98..c95c207f 100644 --- a/tornado/platform/asyncio.py +++ b/tornado/platform/asyncio.py @@ -1,12 +1,22 @@ """Bridges between the `asyncio` module and Tornado IOLoop. -This is a work in progress and interfaces are subject to change. +.. versionadded:: 3.2 -To test: -python3.4 -m tornado.test.runtests --ioloop=tornado.platform.asyncio.AsyncIOLoop -python3.4 -m tornado.test.runtests --ioloop=tornado.platform.asyncio.AsyncIOMainLoop -(the tests log a few warnings with AsyncIOMainLoop because they leave some -unfinished callbacks on the event loop that fail when it resumes) +This module integrates Tornado with the ``asyncio`` module introduced +in Python 3.4 (and available `as a separate download +`_ for Python 3.3). This makes +it possible to combine the two libraries on the same event loop. + +Most applications should use `AsyncIOMainLoop` to run Tornado on the +default ``asyncio`` event loop. Applications that need to run event +loops on multiple threads may use `AsyncIOLoop` to create multiple +loops. + +.. note:: + + Tornado requires the `~asyncio.BaseEventLoop.add_reader` family of methods, + so it is not compatible with the `~asyncio.ProactorEventLoop` on Windows. + Use the `~asyncio.SelectorEventLoop` instead. """ from __future__ import absolute_import, division, print_function, with_statement @@ -140,12 +150,33 @@ class BaseAsyncIOLoop(IOLoop): class AsyncIOMainLoop(BaseAsyncIOLoop): + """``AsyncIOMainLoop`` creates an `.IOLoop` that corresponds to the + current ``asyncio`` event loop (i.e. the one returned by + ``asyncio.get_event_loop()``). Recommended usage:: + + from tornado.platform.asyncio import AsyncIOMainLoop + import asyncio + AsyncIOMainLoop().install() + asyncio.get_event_loop().run_forever() + """ def initialize(self, **kwargs): super(AsyncIOMainLoop, self).initialize(asyncio.get_event_loop(), close_loop=False, **kwargs) class AsyncIOLoop(BaseAsyncIOLoop): + """``AsyncIOLoop`` is an `.IOLoop` that runs on an ``asyncio`` event loop. + This class follows the usual Tornado semantics for creating new + ``IOLoops``; these loops are not necessarily related to the + ``asyncio`` default event loop. Recommended usage:: + + from tornado.ioloop import IOLoop + IOLoop.configure('tornado.platform.asyncio.AsyncIOLoop') + IOLoop.current().start() + + Each ``AsyncIOLoop`` creates a new ``asyncio.EventLoop``; this object + can be accessed with the ``asyncio_loop`` attribute. + """ def initialize(self, **kwargs): loop = asyncio.new_event_loop() try: @@ -158,14 +189,20 @@ class AsyncIOLoop(BaseAsyncIOLoop): def to_tornado_future(asyncio_future): - """Convert an ``asyncio.Future`` to a `tornado.concurrent.Future`.""" + """Convert an `asyncio.Future` to a `tornado.concurrent.Future`. + + .. versionadded:: 4.1 + """ tf = tornado.concurrent.Future() tornado.concurrent.chain_future(asyncio_future, tf) return tf def to_asyncio_future(tornado_future): - """Convert a `tornado.concurrent.Future` to an ``asyncio.Future``.""" + """Convert a `tornado.concurrent.Future` to an `asyncio.Future`. + + .. versionadded:: 4.1 + """ af = asyncio.Future() tornado.concurrent.chain_future(tornado_future, af) return af diff --git a/tornado/platform/twisted.py b/tornado/platform/twisted.py index 272955a8..827e3bd2 100644 --- a/tornado/platform/twisted.py +++ b/tornado/platform/twisted.py @@ -12,10 +12,6 @@ # WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the # License for the specific language governing permissions and limitations # under the License. - -# Note: This module's docs are not currently extracted automatically, -# so changes must be made manually to twisted.rst -# TODO: refactor doc build process to use an appropriate virtualenv """Bridges between the Twisted reactor and Tornado IOLoop. This module lets you run applications and libraries written for @@ -23,45 +19,6 @@ Twisted in a Tornado application. It can be used in two modes, depending on which library's underlying event loop you want to use. This module has been tested with Twisted versions 11.0.0 and newer. - -Twisted on Tornado ------------------- - -`TornadoReactor` implements the Twisted reactor interface on top of -the Tornado IOLoop. To use it, simply call `install` at the beginning -of the application:: - - import tornado.platform.twisted - tornado.platform.twisted.install() - from twisted.internet import reactor - -When the app is ready to start, call `IOLoop.current().start()` -instead of `reactor.run()`. - -It is also possible to create a non-global reactor by calling -`tornado.platform.twisted.TornadoReactor(io_loop)`. However, if -the `IOLoop` and reactor are to be short-lived (such as those used in -unit tests), additional cleanup may be required. Specifically, it is -recommended to call:: - - reactor.fireSystemEvent('shutdown') - reactor.disconnectAll() - -before closing the `IOLoop`. - -Tornado on Twisted ------------------- - -`TwistedIOLoop` implements the Tornado IOLoop interface on top of the Twisted -reactor. Recommended usage:: - - from tornado.platform.twisted import TwistedIOLoop - from twisted.internet import reactor - TwistedIOLoop().install() - # Set up your tornado application as usual using `IOLoop.instance` - reactor.run() - -`TwistedIOLoop` always uses the global Twisted reactor. """ from __future__ import absolute_import, division, print_function, with_statement @@ -144,12 +101,27 @@ class TornadoDelayedCall(object): class TornadoReactor(PosixReactorBase): """Twisted reactor built on the Tornado IOLoop. - Since it is intended to be used in applications where the top-level - event loop is ``io_loop.start()`` rather than ``reactor.run()``, - it is implemented a little differently than other Twisted reactors. - We override `mainLoop` instead of `doIteration` and must implement - timed call functionality on top of `IOLoop.add_timeout` rather than - using the implementation in `PosixReactorBase`. + `TornadoReactor` implements the Twisted reactor interface on top of + the Tornado IOLoop. To use it, simply call `install` at the beginning + of the application:: + + import tornado.platform.twisted + tornado.platform.twisted.install() + from twisted.internet import reactor + + When the app is ready to start, call ``IOLoop.current().start()`` + instead of ``reactor.run()``. + + It is also possible to create a non-global reactor by calling + ``tornado.platform.twisted.TornadoReactor(io_loop)``. However, if + the `.IOLoop` and reactor are to be short-lived (such as those used in + unit tests), additional cleanup may be required. Specifically, it is + recommended to call:: + + reactor.fireSystemEvent('shutdown') + reactor.disconnectAll() + + before closing the `.IOLoop`. .. versionchanged:: 4.1 The ``io_loop`` argument is deprecated. @@ -191,7 +163,6 @@ class TornadoReactor(PosixReactorBase): # IReactorThreads def callFromThread(self, f, *args, **kw): - """See `twisted.internet.interfaces.IReactorThreads.callFromThread`""" assert callable(f), "%s is not callable" % f with NullContext(): # This NullContext is mainly for an edge case when running @@ -237,7 +208,6 @@ class TornadoReactor(PosixReactorBase): writer.writeConnectionLost(failure.Failure(err)) def addReader(self, reader): - """Add a FileDescriptor for notification of data available to read.""" if reader in self._readers: # Don't add the reader if it's already there return @@ -257,7 +227,6 @@ class TornadoReactor(PosixReactorBase): IOLoop.READ) def addWriter(self, writer): - """Add a FileDescriptor for notification of data available to write.""" if writer in self._writers: return fd = writer.fileno() @@ -276,7 +245,6 @@ class TornadoReactor(PosixReactorBase): IOLoop.WRITE) def removeReader(self, reader): - """Remove a Selectable for notification of data available to read.""" if reader in self._readers: fd = self._readers.pop(reader) (_, writer) = self._fds[fd] @@ -293,7 +261,6 @@ class TornadoReactor(PosixReactorBase): self._io_loop.remove_handler(fd) def removeWriter(self, writer): - """Remove a Selectable for notification of data available to write.""" if writer in self._writers: fd = self._writers.pop(writer) (reader, _) = self._fds[fd] @@ -334,6 +301,14 @@ class TornadoReactor(PosixReactorBase): raise NotImplementedError("doIteration") def mainLoop(self): + # Since this class is intended to be used in applications + # where the top-level event loop is ``io_loop.start()`` rather + # than ``reactor.run()``, it is implemented a little + # differently than other Twisted reactors. We override + # ``mainLoop`` instead of ``doIteration`` and must implement + # timed call functionality on top of `.IOLoop.add_timeout` + # rather than using the implementation in + # ``PosixReactorBase``. self._io_loop.start() @@ -408,8 +383,17 @@ class _FD(object): class TwistedIOLoop(tornado.ioloop.IOLoop): """IOLoop implementation that runs on Twisted. + `TwistedIOLoop` implements the Tornado IOLoop interface on top of + the Twisted reactor. Recommended usage:: + + from tornado.platform.twisted import TwistedIOLoop + from twisted.internet import reactor + TwistedIOLoop().install() + # Set up your tornado application as usual using `IOLoop.instance` + reactor.run() + Uses the global Twisted reactor by default. To create multiple - `TwistedIOLoops` in the same process, you must pass a unique reactor + ``TwistedIOLoops`` in the same process, you must pass a unique reactor when constructing each one. Not compatible with `tornado.process.Subprocess.set_exit_callback`