The dns.resolver.Resolver and dns.resolver.Answer Classes

class dns.resolver.Resolver(filename: str = '/etc/resolv.conf', configure: bool = True)[source]

DNS stub resolver.

Initialize a resolver.

Parameters:

filename (str or file) – A str or file object specifying a file in standard /etc/resolv.conf format. Meaningful only when configure is True and the platform is POSIX.
configure (bool) – If True (the default), configure the resolver for the operating system (reads /etc/resolv.conf on POSIX, registry on Windows).

domain: A dns.name.Name, the domain of this host.

nameservers

A list of str or dns.nameserver.Nameserver. A string may be an IPv4 or IPv6 address, or an https URL.

This field is actually a property, and returns a tuple as of dnspython 2.4. Assigning this field converts any strings into dns.nameserver.Nameserver instances.

search: A list of dns.name.Name objects. If the query name is a relative name, the resolver will construct absolute query names to try by appending values from the search list.

use_search_by_default: A bool, specifes whether or not resolve() uses the search list configured in the system’s resolver configuration when the search parameter to resolve() is None. The default is False.

port: An int, the default DNS port to send to if not overridden by nameserver_ports. The default value is 53.

nameserver_ports: A dict mapping an IPv4 or IPv6 address str to an int. This specifies the port to use when sending to a nameserver. If a port is not defined for an address, the value of the port attribute will be used.

timeout: A float, the number of seconds to wait for a response from a server.

lifetime: A float, the number of seconds to spend trying to get an answer to the question. If the lifetime expires a dns.exception.Timeout exception will be raised.

cache: An object implementing the caching protocol, e.g. a dns.resolver.Cache or a dns.resolver.LRUCache. The default is None, in which case there is no local caching.

retry_servfail: A bool. Should we retry a nameserver if it says SERVFAIL? The default is False.

keyring: A dict, the TSIG keyring to use. If a keyring is specified but a keyname is not, then the key used will be the first key in the keyring. Note that the order of keys in a dictionary is not defined, so applications should supply a keyname when a keyring is used, unless they know the keyring contains only one key.

keyname: A dns.name.Name or None, the name of the TSIG key to use; defaults to None. The key must be defined in the keyring.

keyalgorithm: A dns.name.Name or str, the TSIG algorithm to use.

edns: An int, the EDNS level to use. Specifying None, False, or -1 means “do not use EDNS”, and in this case the other parameters are ignored. Specifying True is equivalent to specifying 0, i.e. “use EDNS0”.

ednsflags: An int, the EDNS flag values.

payload: An int, is the EDNS sender’s payload field, which is the maximum size of UDP datagram the sender can handle. I.e. how big a response to this message can be.

flags: An int or None, the message flags to use. If None, then the default flags as set by the dns.message.Message constructor will be used.

canonical_name(name: Name | str) → Name[source]

Determine the canonical name of name.

The canonical name is the name the resolver uses for queries after all CNAME and DNAME renamings have been applied.

Parameters:: name (dns.name.Name or str) – The query name.
Return type:: dns.name.Name

This method can raise any exception that resolve() can raise, other than dns.resolver.NoAnswer and dns.resolver.NXDOMAIN.

query(qname: Name | str, rdtype: RdataType | str = RdataType.A, rdclass: RdataClass | str = RdataClass.IN, tcp: bool = False, source: str | None = None, raise_on_no_answer: bool = True, source_port: int = 0, lifetime: float | None = None) → Answer[source]

Query nameservers to find the answer to the question.

This method calls resolve() with search=True, and is provided for backwards compatibility with prior versions of dnspython. See the documentation for the dns.resolver.Resolver.resolve() method for further details.

resolve(qname: Name | str, rdtype: RdataType | str = RdataType.A, rdclass: RdataClass | str = RdataClass.IN, tcp: bool = False, source: str | None = None, raise_on_no_answer: bool = True, source_port: int = 0, lifetime: float | None = None, search: bool | None = None) → Answer[source]

