async doco

14 files changed, 161 insertions, 100 deletions

diff --git a/dns/asyncbackend.py b/dns/asyncbackend.py
index 92a1ae3..069eaf0 100644
--- a/dns/asyncbackend.py
+++ b/dns/asyncbackend.py
@@ -6,16 +6,51 @@ from dns._asyncbackend import Socket, DatagramSocket, \
 
 
 _default_backend = None
+_trio_backend = None
+_curio_backend = None
+_asyncio_backend = None
 
 
-def get_default_backend():
-    if _default_backend:
-        return _default_backend
+def get_backend(name):
+    """Get the specified asychronous backend.
 
-    return set_default_backend(sniff())
+    *name*, a ``str``, the name of the backend.  Currently the "trio",
+    "curio", and "asyncio" backends are available.
+
+    Raises NotImplementError if an unknown backend name is specified.
+    """
+    if name == 'trio':
+        global _trio_backend
+        if _trio_backend:
+            return _trio_backend
+        import dns._trio_backend
+        _trio_backend = dns._trio_backend.Backend()
+        return _trio_backend
+    elif name == 'curio':
+        global _curio_backend
+        if _curio_backend:
+            return _curio_backend
+        import dns._curio_backend
+        _curio_backend = dns._curio_backend.Backend()
+        return _curio_backend
+    elif name == 'asyncio':
+        global _asyncio_backend
+        if _asyncio_backend:
+            return _asyncio_backend
+        import dns._asyncio_backend
+        _asyncio_backend = dns._asyncio_backend.Backend()
+        return _asyncio_backend
+    else:
+        raise NotImplementedError(f'unimplemented async backend {name}')
 
 
 def sniff():
+    """Attempt to determine the in-use asynchronous I/O library by using
+    the ``sniffio`` module if it is available.
+
+    Returns the name of the library, defaulting to "asyncio" if no other
+    library appears to be in use.
+    """
     name = 'asyncio'
     try:
         import sniffio
@@ -25,19 +60,26 @@ def sniff():
     return name
 
 
+def get_default_backend():
+    """Get the default backend, initializing it if necessary.
+    """
+    if _default_backend:
+        return _default_backend
+
+    return set_default_backend(sniff())
+
+
 def set_default_backend(name):
+    """Set the default backend.
+
+    It's not normally necessary to call this method, as
+    ``get_default_backend()`` will initialize the backend
+    appropriately in many cases.  If ``sniffio`` is not installed, or
+    in testing situations, this function allows the backend to be set
+    explicitly.
+    """
     global _default_backend
+    _default_backend = get_backend(name)
+    return _default_backend
 
-    if name == 'trio':
-        import dns._trio_backend
-        _default_backend = dns._trio_backend.Backend()
-    elif name == 'curio':
-        import dns._curio_backend
-        _default_backend = dns._curio_backend.Backend()
-    elif name == 'asyncio':
-        import dns._asyncio_backend
-        _default_backend = dns._asyncio_backend.Backend()
-    else:
-        raise NotImplementedException(f'unimplemented async backend {name}')
 
