International Domain Name CODECs

Representing non-ASCII text in the DNS is a complex and evolving topic. Generally speaking, Unicode is converted into an ASCII-only, case-insensitive form called “Punycode” by complex rules. There are two standard specifications for this process, “IDNA 2008”, which is widely used, and the older not fully compatible standard “IDNA 2003”. There are also varying degrees of strictness that can be applied in encoding and decoding. Explaining the standards in detail is out of scope for this document; Unicode Technical Standard #46 https://unicode.org/reports/tr46/ is a good place to start learning more.

Dnspython provides “codecs” to implement International Domain Name policy according to the user’s desire.

The default codec to use for all of dnspython can be set by calling dns.name.set_default_idna_codec(). The default default codec is dns.name.IDNA_2008_Practical if the idna module is installed, and dns.name.IDNA_2003_Practical otherwise.

class dns.name.IDNACodec[source]: Abstract base class for IDNA encoder/decoders.

class dns.name.IDNA2003Codec(strict_decode: bool = False)[source]

IDNA 2003 encoder/decoder.

Initialize the IDNA 2003 encoder/decoder.

Parameters:: strict_decode (bool) – If True, then IDNA2003 checking is done when decoding. This can cause failures if the name was encoded with IDNA2008. The default is False.

decode(label: bytes) → str[source]: Decode label.

encode(label: str) → bytes[source]: Encode label.

class dns.name.IDNA2008Codec(uts_46: bool = False, transitional: bool = False, allow_pure_ascii: bool = False, strict_decode: bool = False)[source]

IDNA 2008 encoder/decoder.

Initialize the IDNA 2008 encoder/decoder.

Parameters:

uts_46 (bool) – If True, apply Unicode IDNA compatibility processing as described in Unicode Technical Standard #46 (https://unicode.org/reports/tr46/). If False, do not apply the mapping. The default is False.
transitional (bool) – If True, use the “transitional” mode described in Unicode Technical Standard #46. The default is False. This setting has no effect in idna 3.11 and later as transitional support has been removed.
allow_pure_ascii (bool) – If True, then a label which consists of only ASCII characters is allowed. This is less strict than regular IDNA 2008, but is also necessary for mixed names, e.g. a name starting with _sip._tcp. and ending in an IDN suffix which would otherwise be disallowed. The default is False.
strict_decode (bool) – If True, then IDNA2008 checking is done when decoding. This can cause failures if the name was encoded with IDNA2003. The default is False.

dns.name.IDNA_2003_Practical: The “practical” codec encodes using IDNA 2003 rules and decodes punycode without checking for strict IDNA 2003 compliance.

dns.name.IDNA_2003_Strict: The “strict” codec encodes using IDNA 2003 rules and decodes punycode checking for IDNA 2003 compliance.

dns.name.IDNA_2003: A synonym for dns.name.IDNA_2003_Practical.

dns.name.IDNA_2008_Practical: The “practical” codec encodes using IDNA 2008 rules with UTS 46 compatibility processing, and allowing pure ASCII labels. It decodes punycode without checking for strict IDNA 2008 compliance.

dns.name.IDNA_2008_Strict: The “strict” codec encodes using IDNA 2008 rules and decodes punycode checking for IDNA 2008 compliance.

dns.name.IDNA_2008_UTS_46: The “UTS 46” codec encodes using IDNA 2008 rules with UTS 46 compatibility processing and decodes punycode without checking for IDNA 2008 compliance.

dns.name.IDNA_2008_Transitional: The “UTS 46” codec encodes using IDNA 2008 rules with UTS 46 compatibility processing in the “transitional mode” and decodes punycode without checking for IDNA 2008 compliance. This codec is the same as dns.name.IDNA_2008_UTS_46 in idna 3.11 and later as transitional support has been removed.

dns.name.IDNA_2008: A synonym for dns.name.IDNA_2008_Practical.

dns.name.IDNA_DEFAULT: The default IDNA codec.

dns.name.set_default_idna_codec(idna_codec: IDNACodec)[source]: Set the default IDNA codec.