===============================
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 <https://github.com/saghul/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
<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.
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é <s@saghul.net>
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 :-)
Raw data
{
"_id": null,
"home_page": "https://github.com/saghul/aiodns",
"name": "aiodns",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": null,
"author": "Sa\u00fal Ibarra Corretg\u00e9",
"author_email": "s@saghul.net",
"download_url": "https://files.pythonhosted.org/packages/e7/84/41a6a2765abc124563f5380e76b9b24118977729e25a84112f8dfb2b33dc/aiodns-3.2.0.tar.gz",
"platform": "POSIX",
"description": "===============================\nSimple DNS resolver for asyncio\n===============================\n\n.. image:: https://badge.fury.io/py/aiodns.png\n :target: https://pypi.org/project/aiodns/\n\n.. image:: https://github.com/saghul/aiodns/workflows/CI/badge.svg\n :target: https://github.com/saghul/aiodns/actions\n\naiodns provides a simple way for doing asynchronous DNS resolutions using `pycares <https://github.com/saghul/pycares>`_.\n\n\nExample\n=======\n\n.. code:: python\n\n import asyncio\n import aiodns\n\n loop = asyncio.get_event_loop()\n resolver = aiodns.DNSResolver(loop=loop)\n\n async def query(name, query_type):\n return await resolver.query(name, query_type)\n\n coro = query('google.com', 'A')\n result = loop.run_until_complete(coro)\n\n\nThe following query types are supported: A, AAAA, ANY, CAA, CNAME, MX, NAPTR, NS, PTR, SOA, SRV, TXT.\n\n\nAPI\n===\n\nThe API is pretty simple, three functions are provided in the ``DNSResolver`` class:\n\n* ``query(host, type)``: Do a DNS resolution of the given type for the given hostname. It returns an\n instance of ``asyncio.Future``. The actual result of the DNS query is taken directly from pycares.\n As of version 1.0.0 of aiodns (and pycares, for that matter) results are always namedtuple-like\n objects with different attributes. Please check the `documentation \n <http://pycares.readthedocs.org/en/latest/channel.html#pycares.Channel.query>`_\n for the result fields.\n* ``gethostbyname(host, socket_family)``: Do a DNS resolution for the given\n hostname and the desired type of address family (i.e. ``socket.AF_INET``).\n While ``query()`` always performs a request to a DNS server,\n ``gethostbyname()`` first looks into ``/etc/hosts`` and thus can resolve\n local hostnames (such as ``localhost``). Please check `the documentation\n <http://pycares.readthedocs.io/en/latest/channel.html#pycares.Channel.gethostbyname>`_\n for the result fields. The actual result of the call is a ``asyncio.Future``.\n* ``gethostbyaddr(name)``: Make a reverse lookup for an address.\n* ``cancel()``: Cancel all pending DNS queries. All futures will get ``DNSError`` exception set, with\n ``ARES_ECANCELLED`` errno.\n\n\nNote for Windows users\n======================\n\nThis library requires the asyncio loop to be a `SelectorEventLoop`, which is not the default on Windows since\nPython 3.8.\n\nThe default can be changed as follows (do this very early in your application):\n\n.. code:: python\n\n asyncio.set_event_loop_policy(asyncio.WindowsSelectorEventLoopPolicy())\n\nThis may have other implications for the rest of your codebase, so make sure to test thoroughly.\n\n\nRunning the test suite\n======================\n\nTo run the test suite: ``python tests.py``\n\n\nAuthor\n======\n\nSa\u00fal Ibarra Corretg\u00e9 <s@saghul.net>\n\n\nLicense\n=======\n\naiodns uses the MIT license, check LICENSE file.\n\n\nPython versions\n===============\n\nPython >= 3.6 are supported.\n\n\nContributing\n============\n\nIf you'd like to contribute, fork the project, make a patch and send a pull\nrequest. Have a look at the surrounding code and please, make yours look\nalike :-)\n\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Simple DNS resolver for asyncio",
"version": "3.2.0",
"project_urls": {
"Homepage": "https://github.com/saghul/aiodns"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "151413c65b1bd59f7e707e0cc0964fbab45c003f90292ed267d159eeeeaa2224",
"md5": "18cd4292d83d7060ee152fda1a4a332c",
"sha256": "e443c0c27b07da3174a109fd9e736d69058d808f144d3c9d56dbd1776964c5f5"
},
"downloads": -1,
"filename": "aiodns-3.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "18cd4292d83d7060ee152fda1a4a332c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 5735,
"upload_time": "2024-03-31T11:27:28",
"upload_time_iso_8601": "2024-03-31T11:27:28.615129Z",
"url": "https://files.pythonhosted.org/packages/15/14/13c65b1bd59f7e707e0cc0964fbab45c003f90292ed267d159eeeeaa2224/aiodns-3.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e78441a6a2765abc124563f5380e76b9b24118977729e25a84112f8dfb2b33dc",
"md5": "0bfcd1b040912744badd2771a33a32fc",
"sha256": "62869b23409349c21b072883ec8998316b234c9a9e36675756e8e317e8768f72"
},
"downloads": -1,
"filename": "aiodns-3.2.0.tar.gz",
"has_sig": false,
"md5_digest": "0bfcd1b040912744badd2771a33a32fc",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 7823,
"upload_time": "2024-03-31T11:27:30",
"upload_time_iso_8601": "2024-03-31T11:27:30.639519Z",
"url": "https://files.pythonhosted.org/packages/e7/84/41a6a2765abc124563f5380e76b9b24118977729e25a84112f8dfb2b33dc/aiodns-3.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-31 11:27:30",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "saghul",
"github_project": "aiodns",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "aiodns"
}
JSON
