[OpenSPARC-T2-SAM] / sam-t2 / devtools / amd64 / html / python / lib / module-encodings.idna.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<link rel="STYLESHEET" href="lib.css" type='text/css' />
<link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" />
<link rel='start' href='../index.html' title='Python Documentation Index' />
<link rel="first" href="lib.html" title='Python Library Reference' />
<link rel='contents' href='contents.html' title="Contents" />
<link rel='index' href='genindex.html' title='Index' />
<link rel='last' href='about.html' title='About this document...' />
<link rel='help' href='about.html' title='About this document...' />
<link rel="prev" href="standard-encodings.html" />
<link rel="parent" href="module-codecs.html" />
<link rel="next" href="module-unicodedata.html" />
<meta name='aesop' content='information' />
<title>4.9.3 encodings.idna -- Internationalized Domain Names in Applications</title>
</head>
<body>
<DIV CLASS="navigation">
<div id='top-navigation-panel' xml:id='top-navigation-panel'>
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="4.9.2 Standard Encodings"
  href="standard-encodings.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></A></td>
<td class='online-navigation'><a rel="parent" title="4.9 codecs  "
  href="module-codecs.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up One Level' width='32' /></A></td>
<td class='online-navigation'><a rel="next" title="4.10 unicodedata  "
  href="module-unicodedata.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></A></td>
<td align="center" width="100%">Python Library Reference</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></A></td>
<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
  border='0' height='32'  alt='Module Index' width='32' /></a></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></A></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="standard-encodings.html">4.9.2 Standard Encodings</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="module-codecs.html">4.9 codecs  </A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="module-unicodedata.html">4.10 unicodedata  </A>
</div>
<hr /></div>
</DIV>
<!--End of Navigation Panel-->

<H2><A NAME="SECTION006930000000000000000">
4.9.3 <tt class="module">encodings.idna</tt> --
            Internationalized Domain Names in Applications</A>
</H2>

<P>
<A NAME="module-encodings.idna"></A>

<P>

<span class="versionnote">New in version 2.3.</span>

<P>
This module implements <a class="rfc" id='rfcref-87091' xml:id='rfcref-87091'
href="http://www.faqs.org/rfcs/rfc3490.html">RFC 3490</a> (Internationalized Domain Names in
Applications) and <a class="rfc" id='rfcref-87093' xml:id='rfcref-87093'
href="http://www.faqs.org/rfcs/rfc3492.html">RFC 3492</a> (Nameprep: A Stringprep Profile for
Internationalized Domain Names (IDN)). It builds upon the
<code>punycode</code> encoding and <tt class="module"><a href="module-stringprep.html">stringprep</a></tt>.

<P>
These RFCs together define a protocol to support non-ASCII characters
in domain names. A domain name containing non-ASCII characters (such
as ``www.Alliancefran&#231;aise.nu'') is converted into an
ASCII-compatible encoding (ACE, such as
``www.xn-alliancefranaise-npb.nu''). The ACE form of the domain name
is then used in all places where arbitrary characters are not allowed
by the protocol, such as DNS queries, HTTP <span class="mailheader">Host:</span> fields, and so
on. This conversion is carried out in the application; if possible
invisible to the user: The application should transparently convert
Unicode domain labels to IDNA on the wire, and convert back ACE labels
to Unicode before presenting them to the user.

<P>
Python supports this conversion in several ways: The <code>idna</code> codec
allows to convert between Unicode and the ACE. Furthermore, the
<tt class="module"><a href="module-socket.html">socket</a></tt> 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 parameters, such as
<tt class="module"><a href="module-httplib.html">httplib</a></tt> and <tt class="module"><a href="module-ftplib.html">ftplib</a></tt>, accept Unicode host names
(<tt class="module"><a href="module-httplib.html">httplib</a></tt> then also transparently sends an IDNA hostname in
the <span class="mailheader">Host:</span> field if it sends that field at all). 

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

<P>
The module <tt class="module">encodings.idna</tt> also implements the nameprep
procedure, which performs certain normalizations on host names, to
achieve case-insensitivity of international domain names, and to unify
similar characters. The nameprep functions can be used directly if
desired.

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-1019' xml:id='l2h-1019' class="function">nameprep</tt></b>(</nobr></td>
  <td><var>label</var>)</td></tr></table></dt>
