From 1ac8189506f71b9e683e9af29431f6811ad18de1 Mon Sep 17 00:00:00 2001 From: Bob Halley Date: Sun, 15 Jan 2017 05:25:32 -0800 Subject: [PATCH] doco overhaul of name helpers --- dns/e164.py | 11 ++++++++++- dns/reversename.py | 34 +++++++++++++++++++--------------- doc/name-helpers.rst | 41 +++++++++++++++++++++++++++++++++++++++++ doc/name.rst | 1 + 4 files changed, 71 insertions(+), 16 deletions(-) create mode 100644 doc/name-helpers.rst diff --git a/dns/e164.py b/dns/e164.py index 2618b4f3..0dbd3ff9 100644 --- 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 9ea9395a..e2ec77df 100644 --- 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 index 00000000..3c91a73c --- /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 d44d9717..201e69b5 100644 --- a/doc/name.rst +++ b/doc/name.rst @@ -38,4 +38,5 @@ full details. name-class name-make + name-helpers name-codecs -- 2.47.3