diff options
-rw-r--r-- | dns/asyncbackend.py | 74 | ||||
-rw-r--r-- | doc/async-backend.rst | 18 | ||||
-rw-r--r-- | doc/async-query.rst | 28 | ||||
-rw-r--r-- | doc/async-resolver-class.rst | 11 | ||||
-rw-r--r-- | doc/async-resolver-functions.rst | 8 | ||||
-rw-r--r-- | doc/async-resolver.rst | 12 | ||||
-rw-r--r-- | doc/async.rst | 21 | ||||
-rw-r--r-- | doc/manual.rst | 2 | ||||
-rw-r--r-- | doc/trio-query.rst | 28 | ||||
-rw-r--r-- | doc/trio-resolver-class.rst | 11 | ||||
-rw-r--r-- | doc/trio-resolver-functions.rst | 8 | ||||
-rw-r--r-- | doc/trio-resolver.rst | 12 | ||||
-rw-r--r-- | doc/trio.rst | 20 | ||||
-rw-r--r-- | doc/whatsnew.rst | 8 |
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. |