Commit 6ff24b44 authored by Jason Madden's avatar Jason Madden

Enable a default cache for dnspython. Add more docs.

parent 666b0f38
......@@ -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)
==================
......
......@@ -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
=============================================================
:mod:`gevent.resolver.blocking` -- Non-cooperative resolver
=============================================================
.. automodule:: gevent.resolver.blocking
:members:
......@@ -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
-------
......
......@@ -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):
......
......@@ -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 completely ignores the contents of ``/etc/hosts``, but it is
configured by ``/etc/resolv.conf`` (on Unix) or the registry (on
Windows).
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.
This uses thread locks and sockets, so it only functions if the system
has been monkey-patched. Otherwise it will raise a ``ValueError``.
Under Python 2, if the ``idna`` package is installed, this
resolver can resolve Unicode host names that the system resolver
cannot.
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). There are some measures in place to be able to resolve
``localhost`` related names and addresses through the system resolver.
.. caution::
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
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment