jpayne@7: Metadata-Version: 2.1 jpayne@7: Name: idna jpayne@7: Version: 3.7 jpayne@7: Summary: Internationalized Domain Names in Applications (IDNA) jpayne@7: Author-email: Kim Davies jpayne@7: Requires-Python: >=3.5 jpayne@7: Description-Content-Type: text/x-rst jpayne@7: Classifier: Development Status :: 5 - Production/Stable jpayne@7: Classifier: Intended Audience :: Developers jpayne@7: Classifier: Intended Audience :: System Administrators jpayne@7: Classifier: License :: OSI Approved :: BSD License jpayne@7: Classifier: Operating System :: OS Independent jpayne@7: Classifier: Programming Language :: Python jpayne@7: Classifier: Programming Language :: Python :: 3 jpayne@7: Classifier: Programming Language :: Python :: 3 :: Only jpayne@7: Classifier: Programming Language :: Python :: 3.5 jpayne@7: Classifier: Programming Language :: Python :: 3.6 jpayne@7: Classifier: Programming Language :: Python :: 3.7 jpayne@7: Classifier: Programming Language :: Python :: 3.8 jpayne@7: Classifier: Programming Language :: Python :: 3.9 jpayne@7: Classifier: Programming Language :: Python :: 3.10 jpayne@7: Classifier: Programming Language :: Python :: 3.11 jpayne@7: Classifier: Programming Language :: Python :: 3.12 jpayne@7: Classifier: Programming Language :: Python :: Implementation :: CPython jpayne@7: Classifier: Programming Language :: Python :: Implementation :: PyPy jpayne@7: Classifier: Topic :: Internet :: Name Service (DNS) jpayne@7: Classifier: Topic :: Software Development :: Libraries :: Python Modules jpayne@7: Classifier: Topic :: Utilities jpayne@7: Project-URL: Changelog, https://github.com/kjd/idna/blob/master/HISTORY.rst jpayne@7: Project-URL: Issue tracker, https://github.com/kjd/idna/issues jpayne@7: Project-URL: Source, https://github.com/kjd/idna jpayne@7: jpayne@7: Internationalized Domain Names in Applications (IDNA) jpayne@7: ===================================================== jpayne@7: jpayne@7: Support for the Internationalized Domain Names in jpayne@7: Applications (IDNA) protocol as specified in `RFC 5891 jpayne@7: `_. This is the latest version of jpayne@7: the protocol and is sometimes referred to as “IDNA 2008”. jpayne@7: jpayne@7: This library also provides support for Unicode Technical jpayne@7: Standard 46, `Unicode IDNA Compatibility Processing jpayne@7: `_. jpayne@7: jpayne@7: This acts as a suitable replacement for the “encodings.idna” jpayne@7: module that comes with the Python standard library, but which jpayne@7: only supports the older superseded IDNA specification (`RFC 3490 jpayne@7: `_). jpayne@7: jpayne@7: Basic functions are simply executed: jpayne@7: jpayne@7: .. code-block:: pycon jpayne@7: jpayne@7: >>> import idna jpayne@7: >>> idna.encode('ドメイン.テスト') jpayne@7: b'xn--eckwd4c7c.xn--zckzah' jpayne@7: >>> print(idna.decode('xn--eckwd4c7c.xn--zckzah')) jpayne@7: ドメイン.テスト jpayne@7: jpayne@7: jpayne@7: Installation jpayne@7: ------------ jpayne@7: jpayne@7: This package is available for installation from PyPI: jpayne@7: jpayne@7: .. code-block:: bash jpayne@7: jpayne@7: $ python3 -m pip install idna jpayne@7: jpayne@7: jpayne@7: Usage jpayne@7: ----- jpayne@7: jpayne@7: For typical usage, the ``encode`` and ``decode`` functions will take a jpayne@7: domain name argument and perform a conversion to A-labels or U-labels jpayne@7: respectively. jpayne@7: jpayne@7: .. code-block:: pycon jpayne@7: jpayne@7: >>> import idna jpayne@7: >>> idna.encode('ドメイン.テスト') jpayne@7: b'xn--eckwd4c7c.xn--zckzah' jpayne@7: >>> print(idna.decode('xn--eckwd4c7c.xn--zckzah')) jpayne@7: ドメイン.テスト jpayne@7: jpayne@7: You may use the codec encoding and decoding methods using the jpayne@7: ``idna.codec`` module: jpayne@7: jpayne@7: .. code-block:: pycon jpayne@7: jpayne@7: >>> import idna.codec jpayne@7: >>> print('домен.испытание'.encode('idna2008')) jpayne@7: b'xn--d1acufc.xn--80akhbyknj4f' jpayne@7: >>> print(b'xn--d1acufc.xn--80akhbyknj4f'.decode('idna2008')) jpayne@7: домен.испытание jpayne@7: jpayne@7: Conversions can be applied at a per-label basis using the ``ulabel`` or jpayne@7: ``alabel`` functions if necessary: jpayne@7: jpayne@7: .. code-block:: pycon jpayne@7: jpayne@7: >>> idna.alabel('测试') jpayne@7: b'xn--0zwm56d' jpayne@7: jpayne@7: Compatibility Mapping (UTS #46) jpayne@7: +++++++++++++++++++++++++++++++ jpayne@7: jpayne@7: As described in `RFC 5895 `_, the jpayne@7: IDNA specification does not normalize input from different potential jpayne@7: ways a user may input a domain name. This functionality, known as jpayne@7: a “mapping”, is considered by the specification to be a local jpayne@7: user-interface issue distinct from IDNA conversion functionality. jpayne@7: jpayne@7: This library provides one such mapping that was developed by the jpayne@7: Unicode Consortium. Known as `Unicode IDNA Compatibility Processing jpayne@7: `_, it provides for both a regular jpayne@7: mapping for typical applications, as well as a transitional mapping to jpayne@7: help migrate from older IDNA 2003 applications. jpayne@7: jpayne@7: For example, “Königsgäßchen” is not a permissible label as *LATIN jpayne@7: CAPITAL LETTER K* is not allowed (nor are capital letters in general). jpayne@7: UTS 46 will convert this into lower case prior to applying the IDNA jpayne@7: conversion. jpayne@7: jpayne@7: .. code-block:: pycon jpayne@7: jpayne@7: >>> import idna jpayne@7: >>> idna.encode('Königsgäßchen') jpayne@7: ... jpayne@7: idna.core.InvalidCodepoint: Codepoint U+004B at position 1 of 'Königsgäßchen' not allowed jpayne@7: >>> idna.encode('Königsgäßchen', uts46=True) jpayne@7: b'xn--knigsgchen-b4a3dun' jpayne@7: >>> print(idna.decode('xn--knigsgchen-b4a3dun')) jpayne@7: königsgäßchen jpayne@7: jpayne@7: Transitional processing provides conversions to help transition from jpayne@7: the older 2003 standard to the current standard. For example, in the jpayne@7: original IDNA specification, the *LATIN SMALL LETTER SHARP S* (ß) was jpayne@7: converted into two *LATIN SMALL LETTER S* (ss), whereas in the current jpayne@7: IDNA specification this conversion is not performed. jpayne@7: jpayne@7: .. code-block:: pycon jpayne@7: jpayne@7: >>> idna.encode('Königsgäßchen', uts46=True, transitional=True) jpayne@7: 'xn--knigsgsschen-lcb0w' jpayne@7: jpayne@7: Implementers should use transitional processing with caution, only in jpayne@7: rare cases where conversion from legacy labels to current labels must be jpayne@7: performed (i.e. IDNA implementations that pre-date 2008). For typical jpayne@7: applications that just need to convert labels, transitional processing jpayne@7: is unlikely to be beneficial and could produce unexpected incompatible jpayne@7: results. jpayne@7: jpayne@7: ``encodings.idna`` Compatibility jpayne@7: ++++++++++++++++++++++++++++++++ jpayne@7: jpayne@7: Function calls from the Python built-in ``encodings.idna`` module are jpayne@7: mapped to their IDNA 2008 equivalents using the ``idna.compat`` module. jpayne@7: Simply substitute the ``import`` clause in your code to refer to the new jpayne@7: module name. jpayne@7: jpayne@7: Exceptions jpayne@7: ---------- jpayne@7: jpayne@7: All errors raised during the conversion following the specification jpayne@7: should raise an exception derived from the ``idna.IDNAError`` base jpayne@7: class. jpayne@7: jpayne@7: More specific exceptions that may be generated as ``idna.IDNABidiError`` jpayne@7: when the error reflects an illegal combination of left-to-right and jpayne@7: right-to-left characters in a label; ``idna.InvalidCodepoint`` when jpayne@7: a specific codepoint is an illegal character in an IDN label (i.e. jpayne@7: INVALID); and ``idna.InvalidCodepointContext`` when the codepoint is jpayne@7: illegal based on its positional context (i.e. it is CONTEXTO or CONTEXTJ jpayne@7: but the contextual requirements are not satisfied.) jpayne@7: jpayne@7: Building and Diagnostics jpayne@7: ------------------------ jpayne@7: jpayne@7: The IDNA and UTS 46 functionality relies upon pre-calculated lookup jpayne@7: tables for performance. These tables are derived from computing against jpayne@7: eligibility criteria in the respective standards. These tables are jpayne@7: computed using the command-line script ``tools/idna-data``. jpayne@7: jpayne@7: This tool will fetch relevant codepoint data from the Unicode repository jpayne@7: and perform the required calculations to identify eligibility. There are jpayne@7: three main modes: jpayne@7: jpayne@7: * ``idna-data make-libdata``. Generates ``idnadata.py`` and jpayne@7: ``uts46data.py``, the pre-calculated lookup tables used for IDNA and jpayne@7: UTS 46 conversions. Implementers who wish to track this library against jpayne@7: a different Unicode version may use this tool to manually generate a jpayne@7: different version of the ``idnadata.py`` and ``uts46data.py`` files. jpayne@7: jpayne@7: * ``idna-data make-table``. Generate a table of the IDNA disposition jpayne@7: (e.g. PVALID, CONTEXTJ, CONTEXTO) in the format found in Appendix jpayne@7: B.1 of RFC 5892 and the pre-computed tables published by `IANA jpayne@7: `_. jpayne@7: jpayne@7: * ``idna-data U+0061``. Prints debugging output on the various jpayne@7: properties associated with an individual Unicode codepoint (in this jpayne@7: case, U+0061), that are used to assess the IDNA and UTS 46 status of a jpayne@7: codepoint. This is helpful in debugging or analysis. jpayne@7: jpayne@7: The tool accepts a number of arguments, described using ``idna-data jpayne@7: -h``. Most notably, the ``--version`` argument allows the specification jpayne@7: of the version of Unicode to be used in computing the table data. For jpayne@7: example, ``idna-data --version 9.0.0 make-libdata`` will generate jpayne@7: library data against Unicode 9.0.0. jpayne@7: jpayne@7: jpayne@7: Additional Notes jpayne@7: ---------------- jpayne@7: jpayne@7: * **Packages**. The latest tagged release version is published in the jpayne@7: `Python Package Index `_. jpayne@7: jpayne@7: * **Version support**. This library supports Python 3.5 and higher. jpayne@7: As this library serves as a low-level toolkit for a variety of jpayne@7: applications, many of which strive for broad compatibility with older jpayne@7: Python versions, there is no rush to remove older interpreter support. jpayne@7: Removing support for older versions should be well justified in that the jpayne@7: maintenance burden has become too high. jpayne@7: jpayne@7: * **Python 2**. Python 2 is supported by version 2.x of this library. jpayne@7: While active development of the version 2.x series has ended, notable jpayne@7: issues being corrected may be backported to 2.x. Use "idna<3" in your jpayne@7: requirements file if you need this library for a Python 2 application. jpayne@7: jpayne@7: * **Testing**. The library has a test suite based on each rule of the jpayne@7: IDNA specification, as well as tests that are provided as part of the jpayne@7: Unicode Technical Standard 46, `Unicode IDNA Compatibility Processing jpayne@7: `_. jpayne@7: jpayne@7: * **Emoji**. It is an occasional request to support emoji domains in jpayne@7: this library. Encoding of symbols like emoji is expressly prohibited by jpayne@7: the technical standard IDNA 2008 and emoji domains are broadly phased jpayne@7: out across the domain industry due to associated security risks. For jpayne@7: now, applications that need to support these non-compliant labels jpayne@7: may wish to consider trying the encode/decode operation in this library jpayne@7: first, and then falling back to using `encodings.idna`. See `the Github jpayne@7: project `_ for more discussion. jpayne@7: