|
jpayne@7
|
1 Metadata-Version: 2.1
|
|
jpayne@7
|
2 Name: idna
|
|
jpayne@7
|
3 Version: 3.7
|
|
jpayne@7
|
4 Summary: Internationalized Domain Names in Applications (IDNA)
|
|
jpayne@7
|
5 Author-email: Kim Davies <kim+pypi@gumleaf.org>
|
|
jpayne@7
|
6 Requires-Python: >=3.5
|
|
jpayne@7
|
7 Description-Content-Type: text/x-rst
|
|
jpayne@7
|
8 Classifier: Development Status :: 5 - Production/Stable
|
|
jpayne@7
|
9 Classifier: Intended Audience :: Developers
|
|
jpayne@7
|
10 Classifier: Intended Audience :: System Administrators
|
|
jpayne@7
|
11 Classifier: License :: OSI Approved :: BSD License
|
|
jpayne@7
|
12 Classifier: Operating System :: OS Independent
|
|
jpayne@7
|
13 Classifier: Programming Language :: Python
|
|
jpayne@7
|
14 Classifier: Programming Language :: Python :: 3
|
|
jpayne@7
|
15 Classifier: Programming Language :: Python :: 3 :: Only
|
|
jpayne@7
|
16 Classifier: Programming Language :: Python :: 3.5
|
|
jpayne@7
|
17 Classifier: Programming Language :: Python :: 3.6
|
|
jpayne@7
|
18 Classifier: Programming Language :: Python :: 3.7
|
|
jpayne@7
|
19 Classifier: Programming Language :: Python :: 3.8
|
|
jpayne@7
|
20 Classifier: Programming Language :: Python :: 3.9
|
|
jpayne@7
|
21 Classifier: Programming Language :: Python :: 3.10
|
|
jpayne@7
|
22 Classifier: Programming Language :: Python :: 3.11
|
|
jpayne@7
|
23 Classifier: Programming Language :: Python :: 3.12
|
|
jpayne@7
|
24 Classifier: Programming Language :: Python :: Implementation :: CPython
|
|
jpayne@7
|
25 Classifier: Programming Language :: Python :: Implementation :: PyPy
|
|
jpayne@7
|
26 Classifier: Topic :: Internet :: Name Service (DNS)
|
|
jpayne@7
|
27 Classifier: Topic :: Software Development :: Libraries :: Python Modules
|
|
jpayne@7
|
28 Classifier: Topic :: Utilities
|
|
jpayne@7
|
29 Project-URL: Changelog, https://github.com/kjd/idna/blob/master/HISTORY.rst
|
|
jpayne@7
|
30 Project-URL: Issue tracker, https://github.com/kjd/idna/issues
|
|
jpayne@7
|
31 Project-URL: Source, https://github.com/kjd/idna
|
|
jpayne@7
|
32
|
|
jpayne@7
|
33 Internationalized Domain Names in Applications (IDNA)
|
|
jpayne@7
|
34 =====================================================
|
|
jpayne@7
|
35
|
|
jpayne@7
|
36 Support for the Internationalized Domain Names in
|
|
jpayne@7
|
37 Applications (IDNA) protocol as specified in `RFC 5891
|
|
jpayne@7
|
38 <https://tools.ietf.org/html/rfc5891>`_. This is the latest version of
|
|
jpayne@7
|
39 the protocol and is sometimes referred to as “IDNA 2008”.
|
|
jpayne@7
|
40
|
|
jpayne@7
|
41 This library also provides support for Unicode Technical
|
|
jpayne@7
|
42 Standard 46, `Unicode IDNA Compatibility Processing
|
|
jpayne@7
|
43 <https://unicode.org/reports/tr46/>`_.
|
|
jpayne@7
|
44
|
|
jpayne@7
|
45 This acts as a suitable replacement for the “encodings.idna”
|
|
jpayne@7
|
46 module that comes with the Python standard library, but which
|
|
jpayne@7
|
47 only supports the older superseded IDNA specification (`RFC 3490
|
|
jpayne@7
|
48 <https://tools.ietf.org/html/rfc3490>`_).
|
|
jpayne@7
|
49
|
|
jpayne@7
|
50 Basic functions are simply executed:
|
|
jpayne@7
|
51
|
|
jpayne@7
|
52 .. code-block:: pycon
|
|
jpayne@7
|
53
|
|
jpayne@7
|
54 >>> import idna
|
|
jpayne@7
|
55 >>> idna.encode('ドメイン.テスト')
|
|
jpayne@7
|
56 b'xn--eckwd4c7c.xn--zckzah'
|
|
jpayne@7
|
57 >>> print(idna.decode('xn--eckwd4c7c.xn--zckzah'))
|
|
jpayne@7
|
58 ドメイン.テスト
|
|
jpayne@7
|
59
|
|
jpayne@7
|
60
|
|
jpayne@7
|
61 Installation
|
|
jpayne@7
|
62 ------------
|
|
jpayne@7
|
63
|
|
jpayne@7
|
64 This package is available for installation from PyPI:
|
|
jpayne@7
|
65
|
|
jpayne@7
|
66 .. code-block:: bash
|
|
jpayne@7
|
67
|
|
jpayne@7
|
68 $ python3 -m pip install idna
|
|
jpayne@7
|
69
|
|
jpayne@7
|
70
|
|
jpayne@7
|
71 Usage
|
|
jpayne@7
|
72 -----
|
|
jpayne@7
|
73
|
|
jpayne@7
|
74 For typical usage, the ``encode`` and ``decode`` functions will take a
|
|
jpayne@7
|
75 domain name argument and perform a conversion to A-labels or U-labels
|
|
jpayne@7
|
76 respectively.
|
|
jpayne@7
|
77
|
|
jpayne@7
|
78 .. code-block:: pycon
|
|
jpayne@7
|
79
|
|
jpayne@7
|
80 >>> import idna
|
|
jpayne@7
|
81 >>> idna.encode('ドメイン.テスト')
|
|
jpayne@7
|
82 b'xn--eckwd4c7c.xn--zckzah'
|
|
jpayne@7
|
83 >>> print(idna.decode('xn--eckwd4c7c.xn--zckzah'))
|
|
jpayne@7
|
84 ドメイン.テスト
|
|
jpayne@7
|
85
|
|
jpayne@7
|
86 You may use the codec encoding and decoding methods using the
|
|
jpayne@7
|
87 ``idna.codec`` module:
|
|
jpayne@7
|
88
|
|
jpayne@7
|
89 .. code-block:: pycon
|
|
jpayne@7
|
90
|
|
jpayne@7
|
91 >>> import idna.codec
|
|
jpayne@7
|
92 >>> print('домен.испытание'.encode('idna2008'))
|
|
jpayne@7
|
93 b'xn--d1acufc.xn--80akhbyknj4f'
|
|
jpayne@7
|
94 >>> print(b'xn--d1acufc.xn--80akhbyknj4f'.decode('idna2008'))
|
|
jpayne@7
|
95 домен.испытание
|
|
jpayne@7
|
96
|
|
jpayne@7
|
97 Conversions can be applied at a per-label basis using the ``ulabel`` or
|
|
jpayne@7
|
98 ``alabel`` functions if necessary:
|
|
jpayne@7
|
99
|
|
jpayne@7
|
100 .. code-block:: pycon
|
|
jpayne@7
|
101
|
|
jpayne@7
|
102 >>> idna.alabel('测试')
|
|
jpayne@7
|
103 b'xn--0zwm56d'
|
|
jpayne@7
|
104
|
|
jpayne@7
|
105 Compatibility Mapping (UTS #46)
|
|
jpayne@7
|
106 +++++++++++++++++++++++++++++++
|
|
jpayne@7
|
107
|
|
jpayne@7
|
108 As described in `RFC 5895 <https://tools.ietf.org/html/rfc5895>`_, the
|
|
jpayne@7
|
109 IDNA specification does not normalize input from different potential
|
|
jpayne@7
|
110 ways a user may input a domain name. This functionality, known as
|
|
jpayne@7
|
111 a “mapping”, is considered by the specification to be a local
|
|
jpayne@7
|
112 user-interface issue distinct from IDNA conversion functionality.
|
|
jpayne@7
|
113
|
|
jpayne@7
|
114 This library provides one such mapping that was developed by the
|
|
jpayne@7
|
115 Unicode Consortium. Known as `Unicode IDNA Compatibility Processing
|
|
jpayne@7
|
116 <https://unicode.org/reports/tr46/>`_, it provides for both a regular
|
|
jpayne@7
|
117 mapping for typical applications, as well as a transitional mapping to
|
|
jpayne@7
|
118 help migrate from older IDNA 2003 applications.
|
|
jpayne@7
|
119
|
|
jpayne@7
|
120 For example, “Königsgäßchen” is not a permissible label as *LATIN
|
|
jpayne@7
|
121 CAPITAL LETTER K* is not allowed (nor are capital letters in general).
|
|
jpayne@7
|
122 UTS 46 will convert this into lower case prior to applying the IDNA
|
|
jpayne@7
|
123 conversion.
|
|
jpayne@7
|
124
|
|
jpayne@7
|
125 .. code-block:: pycon
|
|
jpayne@7
|
126
|
|
jpayne@7
|
127 >>> import idna
|
|
jpayne@7
|
128 >>> idna.encode('Königsgäßchen')
|
|
jpayne@7
|
129 ...
|
|
jpayne@7
|
130 idna.core.InvalidCodepoint: Codepoint U+004B at position 1 of 'Königsgäßchen' not allowed
|
|
jpayne@7
|
131 >>> idna.encode('Königsgäßchen', uts46=True)
|
|
jpayne@7
|
132 b'xn--knigsgchen-b4a3dun'
|
|
jpayne@7
|
133 >>> print(idna.decode('xn--knigsgchen-b4a3dun'))
|
|
jpayne@7
|
134 königsgäßchen
|
|
jpayne@7
|
135
|
|
jpayne@7
|
136 Transitional processing provides conversions to help transition from
|
|
jpayne@7
|
137 the older 2003 standard to the current standard. For example, in the
|
|
jpayne@7
|
138 original IDNA specification, the *LATIN SMALL LETTER SHARP S* (ß) was
|
|
jpayne@7
|
139 converted into two *LATIN SMALL LETTER S* (ss), whereas in the current
|
|
jpayne@7
|
140 IDNA specification this conversion is not performed.
|
|
jpayne@7
|
141
|
|
jpayne@7
|
142 .. code-block:: pycon
|
|
jpayne@7
|
143
|
|
jpayne@7
|
144 >>> idna.encode('Königsgäßchen', uts46=True, transitional=True)
|
|
jpayne@7
|
145 'xn--knigsgsschen-lcb0w'
|
|
jpayne@7
|
146
|
|
jpayne@7
|
147 Implementers should use transitional processing with caution, only in
|
|
jpayne@7
|
148 rare cases where conversion from legacy labels to current labels must be
|
|
jpayne@7
|
149 performed (i.e. IDNA implementations that pre-date 2008). For typical
|
|
jpayne@7
|
150 applications that just need to convert labels, transitional processing
|
|
jpayne@7
|
151 is unlikely to be beneficial and could produce unexpected incompatible
|
|
jpayne@7
|
152 results.
|
|
jpayne@7
|
153
|
|
jpayne@7
|
154 ``encodings.idna`` Compatibility
|
|
jpayne@7
|
155 ++++++++++++++++++++++++++++++++
|
|
jpayne@7
|
156
|
|
jpayne@7
|
157 Function calls from the Python built-in ``encodings.idna`` module are
|
|
jpayne@7
|
158 mapped to their IDNA 2008 equivalents using the ``idna.compat`` module.
|
|
jpayne@7
|
159 Simply substitute the ``import`` clause in your code to refer to the new
|
|
jpayne@7
|
160 module name.
|
|
jpayne@7
|
161
|
|
jpayne@7
|
162 Exceptions
|
|
jpayne@7
|
163 ----------
|
|
jpayne@7
|
164
|
|
jpayne@7
|
165 All errors raised during the conversion following the specification
|
|
jpayne@7
|
166 should raise an exception derived from the ``idna.IDNAError`` base
|
|
jpayne@7
|
167 class.
|
|
jpayne@7
|
168
|
|
jpayne@7
|
169 More specific exceptions that may be generated as ``idna.IDNABidiError``
|
|
jpayne@7
|
170 when the error reflects an illegal combination of left-to-right and
|
|
jpayne@7
|
171 right-to-left characters in a label; ``idna.InvalidCodepoint`` when
|
|
jpayne@7
|
172 a specific codepoint is an illegal character in an IDN label (i.e.
|
|
jpayne@7
|
173 INVALID); and ``idna.InvalidCodepointContext`` when the codepoint is
|
|
jpayne@7
|
174 illegal based on its positional context (i.e. it is CONTEXTO or CONTEXTJ
|
|
jpayne@7
|
175 but the contextual requirements are not satisfied.)
|
|
jpayne@7
|
176
|
|
jpayne@7
|
177 Building and Diagnostics
|
|
jpayne@7
|
178 ------------------------
|
|
jpayne@7
|
179
|
|
jpayne@7
|
180 The IDNA and UTS 46 functionality relies upon pre-calculated lookup
|
|
jpayne@7
|
181 tables for performance. These tables are derived from computing against
|
|
jpayne@7
|
182 eligibility criteria in the respective standards. These tables are
|
|
jpayne@7
|
183 computed using the command-line script ``tools/idna-data``.
|
|
jpayne@7
|
184
|
|
jpayne@7
|
185 This tool will fetch relevant codepoint data from the Unicode repository
|
|
jpayne@7
|
186 and perform the required calculations to identify eligibility. There are
|
|
jpayne@7
|
187 three main modes:
|
|
jpayne@7
|
188
|
|
jpayne@7
|
189 * ``idna-data make-libdata``. Generates ``idnadata.py`` and
|
|
jpayne@7
|
190 ``uts46data.py``, the pre-calculated lookup tables used for IDNA and
|
|
jpayne@7
|
191 UTS 46 conversions. Implementers who wish to track this library against
|
|
jpayne@7
|
192 a different Unicode version may use this tool to manually generate a
|
|
jpayne@7
|
193 different version of the ``idnadata.py`` and ``uts46data.py`` files.
|
|
jpayne@7
|
194
|
|
jpayne@7
|
195 * ``idna-data make-table``. Generate a table of the IDNA disposition
|
|
jpayne@7
|
196 (e.g. PVALID, CONTEXTJ, CONTEXTO) in the format found in Appendix
|
|
jpayne@7
|
197 B.1 of RFC 5892 and the pre-computed tables published by `IANA
|
|
jpayne@7
|
198 <https://www.iana.org/>`_.
|
|
jpayne@7
|
199
|
|
jpayne@7
|
200 * ``idna-data U+0061``. Prints debugging output on the various
|
|
jpayne@7
|
201 properties associated with an individual Unicode codepoint (in this
|
|
jpayne@7
|
202 case, U+0061), that are used to assess the IDNA and UTS 46 status of a
|
|
jpayne@7
|
203 codepoint. This is helpful in debugging or analysis.
|
|
jpayne@7
|
204
|
|
jpayne@7
|
205 The tool accepts a number of arguments, described using ``idna-data
|
|
jpayne@7
|
206 -h``. Most notably, the ``--version`` argument allows the specification
|
|
jpayne@7
|
207 of the version of Unicode to be used in computing the table data. For
|
|
jpayne@7
|
208 example, ``idna-data --version 9.0.0 make-libdata`` will generate
|
|
jpayne@7
|
209 library data against Unicode 9.0.0.
|
|
jpayne@7
|
210
|
|
jpayne@7
|
211
|
|
jpayne@7
|
212 Additional Notes
|
|
jpayne@7
|
213 ----------------
|
|
jpayne@7
|
214
|
|
jpayne@7
|
215 * **Packages**. The latest tagged release version is published in the
|
|
jpayne@7
|
216 `Python Package Index <https://pypi.org/project/idna/>`_.
|
|
jpayne@7
|
217
|
|
jpayne@7
|
218 * **Version support**. This library supports Python 3.5 and higher.
|
|
jpayne@7
|
219 As this library serves as a low-level toolkit for a variety of
|
|
jpayne@7
|
220 applications, many of which strive for broad compatibility with older
|
|
jpayne@7
|
221 Python versions, there is no rush to remove older interpreter support.
|
|
jpayne@7
|
222 Removing support for older versions should be well justified in that the
|
|
jpayne@7
|
223 maintenance burden has become too high.
|
|
jpayne@7
|
224
|
|
jpayne@7
|
225 * **Python 2**. Python 2 is supported by version 2.x of this library.
|
|
jpayne@7
|
226 While active development of the version 2.x series has ended, notable
|
|
jpayne@7
|
227 issues being corrected may be backported to 2.x. Use "idna<3" in your
|
|
jpayne@7
|
228 requirements file if you need this library for a Python 2 application.
|
|
jpayne@7
|
229
|
|
jpayne@7
|
230 * **Testing**. The library has a test suite based on each rule of the
|
|
jpayne@7
|
231 IDNA specification, as well as tests that are provided as part of the
|
|
jpayne@7
|
232 Unicode Technical Standard 46, `Unicode IDNA Compatibility Processing
|
|
jpayne@7
|
233 <https://unicode.org/reports/tr46/>`_.
|
|
jpayne@7
|
234
|
|
jpayne@7
|
235 * **Emoji**. It is an occasional request to support emoji domains in
|
|
jpayne@7
|
236 this library. Encoding of symbols like emoji is expressly prohibited by
|
|
jpayne@7
|
237 the technical standard IDNA 2008 and emoji domains are broadly phased
|
|
jpayne@7
|
238 out across the domain industry due to associated security risks. For
|
|
jpayne@7
|
239 now, applications that need to support these non-compliant labels
|
|
jpayne@7
|
240 may wish to consider trying the encode/decode operation in this library
|
|
jpayne@7
|
241 first, and then falling back to using `encodings.idna`. See `the Github
|
|
jpayne@7
|
242 project <https://github.com/kjd/idna/issues/18>`_ for more discussion.
|
|
jpayne@7
|
243
|