<dd>
Return the nameprepped version of <var>label</var>. The implementation
currently assumes query strings, so <code>AllowUnassigned</code> is
true.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-1020' xml:id='l2h-1020' class="function">ToASCII</tt></b>(</nobr></td>
  <td><var>label</var>)</td></tr></table></dt>
<dd>
Convert a label to ASCII, as specified in <a class="rfc" id='rfcref-87095' xml:id='rfcref-87095'
href="http://www.faqs.org/rfcs/rfc3490.html">RFC 3490</a>.
<code>UseSTD3ASCIIRules</code> is assumed to be false.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-1021' xml:id='l2h-1021' class="function">ToUnicode</tt></b>(</nobr></td>
  <td><var>label</var>)</td></tr></table></dt>
<dd>
Convert a label to Unicode, as specified in <a class="rfc" id='rfcref-87097' xml:id='rfcref-87097'
href="http://www.faqs.org/rfcs/rfc3490.html">RFC 3490</a>.
</dl>

<DIV CLASS="navigation">
<div class='online-navigation'>
<p></p><hr />
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="4.9.2 Standard Encodings"
  href="standard-encodings.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></A></td>
<td class='online-navigation'><a rel="parent" title="4.9 codecs  "
  href="module-codecs.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up One Level' width='32' /></A></td>
<td class='online-navigation'><a rel="next" title="4.10 unicodedata  "
  href="module-unicodedata.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></A></td>
<td align="center" width="100%">Python Library Reference</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></A></td>
<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
  border='0' height='32'  alt='Module Index' width='32' /></a></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></A></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="standard-encodings.html">4.9.2 Standard Encodings</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="module-codecs.html">4.9 codecs  </A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="module-unicodedata.html">4.10 unicodedata  </A>
</div>
</div>
<hr />
<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
</DIV>
<!--End of Navigation Panel-->
<ADDRESS>
See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
</ADDRESS>
</BODY>
</HTML>
Commit	Line	Data
920dae64 AT	1	<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
	2	<html>
	3	<head>
	4	<link rel="STYLESHEET" href="lib.css" type='text/css' />
	5	<link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" />
	6	<link rel='start' href='../index.html' title='Python Documentation Index' />
	7	<link rel="first" href="lib.html" title='Python Library Reference' />
	8	<link rel='contents' href='contents.html' title="Contents" />
	9	<link rel='index' href='genindex.html' title='Index' />
	10	<link rel='last' href='about.html' title='About this document...' />
	11	<link rel='help' href='about.html' title='About this document...' />
	12	<link rel="prev" href="standard-encodings.html" />
	13	<link rel="parent" href="module-codecs.html" />
	14	<link rel="next" href="module-unicodedata.html" />
	15	<meta name='aesop' content='information' />
	16	<title>4.9.3 encodings.idna -- Internationalized Domain Names in Applications</title>
	17	</head>
	18	<body>
	19	<DIV CLASS="navigation">
	20	<div id='top-navigation-panel' xml:id='top-navigation-panel'>
	21	<table align="center" width="100%" cellpadding="0" cellspacing="2">
	22	<tr>
	23	<td class='online-navigation'><a rel="prev" title="4.9.2 Standard Encodings"
	24	href="standard-encodings.html"><img src='../icons/previous.png'
	25	border='0' height='32' alt='Previous Page' width='32' /></A></td>
	26	<td class='online-navigation'><a rel="parent" title="4.9 codecs "
	27	href="module-codecs.html"><img src='../icons/up.png'
	28	border='0' height='32' alt='Up One Level' width='32' /></A></td>
	29	<td class='online-navigation'><a rel="next" title="4.10 unicodedata "
	30	href="module-unicodedata.html"><img src='../icons/next.png'
	31	border='0' height='32' alt='Next Page' width='32' /></A></td>
	32	<td align="center" width="100%">Python Library Reference</td>
	33	<td class='online-navigation'><a rel="contents" title="Table of Contents"
	34	href="contents.html"><img src='../icons/contents.png'
	35	border='0' height='32' alt='Contents' width='32' /></A></td>
	36	<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
	37	border='0' height='32' alt='Module Index' width='32' /></a></td>
	38	<td class='online-navigation'><a rel="index" title="Index"
	39	href="genindex.html"><img src='../icons/index.png'
	40	border='0' height='32' alt='Index' width='32' /></A></td>
	41	</tr></table>
	42	<div class='online-navigation'>
	43	<b class="navlabel">Previous:</b>
	44	<a class="sectref" rel="prev" href="standard-encodings.html">4.9.2 Standard Encodings</A>
	45	<b class="navlabel">Up:</b>
	46	<a class="sectref" rel="parent" href="module-codecs.html">4.9 codecs </A>
	47	<b class="navlabel">Next:</b>
	48	<a class="sectref" rel="next" href="module-unicodedata.html">4.10 unicodedata </A>
	49	</div>
	50	<hr /></div>
	51	</DIV>
	52	<!--End of Navigation Panel-->
	53
	54	<H2><A NAME="SECTION006930000000000000000">
	55	4.9.3 <tt class="module">encodings.idna</tt> --
	56	Internationalized Domain Names in Applications</A>
	57	</H2>
	58
	59	<P>
	60	<A NAME="module-encodings.idna"></A>
	61
	62	<P>
	63
	64	<span class="versionnote">New in version 2.3.</span>
