Go to the latest version of this document.

# ``twisted`.`names`.`client``

module documentation
(source)

Asynchronous client DNS

The functions exposed in this module can be used for asynchronous name resolution and dns queries.

If you need to create a resolver with specific requirements, such as needing to do queries against a particular host, the `createResolver` function will return an `IResolver`.

Future plans: Proper nameserver acquisition on Windows/MacOS, better caching, respect timeouts

Class | `AXFRController` | Undocumented
Class | `DNSClientFactory` | No class docstring; 0/2 instance variable, 1/4 method documented
Class | `Resolver` | No summary
Class | `ThreadedResolver` | Undocumented
Function | `createResolver` | Create and return a Resolver.
Function | `getHostByName` | Resolve a name to a valid ipv4 or ipv6 address.
Function | `getResolver` | Get a Resolver instance.
Function | `lookupAddress` | Perform an A record lookup.
Function | `lookupAddress6` | Perform an A6 record lookup.
Function | `lookupAFSDatabase` | Perform an AFSDB record lookup.
Function | `lookupAllRecords` | Perform an ALL_RECORD lookup.
Function | `lookupAuthority` | Perform an SOA record lookup.
Function | `lookupCanonicalName` | Perform a CNAME record lookup.
Function | `lookupHostInfo` | Perform a HINFO record lookup.
Function | `lookupIPV6Address` | Perform an AAAA record lookup.
Function | `lookupMailBox` | Perform an MB record lookup.
Function | `lookupMailboxInfo` | Perform an MINFO record lookup.
Function | `lookupMailExchange` | Perform an MX record lookup.
Function | `lookupMailGroup` | Perform an MG record lookup.
Function | `lookupMailRename` | Perform an MR record lookup.
Function | `lookupNameservers` | Perform an NS record lookup.
Function | `lookupNamingAuthorityPointer` | Perform a NAPTR record lookup.
Function | `lookupNull` | Perform a NULL record lookup.
Function | `lookupPointer` | Perform a PTR record lookup.
Function | `lookupResponsibility` | Perform an RP record lookup.
Function | `lookupSenderPolicy` | Perform a SPF record lookup.
Function | `lookupService` | Perform an SRV record lookup.
Function | `lookupText` | Perform a TXT record lookup.
Function | `lookupWellKnownServices` | Perform a WKS record lookup.
Function | `lookupZone` | Perform an AXFR record lookup.
Function | `query` | Dispatch `query` to the method which can handle its type.
Variable | `theResolver` | Undocumented

def createResolver(servers=None, resolvconf=None, hosts=None): (source)

Create and return a Resolver.

Parameters
servers:`list` of `(str, int)` or `None` | If not `None`, interpreted as a list of domain name servers to attempt to use. Each server is a tuple of address in `str` dotted-quad form and `int` port number.
resolvconf:`str` or `None` | If not `None`, on posix systems will be interpreted as an alternate resolv.conf to use. Will do nothing on windows systems. If `None`, /etc/resolv.conf will be used.
hosts:`str` or `None` | If not `None`, an alternate hosts file to use. If `None` on posix systems, /etc/hosts will be used. On windows, C:\windows\hosts will be used.

Returns
`IResolver` | Undocumented

def getHostByName(name, timeout=None, effort=10): (source)

Resolve a name to a valid ipv4 or ipv6 address.

Will errback with `DNSQueryTimeoutError` on a timeout, `DomainError` or `AuthoritativeDomainError` (or subclasses) on other errors.

Parameters
name:`str` | DNS name to resolve.
timeout:Sequence of `int` | Number of seconds after which to reissue the query. When the last timeout expires, the query is considered failed.
effort:`int` | How many times CNAME and NS records to follow while resolving this name.

Returns
`Deferred` | Undocumented

def getResolver(): (source)

Get a Resolver instance.

Create twisted.names.client.theResolver if it is `None`, and then return that value.

Returns
`IResolver` | Undocumented

def lookupAddress(name, timeout=None): (source)

Perform an A record lookup.

Parameters
name | DNS name to resolve.
timeout | Number of seconds after which to reissue the query. When the last timeout expires, the query is considered failed.

Returns
A `Deferred` which fires with a three-tuple of lists of `twisted.names.dns.RRHeader` instances. The first element of the tuple gives answers. The second element of the tuple gives authorities. The third element of the tuple gives additional information. The `Deferred` may instead fail with one of the exceptions defined in `twisted.names.error` or with `NotImplementedError`.

