PKG-INFO 10 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237
  1. Metadata-Version: 1.1
  2. Name: idna
  3. Version: 2.6
  4. Summary: Internationalized Domain Names in Applications (IDNA)
  5. Home-page: https://github.com/kjd/idna
  6. Author: Kim Davies
  7. Author-email: kim@cynosure.com.au
  8. License: BSD-like
  9. Description: Internationalized Domain Names in Applications (IDNA)
  10. =====================================================
  11. Support for the Internationalised Domain Names in Applications
  12. (IDNA) protocol as specified in `RFC 5891 <http://tools.ietf.org/html/rfc5891>`_.
  13. This is the latest version of the protocol and is sometimes referred to as
  14. “IDNA 2008”.
  15. This library also provides support for Unicode Technical Standard 46,
  16. `Unicode IDNA Compatibility Processing <http://unicode.org/reports/tr46/>`_.
  17. This acts as a suitable replacement for the “encodings.idna” module that
  18. comes with the Python standard library, but only supports the
  19. old, deprecated IDNA specification (`RFC 3490 <http://tools.ietf.org/html/rfc3490>`_).
  20. Basic functions are simply executed:
  21. .. code-block:: pycon
  22. # Python 3
  23. >>> import idna
  24. >>> idna.encode('ドメイン.テスト')
  25. b'xn--eckwd4c7c.xn--zckzah'
  26. >>> print(idna.decode('xn--eckwd4c7c.xn--zckzah'))
  27. ドメイン.テスト
  28. # Python 2
  29. >>> import idna
  30. >>> idna.encode(u'ドメイン.テスト')
  31. 'xn--eckwd4c7c.xn--zckzah'
  32. >>> print idna.decode('xn--eckwd4c7c.xn--zckzah')
  33. ドメイン.テスト
  34. Packages
  35. --------
  36. The latest tagged release version is published in the PyPI repository:
  37. .. image:: https://badge.fury.io/py/idna.svg
  38. :target: http://badge.fury.io/py/idna
  39. Installation
  40. ------------
  41. To install this library, you can use pip:
  42. .. code-block:: bash
  43. $ pip install idna
  44. Alternatively, you can install the package using the bundled setup script:
  45. .. code-block:: bash
  46. $ python setup.py install
  47. This library works with Python 2.6 or later, and Python 3.3 or later.
  48. Usage
  49. -----
  50. For typical usage, the ``encode`` and ``decode`` functions will take a domain
  51. name argument and perform a conversion to A-labels or U-labels respectively.
  52. .. code-block:: pycon
  53. # Python 3
  54. >>> import idna
  55. >>> idna.encode('ドメイン.テスト')
  56. b'xn--eckwd4c7c.xn--zckzah'
  57. >>> print(idna.decode('xn--eckwd4c7c.xn--zckzah'))
  58. ドメイン.テスト
  59. You may use the codec encoding and decoding methods using the
  60. ``idna.codec`` module:
  61. .. code-block:: pycon
  62. # Python 2
  63. >>> import idna.codec
  64. >>> print u'домена.испытание'.encode('idna')
  65. xn--80ahd1agd.xn--80akhbyknj4f
  66. >>> print 'xn--80ahd1agd.xn--80akhbyknj4f'.decode('idna')
  67. домена.испытание
  68. Conversions can be applied at a per-label basis using the ``ulabel`` or ``alabel``
  69. functions if necessary:
  70. .. code-block:: pycon
  71. # Python 2
  72. >>> idna.alabel(u'测试')
  73. 'xn--0zwm56d'
  74. Compatibility Mapping (UTS #46)
  75. +++++++++++++++++++++++++++++++
  76. As described in `RFC 5895 <http://tools.ietf.org/html/rfc5895>`_, the IDNA
  77. specification no longer normalizes input from different potential ways a user
  78. may input a domain name. This functionality, known as a “mapping”, is now
  79. considered by the specification to be a local user-interface issue distinct
  80. from IDNA conversion functionality.
  81. This library provides one such mapping, that was developed by the Unicode
  82. Consortium. Known as `Unicode IDNA Compatibility Processing <http://unicode.org/reports/tr46/>`_,
  83. it provides for both a regular mapping for typical applications, as well as
  84. a transitional mapping to help migrate from older IDNA 2003 applications.
  85. For example, “Königsgäßchen” is not a permissible label as *LATIN CAPITAL
  86. LETTER K* is not allowed (nor are capital letters in general). UTS 46 will
  87. convert this into lower case prior to applying the IDNA conversion.
  88. .. code-block:: pycon
  89. # Python 3
  90. >>> import idna
  91. >>> idna.encode(u'Königsgäßchen')
  92. ...
  93. idna.core.InvalidCodepoint: Codepoint U+004B at position 1 of 'Königsgäßchen' not allowed
  94. >>> idna.encode('Königsgäßchen', uts46=True)
  95. b'xn--knigsgchen-b4a3dun'
  96. >>> print(idna.decode('xn--knigsgchen-b4a3dun'))
  97. königsgäßchen
  98. Transitional processing provides conversions to help transition from the older
  99. 2003 standard to the current standard. For example, in the original IDNA
  100. specification, the *LATIN SMALL LETTER SHARP S* (ß) was converted into two
  101. *LATIN SMALL LETTER S* (ss), whereas in the current IDNA specification this
  102. conversion is not performed.
  103. .. code-block:: pycon
  104. # Python 2
  105. >>> idna.encode(u'Königsgäßchen', uts46=True, transitional=True)
  106. 'xn--knigsgsschen-lcb0w'
  107. Implementors should use transitional processing with caution, only in rare
  108. cases where conversion from legacy labels to current labels must be performed
  109. (i.e. IDNA implementations that pre-date 2008). For typical applications
  110. that just need to convert labels, transitional processing is unlikely to be
  111. beneficial and could produce unexpected incompatible results.
  112. ``encodings.idna`` Compatibility
  113. ++++++++++++++++++++++++++++++++
  114. Function calls from the Python built-in ``encodings.idna`` module are
  115. mapped to their IDNA 2008 equivalents using the ``idna.compat`` module.
  116. Simply substitute the ``import`` clause in your code to refer to the
  117. new module name.
  118. Exceptions
  119. ----------
  120. All errors raised during the conversion following the specification should
  121. raise an exception derived from the ``idna.IDNAError`` base class.
  122. More specific exceptions that may be generated as ``idna.IDNABidiError``
  123. when the error reflects an illegal combination of left-to-right and right-to-left
  124. characters in a label; ``idna.InvalidCodepoint`` when a specific codepoint is
  125. an illegal character in an IDN label (i.e. INVALID); and ``idna.InvalidCodepointContext``
  126. when the codepoint is illegal based on its positional context (i.e. it is CONTEXTO
  127. or CONTEXTJ but the contextual requirements are not satisfied.)
  128. Building and Diagnostics
  129. ------------------------
  130. The IDNA and UTS 46 functionality relies upon pre-calculated lookup tables for
  131. performance. These tables are derived from computing against eligibility criteria
  132. in the respective standards. These tables are computed using the command-line
  133. script ``tools/idna-data``.
  134. This tool will fetch relevant tables from the Unicode Consortium and perform the
  135. required calculations to identify eligibility. It has three main modes:
  136. * ``idna-data make-libdata``. Generates ``idnadata.py`` and ``uts46data.py``,
  137. the pre-calculated lookup tables using for IDNA and UTS 46 conversions. Implementors
  138. who wish to track this library against a different Unicode version may use this tool
  139. to manually generate a different version of the ``idnadata.py`` and ``uts46data.py``
  140. files.
  141. * ``idna-data make-table``. Generate a table of the IDNA disposition
  142. (e.g. PVALID, CONTEXTJ, CONTEXTO) in the format found in Appendix B.1 of RFC
  143. 5892 and the pre-computed tables published by `IANA <http://iana.org/>`_.
  144. * ``idna-data U+0061``. Prints debugging output on the various properties
  145. associated with an individual Unicode codepoint (in this case, U+0061), that are
  146. used to assess the IDNA and UTS 46 status of a codepoint. This is helpful in debugging
  147. or analysis.
  148. The tool accepts a number of arguments, described using ``idna-data -h``. Most notably,
  149. the ``--version`` argument allows the specification of the version of Unicode to use
  150. in computing the table data. For example, ``idna-data --version 9.0.0 make-libdata``
  151. will generate library data against Unicode 9.0.0.
  152. Note that this script requires Python 3, but all generated library data will work
  153. in Python 2.6+.
  154. Testing
  155. -------
  156. The library has a test suite based on each rule of the IDNA specification, as
  157. well as tests that are provided as part of the Unicode Technical Standard 46,
  158. `Unicode IDNA Compatibility Processing <http://unicode.org/reports/tr46/>`_.
  159. The tests are run automatically on each commit at Travis CI:
  160. .. image:: https://travis-ci.org/kjd/idna.svg?branch=master
  161. :target: https://travis-ci.org/kjd/idna
  162. Platform: UNKNOWN
  163. Classifier: Development Status :: 5 - Production/Stable
  164. Classifier: Intended Audience :: Developers
  165. Classifier: Intended Audience :: System Administrators
  166. Classifier: License :: OSI Approved :: BSD License
  167. Classifier: Operating System :: OS Independent
  168. Classifier: Programming Language :: Python
  169. Classifier: Programming Language :: Python :: 2.6
  170. Classifier: Programming Language :: Python :: 2.7
  171. Classifier: Programming Language :: Python :: 3
  172. Classifier: Programming Language :: Python :: 3.3
  173. Classifier: Programming Language :: Python :: 3.4
  174. Classifier: Programming Language :: Python :: 3.5
  175. Classifier: Programming Language :: Python :: 3.6
  176. Classifier: Topic :: Internet :: Name Service (DNS)
  177. Classifier: Topic :: Software Development :: Libraries :: Python Modules
  178. Classifier: Topic :: Utilities