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