Channel - Ares Channel

class pycares.Channel([flags, timeout, tries, ndots, tcp_port, udp_port, servers, domains, lookups, sock_state_cb, socket_send_buffer_size, socket_receive_buffer_size, rotate, local_ip, local_dev, resolvconf_path])
Parameters:

  • flags (int) – Flags controlling the behavior of the resolver. See constants for available values.

  • timeout (float) – The number of seconds each name server is given to respond to a query on the first try. The default is five seconds.

  • tries (int) – The number of tries the resolver will try contacting each name server before giving up. The default is four tries.

  • ndots (int) – The number of dots which must be present in a domain name for it to be queried for “as is” prior to querying for it with the default domain extensions appended. The default value is 1 unless set otherwise by resolv.conf or the RES_OPTIONS environment variable.

  • tcp_port (int) – The (TCP) port to use for queries. The default is 53.

  • udp_port (int) – The (UDP) port to use for queries. The default is 53.

  • servers (list) – List of nameservers to be used to do the lookups.

  • domains (list) – The domains to search, instead of the domains specified in resolv.conf or the domain derived from the kernel hostname variable.

  • lookup (str) – The lookups to perform for host queries. lookups should be set to a string of the characters “b” or “f”, where “b” indicates a DNS lookup and “f” indicates a lookup in the hosts file.

  • sock_state_cb (callable) –

    A callback function to be invoked when a socket changes state. Callback signature: sock_state_cb(self, fd, readable, writable)

    This option is mutually exclusive with the event_thread option.

  • event_thread (bool) –

    If set to True, c-ares will use its own thread to process events. This is the recommended way to use c-ares, as it allows for automatic reinitialization of the channel when the system resolver configuration changes. Verify that c-ares was compiled with thread-safety by calling ares_threadsafety() before using this option.

    This option is mutually exclusive with the sock_state_cb option.

  • socket_send_buffer_size (int) – Size for the created socket’s send buffer.

  • socket_receive_buffer_size (int) – Size for the created socket’s receive buffer.

  • rotate (bool) – If set to True, the nameservers are rotated when doing queries.

  • local_ip (str) – Sets the local IP address for DNS operations.

  • local_dev (str) – Sets the local network adapter to use for DNS operations. Linux only.

  • resolvconf_path (str) – Path to resolv.conf, defaults to /etc/resolv.conf. Unix only.

The c-ares Channel provides asynchronous DNS operations.

getaddrinfo(host, port, callback, family=0, type=0, proto=0, flags=0)
Parameters:

  • host (string) – Hostname to resolve.

  • port (string) – Service to resolve. Can be a string, int or None.

  • callback (callable) – Callback to be called with the result of the query.

The family, type and proto arguments can be optionally specified in order to narrow the list of addresses returned. Passing zero as a value for each of these arguments selects the full range of results. The flags argument can be one or several of the AI_* constants, and will influence how results are computed and returned. For example, AI_NUMERICHOST will disable domain name resolution.

Translate the host/port argument into a sequence of 5-tuples that contain all the necessary arguments for creating a socket connected to that service.

Callback signature: callback(result, errorno)

gethostbyname(name, family, callback)
Parameters:

  • name (string) – Name to query.

  • family (int) – Socket family.

  • callback (callable) – Callback to be called with the result of the query.

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

Callback signature: callback(result, errorno)

gethostbyaddr(name, callback)
Parameters:

  • name (string) – Name to query.

  • callback (callable) – Callback to be called with the result of the query.

Retrieves the host information corresponding to a network address.

Callback signature: callback(result, errorno)

getnameinfo(address, flags, callback)
Parameters:

  • address (tuple) – address tuple to get info about.

  • flags (int) – Query flags, see the NI flags section.

  • callback (callable) – Callback to be called with the result of the query.

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

address must be a 2-item tuple for IPv4 or a 4-item tuple for IPv6. Format of fields is the same as one returned by getaddrinfo().

Callback signature: callback(result, errorno)

query(name, query_type, callback)
Parameters:

  • name (string) – Name to query.

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

  • callback (callable) – Callback to be called with the result of the query.

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

  • QUERY_TYPE_A

  • QUERY_TYPE_AAAA

  • QUERY_TYPE_ANY

  • QUERY_TYPE_CAA

  • QUERY_TYPE_CNAME

  • QUERY_TYPE_MX

  • QUERY_TYPE_NAPTR

  • QUERY_TYPE_NS

  • QUERY_TYPE_PTR

  • QUERY_TYPE_SOA

  • QUERY_TYPE_SRV

  • QUERY_TYPE_TXT

Callback signature: callback(result, errorno). The result type varies depending on the query type:

  • A: (list of) ares_query_a_result, fields:

    • host

    • ttl

  • AAAA: (list of) ares_query_aaaa_result, fields:

    • host

    • ttl

  • CAA: (list of) ares_query_caa_result, fields:

    • critical

    • property

    • value

    • ttl

  • CNAME: ares_query_cname_result, fields:

    • cname

    • ttl

  • MX: (list of) ares_query_mx_result, fields:

    • host

    • priority

    • ttl

  • NAPTR: (list of) ares_query_naptr_result, fields:

    • order

    • preference

    • flags

    • service

    • regex

    • replacement

    • ttl

  • NS: (list of) ares_query_ns_result, fields:

    • host

    • ttl

  • PTR: (list of) ares_query_ptr_result, fields:

    • name

    • ttl

  • SOA: ares_query_soa_result, fields:

    • nsname

    • hostmaster

    • serial

    • refresh

    • retry

    • expires

    • minttl

    • ttl

  • SRV: (list of) ares_query_srv_result, fields:

    • host

    • port

    • priority

    • weight

    • ttl

  • TXT: (list of) ares_query_txt_result, fields:

    • text

    • ttl

  • ANY: a list of any of the above.

Note

TTL is not implemented for CNAME and NS), so it’s set to -1.

search(name, query_type, callback)
Parameters:

  • name (string) – Name to query.

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

  • callback (callable) – Callback to be called with the result of the query.

Tis function does the same as query() but it will honor the domain and search directives in resolv.conf.

cancel()

Cancel any pending query on this channel. All pending callbacks will be called with ARES_ECANCELLED errorno.

reinit()

Reinitialize the channel.

For more details, see the ares_reinit documentation.

process_fd(read_fd, write_fd)
Parameters:

  • read_fd (int) – File descriptor ready to read from.

  • write_fd (int) – File descriptor ready to write to.

Process the given file descriptors for read and/or write events.

getsock()

Return a tuple containing 2 lists with the file descriptors ready to read and write.

timeout([max_timeout])
Parameters:

max_timeout (float) – Maximum timeout.

Determines 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.

set_local_ip(local_ip)
Parameters:

local_ip (str) – IP address.

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

set_local_dev(local_dev)
Parameters:

local_dev (str) – Network device name.

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

servers

List of nameservers to use for DNS queries.