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.
filename, a
str
or file object, specifying a file in standard /etc/resolv.conf format. This parameter is meaningful only when configure is true and the platform is POSIX.configure, a
bool
. If True (the default), the resolver instance is configured in the normal fashion for the operating system the resolver is running on. (I.e. by reading a /etc/resolv.conf file on POSIX systems and from the registry on Windows systems.)- domain
A
dns.name.Name
, the domain of this host.
- nameservers
A
list
ofstr
ordns.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 notresolve()
uses the search list configured in the system’s resolver configuration when thesearch
parameter toresolve()
isNone
. The default isFalse
.
- 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 addressstr
to anint
. 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 adns.exception.Timeout
exception will be raised.
- cache
An object implementing the caching protocol, e.g. a
dns.resolver.Cache
or adns.resolver.LRUCache
. The default isNone
, in which case there is no local caching.
- retry_servfail
A
bool
. Should we retry a nameserver if it saysSERVFAIL
? The default isFalse
.
- 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
orNone
, the name of the TSIG key to use; defaults toNone
. The key must be defined in the keyring.
- keyalgorithm
A
dns.name.Name
orstr
, the TSIG algorithm to use.
- edns
An
int
, the EDNS level to use. SpecifyingNone
,False
, or-1
means “do not use EDNS”, and in this case the other parameters are ignored. SpecifyingTrue
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
orNone
, the message flags to use. IfNone
, then the default flags as set by thedns.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.
name, a
dns.name.Name
orstr
, the query name.This method can raise any exception that
resolve()
can raise, other thandns.resolver.NoAnswer
anddns.resolver.NXDOMAIN
.Returns a
dns.name.Name
.
- 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 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 can be converted into objects of the appropriate type.
qname, a
dns.name.Name
orstr
, the query name.rdtype, an
int
orstr
, the query type.rdclass, an
int
orstr
, the query class.tcp, a
bool
. IfTrue
, use TCP to make the query.source, a
str
orNone
. If notNone
, bind to this IP address when making queries.raise_on_no_answer, a
bool
. IfTrue
, raisedns.resolver.NoAnswer
if there’s no answer to the question.source_port, an
int
, the port from which to send the message.lifetime, a
float
, how many seconds a query should run before timing out.search, a
bool
orNone
, determines whether the search list configured in the system’s resolver configuration are used for relative names, and whether the resolver’s domain may be added to relative names. The default isNone
, which causes the value of the resolver’suse_search_by_default
attribute to be used.Raises
dns.resolver.LifetimeTimeout
if no answers could be found in the specified lifetime.Raises
dns.resolver.NXDOMAIN
if the query name does not exist.Raises
dns.resolver.YXDOMAIN
if the query name is too long after DNAME substitution.Raises
dns.resolver.NoAnswer
if raise_on_no_answer isTrue
and the query name exists but has no RRset of the desired type and class.Raises
dns.resolver.NoNameservers
if no non-broken nameservers are available to answer the question.Returns a
dns.resolver.Answer
instance.
- resolve_address(ipaddr: str, *args: Any, **kwargs: Any) Answer [source]
Use a resolver to run a reverse query for PTR records.
This utilizes the resolve() method to perform a PTR lookup on the specified IP address.
ipaddr, a
str
, the IPv4 or IPv6 address you want to get the PTR record for.All other arguments that can be passed to the resolve() function except for rdtype and rdclass are also supported by this function.
- resolve_name(name: Name | str, family: int = AddressFamily.AF_UNSPEC, **kwargs: Any) HostAnswers [source]
Use a resolver to query for address records.
This utilizes the resolve() method to perform A and/or AAAA lookups on the specified name.
qname, a
dns.name.Name
orstr
, the name to resolve.family, an
int
, the address family. If socket.AF_UNSPEC (the default), both A and AAAA records will be retrieved.All other arguments that can be passed to the resolve() function except for rdtype and rdclass are also supported by this function.
- 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.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 tofor a in answer.rrset
.answer[i]
is equivalent toanswer.rrset[i]
, andanswer[i:j]
is equivalent toanswer.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
orNone
, 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.