def lookupAddress6(name, timeout=None): (source)

Perform an A6 record lookup.

Parameters
name | DNS name to resolve.
timeout | Number of seconds after which to reissue the query. When the last timeout expires, the query is considered failed.

Returns
A `Deferred` which fires with a three-tuple of lists of `twisted.names.dns.RRHeader` instances. The first element of the tuple gives answers. The second element of the tuple gives authorities. The third element of the tuple gives additional information. The `Deferred` may instead fail with one of the exceptions defined in `twisted.names.error` or with `NotImplementedError`.

def lookupAFSDatabase(name, timeout=None): (source)

Perform an AFSDB record lookup.

Parameters
name | DNS name to resolve.
timeout | Number of seconds after which to reissue the query. When the last timeout expires, the query is considered failed.

Returns
A `Deferred` which fires with a three-tuple of lists of `twisted.names.dns.RRHeader` instances. The first element of the tuple gives answers. The second element of the tuple gives authorities. The third element of the tuple gives additional information. The `Deferred` may instead fail with one of the exceptions defined in `twisted.names.error` or with `NotImplementedError`.

def lookupAllRecords(name, timeout=None): (source)

Perform an ALL_RECORD lookup.

Parameters
name | DNS name to resolve.
timeout | Number of seconds after which to reissue the query. When the last timeout expires, the query is considered failed.

Returns
A `Deferred` which fires with a three-tuple of lists of `twisted.names.dns.RRHeader` instances. The first element of the tuple gives answers. The second element of the tuple gives authorities. The third element of the tuple gives additional information. The `Deferred` may instead fail with one of the exceptions defined in `twisted.names.error` or with `NotImplementedError`.

def lookupAuthority(name, timeout=None): (source)

Perform an SOA record lookup.

Parameters
name | DNS name to resolve.
timeout | Number of seconds after which to reissue the query. When the last timeout expires, the query is considered failed.

Returns
A `Deferred` which fires with a three-tuple of lists of `twisted.names.dns.RRHeader` instances. The first element of the tuple gives answers. The second element of the tuple gives authorities. The third element of the tuple gives additional information. The `Deferred` may instead fail with one of the exceptions defined in `twisted.names.error` or with `NotImplementedError`.

def lookupCanonicalName(name, timeout=None): (source)

Perform a CNAME record lookup.

Parameters
name | DNS name to resolve.
timeout | Number of seconds after which to reissue the query. When the last timeout expires, the query is considered failed.

Returns
A `Deferred` which fires with a three-tuple of lists of `twisted.names.dns.RRHeader` instances. The first element of the tuple gives answers. The second element of the tuple gives authorities. The third element of the tuple gives additional information. The `Deferred` may instead fail with one of the exceptions defined in `twisted.names.error` or with `NotImplementedError`.

def lookupHostInfo(name, timeout=None): (source)

Perform a HINFO record lookup.

Parameters
name | DNS name to resolve.
timeout | Number of seconds after which to reissue the query. When the last timeout expires, the query is considered failed.

Returns
A `Deferred` which fires with a three-tuple of lists of `twisted.names.dns.RRHeader` instances. The first element of the tuple gives answers. The second element of the tuple gives authorities. The third element of the tuple gives additional information. The `Deferred` may instead fail with one of the exceptions defined in `twisted.names.error` or with `NotImplementedError`.

def lookupIPV6Address(name, timeout=None): (source)

Perform an AAAA record lookup.

Parameters
name | DNS name to resolve.
timeout | Number of seconds after which to reissue the query. When the last timeout expires, the query is considered failed.

Returns
A `Deferred` which fires with a three-tuple of lists of `twisted.names.dns.RRHeader` instances. The first element of the tuple gives answers. The second element of the tuple gives authorities. The third element of the tuple gives additional information. The `Deferred` may instead fail with one of the exceptions defined in `twisted.names.error` or with `NotImplementedError`.

def lookupMailBox(name, timeout=None): (source)

Perform an MB record lookup.

Parameters
name | DNS name to resolve.
timeout | Number of seconds after which to reissue the query. When the last timeout expires, the query is considered failed.

