annotate idna-3.7.dist-info/METADATA @ 11:7fd0ef5842e7

planemo upload for repository https://toolrepo.galaxytrakr.org/view/jpayne/bioproject_to_srr_2/556cac4fb538
author jpayne
date Mon, 06 May 2024 01:42:27 -0400
parents 5eb2d5e3bf22
children
rev   line source
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