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