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 2003”, which is widely used, and the revised and not fully compatible standard “IDNA 2008”. 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.

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.

strict_decode is a 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.

uts_46 is a 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 is a bool: If True, use the “transitional” mode described in Unicode Technical Standard #46. The default is False.

allow_pure_ascii is a 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 with starting with “_sip._tcp.” and ending in an IDN suffix which would otherwise be disallowed. The default is False.

strict_decode is a 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.

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