-    return _default_backend
diff --git a/doc/async-backend.rst b/doc/async-backend.rst
new file mode 100644
index 0000000..ad3de00
--- /dev/null
+++ b/doc/async-backend.rst
@@ -0,0 +1,18 @@
+module:: dns.asyncbackend
+.. _async-backend:
+
+Asynchronous Backend Functions
+==============================
+
+Dnspython has a "backend" for Trio, Curio, and asyncio which implements
+the library-specific functionality needed by the generic asynchronous
+DNS code.
+
+Dnspython attempts to determine which backend is in use by "sniffing" for it
+with the ``sniffio`` module if it is installed, otherwise it assumes asyncio
+is in use.
+
+.. autofunction:: dns.asyncbackend.get_default_backend
+.. autofunction:: dns.asyncbackend.set_default_backend
+.. autofunction:: dns.asyncbackend.sniff
+.. autofunction:: dns.asyncbackend.get_backend
diff --git a/doc/async-query.rst b/doc/async-query.rst
new file mode 100644
index 0000000..1dc51cd
--- /dev/null
+++ b/doc/async-query.rst
@@ -0,0 +1,28 @@
+.. module:: dns.asyncquery
+.. _async_query:
+
+DNS Query Support
+=================
+
+The ``dns.asyncquery`` module is for sending messages to DNS servers, and
+processing their responses.  If you want "stub resolver" behavior, then
+you should use the higher level ``dns.asyncresolver`` module; see
+:ref:`async_resolver`.
+
+There is currently no support for zone transfers or DNS-over-HTTPS
+using asynchronous I/O but we hope to offer this in the future.
+
+UDP
+---
+
+.. autofunction:: dns.asyncquery.udp
+.. autofunction:: dns.asyncquery.udp_with_fallback
+.. autofunction:: dns.asyncquery.send_udp
+.. autofunction:: dns.asyncquery.receive_udp
+
+TCP
+---
+
+.. autofunction:: dns.asyncquery.tcp
+.. autofunction:: dns.asyncquery.send_tcp
+.. autofunction:: dns.asyncquery.receive_tcp
diff --git a/doc/async-resolver-class.rst b/doc/async-resolver-class.rst
new file mode 100644
index 0000000..9cf39a3
--- /dev/null
+++ b/doc/async-resolver-class.rst
@@ -0,0 +1,11 @@
+.. _async-resolver-class:
+
+The dns.asyncresolver.Resolver Class
+------------------------------------
+
+The async resolver is a subclass of ``dns.resolver.Resolver`` and has the
+same attributes.  The methods are similar, but I/O methods like ``resolve()``
+are asynchronous.
+
+.. autoclass:: dns.asyncresolver.Resolver
+   :members:
diff --git a/doc/async-resolver-functions.rst b/doc/async-resolver-functions.rst
new file mode 100644
index 0000000..fc5798a
--- /dev/null
+++ b/doc/async-resolver-functions.rst
@@ -0,0 +1,8 @@
+.. _async-resolver-functions:
+
+Asynchronous Resolver Functions
+===============================
+
+.. autofunction:: dns.asyncresolver.resolve
+.. autofunction:: dns.asyncresolver.resolve_address
+.. autofunction:: dns.asyncresolver.zone_for_name
diff --git a/doc/async-resolver.rst b/doc/async-resolver.rst
new file mode 100644
index 0000000..065c0a6
--- /dev/null
+++ b/doc/async-resolver.rst
@@ -0,0 +1,12 @@
+.. module:: dns.asyncresolver
+.. _async_resolver:
+
+Stub Resolver
+=============
+
+Dnspython's asyncresolver module implements an asynchronous "stub resolver".
+
+.. toctree::
+
+   async-resolver-class
+   async-resolver-functions
diff --git a/doc/async.rst b/doc/async.rst
new file mode 100644
index 0000000..e69b972
--- /dev/null
+++ b/doc/async.rst
@@ -0,0 +1,21 @@
+.. _async:
+
+Asynchronous I/O Support
+========================
+
+The ``dns.asyncquery`` and ``dns.asyncresolver`` modules offer
+asynchronous APIs equivalent to those of ``dns.query`` and
+``dns.resolver``.
+
+Dnspython presents a uniform API, but offers three different backend
+implementations, to support the Trio, Curio, and asyncio libraries.
+Dnspython attempts to detect which library is in use by using the
+``sniffio`` library if it is available.  It's also possible to
+explicitly select a "backend" library, or to pass a backend to
+a particular call, allowing for use in mixed library situations.
+
+.. toctree::
+
+   async-query
+   async-resolver
+   async-backend
diff --git a/doc/manual.rst b/doc/manual.rst
index 48243fa..b82b7e1 100644
--- a/doc/manual.rst
+++ b/doc/manual.rst
@@ -12,6 +12,6 @@ Dnspython Manual
    resolver
    zone
    dnssec
-   trio
+   async
    exceptions
    utilities
