https://github.com/aio-libs/aiodns

Simple DNS resolver for asyncio
https://github.com/aio-libs/aiodns

asyncio dns python

Last synced: 2 months ago
JSON representation

Simple DNS resolver for asyncio

• Host: GitHub
• URL: https://github.com/aio-libs/aiodns
• Owner: aio-libs
• License: mit
• Created: 2014-03-26T23:19:57.000Z (over 10 years ago)
• Default Branch: master
• Last Pushed: 2024-09-05T08:01:43.000Z (2 months ago)
• Last Synced: 2024-09-06T14:40:37.201Z (2 months ago)
• Topics: asyncio, dns, python
• Language: Python
• Homepage: https://pypi.python.org/pypi/aiodns
• Size: 81.1 KB
• Stars: 529
• Watchers: 19
• Forks: 69
• Open Issues: 8
• Metadata Files:
  • Readme: README.rst
  • Changelog: ChangeLog
  • License: LICENSE

Awesome Lists containing this project

README

        
===============================

Simple DNS resolver for asyncio

===============================

.. 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 `_.

Example

=======

.. 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.

API

===

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 

  `_

  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

  `_

  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.

Note for Windows users

======================

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.

Running the test suite

======================

To run the test suite: ``python tests.py``

Author

======

Saúl Ibarra Corretgé 

License

=======

aiodns uses the MIT license, check LICENSE file.

Python versions

===============

Python >= 3.6 are supported.

Contributing

============

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 :-)