--- /dev/null
+``tornado.platform.caresresolver`` --- Asynchronous DNS Resolver using C-Ares
+=============================================================================
+
+.. module:: tornado.platform.caresresolver
+
+This module contains a DNS resolver using the c-ares library (and its
+wrapper ``pycares``).
+
+.. py:class:: CaresResolver
+
+ Name resolver based on the c-ares library.
+
+ This is a non-blocking and non-threaded resolver. It may not produce
+ the same results as the system resolver, but can be used for non-blocking
+ resolution when threads cannot be used.
+
+ c-ares fails to resolve some names when ``family`` is ``AF_UNSPEC``,
+ so it is only recommended for use in ``AF_INET`` (i.e. IPv4). This is
+ the default for ``tornado.simple_httpclient``, but other libraries
+ may default to ``AF_UNSPEC``.
.. toctree::
auth
+ caresresolver
twisted
websocket
wsgi
to the root logger, allowing for finer-grained configuration.
* New class `tornado.process.Subprocess` wraps `subprocess.Popen` with
`.PipeIOStream` access to the child's file descriptors.
-* `.IOLoop` now has a static ``configure`` method like the one on
- `.AsyncHTTPClient`, which can be used to select an IOLoop implementation
- other than the default.
+* `.IOLoop` now has a static `configure <.Configurable.configure>`
+ method like the one on `.AsyncHTTPClient`, which can be used to
+ select an `.IOLoop` implementation other than the default.
* `.IOLoop` can now optionally use a monotonic clock if available
(see below for more details).
specific thread's (usually the main thread's) IOLoop).
* New method `.IOLoop.add_future` to run a callback on the IOLoop when
an asynchronous ``Future`` finishes.
-* `.IOLoop` now has a static ``configure`` method like the one on
- `.AsyncHTTPClient`, which can be used to select an IOLoop implementation
- other than the default.
+* `.IOLoop` now has a static `configure <.Configurable.configure>`
+ method like the one on `.AsyncHTTPClient`, which can be used to
+ select an `.IOLoop` implementation other than the default.
* The `.IOLoop` poller implementations (``select``, ``epoll``, ``kqueue``)
are now available as distinct subclasses of `.IOLoop`. Instantiating
`.IOLoop` will continue to automatically choose the best available
blocking, but non-blocking implementations are available using one
of three optional dependencies: `~tornado.netutil.ThreadedResolver`
using the `concurrent.futures` thread pool,
- ``tornado.platform.caresresolver.CaresResolver`` using the ``pycares``
- library, or ``tornado.platform.twisted.TwistedResolver`` using ``twisted``
+ `tornado.platform.caresresolver.CaresResolver` using the ``pycares``
+ library, or `tornado.platform.twisted.TwistedResolver` using ``twisted``
* New function `tornado.netutil.is_valid_ip` returns true if a given string
is a valid IP (v4 or v6) address.
* `tornado.netutil.bind_sockets` has a new ``flags`` argument that can
* Function ``tornado.options.enable_pretty_logging`` has been moved to the
`tornado.log` module.
-```tornado.platform.caresresolver``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+`tornado.platform.caresresolver`
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* New module containing an asynchronous implementation of the `.Resolver`
interface, using the ``pycares`` library.
`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).
-* New class ``tornado.platform.twisted.TwistedResolver`` is an asynchronous
+ `.TornadoReactor`, which bridges the gap in the other direction).
+* New class `tornado.platform.twisted.TwistedResolver` is an asynchronous
implementation of the `.Resolver` interface.
`tornado.process`
``tornado.simple_httpclient``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-* ``SimpleAsyncHTTPClient`` now takes a ``resolver`` keyword argument (which
- may be passed to either the constructor or ``configure``), to allow it to
- use the new non-blocking `tornado.netutil.Resolver`.
+* ``SimpleAsyncHTTPClient`` now takes a ``resolver`` keyword argument
+ (which may be passed to either the constructor or `configure
+ <.Configurable.configure>`), to allow it to use the new non-blocking
+ `tornado.netutil.Resolver`.
* When following redirects, ``SimpleAsyncHTTPClient`` now treats a 302
response code the same as a 303. This is contrary to the HTTP spec
but consistent with all browsers and other major HTTP clients
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::
+.. py:class:: TornadoReactor
- import tornado.platform.twisted
- tornado.platform.twisted.install()
- from twisted.internet import reactor
+ ``TornadoReactor`` implements the Twisted reactor interface on top of
+ the Tornado IOLoop. To use it, simply call ``install`` at the beginning
+ of the application::
-When the app is ready to start, call ``IOLoop.instance().start()``
-instead of ``reactor.run()``.
+ import tornado.platform.twisted
+ tornado.platform.twisted.install()
+ from twisted.internet import reactor
-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::
+ When the app is ready to start, call ``IOLoop.instance().start()``
+ instead of ``reactor.run()``.
- reactor.fireSystemEvent('shutdown')
- reactor.disconnectAll()
+ 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::
-before closing the `.IOLoop`.
+ 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::
+.. py:class:: TwistedIOLoop
- 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`` implements the Tornado IOLoop interface on top
+ of the Twisted reactor. Recommended usage::
-``TwistedIOLoop`` always uses the global Twisted reactor.
+ 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()
-This module has been tested with Twisted versions 11.0.0 and newer.
+ ``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.
--- /dev/null
+``tornado.util`` --- General-purpose utilities
+==============================================
+
+.. automodule:: tornado.util
+ :members:
process
stack_context
testing
+ util
By default, a blocking implementation is used (which simply calls
`socket.getaddrinfo`). An alternative implementation can be
- chosen with the ``Resolver.configure`` class method::
+ chosen with the `Resolver.configure <.Configurable.configure>`
+ class method::
Resolver.configure('tornado.netutil.ThreadedResolver')
* `tornado.netutil.BlockingResolver`
* `tornado.netutil.ThreadedResolver`
* `tornado.netutil.OverrideResolver`
- * ``tornado.platform.twisted.TwistedResolver``
- * ``tornado.platform.caresresolver.CaresResolver``
+ * `tornado.platform.twisted.TwistedResolver`
+ * `tornado.platform.caresresolver.CaresResolver`
"""
@classmethod
def configurable_base(cls):
c-ares fails to resolve some names when ``family`` is ``AF_UNSPEC``,
so it is only recommended for use in ``AF_INET`` (i.e. IPv4). This is
- the default for `tornado.simple_httpclient`, but other libraries
+ the default for ``tornado.simple_httpclient``, but other libraries
may default to ``AF_UNSPEC``.
"""
def initialize(self, io_loop=None):
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
------------------
reactor.run()
`TwistedIOLoop` always uses the global Twisted reactor.
-
-This module has been tested with Twisted versions 11.0.0 and newer.
"""
from __future__ import absolute_import, division, print_function, with_statement
-"""Miscellaneous utility functions."""
+"""Miscellaneous utility functions and classes.
+
+This module is used internally by Tornado. It is not necessarily expected
+that the functions and classes defined here will be useful to other
+applications, but they are documented here in case they are.
+
+The one public-facing part of this module is the `Configurable` class
+and its `~Configurable.configure` method, which becomes a part of the
+interface of its subclasses, including `.AsyncHTTPClient`, `.IOLoop`,
+and `.Resolver`.
+"""
from __future__ import absolute_import, division, print_function, with_statement
class ObjectDict(dict):
- """Makes a dictionary behave like an object."""
+ """Makes a dictionary behave like an object, with attribute-style access.
+ """
def __getattr__(self, name):
try:
return self[name]
The implementation subclass as well as optional keyword arguments to
its initializer can be set globally at runtime with `configure`.
- By using the constructor as the factory method, the interface looks like
- a normal class, ``isinstance()`` works as usual, etc. This pattern
- is most useful when the choice of implementation is likely to be a
- global decision (e.g. when epoll is available, always use it instead of
- select), or when a previously-monolithic class has been split into
- specialized subclasses.
+ By using the constructor as the factory method, the interface
+ looks like a normal class, `isinstance` works as usual, etc. This
+ pattern is most useful when the choice of implementation is likely
+ to be a global decision (e.g. when `~select.epoll` is available,
+ always use it instead of `~select.select`), or when a
+ previously-monolithic class has been split into specialized
+ subclasses.
Configurable subclasses must define the class methods
`configurable_base` and `configurable_default`, and use the instance
- method `initialize` instead of `__init__`.
+ method `initialize` instead of ``__init__``.
"""
__impl_class = None
__impl_kwargs = None
def initialize(self):
"""Initialize a `Configurable` subclass instance.
- Configurable classes should use `initialize` instead of `__init__`.
+ Configurable classes should use `initialize` instead of ``__init__``.
"""
@classmethod
and similar wrappers.
"""
def __init__(self, func, name):
- """Create an ArgReplacer for the named argument to the given function.
- """
self.name = name
try:
self.arg_pos = inspect.getargspec(func).args.index(self.name)
projects / thirdparty / tornado.git / commitdiff
