tdns API

The Channel implements a Python class for interacting with the c-ares API using native Tornado asynchronous conventions. For example, to query the MX records for google you could use the following snippet:

from tornado import gen, ioloop, web
import tdns


class RequestHandler(web.RequestHandler):

    @gen.coroutine
    def get(self, *args, **kwargs):
        channel = tdns.Channel(io_loop=ioloop.IOLoop.current())
        response = yield channel.query('google.com', 'MX')

tnds is build on top of the excellent pycares library.

Ares Channel

class tdns.Channel(io_loop=None, **kwargs)

An asynchronous wrapper class for c-ares channels.

cancel()

Cancel any pending query on this channel. All pending requests will raise a AresError with the ARES_ECANCELLED errorno.

Raises:AresError

destroy()

Destroy the channel. All pending requests will raise a AresError with the ARES_EDESTRUCTION errorno.

Raises:AresError

gethostbyaddr(addr)

Retrieves the host information corresponding to a network address.

Parameters:addr (str) – Network address to query Return type:str Raises:AresError

gethostbyname(name, family)

Retrieves host information corresponding to a host name from a host database.

Parameters:

• name (str) – Name to query
• family (int) – Socket family

Raises:

AresError

getnameinfo(name, port, flags)

Provides protocol-independent name resolution from an address to a host name and from a port number to the service name.

Parameters:

• name (str) – Name to query
• port (int) – Port of the service to query
• flags (int) – Query flags, see the NI flags section

Raises:

AresError

query(name, query_type)

Do a DNS query of the specified type. Available types:

• tdns.QUERY_TYPE_A
• tdns.QUERY_TYPE_AAAA
• tdns.QUERY_TYPE_CNAME
• tdns.QUERY_TYPE_MX
• tdns.QUERY_TYPE_NAPTR
• tdns.QUERY_TYPE_NS
• tdns.QUERY_TYPE_PTR
• tdns.QUERY_TYPE_SOA
• tdns.QUERY_TYPE_SRV
• tdns.QUERY_TYPE_TXT

Parameters:

• name (str) – Name to query
• query_type (int) – Type of query to perform.

Return Types:

• A and AAAA: ares_query_simple_result, fields:
  • host
  • ttl
• CNAME: ares_query_cname_result, fields:
  • cname
  • ttl
• MX: ares_query_mx_result, fields:
  • host
  • priority
  • ttl
• NAPTR: ares_query_naptr_result, fields:
  • order
  • preference
  • flags
  • service
  • regex
  • replacement
  • ttl
• NS: ares_query_ns_result, fields:

• host
• ttl

• PTR: ares_query_ptr_result, fields:
  • name
  • ttl
• SOA: ares_query_soa_result, fields:
  • nsmane
  • hostmaster
  • serial
  • refresh
  • retry
  • expires
  • minttl
  • ttl
• SRV: ares_query_srv_result, fields:
  • host
  • port
  • priority
  • weight
  • ttl
• TXT: ares_query_txt_result, fields:
  • text
  • ttl

Raises:AresError

servers

List of nameservers to use for DNS queries

Return type:list

set_local_dev(local_dev)

Set the local ethernet device from which the queries will be sent.

Parameters:local_dev (str) – Network device name Raises:AresError Raises:ValueError

set_local_ip(local_ip)

Set the local IPv4 or IPv6 address from which the queries will be sent.

Parameters:local_ip (str) – IP address Raises:AresError Raises:ValueError

timeout(max_timeout)

Set the maximum time for which the caller should wait before invoking process_fd to process timeouts. If the max_timeout parameter is specified, it is stored on the channel and the appropriate value is then returned.

Parameters:max_timeout (float) – Maximum timeout Return type:float Raises:AresError Raises:ValueError

Utility Functions

tdns.reverse_address(ip_address)

Returns the reversed representation of an IP address, usually used when doing PTR queries.

Parameters:ip_address (str) – IP address to be reversed Return type:str