DNS Query Support

The dns.asyncquery module is for sending messages to DNS servers, and processing their responses. If you want “stub resolver” behavior, then you should use the higher level dns.asyncresolver module; see Stub Resolver.

For UDP and TCP, the module provides a single “do everything” query function, and also provides the send and receive halves of this function individually for situations where more sophisticated I/O handling is being used by the application.

UDP

async dns.asyncquery.udp(q: Message, where: str, timeout: float | None = None, port: int = 53, source: str | None = None, source_port: int = 0, ignore_unexpected: bool = False, one_rr_per_rrset: bool = False, ignore_trailing: bool = False, raise_on_truncation: bool = False, sock: DatagramSocket | None = None, backend: Backend | None = None, ignore_errors: bool = False) → Message

Return the response obtained after sending a query via UDP.

sock, a dns.asyncbackend.DatagramSocket, or None, the socket to use for the query. If None, the default, a socket is created. Note that if a socket is provided, the source, source_port, and backend are ignored.

backend, a dns.asyncbackend.Backend, or None. If None, the default, then dnspython will use the default backend.

See dns.query.udp() for the documentation of the other parameters, exceptions, and return type of this method.

async dns.asyncquery.udp_with_fallback(q: Message, where: str, timeout: float | None = None, port: int = 53, source: str | None = None, source_port: int = 0, ignore_unexpected: bool = False, one_rr_per_rrset: bool = False, ignore_trailing: bool = False, udp_sock: DatagramSocket | None = None, tcp_sock: StreamSocket | None = None, backend: Backend | None = None, ignore_errors: bool = False) → Tuple[Message, bool]

Return the response to the query, trying UDP first and falling back to TCP if UDP results in a truncated response.

udp_sock, a dns.asyncbackend.DatagramSocket, or None, the socket to use for the UDP query. If None, the default, a socket is created. Note that if a socket is provided the source, source_port, and backend are ignored for the UDP query.

tcp_sock, a dns.asyncbackend.StreamSocket, or None, the socket to use for the TCP query. If None, the default, a socket is created. Note that if a socket is provided where, source, source_port, and backend are ignored for the TCP query.

backend, a dns.asyncbackend.Backend, or None. If None, the default, then dnspython will use the default backend.

See dns.query.udp_with_fallback() for the documentation of the other parameters, exceptions, and return type of this method.

async dns.asyncquery.send_udp(sock: DatagramSocket, what: Message | bytes, destination: Any, expiration: float | None = None) → Tuple[int, float]

Send a DNS message to the specified UDP socket.

sock, a dns.asyncbackend.DatagramSocket.

what, a bytes or dns.message.Message, the message to send.

destination, a destination tuple appropriate for the address family of the socket, specifying where to send the query.

expiration, a float or None, the absolute time at which a timeout exception should be raised. If None, no timeout will occur. The expiration value is meaningless for the asyncio backend, as asyncio’s transport sendto() never blocks.

Returns an (int, float) tuple of bytes sent and the sent time.

async dns.asyncquery.receive_udp(sock: DatagramSocket, destination: Any | None = None, expiration: float | None = None, ignore_unexpected: bool = False, one_rr_per_rrset: bool = False, keyring: Dict[Name, Key] | None = None, request_mac: bytes | None = b'', ignore_trailing: bool = False, raise_on_truncation: bool = False, ignore_errors: bool = False, query: Message | None = None) → Any

Read a DNS message from a UDP socket.

sock, a dns.asyncbackend.DatagramSocket.

See dns.query.receive_udp() for the documentation of the other parameters, and exceptions.

Returns a (dns.message.Message, float, tuple) tuple of the received message, the received time, and the address where the message arrived from.

TCP

async dns.asyncquery.tcp(q: Message, where: str, timeout: float | None = None, port: int = 53, source: str | None = None, source_port: int = 0, one_rr_per_rrset: bool = False, ignore_trailing: bool = False, sock: StreamSocket | None = None, backend: Backend | None = None) → Message

Return the response obtained after sending a query via TCP.

sock, a dns.asyncbacket.StreamSocket, or None, the socket to use for the query. If None, the default, a socket is created. Note that if a socket is provided where, port, source, source_port, and backend are ignored.

backend, a dns.asyncbackend.Backend, or None. If None, the default, then dnspython will use the default backend.

See dns.query.tcp() for the documentation of the other parameters, exceptions, and return type of this method.

async dns.asyncquery.send_tcp(sock: StreamSocket, what: Message | bytes, expiration: float | None = None) → Tuple[int, float]

Send a DNS message to the specified TCP socket.

sock, a dns.asyncbackend.StreamSocket.

See dns.query.send_tcp() for the documentation of the other parameters, exceptions, and return type of this method.

async dns.asyncquery.receive_tcp(sock: StreamSocket, expiration: float | None = None, one_rr_per_rrset: bool = False, keyring: Dict[Name, Key] | None = None, request_mac: bytes | None = b'', ignore_trailing: bool = False) → Tuple[Message, float]

Read a DNS message from a TCP socket.

sock, a dns.asyncbackend.StreamSocket.

See dns.query.receive_tcp() for the documentation of the other parameters, exceptions, and return type of this method.

TLS

async dns.asyncquery.tls(q: Message, where: str, timeout: float | None = None, port: int = 853, source: str | None = None, source_port: int = 0, one_rr_per_rrset: bool = False, ignore_trailing: bool = False, sock: StreamSocket | None = None, backend: Backend | None = None, ssl_context: SSLContext | None = None, server_hostname: str | None = None, verify: bool | str = True) → Message

Return the response obtained after sending a query via TLS.

sock, an asyncbackend.StreamSocket, or None, the socket to use for the query. If None, the default, a socket is created. Note that if a socket is provided, it must be a connected SSL stream socket, and where, port, source, source_port, backend, ssl_context, and server_hostname are ignored.

backend, a dns.asyncbackend.Backend, or None. If None, the default, then dnspython will use the default backend.

See dns.query.tls() for the documentation of the other parameters, exceptions, and return type of this method.

HTTPS

async dns.asyncquery.https(q: Message, where: str, timeout: float | None = None, port: int = 443, source: str | None = None, source_port: int = 0, one_rr_per_rrset: bool = False, ignore_trailing: bool = False, client: httpx.AsyncClient | None = None, path: str = '/dns-query', post: bool = True, verify: bool | str = True, bootstrap_address: str | None = None, resolver: dns.asyncresolver.Resolver | None = None, family: int = AddressFamily.AF_UNSPEC, http_version: HTTPVersion = HTTPVersion.DEFAULT) → Message

Return the response obtained after sending a query via DNS-over-HTTPS.

client, a httpx.AsyncClient. If provided, the client to use for the query.

Unlike the other dnspython async functions, a backend cannot be provided in this function because httpx always auto-detects the async backend.

See dns.query.https() for the documentation of the other parameters, exceptions, and return type of this method.

Zone Transfers

async dns.asyncquery.inbound_xfr(where: str, txn_manager: TransactionManager, query: Message | None = None, port: int = 53, timeout: float | None = None, lifetime: float | None = None, source: str | None = None, source_port: int = 0, udp_mode: UDPMode = UDPMode.NEVER, backend: Backend | None = None) → None

Conduct an inbound transfer and apply it via a transaction from the txn_manager.

backend, a dns.asyncbackend.Backend, or None. If None, the default, then dnspython will use the default backend.

See dns.query.inbound_xfr() for the documentation of the other parameters, exceptions, and return type of this method.