Debian Codegraph @

aiodns.egg-info/PKG-INFO

raw
1 Metadata-Version: 2.4
2 Name: aiodns
3 Version: 4.0.0
4 Summary: Simple DNS resolver for asyncio
5 Home-page: https://github.com/saghul/aiodns
6 Author: Saúl Ibarra Corretgé
7 Author-email: [email protected]
8 License: MIT
9 Platform: POSIX
10 Platform: Microsoft Windows
11 Classifier: Development Status :: 5 - Production/Stable
12 Classifier: Intended Audience :: Developers
13 Classifier: License :: OSI Approved :: MIT License
14 Classifier: Operating System :: POSIX
15 Classifier: Operating System :: Microsoft :: Windows
16 Classifier: Programming Language :: Python
17 Classifier: Programming Language :: Python :: 3
18 Classifier: Programming Language :: Python :: 3.10
19 Classifier: Programming Language :: Python :: 3.11
20 Classifier: Programming Language :: Python :: 3.12
21 Classifier: Programming Language :: Python :: 3.13
22 Classifier: Programming Language :: Python :: 3.14
23 Requires-Python: >=3.10
24 Description-Content-Type: text/x-rst
25 License-File: LICENSE
26 Requires-Dist: pycares<6,>=5.0.0
27 Dynamic: author
28 Dynamic: author-email
29 Dynamic: classifier
30 Dynamic: description
31 Dynamic: description-content-type
32 Dynamic: home-page
33 Dynamic: license
34 Dynamic: license-file
35 Dynamic: platform
36 Dynamic: requires-dist
37 Dynamic: requires-python
38 Dynamic: summary
39
40 ===============================
41 Simple DNS resolver for asyncio
42 ===============================
43
44 .. image:: https://badge.fury.io/py/aiodns.png
45 :target: https://pypi.org/project/aiodns/
46
47 .. image:: https://github.com/saghul/aiodns/workflows/CI/badge.svg
48 :target: https://github.com/saghul/aiodns/actions
49
50 aiodns provides a simple way for doing asynchronous DNS resolutions using `pycares <https://github.com/saghul/pycares>`_.
51
52
53 Example
54 =======
55
56 .. code:: python
57
58 import asyncio
59 import aiodns
60
61 async def main():
62 resolver = aiodns.DNSResolver()
63 result = await resolver.query_dns('google.com', 'A')
64 for record in result.answer:
65 print(record.data.addr)
66
67 asyncio.run(main())
68
69
70 The following query types are supported: A, AAAA, ANY, CAA, CNAME, MX, NAPTR, NS, PTR, SOA, SRV, TXT.
71
72
73 API
74 ===
75
76 The API is pretty simple, the following functions are provided in the ``DNSResolver`` class:
77
78 * ``query_dns(host, type)``: Do a DNS resolution of the given type for the given hostname. It returns an
79 instance of ``asyncio.Future``. The result is a ``pycares.DNSResult`` object with ``answer``,
80 ``authority``, and ``additional`` attributes containing lists of ``pycares.DNSRecord`` objects.
81 Each record has ``type``, ``ttl``, and ``data`` attributes. Check the `pycares documentation
82 <https://pycares.readthedocs.io/>`_ for details on the data attributes for each record type.
83 * ``query(host, type)``: **Deprecated** - use ``query_dns()`` instead. This method returns results
84 in a legacy format compatible with aiodns 3.x for backward compatibility.
85 * ``gethostbyname(host, socket_family)``: **Deprecated** - use ``getaddrinfo()`` instead.
86 Do a DNS resolution for the given hostname and the desired type of address family
87 (i.e. ``socket.AF_INET``). The actual result of the call is a ``asyncio.Future``.
88 * ``gethostbyaddr(name)``: Make a reverse lookup for an address.
89 * ``getaddrinfo(host, family, port, proto, type, flags)``: Resolve a host and port into a list of
90 address info entries.
91 * ``getnameinfo(sockaddr, flags)``: Resolve a socket address to a host and port.
92 * ``cancel()``: Cancel all pending DNS queries. All futures will get ``DNSError`` exception set, with
93 ``ARES_ECANCELLED`` errno.
94 * ``close()``: Close the resolver. This releases all resources and cancels any pending queries. It must be called
95 when the resolver is no longer needed (e.g., application shutdown). The resolver should only be closed from the
96 event loop that created the resolver.
97
98
99 Migrating from aiodns 3.x
100 =========================
101
102 aiodns 4.x introduces a new ``query_dns()`` method that returns native pycares 5.x result types.
103 See the `pycares documentation <https://pycares.readthedocs.io/latest/channel.html#pycares.Channel.query>`_
104 for details on the result types. The old ``query()`` method is deprecated but continues to work
105 for backward compatibility.
106
107 .. code:: python
108
109 # Old API (deprecated)
110 result = await resolver.query('example.com', 'MX')
111 for record in result:
112 print(record.host, record.priority)
113
114 # New API (recommended)
115 result = await resolver.query_dns('example.com', 'MX')
116 for record in result.answer:
117 print(record.data.exchange, record.data.priority)
118
119
120 Future migration to aiodns 5.x
121 ------------------------------
122
123 The temporary ``query_dns()`` naming allows gradual migration without breaking changes:
124
125 +-----------+---------------------------------------+--------------------------------------------+
126 | Version | ``query()`` | ``query_dns()`` |
127 +===========+=======================================+============================================+
128 | **4.x** | Deprecated, returns compat types | New API, returns pycares 5.x types |
129 +-----------+---------------------------------------+--------------------------------------------+
130 | **5.x** | New API, returns pycares 5.x types | Alias to ``query()`` for back compat |
131 +-----------+---------------------------------------+--------------------------------------------+
132
133 In aiodns 5.x, ``query()`` will become the primary API returning native pycares 5.x types,
134 and ``query_dns()`` will remain as an alias for backward compatibility. This allows downstream
135 projects to migrate at their own pace.
136
137
138 Async Context Manager Support
139 =============================
140
141 While not recommended for typical use cases, ``DNSResolver`` can be used as an async context manager
142 for scenarios where automatic cleanup is desired:
143
144 .. code:: python
145
146 async with aiodns.DNSResolver() as resolver:
147 result = await resolver.query_dns('example.com', 'A')
148 # resolver.close() is called automatically when exiting the context
149
150 **Important**: This pattern is discouraged for most applications because ``DNSResolver`` instances
151 are designed to be long-lived and reused for many queries. Creating and destroying resolvers
152 frequently adds unnecessary overhead. Use the context manager pattern only when you specifically
153 need automatic cleanup for short-lived resolver instances, such as in tests or one-off scripts.
154
155
156 Note for Windows users
157 ======================
158
159 This library requires the use of an ``asyncio.SelectorEventLoop`` or ``winloop`` on Windows
160 **only** when using a custom build of ``pycares`` that links against a system-
161 provided ``c-ares`` library **without** thread-safety support. This is because
162 non-thread-safe builds of ``c-ares`` are incompatible with the default
163 ``ProactorEventLoop`` on Windows.
164
165 If you're using the official prebuilt ``pycares`` wheels on PyPI (version 4.7.0 or
166 later), which include a thread-safe version of ``c-ares``, this limitation does
167 **not** apply and can be safely ignored.
168
169 The default event loop can be changed as follows (do this very early in your application):
170
171 .. code:: python
172
173 asyncio.set_event_loop_policy(asyncio.WindowsSelectorEventLoopPolicy())
174
175 This may have other implications for the rest of your codebase, so make sure to test thoroughly.
176
177
178 Running the test suite
179 ======================
180
181 To run the test suite: ``python -m pytest tests/``
182
183
184 Author
185 ======
186
187 Saúl Ibarra Corretgé <[email protected]>
188
189
190 License
191 =======
192
193 aiodns uses the MIT license, check LICENSE file.
194
195
196 Contributing
197 ============
198
199 If you'd like to contribute, fork the project, make a patch and send a pull
200 request. Have a look at the surrounding code and please, make yours look
201 alike :-)