Returns
A `Deferred` which fires with a three-tuple of lists of `twisted.names.dns.RRHeader` instances. The first element of the tuple gives answers. The second element of the tuple gives authorities. The third element of the tuple gives additional information. The `Deferred` may instead fail with one of the exceptions defined in `twisted.names.error` or with `NotImplementedError`.

def lookupMailboxInfo(name, timeout=None): (source)

Perform an MINFO record lookup.

Parameters
name | DNS name to resolve.
timeout | Number of seconds after which to reissue the query. When the last timeout expires, the query is considered failed.

Returns
A `Deferred` which fires with a three-tuple of lists of `twisted.names.dns.RRHeader` instances. The first element of the tuple gives answers. The second element of the tuple gives authorities. The third element of the tuple gives additional information. The `Deferred` may instead fail with one of the exceptions defined in `twisted.names.error` or with `NotImplementedError`.

def lookupMailExchange(name, timeout=None): (source)

Perform an MX record lookup.

Parameters
name | DNS name to resolve.
timeout | Number of seconds after which to reissue the query. When the last timeout expires, the query is considered failed.

Returns
A `Deferred` which fires with a three-tuple of lists of `twisted.names.dns.RRHeader` instances. The first element of the tuple gives answers. The second element of the tuple gives authorities. The third element of the tuple gives additional information. The `Deferred` may instead fail with one of the exceptions defined in `twisted.names.error` or with `NotImplementedError`.

def lookupMailGroup(name, timeout=None): (source)

Perform an MG record lookup.

Parameters
name | DNS name to resolve.
timeout | Number of seconds after which to reissue the query. When the last timeout expires, the query is considered failed.

Returns
A `Deferred` which fires with a three-tuple of lists of `twisted.names.dns.RRHeader` instances. The first element of the tuple gives answers. The second element of the tuple gives authorities. The third element of the tuple gives additional information. The `Deferred` may instead fail with one of the exceptions defined in `twisted.names.error` or with `NotImplementedError`.

def lookupMailRename(name, timeout=None): (source)

Perform an MR record lookup.

Parameters
name | DNS name to resolve.
timeout | Number of seconds after which to reissue the query. When the last timeout expires, the query is considered failed.

Returns
A `Deferred` which fires with a three-tuple of lists of `twisted.names.dns.RRHeader` instances. The first element of the tuple gives answers. The second element of the tuple gives authorities. The third element of the tuple gives additional information. The `Deferred` may instead fail with one of the exceptions defined in `twisted.names.error` or with `NotImplementedError`.

def lookupNameservers(name, timeout=None): (source)

Perform an NS record lookup.

Parameters
name | DNS name to resolve.
timeout | Number of seconds after which to reissue the query. When the last timeout expires, the query is considered failed.

Returns
A `Deferred` which fires with a three-tuple of lists of `twisted.names.dns.RRHeader` instances. The first element of the tuple gives answers. The second element of the tuple gives authorities. The third element of the tuple gives additional information. The `Deferred` may instead fail with one of the exceptions defined in `twisted.names.error` or with `NotImplementedError`.

def lookupNamingAuthorityPointer(name, timeout=None): (source)

Perform a NAPTR record lookup.

Parameters
name | DNS name to resolve.
timeout | Number of seconds after which to reissue the query. When the last timeout expires, the query is considered failed.

Returns
A `Deferred` which fires with a three-tuple of lists of `twisted.names.dns.RRHeader` instances. The first element of the tuple gives answers. The second element of the tuple gives authorities. The third element of the tuple gives additional information. The `Deferred` may instead fail with one of the exceptions defined in `twisted.names.error` or with `NotImplementedError`.

def lookupNull(name, timeout=None): (source)

Perform a NULL record lookup.

Parameters
name | DNS name to resolve.
timeout | Number of seconds after which to reissue the query. When the last timeout expires, the query is considered failed.

Returns
A `Deferred` which fires with a three-tuple of lists of `twisted.names.dns.RRHeader` instances. The first element of the tuple gives answers. The second element of the tuple gives authorities. The third element of the tuple gives additional information. The `Deferred` may instead fail with one of the exceptions defined in `twisted.names.error` or with `NotImplementedError`.

def lookupPointer(name, timeout=None): (source)

Perform a PTR record lookup.

Parameters
name | DNS name to resolve.
timeout | Number of seconds after which to reissue the query. When the last timeout expires, the query is considered failed.

