Pycares: Asynchronous DNS Resolver

Warnings

• breaking The DNS query results API was completely rewritten in v5.0.0. Results are now returned as structured dataclasses (`DNSResult`, `DNSRecord`, and specific `RecordData` types like `ARecordData`, `MXRecordData`, etc.) instead of a list of record-specific objects. Existing code accessing results will break.
  Fix: Update your result parsing logic to expect `DNSResult` objects with `answer`, `authority`, and `additional` sections, and access record data via `record.data.addr`, `record.data.exchange`, etc. Refer to the v5.0.0 migration guide for details.
• breaking In v5.0.0, the `Channel` constructor arguments and the `callback` parameter for query methods are now strictly keyword-only. The `event_thread` parameter has also been removed, as event thread mode is now implicit.
  Fix: Pass all `Channel` constructor arguments (e.g., `timeout`, `flags`, `lookups`) and the `callback` argument to query methods as keyword arguments. Remove any explicit `event_thread` arguments.
• breaking As of v5.0.0, TXT record data is returned as bytes instead of strings. This change affects how TXT record content should be handled.
  Fix: Ensure your application decodes TXT record data (e.g., `record.data.data.decode('utf-8')`) if string representation is required.
• breaking Pycares v5.0.0 switched its build system for the bundled c-ares library to CMake. Building from source now requires CMake version 3.5 or higher to be installed on the system.
  Fix: Install CMake (version 3.5+) on your system before attempting to build `pycares` from source (e.g., `apt-get install cmake` on Debian/Ubuntu, `brew install cmake` on macOS).
• gotcha Improper management of `pycares.Channel` objects, particularly allowing them to be garbage collected while DNS queries are still pending, can lead to a use-after-free vulnerability, causing a fatal Python interpreter crash.
  Fix: Ensure `Channel` objects are explicitly kept alive and properly managed for the entire duration of any pending DNS queries. Implement robust lifecycle management, especially in long-running or highly concurrent applications. Avoid creating `Channel` objects per-request that might be prematurely destroyed.
• gotcha DNS queries made by `pycares` are real network operations. Consequently, tests and examples often require active internet access and can be sensitive to network conditions or DNS server configurations, potentially leading to environment-specific failures.
  Fix: When developing or testing, ensure a stable network connection and a properly configured DNS resolver. Account for network-related errors in your application's error handling for DNS lookups.

Install

• pip install pycares Install Pycares
• pip install pycares[idna] Install with IDNA 2008 support

Imports

• pycares

  import pycares

Quickstart

This quickstart demonstrates how to perform asynchronous DNS queries for A and MX records using `pycares`. It sets up a `Channel` and makes two queries with a shared callback function. A basic `select`-based loop is used to process file descriptors and handle the asynchronous responses. In a production environment, `pycares` is typically integrated with a more robust event loop like `asyncio` (via `aiodns`), `Tornado`, or `Gevent`.

import pycares
import socket

def callback(result, error):
    if error:
        print(f"Error: {error}")
        return
    if result:
        for record in result.answer:
            if record.type == pycares.QUERY_TYPE_A:
                print(f"A record for {record.name}: {record.data.addr}")
            elif record.type == pycares.QUERY_TYPE_AAAA:
                print(f"AAAA record for {record.name}: {record.data.addr}")
            elif record.type == pycares.QUERY_TYPE_MX:
                print(f"MX record for {record.name}: priority={record.data.priority}, exchange={record.data.exchange}")
            # Add other record types as needed
    else:
        print("No records found.")


# Using a simple select-based event loop
channel = pycares.Channel(timeout=5.0)

# Query for A records
channel.query("google.com", pycares.QUERY_TYPE_A, callback=callback)

# Query for MX records
channel.query("example.com", pycares.QUERY_TYPE_MX, callback=callback)

# Basic event loop processing
while True:
    read_fds, write_fds = channel.getsockname()
    if not read_fds and not write_fds:
        break
    
    # In a real application, use an actual event loop (e.g., asyncio, Tornado, Gevent)
    # For this simple example, we block briefly
    try:
        rlist, wlist, xlist = socket.select(read_fds, write_fds, [], 1.0)
    except socket.error as e:
        print(f"Socket error in select: {e}")
        break

    channel.process_fd(rlist, wlist)