65
66	<P>
67	This module implements <a class="rfc" id='rfcref-87091' xml:id='rfcref-87091'
68	href="http://www.faqs.org/rfcs/rfc3490.html">RFC 3490</a> (Internationalized Domain Names in
69	Applications) and <a class="rfc" id='rfcref-87093' xml:id='rfcref-87093'
70	href="http://www.faqs.org/rfcs/rfc3492.html">RFC 3492</a> (Nameprep: A Stringprep Profile for
71	Internationalized Domain Names (IDN)). It builds upon the
72	<code>punycode</code> encoding and <tt class="module"><a href="module-stringprep.html">stringprep</a></tt>.
73
74	<P>
75	These RFCs together define a protocol to support non-ASCII characters
76	in domain names. A domain name containing non-ASCII characters (such
77	as ``www.Alliancefrançaise.nu'') is converted into an
78	ASCII-compatible encoding (ACE, such as
79	``www.xn-alliancefranaise-npb.nu''). The ACE form of the domain name
80	is then used in all places where arbitrary characters are not allowed
81	by the protocol, such as DNS queries, HTTP <span class="mailheader">Host:</span> fields, and so
82	on. This conversion is carried out in the application; if possible
83	invisible to the user: The application should transparently convert
84	Unicode domain labels to IDNA on the wire, and convert back ACE labels
85	to Unicode before presenting them to the user.
86
87	<P>
88	Python supports this conversion in several ways: The <code>idna</code> codec
89	allows to convert between Unicode and the ACE. Furthermore, the
90	<tt class="module"><a href="module-socket.html">socket</a></tt> module transparently converts Unicode host names to
91	ACE, so that applications need not be concerned about converting host
92	names themselves when they pass them to the socket module. On top of
93	that, modules that have host names as function parameters, such as
94	<tt class="module"><a href="module-httplib.html">httplib</a></tt> and <tt class="module"><a href="module-ftplib.html">ftplib</a></tt>, accept Unicode host names
95	(<tt class="module"><a href="module-httplib.html">httplib</a></tt> then also transparently sends an IDNA hostname in
96	the <span class="mailheader">Host:</span> field if it sends that field at all).
97
98	<P>
99	When receiving host names from the wire (such as in reverse name
100	lookup), no automatic conversion to Unicode is performed: Applications
101	wishing to present such host names to the user should decode them to
102	Unicode.
103
104	<P>
105	The module <tt class="module">encodings.idna</tt> also implements the nameprep
106	procedure, which performs certain normalizations on host names, to
107	achieve case-insensitivity of international domain names, and to unify
108	similar characters. The nameprep functions can be used directly if
109	desired.
110
111	<P>
112	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
113	<td><nobr><b><tt id='l2h-1019' xml:id='l2h-1019' class="function">nameprep</tt></b>(</nobr></td>
114	<td><var>label</var>)</td></tr></table></dt>
115	<dd>
116	Return the nameprepped version of <var>label</var>. The implementation
117	currently assumes query strings, so <code>AllowUnassigned</code> is
118	true.
119	</dl>
120
121	<P>
122	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
123	<td><nobr><b><tt id='l2h-1020' xml:id='l2h-1020' class="function">ToASCII</tt></b>(</nobr></td>
124	<td><var>label</var>)</td></tr></table></dt>
125	<dd>
126	Convert a label to ASCII, as specified in <a class="rfc" id='rfcref-87095' xml:id='rfcref-87095'
127	href="http://www.faqs.org/rfcs/rfc3490.html">RFC 3490</a>.
128	<code>UseSTD3ASCIIRules</code> is assumed to be false.
129	</dl>
130
131	<P>
132	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
133	<td><nobr><b><tt id='l2h-1021' xml:id='l2h-1021' class="function">ToUnicode</tt></b>(</nobr></td>
134	<td><var>label</var>)</td></tr></table></dt>
135	<dd>
136	Convert a label to Unicode, as specified in <a class="rfc" id='rfcref-87097' xml:id='rfcref-87097'
137	href="http://www.faqs.org/rfcs/rfc3490.html">RFC 3490</a>.
138	</dl>
139
140	<DIV CLASS="navigation">
141	<div class='online-navigation'>
142	<p></p><hr />
143	<table align="center" width="100%" cellpadding="0" cellspacing="2">
144	<tr>
145	<td class='online-navigation'><a rel="prev" title="4.9.2 Standard Encodings"
146	href="standard-encodings.html"><img src='../icons/previous.png'
147	border='0' height='32' alt='Previous Page' width='32' /></A></td>
148	<td class='online-navigation'><a rel="parent" title="4.9 codecs "
149	href="module-codecs.html"><img src='../icons/up.png'
150	border='0' height='32' alt='Up One Level' width='32' /></A></td>
151	<td class='online-navigation'><a rel="next" title="4.10 unicodedata "
152	href="module-unicodedata.html"><img src='../icons/next.png'
153	border='0' height='32' alt='Next Page' width='32' /></A></td>
154	<td align="center" width="100%">Python Library Reference</td>
155	<td class='online-navigation'><a rel="contents" title="Table of Contents"
156	href="contents.html"><img src='../icons/contents.png'
157	border='0' height='32' alt='Contents' width='32' /></A></td>
158	<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
159	border='0' height='32' alt='Module Index' width='32' /></a></td>
160	<td class='online-navigation'><a rel="index" title="Index"
161	href="genindex.html"><img src='../icons/index.png'
162	border='0' height='32' alt='Index' width='32' /></A></td>
163	</tr></table>
164	<div class='online-navigation'>
165	<b class="navlabel">Previous:</b>
166	<a class="sectref" rel="prev" href="standard-encodings.html">4.9.2 Standard Encodings</A>
167	<b class="navlabel">Up:</b>
168	<a class="sectref" rel="parent" href="module-codecs.html">4.9 codecs </A>
169	<b class="navlabel">Next:</b>
170	<a class="sectref" rel="next" href="module-unicodedata.html">4.10 unicodedata </A>
171	</div>
172	</div>
173	<hr />
174	<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
175	</DIV>
176	<!--End of Navigation Panel-->
177	<ADDRESS>
178	See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
179	</ADDRESS>
180	</BODY>
181	</HTML>