Returns
A `Deferred` which fires with a three-tuple of lists of `twisted.names.dns.RRHeader` instances. The first element of the tuple gives answers. The second element of the tuple gives authorities. The third element of the tuple gives additional information. The `Deferred` may instead fail with one of the exceptions defined in `twisted.names.error` or with `NotImplementedError`.

def lookupResponsibility(name, timeout=None): (source)

Perform an RP record lookup.

Parameters
name | DNS name to resolve.
timeout | Number of seconds after which to reissue the query. When the last timeout expires, the query is considered failed.

Returns
A `Deferred` which fires with a three-tuple of lists of `twisted.names.dns.RRHeader` instances. The first element of the tuple gives answers. The second element of the tuple gives authorities. The third element of the tuple gives additional information. The `Deferred` may instead fail with one of the exceptions defined in `twisted.names.error` or with `NotImplementedError`.

def lookupSenderPolicy(name, timeout=None): (source)

Perform a SPF record lookup.

Parameters
name | DNS name to resolve.
timeout | Number of seconds after which to reissue the query. When the last timeout expires, the query is considered failed.

Returns
A `Deferred` which fires with a three-tuple of lists of `twisted.names.dns.RRHeader` instances. The first element of the tuple gives answers. The second element of the tuple gives authorities. The third element of the tuple gives additional information. The `Deferred` may instead fail with one of the exceptions defined in `twisted.names.error` or with `NotImplementedError`.

def lookupService(name, timeout=None): (source)

Perform an SRV record lookup.

Parameters
name | DNS name to resolve.
timeout | Number of seconds after which to reissue the query. When the last timeout expires, the query is considered failed.

Returns
A `Deferred` which fires with a three-tuple of lists of `twisted.names.dns.RRHeader` instances. The first element of the tuple gives answers. The second element of the tuple gives authorities. The third element of the tuple gives additional information. The `Deferred` may instead fail with one of the exceptions defined in `twisted.names.error` or with `NotImplementedError`.

def lookupText(name, timeout=None): (source)

Perform a TXT record lookup.

Parameters
name | DNS name to resolve.
timeout | Number of seconds after which to reissue the query. When the last timeout expires, the query is considered failed.

Returns
A `Deferred` which fires with a three-tuple of lists of `twisted.names.dns.RRHeader` instances. The first element of the tuple gives answers. The second element of the tuple gives authorities. The third element of the tuple gives additional information. The `Deferred` may instead fail with one of the exceptions defined in `twisted.names.error` or with `NotImplementedError`.

def lookupWellKnownServices(name, timeout=None): (source)

Perform a WKS record lookup.

Parameters
name | DNS name to resolve.
timeout | Number of seconds after which to reissue the query. When the last timeout expires, the query is considered failed.

Returns
A `Deferred` which fires with a three-tuple of lists of `twisted.names.dns.RRHeader` instances. The first element of the tuple gives answers. The second element of the tuple gives authorities. The third element of the tuple gives additional information. The `Deferred` may instead fail with one of the exceptions defined in `twisted.names.error` or with `NotImplementedError`.

def lookupZone(name, timeout=None): (source)

Perform an AXFR record lookup.

NB This is quite different from other DNS requests. See http://cr.yp.to/djbdns/axfr-notes.html for more information.

NB Unlike other `lookup*` methods, the timeout here is not a list of ints, it is a single int.

Parameters
name | DNS name to resolve.
timeout | When this timeout expires, the query is considered failed.

Returns
A `Deferred` which fires with a three-tuple of lists of `twisted.names.dns.RRHeader` instances. The first element of the tuple gives answers. The second and third elements are always empty. The `Deferred` may instead fail with one of the exceptions defined in `twisted.names.error` or with `NotImplementedError`.

def query(query, timeout=None): (source)

Dispatch `query` to the method which can handle its type.

Parameters
query | The DNS query being issued, to which a response is to be generated.
timeout | Number of seconds after which to reissue the query. When the last timeout expires, the query is considered failed.

Returns
A `Deferred` which fires with a three-tuple of lists of `twisted.names.dns.RRHeader` instances. The first element of the tuple gives answers. The second element of the tuple gives authorities. The third element of the tuple gives additional information. The `Deferred` may instead fail with one of the exceptions defined in `twisted.names.error` or with `NotImplementedError`.

theResolver = (source)

Undocumented