kjd/idna
GitHub: kjd/idna
一个实现了 IDNA 2008 和 UTS #46 标准的 Python 库，用于国际化域名与 ASCII 兼容编码（Punycode）之间的相互转换。
Stars: 285 | Forks: 123
# 应用程序中的国际化域名 (IDNA)
支持[应用程序中的国际化域名 (IDNA)](https://tools.ietf.org/html/rfc5891)和 [Unicode IDNA 兼容性处理](https://unicode.org/reports/tr46/)。
此处提供的这些标准的最新版本提供了更全面的语言覆盖范围，并降低了允许存在已知安全漏洞的域名的可能性。该库是 Python 标准库附带的 "encodings.idna" 模块的合适替代品，因为该模块仅支持 2003 年旧版的、已被取代的 IDNA 规范。
基本函数的执行非常简单：
```
>>> import idna
>>> idna.encode('ドメイン.テスト')
b'xn--eckwd4c7c.xn--zckzah'
>>> print(idna.decode('xn--eckwd4c7c.xn--zckzah'))
ドメイン.テスト
```
## 安装
该软件包可以通过典型机制从 PyPI 安装，例如：
```
$ python3 -m pip install idna
```
## 使用方法
对于典型用法，`encode` 和 `decode` 函数将接收一个域名参数，并分别执行到 ASCII 兼容编码（称为 A-labels）或 Unicode 字符串（称为 U-labels）的转换。
```
>>> import idna
>>> idna.encode('ドメイン.テスト')
b'xn--eckwd4c7c.xn--zckzah'
>>> print(idna.decode('xn--eckwd4c7c.xn--zckzah'))
ドメイン.テスト
```
如有必要，可以使用 `ulabel` 或 `alabel` 函数逐个标签地应用转换：
```
>>> idna.alabel('测试')
b'xn--0zwm56d'
```
### 兼容性映射 (UTS #46)
该库支持 [Unicode IDNA 兼容性处理](https://unicode.org/reports/tr46/)，它会在执行 IDNA 转换操作之前，对用户可能输入域名的不同潜在方式进行标准化处理。这种被称为[映射](https://tools.ietf.org/html/rfc5895)的功能，被该规范视为一个有别于 IDNA 转换功能的本地用户界面问题。
例如，"Königsgäßchen" 不是一个允许的标签，因为不允许使用 *LATIN CAPITAL LETTER K*（通常也不允许使用大写字母）。UTS 46 将在应用 IDNA 转换之前将其转换为小写。
```
>>> import idna
>>> 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
```
## 异常
按照规范，在转换期间引发的所有错误都应抛出派生自 `idna.IDNAError` 基类的异常。
可能引发的更具体的异常包括：当错误反映了标签中从左到右和从右到左字符的非法组合时，会引发 `idna.IDNABidiError`；当特定码位是 IDN 标签中的非法字符（即 INVALID）时，会引发 `idna.InvalidCodepoint`；当码位基于其在字符串中的位置是非法的（即它是 CONTEXTO 或 CONTEXTJ，但不满足上下文要求）时，会引发 `idna.InvalidCodepointContext`。
## 构建与诊断
IDNA 和 UTS 46 功能依赖于预先计算的查找表以提高性能。这些表是通过使用命令行脚本 `tools/idna-data` 对各自标准中的资格条件进行计算得出的。
该工具将从 Unicode 存储库获取相关的码位数据并执行所需的计算以确定资格。它具有三种主要模式：
* `idna-data make-libdata`。生成 `idnadata.py` 和 `uts46data.py`，它们是用于 IDNA 和 UTS 46 转换的预先计算的查找表。希望将此库针对不同 Unicode 版本进行跟踪的实现者，可以使用此工具手动生成不同版本的 `idnadata.py` 和 `uts46data.py` 文件。
* `idna-data make-table`。以 RFC 5892 附录 B.1 中的格式和 [IANA](https://www.iana.org/) 发布的预计算表格式，生成 IDNA 处置（例如 PVALID、CONTEXTJ、CONTEXTO）的表格。
* `idna-data U+0061`。打印关于单个 Unicode 码位（在此示例中为 U+0061）的各种相关属性的调试输出，这些属性用于评估码位的 IDNA 和 UTS 46 状态。这对调试或分析很有帮助。
该工具接受许多参数，可以使用 `idna-data -h` 来查看描述。最值得注意的是，`--version` 参数允许指定用于计算表数据的 Unicode 版本。例如，`idna-data --version 9.0.0 make-libdata` 将针对 Unicode 9.0.0 生成库数据。
## 附加说明
* **软件包**。最新标记的发布版本发布在 [Python Package Index](https://pypi.org/project/idna/) 上。
* **版本支持**。该库支持 Python 3.8 及更高版本。由于该库作为各种应用程序的低级工具包，其中许多应用程序努力实现与旧版 Python 的广泛兼容性，因此不急于移除对旧版解释器的支持。对旧版本的支持可能会在无法再轻松运行自动化测试时（即 Python 版本正式生命周期结束之后）从新版本中移除。
* **测试**。该库拥有一个基于 IDNA 规范每条规则的测试套件，以及作为 Unicode 技术标准 46 [Unicode IDNA 兼容性处理](https://unicode.org/reports/tr46/)的一部分提供的测试。
* **Emoji**。偶尔会有请求要求该库支持 emoji 域名。IDNA 技术标准明令禁止编码诸如 emoji 的符号，并且由于相关的安全风险，emoji 域名在整个域名行业中正在被广泛逐步淘汰。
* **过渡性处理**。Unicode 16.0.0 移除了过渡性处理，因此 encode() 方法的 `transitional` 参数不再具有任何效果，并将在未来被移除。
标签：A-label, ASCII兼容编码, IDNA, IDNA 2008, Punycode, PyPI, Python, RFC 5891, SYN扫描, U-label, UTS #46, 同形异义词防护, 国际化, 国际化域名, 域名编码, 域名解析, 多语言支持, 安全测试框架, 开源库, 搜索引擎爬虫, 文本处理, 无后门, 编码转换, 网络安全, 逆向工具, 隐私保护