Query nameservers to find the answer to the question.

The qname, rdtype, and rdclass parameters may be objects of the appropriate type, or strings that will be converted automatically.

Parameters:

qname (dns.name.Name or str) – The query name.
rdtype (dns.rdatatype.RdataType or str or int) – The query type.
rdclass (dns.rdataclass.RdataClass or str or int) – The query class.
tcp (bool) – If True, use TCP to make the query.
source (str or None) – If not None, bind to this IP address when making queries.
raise_on_no_answer (bool) – If True, raise dns.resolver.NoAnswer if there is no answer.
source_port (int) – The port from which to send the message.
lifetime (float or None) – How many seconds a query should run before timing out.
search (bool or None) – Whether to use the search list for relative names. None uses the resolver’s use_search_by_default setting.

Raises:

dns.resolver.LifetimeTimeout – If no answers could be found in the specified lifetime.
dns.resolver.NXDOMAIN – If the query name does not exist.
dns.resolver.YXDOMAIN – If the query name is too long after DNAME substitution.
dns.resolver.NoAnswer – If raise_on_no_answer is True and the query name exists but has no RRset of the desired type/class.
dns.resolver.NoNameservers – If no non-broken nameservers are available to answer the question.

Return type:

dns.resolver.Answer

resolve_address(ipaddr: str, *args: Any, **kwargs: Any) → Answer[source]

Use a resolver to run a reverse query for PTR records.

Parameters:: ipaddr (str) – The IPv4 or IPv6 address to look up.

All other keyword arguments accepted by resolve() (except rdtype and rdclass) are also supported.

resolve_name(name: Name | str, family: int = AddressFamily.AF_UNSPEC, **kwargs: Any) → HostAnswers[source]

Use a resolver to query for address records.

Parameters:

name (dns.name.Name or str) – The name to resolve.
family (int) – The address family. socket.AF_UNSPEC (the default) retrieves both A and AAAA records.

All other keyword arguments accepted by resolve() (except rdtype and rdclass) are also supported.

try_ddr(lifetime: float = 5.0) → None[source]

Try to update the resolver’s nameservers using Discovery of Designated Resolvers (DDR). If successful, the resolver will subsequently use DNS-over-HTTPS or DNS-over-TLS for future queries.

lifetime, a float, is the maximum time to spend attempting DDR. The default is 5 seconds.

If the SVCB query is successful and results in a non-empty list of nameservers, then the resolver’s nameservers are set to the returned servers in priority order.

The current implementation does not use any address hints from the SVCB record, nor does it resolve addresses for the SCVB target name, rather it assumes that the bootstrap nameserver will always be one of the addresses and uses it. A future revision to the code may offer fuller support. The code verifies that the bootstrap nameserver is in the Subject Alternative Name field of the TLS certficate.

class dns.resolver.HostAnswers[source]: A dict of DNS stub resolver answers to a host name lookup, indexed by type.

class dns.resolver.Answer(qname: Name, rdtype: RdataType, rdclass: RdataClass, response: QueryMessage, nameserver: str | None = None, port: int | None = None)[source]

DNS stub resolver answer.

Instances of this class bundle up the result of a successful DNS resolution.

For convenience, the answer object implements much of the sequence protocol, forwarding to its rrset attribute. E.g. for a in answer is equivalent to for a in answer.rrset. answer[i] is equivalent to answer.rrset[i], and answer[i:j] is equivalent to answer.rrset[i:j].

Note that CNAMEs or DNAMEs in the response may mean that answer RRset’s name might not be the query name.

qname: A dns.name.Name, the query name.

rdclass: An int, the query class.

rdtype: An int, the query type.

response: A dns.message.QueryMessage, the response message.

rrset: A dns.rrset.RRset or None, the answer RRset.

expiration: A float, the time when the answer expires.

canonical_name: A dns.name.Name, the canonical name of the query name, i.e. the owner name of the answer RRset after any CNAME and DNAME chaining.