evdns.py: accept packed ips and return packed ips; return ttl along with the result

 - add docstrings for functions
 - move the examples from module's __doc__ into the functions' docstrings

gevent/evdns.py

-"""DNS functions based on libevent-dns.
+"""Libevent DNS API made synchronous.
 
-This module contains synchronous wrappers around some of the libevent DNS API.
-
-    >>> resolve_ipv4('www.python.org')
-    ['82.94.164.162']
-    >>> resolve_reverse('82.94.164.162').endswith('python.org')
-    True
-
-The errors are reported through a subclass of :class:`socket.gaierror`.
-
-    >>> resolve_ipv4('aaaaaaaaaaa')
-    Traceback (most recent call last):
-     ...
-    DNSError: [Errno 3] name does not exist
+The functions in this module match those in libevent as closely as possible
+yet they return the result instead of passing it to a callback. The calling
+greenlet remains blocked until the result is ready.
 """
 
 from gevent import core
@@ -37,6 +27,11 @@ class DNSError(gaierror):
     """A subclass of :class:`socket.gaierror` used by :mod:`evdns` functions to report errors.
 
     It uses evdns-specific error codes that are different from the standard socket errors.
+
+        >>> resolve_ipv4('aaaaaaaaaaa')
+        Traceback (most recent call last):
+         ...
+        DNSError: [Errno 3] name does not exist
     """
 
     def __init__(self, *args):
@@ -48,37 +43,59 @@ class DNSError(gaierror):
 
 
 def resolve_ipv4(name, flags=0):
+    """Lookup an A record for a given *name*.
+    To disable searching for this query, set *flags* to ``QUERY_NO_SEARCH``.
+
+    Returns (ttl, list of packed IPs).
+
+        >>> resolve_ipv4('www.python.org')
+        (10000, ['R^\\xa4\\xa2'])
+    """
     waiter = Waiter()
     core.dns_resolve_ipv4(name, flags, waiter.switch_args)
-    result, _type, _ttl, addrs = waiter.get()
+    result, _type, ttl, addrs = waiter.get()
     if result != core.DNS_ERR_NONE:
         raise DNSError(result)
-    return addrs
-    # QQQ would be nice to have ttl as an attribute
+    return ttl, addrs
 
 
 def resolve_ipv6(name, flags=0):
+    """Lookup an AAAA record for a given *name*.
+    To disable searching for this query, set *flags* to ``QUERY_NO_SEARCH``.
+
+    Returns (ttl, list of packed IPs).
+    """
     waiter = Waiter()
     core.dns_resolve_ipv6(name, flags, waiter.switch_args)
-    result, _type, _ttl, addrs = waiter.get()
+    result, _type, ttl, addrs = waiter.get()
     if result != core.DNS_ERR_NONE:
         raise DNSError(result)
-    return addrs
+    return ttl, addrs
 
 
-def resolve_reverse(ip, flags=0):
+def resolve_reverse(packed_ip, flags=0):
+    """Lookup a PTR record for a given IP address.
+    To disable searching for this query, set *flags* to ``QUERY_NO_SEARCH``.
+
+        >>> packed_ip = socket.inet_aton('82.94.164.162')
+        >>> resolve_reverse(packed_ip)
+        (10000, 'www.python.org')
+    """
     waiter = Waiter()
-    core.dns_resolve_reverse(ip, flags, waiter.switch_args)
-    result, _type, _ttl, addr = waiter.get()
+    core.dns_resolve_reverse(packed_ip, flags, waiter.switch_args)
+    result, _type, ttl, addr = waiter.get()
     if result != core.DNS_ERR_NONE:
         raise DNSError(result)
-    return addr
+    return ttl, addr
 
 
-def resolve_reverse_ipv6(ip, flags=0):
+def resolve_reverse_ipv6(packed_ip, flags=0):
+    """Lookup a PTR record for a given IPv6 address.
+    To disable searching for this query, set *flags* to ``QUERY_NO_SEARCH``.
+    """
     waiter = Waiter()
-    core.dns_resolve_reverse_ipv6(ip, flags, waiter.switch_args)
-    result, _type, _ttl, addrs = waiter.get()
+    core.dns_resolve_reverse_ipv6(packed_ip, flags, waiter.switch_args)
+    result, _type, ttl, addrs = waiter.get()
     if result != core.DNS_ERR_NONE:
         raise DNSError(result)
-    return addrs
+    return ttl, addrs