.. image:: https://badge.fury.io/py/aiodns.png :target: https://pypi.org/project/aiodns/
.. image:: https://github.com/saghul/aiodns/workflows/CI/badge.svg :target: https://github.com/saghul/aiodns/actions
aiodns provides a simple way for doing asynchronous DNS resolutions using pycares <https://github.com/saghul/pycares>
_.
.. code:: python
import asyncio
import aiodns
loop = asyncio.get_event_loop()
resolver = aiodns.DNSResolver(loop=loop)
async def query(name, query_type):
return await resolver.query(name, query_type)
coro = query('google.com', 'A')
result = loop.run_until_complete(coro)
The following query types are supported: A, AAAA, ANY, CAA, CNAME, MX, NAPTR, NS, PTR, SOA, SRV, TXT.
The API is pretty simple, three functions are provided in the DNSResolver
class:
query(host, type)
: Do a DNS resolution of the given type for the given hostname. It returns an
instance of asyncio.Future
. The actual result of the DNS query is taken directly from pycares.
As of version 1.0.0 of aiodns (and pycares, for that matter) results are always namedtuple-like
objects with different attributes. Please check the documentation <http://pycares.readthedocs.org/en/latest/channel.html#pycares.Channel.query>
_
for the result fields.gethostbyname(host, socket_family)
: Do a DNS resolution for the given
hostname and the desired type of address family (i.e. socket.AF_INET
).
While query()
always performs a request to a DNS server,
gethostbyname()
first looks into /etc/hosts
and thus can resolve
local hostnames (such as localhost
). Please check the documentation <http://pycares.readthedocs.io/en/latest/channel.html#pycares.Channel.gethostbyname>
_
for the result fields. The actual result of the call is a asyncio.Future
.gethostbyaddr(name)
: Make a reverse lookup for an address.cancel()
: Cancel all pending DNS queries. All futures will get DNSError
exception set, with
ARES_ECANCELLED
errno.This library requires the asyncio loop to be a SelectorEventLoop
, which is not the default on Windows since
Python 3.8.
The default can be changed as follows (do this very early in your application):
.. code:: python
asyncio.set_event_loop_policy(asyncio.WindowsSelectorEventLoopPolicy())
This may have other implications for the rest of your codebase, so make sure to test thoroughly.
To run the test suite: python tests.py
Saúl Ibarra Corretgé s@saghul.net
aiodns uses the MIT license, check LICENSE file.
Python >= 3.6 are supported.
If you'd like to contribute, fork the project, make a patch and send a pull request. Have a look at the surrounding code and please, make yours look alike :-)