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.

Parameters:

• sock (dns.asyncbackend.DatagramSocket or None) – The socket to use. If None (the default), a socket is created. Note that if a socket is provided, source, source_port, and backend are ignored.

• backend (dns.asyncbackend.Backend or None) – The async backend. If None (the default), 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.

Parameters:

• udp_sock (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, source, source_port, and backend are ignored for the UDP query.

• tcp_sock (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 (dns.asyncbackend.Backend or None) – The async backend. If None (the default), 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.

Parameters:

• sock (dns.asyncbackend.DatagramSocket) – The socket to use.

• what (bytes or dns.message.Message) – The message to send.

• destination – A destination tuple appropriate for the address family of the socket.

• expiration (float or None) – The absolute time at which to raise a timeout exception. None means no timeout (and is meaningless for the asyncio backend, as sendto() never blocks there).

Returns:

A (bytes_sent, sent_time) tuple.

Return type:

tuple[int, float]

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.

Parameters:

sock (dns.asyncbackend.DatagramSocket) – The socket to read from.

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

Returns:

A (message, received_time, from_address) tuple.

Return type:

tuple

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.

Parameters:

• sock (dns.asyncbackend.StreamSocket or None) – The socket to use. 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 (dns.asyncbackend.Backend or None) – The async backend. If None (the default), 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.

Parameters:

sock (dns.asyncbackend.StreamSocket) – The socket to use.

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, ignore_errors: bool = False) → tuple[Message, float]

Read a DNS message from a TCP socket.

Parameters:

sock (dns.asyncbackend.StreamSocket) – The socket to use.

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.

Parameters:

• sock (dns.asyncbackend.StreamSocket or None) – The socket to use. 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 (dns.asyncbackend.Backend or None) – The async backend. If None (the default), 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: httpx2.AsyncClient | dns.quic.AsyncQuicConnection | None = None, path: str = '/dns-query', post: bool = True, verify: bool | str | SSLContext = 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.

Parameters:

client (httpx2.AsyncClient or None) – If provided, the client to use for the query. Unlike the other dnspython async functions, a backend cannot be provided here because httpx2 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.

Parameters:

backend (dns.asyncbackend.Backend or None) – The async backend. If None (the default), 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.