Add explicit close method (#166)

Co-authored-by: Copilot <[email protected]>

Author: bdraco

README.rst

@@ -35,7 +35,7 @@ The following query types are supported: A, AAAA, ANY, CAA, CNAME, MX, NAPTR, NS
 API
 ===
 
-The API is pretty simple, three functions are provided in the ``DNSResolver`` class:
+The API is pretty simple, the following 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.
@@ -53,6 +53,27 @@ The API is pretty simple, three functions are provided in the ``DNSResolver`` cl
 * ``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.
+* ``close()``: Close the resolver. This releases all resources and cancels any pending queries. It must be called
+  when the resolver is no longer needed (e.g., application shutdown). The resolver should only be closed from the
+  event loop that created the resolver.
+
+
+Async Context Manager Support
+=============================
+
+While not recommended for typical use cases, ``DNSResolver`` can be used as an async context manager
+for scenarios where automatic cleanup is desired:
+
+.. code:: python
+
+    async with aiodns.DNSResolver() as resolver:
+        result = await resolver.query('example.com', 'A')
+        # resolver.close() is called automatically when exiting the context
+
+**Important**: This pattern is discouraged for most applications because ``DNSResolver`` instances
+are designed to be long-lived and reused for many queries. Creating and destroying resolvers
+frequently adds unnecessary overhead. Use the context manager pattern only when you specifically
+need automatic cleanup for short-lived resolver instances, such as in tests or one-off scripts.
 
 
 Note for Windows users

aiodns/__init__.py

@@ -4,6 +4,7 @@
 import socket
 import sys
 from collections.abc import Iterable, Sequence
+from types import TracebackType
 from typing import (
     TYPE_CHECKING,
     Any,
@@ -66,6 +67,7 @@ def __init__(
         loop: Optional[asyncio.AbstractEventLoop] = None,
         **kwargs: Any,
     ) -> None:  # TODO(PY311): Use Unpack for kwargs.
+        self._closed = True
         self.loop = loop or asyncio.get_event_loop()
         if TYPE_CHECKING:
             assert self.loop is not None
@@ -78,6 +80,7 @@ def __init__(
         self._read_fds: set[int] = set()
         self._write_fds: set[int] = set()
         self._timer: Optional[asyncio.TimerHandle] = None
+        self._closed = False
 
     def _make_channel(self, **kwargs: Any) -> tuple[bool, pycares.Channel]:
         if (
@@ -319,3 +322,55 @@ def _start_timer(self) -> None:
             timeout = 0.1
 
         self._timer = self.loop.call_later(timeout, self._timer_cb)
+
+    def _cleanup(self) -> None:
+        """Cleanup timers and file descriptors when closing resolver."""
+        if self._closed:
+            return
+        # Mark as closed first to prevent double cleanup
+        self._closed = True
+        # Cancel timer if running
+        if self._timer is not None:
+            self._timer.cancel()
+            self._timer = None
+
+        # Remove all file descriptors
+        for fd in list(self._read_fds):
+            self.loop.remove_reader(fd)
+        for fd in list(self._write_fds):
+            self.loop.remove_writer(fd)
+
+        self._read_fds.clear()
+        self._write_fds.clear()
+        self._channel.close()
+
+    async def close(self) -> None:
+        """
+        Cleanly close the DNS resolver.
+
+        This should be called to ensure all resources are properly released.
+        After calling close(), the resolver should not be used again.
+        """
+        self._cleanup()
+
+    async def __aenter__(self) -> 'DNSResolver':
+        """Enter the async context manager."""
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: Optional[type[BaseException]],
+        exc_val: Optional[BaseException],
+        exc_tb: Optional[TracebackType],
+    ) -> None:
+        """Exit the async context manager."""
+        await self.close()
+
+    def __del__(self) -> None:
+        """Handle cleanup when the resolver is garbage collected."""
+        # Check if we have a channel to clean up
+        # This can happen if an exception occurs during __init__ before
+        # _channel is created (e.g., RuntimeError on Windows
+        # without proper loop)
+        if hasattr(self, '_channel'):
+            self._cleanup()

setup.py

@@ -21,7 +21,7 @@ def get_version():
     license='MIT',
     long_description=codecs.open('README.rst', encoding='utf-8').read(),
     long_description_content_type='text/x-rst',
-    install_requires=['pycares>=4.0.0'],
+    install_requires=['pycares>=4.9.0'],
     packages=['aiodns'],
     package_data={'aiodns': ['py.typed']},
     platforms=['POSIX', 'Microsoft Windows'],