doco overhaul of name helpers

diff --git a/dns/e164.py b/dns/e164.py
index 2618b4f3114549087f7bc57f588ba6250250d766..0dbd3ff95c8c08e531c18faddd935d76b1b1744c 100644 (file)
--- a/dns/e164.py
+++ b/dns/e164.py
@@ -28,6 +28,9 @@ def from_e164(text, origin=public_enum_domain):
     """Convert an E.164 number in textual form into a Name object whose
     value is the ENUM domain name for that number.
 
+    Non-digits in the text are ignored, i.e. "16505551212",
+    "+1.650.555.1212" and "1 (650) 555-1212" are all the same.
+
     *text*, a ``text``, is an E.164 number in textual form.
 
     *origin*, a ``dns.name.Name``, the domain in which the number
@@ -44,9 +47,14 @@ def from_e164(text, origin=public_enum_domain):
 def to_e164(name, origin=public_enum_domain, want_plus_prefix=True):
     """Convert an ENUM domain name into an E.164 number.
 
+    Note that dnspython does not have any information about preferred
+    number formats within national numbering plans, so all numbers are
+    emitted as a simple string of digits, prefixed by a '+' (unless
+    *want_plus_prefix* is ``False``).
+
     *name* is a ``dns.name.Name``, the ENUM domain name.
 
-    *origin* is a ``dns.anme.Name``, a domain containing the ENUM
+    *origin* is a ``dns.name.Name``, a domain containing the ENUM
     domain name.  The name is relativized to this domain before being
     converted to text.  If ``None``, no relativization is done.
 
@@ -54,6 +62,7 @@ def to_e164(name, origin=public_enum_domain, want_plus_prefix=True):
     the returned number.
 
     Returns a ``text``.
+
     """
     if origin is not None:
         name = name.relativize(origin)

diff --git a/dns/reversename.py b/dns/reversename.py
index 9ea9395a87cf9866fee1d987e499e7936c654d35..e2ec77df0a444c352b2171b58490054eddd5c8f4 100644 (file)
--- a/dns/reversename.py
+++ b/dns/reversename.py
@@ -1,4 +1,4 @@
-# Copyright (C) 2006, 2007, 2009-2011 Nominum, Inc.
+# Copyright (C) 2006-2017 Nominum, Inc.
 #
 # Permission to use, copy, modify, and distribute this software and its
 # documentation for any purpose with or without fee is hereby granted,
@@ -13,13 +13,7 @@
 # ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT
 # OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 
-"""DNS Reverse Map Names.
-
-@var ipv4_reverse_domain: The DNS IPv4 reverse-map domain, in-addr.arpa.
-@type ipv4_reverse_domain: dns.name.Name object
-@var ipv6_reverse_domain: The DNS IPv6 reverse-map domain, ip6.arpa.
-@type ipv6_reverse_domain: dns.name.Name object
-"""
+"""DNS Reverse Map Names."""
 
 import binascii
 import sys
@@ -35,11 +29,15 @@ ipv6_reverse_domain = dns.name.from_text('ip6.arpa.')
 def from_address(text):
     """Convert an IPv4 or IPv6 address in textual form into a Name object whose
     value is the reverse-map domain name of the address.
-    @param text: an IPv4 or IPv6 address in textual form (e.g. '127.0.0.1',
-    '::1')
-    @type text: str
-    @rtype: dns.name.Name object
+
+    *text*, a ``text``, is an IPv4 or IPv6 address in textual form
+    (e.g. '127.0.0.1', '::1')
+
+    Raises ``dns.exception.SyntaxError`` if the address is badly formed.
+
+    Returns a ``dns.name.Name``.
     """
+
     try:
         v6 = dns.ipv6.inet_aton(text)
         if dns.ipv6.is_mapped(v6):
@@ -61,10 +59,16 @@ def from_address(text):
 
 def to_address(name):
     """Convert a reverse map domain name into textual address form.
-    @param name: an IPv4 or IPv6 address in reverse-map form.
-    @type name: dns.name.Name object
-    @rtype: str
+
+    *name*, a ``dns.name.Name``, an IPv4 or IPv6 address in reverse-map name
+    form.
+
+    Raises ``dns.exception.SyntaxError`` if the name does not have a
+    reverse-map form.
+
+    Returns a ``text``.
     """
+
     if name.is_subdomain(ipv4_reverse_domain):
         name = name.relativize(ipv4_reverse_domain)
         labels = list(name.labels)

diff --git a/doc/name-helpers.rst b/doc/name-helpers.rst
new file mode 100644 (file)
index 0000000..3c91a73
--- /dev/null
+++ b/doc/name-helpers.rst
@@ -0,0 +1,41 @@
+.. _name-helpers:
+
+Name Helpers
+------------
+
+Sometimes you want to look up an address in the DNS instead of a name.
+Dnspython provides a helper functions for converting between addresses
+and their "reverse map" form in the DNS.
+
+For example:
+
+========= =========================================================================
+Address   DNS Reverse Name
+========= =========================================================================
+127.0.0.1 1.0.0.127.in-addr.arpa.
+::1       1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.ip6.arpa.
+========= =========================================================================
+
+|
+
+.. autofunction:: dns.reversename.from_address
+.. autofunction:: dns.reversename.to_address
+
+Dnspython also provides helpers for converting E.164 numbers (i.e.
+telephone numbers) into the names used for them in the DNS.
+
+For example:
+
+================ ==================================
+Number           DNS E.164 Name
+================ ==================================
++1.650.555.1212  2.1.2.1.5.5.5.0.5.6.1.e164.arpa.
++44 20 7946 0123 3.2.1.0.6.4.9.7.0.2.4.4.e164.arpa.
+================ ==================================
+
+|
+
+.. autofunction:: dns.e164.from_e164
+.. autofunction:: dns.e164.to_e164
+
+                  

diff --git a/doc/name.rst b/doc/name.rst
index d44d9717722642f0878b85439727b81654332159..201e69b54567e64ad310dc7bf228139fdd46b41b 100644 (file)
--- a/doc/name.rst
+++ b/doc/name.rst
@@ -38,4 +38,5 @@ full details.
 
    name-class
    name-make
+   name-helpers
    name-codecs