Enable a default cache for dnspython. Add more docs.

CHANGES.rst

@@ -33,7 +33,7 @@
   5.10.1.
 
 - Add the ``dnspython`` resolver as a lightweight alternative to
-  c-ares.
+  c-ares. See :pr:`1088`.
 
 1.3a1 (2018-01-27)
 ==================

doc/dns.rst

@@ -11,7 +11,7 @@ through the :attr:`resolver attribute <gevent.hub.Hub.resolver>` of the
 :mod:`gevent.socket` module.
 
 A resolver implements the 5 standandard functions from the
-:mod:`socket` module for resolving hostnames:
+:mod:`socket` module for resolving hostnames and addresses:
 
 * :func:`socket.gethostbyname`
 * :func:`socket.gethostbyname_ex`
@@ -35,8 +35,12 @@ variable. Specify ``ares``, ``thread``, ``dnspython``, or ``block`` to use the
 the fully-qualified name of an implementation of the standard
 functions.
 
+Please see the documentation for each resolver class to understand the
+relative performance and correctness tradeoffs.
+
 .. toctree::
 
    gevent.resolver.thread
    gevent.resolver.ares
    gevent.resolver.dnspython
+   gevent.resolver.blocking

doc/gevent.resolver.blocking.rst

+=============================================================
+ :mod:`gevent.resolver.blocking` -- Non-cooperative resolver
+=============================================================
+
+.. automodule:: gevent.resolver.blocking
+    :members:

doc/gevent.socket.rst

@@ -2,6 +2,8 @@
  :mod:`gevent.socket` -- Cooperative low-level networking interface
 ====================================================================
 
+.. module:: gevent.socket
+
 This module provides socket operations and some related functions. The
 API of the functions and classes matches the API of the corresponding
 items in the standard :mod:`socket` module exactly, but the
@@ -48,6 +50,10 @@ Beyond the basic standard library interface, ``gevent.socket``
 provides some extensions. These are identical and shared by all
 versions of Python.
 
+.. versionchanged:: 1.3a2
+   The undocumented class ``BlockingResolver`` has been documented
+   and moved to :class:`gevent.resolver.blocking.Resolver`.
+
 Waiting
 -------
 

src/gevent/resolver/blocking.py

@@ -5,6 +5,24 @@ import _socket
 class Resolver(object):
     """
     A resolver that directly uses the system's resolver functions.
+
+    .. caution::
+
+        This resolver is *not* cooperative.
+
+    This resolver has the lowest overhead of any resolver and
+    typically approaches the speed of the unmodified :mod:`socket`
+    functions. However, it is not cooperative, so if name resolution
+    blocks, the entire thread and all its greenlets will be blocked.
+
+    This can be useful during debugging, or it may be a good choice if
+    your operating system provides a good caching resolver (such as
+    macOS's Directory Services) that is usually very fast and
+    functionally non-blocking.
+
+    .. versionchanged:: 1.3a2
+       This was previously undocumented and existed in :mod:`gevent.socket`.
+
     """
 
     def __init__(self, hub=None):

src/gevent/resolver/dnspython.py

@@ -125,19 +125,44 @@ def _getaddrinfo(host=None, service=None, family=socket.AF_UNSPEC, socktype=0,
 
 class Resolver(AbstractResolver):
     """
-    A resolver that uses dnspython.
+    An *experimental* resolver that uses `dnspython`_.
+
+    This is typically slower than the default threaded resolver
+    (unless there's a cache hit, in which case it can be much faster).
+    It is usually much faster than the c-ares resolver. It tends to
+    scale well as more concurrent resolutions are attempted.
+
+    Under Python 2, if the ``idna`` package is installed, this
+    resolver can resolve Unicode host names that the system resolver
+    cannot.
+
+    This uses thread locks and sockets, so it only functions if the
+    system has been monkey-patched. Otherwise it will raise a
+    ``ValueError``.
+
+    This uses dnspython's default resolver object. This object has
+    several useful attributes that can be used to adjust the behaviour
+    of the DNS system; in particular, the ``cache`` attribute could be
+    set to an instance of :class:`dns.resolver.Cache` or
+    :class:`dns.resolver.LRUCache` (by default a ``LRUCache`` is
+    used), and ``nameservers`` controls which nameservers to talk to,
+    and ``lifetime`` configures a timeout for each individual query.
+
+    .. caution::
 
         This completely ignores the contents of ``/etc/hosts``, but it is
         configured by ``/etc/resolv.conf`` (on Unix) or the registry (on
-    Windows).
+        Windows). There are some measures in place to be able to resolve
+        ``localhost`` related names and addresses through the system resolver.
 
-    This uses thread locks and sockets, so it only functions if the system
-    has been monkey-patched. Otherwise it will raise a ``ValueError``.
+    .. caution::
 
-    Under Python 2, if the ``idna`` package is installed, this resolver
-    can resolve Unicode host names that the system resolver cannot.
+        This resolver is experimental. It may be removed or modified in
+        the future. As always, feedback is welcome.
 
     .. versionadded:: 1.3a2
+
+    .. _dnspython: http://www.dnspython.org
     """
 
     def __init__(self, hub=None): # pylint: disable=unused-argument
@@ -146,6 +171,8 @@ class Resolver(AbstractResolver):
             raise ValueError("Can only be used when monkey-patched")
         if resolver._resolver is None:
             resolver._resolver = resolver.get_default_resolver()
+            # Add a default cache
+            resolver._resolver.cache = resolver.LRUCache()
         if resolver._getaddrinfo is not _getaddrinfo:
             resolver._getaddrinfo = _getaddrinfo