Installation

This package is available for installation from PyPI via thetypical mechanisms, such as:

$python3-mpipinstallidna

Usage

For typical usage, theencode anddecode functions will take adomain name argument and perform a conversion to ASCII compatible encoding(known as A-labels), or to Unicode strings (known as U-labels)respectively.

>>>importidna>>>idna.encode('ドメイン.テスト')b'xn--eckwd4c7c.xn--zckzah'>>>print(idna.decode('xn--eckwd4c7c.xn--zckzah'))ドメイン.テスト

Conversions can be applied at a per-label basis using theulabel oralabel functions if necessary:

>>>idna.alabel('测试')b'xn--0zwm56d'

>>>importidna>>>idna.encode('Königsgäßchen')...idna.core.InvalidCodepoint: Codepoint U+004B at position 1 of 'Königsgäßchen' not allowed>>>idna.encode('Königsgäßchen',uts46=True)b'xn--knigsgchen-b4a3dun'>>>print(idna.decode('xn--knigsgchen-b4a3dun'))königsgäßchen

Exceptions

All errors raised during the conversion following the specificationshould raise an exception derived from theidna.IDNAError baseclass.

More specific exceptions that may be generated asidna.IDNABidiErrorwhen the error reflects an illegal combination of left-to-right andright-to-left characters in a label;idna.InvalidCodepoint whena specific codepoint is an illegal character in an IDN label (i.e.INVALID); andidna.InvalidCodepointContext when the codepoint isillegal based on its position in the string (i.e. it is CONTEXTO or CONTEXTJbut the contextual requirements are not satisfied.)

Building and Diagnostics

The IDNA and UTS 46 functionality relies upon pre-calculated lookuptables for performance. These tables are derived from computing againsteligibility criteria in the respective standards using the command-linescripttools/idna-data.

This tool will fetch relevant codepoint data from the Unicode repositoryand perform the required calculations to identify eligibility. There arethree main modes:

• idna-datamake-libdata. Generatesidnadata.py anduts46data.py, the pre-calculated lookup tables used for IDNA andUTS 46 conversions. Implementers who wish to track this library againsta different Unicode version may use this tool to manually generate adifferent version of theidnadata.py anduts46data.py files.

• idna-datamake-table. Generate a table of the IDNA disposition(e.g. PVALID, CONTEXTJ, CONTEXTO) in the format found in AppendixB.1 of RFC 5892 and the pre-computed tables published byIANA.

• idna-data U+0061. Prints debugging output on the variousproperties associated with an individual Unicode codepoint (in thiscase, U+0061), that are used to assess the IDNA and UTS 46 status of acodepoint. This is helpful in debugging or analysis.

The tool accepts a number of arguments, described usingidna-data-h. Most notably, the--version argument allows the specificationof the version of Unicode to be used in computing the table data. Forexample,idna-data--version 9.0.0make-libdata will generatelibrary data against Unicode 9.0.0.

Additional Notes

• Packages. The latest tagged release version is published in thePython Package Index.

• Version support. This library supports Python 3.8 and higher.As this library serves as a low-level toolkit for a variety ofapplications, many of which strive for broad compatibility with olderPython versions, there is no rush to remove older interpreter support.Support for older versions are likely to be removed from new releasesas automated tests can no longer easily be run, i.e. once the Pythonversion is officially end-of-life.

• Testing. The library has a test suite based on each rule of theIDNA specification, as well as tests that are provided as part of theUnicode Technical Standard 46,Unicode IDNA Compatibility Processing.

• Emoji. It is an occasional request to support emoji domains inthis library. Encoding of symbols like emoji is expressly prohibited bythe technical standard IDNA 2008 and emoji domains are broadly phasedout across the domain industry due to associated security risks. Fornow, applications that need to support these non-compliant labelsmay wish to consider trying the encode/decode operation in this libraryfirst, and then falling back to usingencodings.idna. Seethe Githubproject for more discussion.

• Transitional processing. Unicode 16.0.0 removed transitionalprocessing so thetransitional argument for the encode() methodno longer has any effect and will be removed at a later date.