diff --git a/doc/trio-query.rst b/doc/trio-query.rst
deleted file mode 100644
index d4d0392..0000000
--- a/doc/trio-query.rst
+++ /dev/null
@@ -1,28 +0,0 @@
-.. module:: dns.trio.query
-.. _trio-query:
-
-DNS Query Support
-=================
-
-The ``dns.trio.query`` module is for sending messages to DNS servers, and
-processing their responses.  If you want "stub resolver" behavior, then
-you should use the higher level ``dns.trio.resolver`` module; see
-:ref:`trio_resolver`.
-
-There is currently no support for zone transfers or DNS-over-HTTPS
-using Trio, but we hope to offer this in the future.
-
-UDP
----
-
-.. autofunction:: dns.trio.query.udp
-.. autofunction:: dns.trio.query.udp_with_fallback
-.. autofunction:: dns.trio.query.send_udp
-.. autofunction:: dns.trio.query.receive_udp
-
-Streams (TCP and TLS)
----------------------
-
-.. autofunction:: dns.trio.query.stream
-.. autofunction:: dns.trio.query.send_stream
-.. autofunction:: dns.trio.query.receive_stream
diff --git a/doc/trio-resolver-class.rst b/doc/trio-resolver-class.rst
deleted file mode 100644
index 537c933..0000000
--- a/doc/trio-resolver-class.rst
+++ /dev/null
@@ -1,11 +0,0 @@
-.. _trio-resolver-class:
-
-The dns.trio.resolver.Resolver Class
-------------------------------------
-
-The Trio resolver is a subclass of ``dns.resolver.Resolver`` and has the
-same attributes.  The methods are similar, but I/O methods like ``resolve()``
-are asynchronous.
-
-.. autoclass:: dns.trio.resolver.Resolver
-   :members:
diff --git a/doc/trio-resolver-functions.rst b/doc/trio-resolver-functions.rst
deleted file mode 100644
index 2a6ab31..0000000
--- a/doc/trio-resolver-functions.rst
+++ /dev/null
@@ -1,8 +0,0 @@
-.. _trio-resolver-functions:
-
-Trio Resolver Functions
-=======================
-
-.. autofunction:: dns.trio.resolver.resolve
-.. autofunction:: dns.trio.resolver.resolve_address
-.. autofunction:: dns.trio.resolver.zone_for_name
diff --git a/doc/trio-resolver.rst b/doc/trio-resolver.rst
deleted file mode 100644
index ccd7824..0000000
--- a/doc/trio-resolver.rst
+++ /dev/null
@@ -1,12 +0,0 @@
-.. module:: dns.trio.resolver
-.. _trio_resolver:
-
-Stub Resolver
-=============
-
-Dnspython's Trio resolver module implements an asynchronous "stub resolver".
-
-.. toctree::
-
-   trio-resolver-class
-   trio-resolver-functions
diff --git a/doc/trio.rst b/doc/trio.rst
deleted file mode 100644
index 3afad5f..0000000
--- a/doc/trio.rst
+++ /dev/null
@@ -1,20 +0,0 @@
-.. module:: dns.trio
-.. _trio:
-
-Trio Asynchronous I/O Support
-=============================
-
-The ``dns.trio.query`` module offers very similar APIs to those of
-``dns.query``, only these versions are asynchronous and use Trio for
-I/O.  There are no timeout parameters, as timeouts are expected to be
-done in the Trio style with a cancellation scope.
-
-The ``dns.trio.resolver`` module offers very similar APIs to those of
-``dns.query``, only these versions are asynchronous and use Trio for
-I/O.  There are no timeout parameters, as timeouts are expected to be
-done in the Trio style with a cancellation scope.
-
-.. toctree::
-
-   trio-query
-   trio-resolver
diff --git a/doc/whatsnew.rst b/doc/whatsnew.rst
index f2e7adf..801e0f6 100644
--- a/doc/whatsnew.rst
+++ b/doc/whatsnew.rst
@@ -21,10 +21,10 @@ What's New in dnspython 2.0.0
 * DNS-over-HTTPS is supported with ``dns.query.https()``, and the resolver
   will use DNS-over-HTTPS for a nameserver which is an HTTPS URL.
 
-* Basic query and resolver support for the Trio asynchronous I/O library has
-  been added in ``dns.trio.query`` and ``dns.trio.resolver``.  This API should
-  be viewed as experimental as asynchronous I/O support in dnspython is still
-  evolving.
+* Basic query and resolver support for the Trio, Curio, and asyncio
+  asynchronous I/O libraries has been added in ``dns.asyncquery`` and
+  ``dns.asyncresolver``.  This API should be viewed as experimental as
+  asynchronous I/O support in dnspython is still evolving.
 
 * TSIG now defaults to using SHA-256.