[Python-checkins] cpython (merge 3.1 -> 3.2): Merge: Fix wording and clarify that the IDNA codec operates on full domain

[r.david.murray]

http://hg.python.org/cpython/rev/f5672fbc7727
changeset:   69329:f5672fbc7727
branch:      3.2
parent:      69324:0eaa8b38e18b
parent:      69328:bc707ca54e00
user:        R David Murray <rdmurray at bitdance.com>
date:        Wed Apr 13 14:12:59 2011 -0400
summary:
  Merge: Fix wording and clarify that the IDNA codec operates on full domain names.

Before reading the code to check, I wasn't sure if it operated on
full domain names or just individual labels.

files:
  Doc/library/codecs.rst |  10 ++++++++--
  1 files changed, 8 insertions(+), 2 deletions(-)


diff --git a/Doc/library/codecs.rst b/Doc/library/codecs.rst
--- a/Doc/library/codecs.rst
+++ b/Doc/library/codecs.rst
@@ -1227,8 +1227,12 @@
 IDNA on the wire, and convert back ACE labels to Unicode before presenting them
 to the user.
 
-Python supports this conversion in several ways: The ``idna`` codec allows to
-convert between Unicode and the ACE. Furthermore, the :mod:`socket` module
+Python supports this conversion in several ways:  the ``idna`` codec performs
+conversion between Unicode and ACE, separating an input string into labels
+based on the separator characters defined in `section 3.1`_ (1) of :rfc:`3490`
+and converting each label to ACE as required, and conversely separating an input
+byte string into labels based on the ``.`` separator and converting any ACE
+labels found into unicode.  Furthermore, the :mod:`socket` module
 transparently converts Unicode host names to ACE, so that applications need not
 be concerned about converting host names themselves when they pass them to the
 socket module. On top of that, modules that have host names as function
@@ -1236,6 +1240,8 @@
 names (:mod:`http.client` then also transparently sends an IDNA hostname in the
 :mailheader:`Host` field if it sends that field at all).
 
+.. _section 3.1: http://tools.ietf.org/html/rfc3490#section-3.1
+
 When receiving host names from the wire (such as in reverse name lookup), no
 automatic conversion to Unicode is performed: Applications wishing to present
 such host names to the user should decode them to Unicode.

-- 
Repository URL: http://hg.python.org/cpython