python 解码器

xhz

内置编解码器
Python 提供了一组以 C 编写以保证运行速度的内置编解码器。 所有这些编解码器均可通过下列函数直接使用。

下列 API 大都接受 encoding 和 errors 两个参数，它们具有与在内置 str() 字符串对象构造器中同名参数相同的语义。

将 encoding 设为 NULL 将使用默认编码格式即 UTF-8。 文件系统调用应当使用 PyUnicode_FSConverter() 来编码文件名。 这将在内部使用 filesystem encoding and error handler。

错误处理方式由 errors 设置并且也可以设为 NULL 表示使用为编解码器定义的默认处理方式。 所有内置编解码器的默认错误处理方式是 "strict" (会引发 ValueError)。

编解码器都使用类似的接口。 为了保持简单只有与下列泛型编解码器的差异才会记录在文档中。

泛型编解码器
以下是泛型编解码器的 API:

PyObject *PyUnicode_Decode(const char *str, Py_ssize_t size, const char *encoding, const char *errors)
返回值：新的引用。 属于 稳定 ABI.
通过解码已编码字节串 str 的 size 个字节创建一个 Unicode 对象。 encoding 和 errors 具有与 str() 内置函数中同名形参相同的含义。 要使用的编解码将使用 Python 编解码器注册表来查找。 如果编解码器引发了异常则返回 NULL。

PyObject *PyUnicode_AsEncodedString(PyObject *unicode, const char *encoding, const char *errors)
返回值：新的引用。 属于 稳定 ABI.
编码一个 Unicode 对象并将结果作为 Python 字节串对象返回。 encoding 和 errors 具有与 Unicode encode() 方法中同名形参相同的含义。 要使用的编解码器将使用 Python 编解码器注册表来查找。 如果编解码器引发了异常则返回 NULL。

UTF-8 编解码器
以下是 UTF-8 编解码器 API:

PyObject *PyUnicode_DecodeUTF8(const char *str, Py_ssize_t size, const char *errors)
返回值：新的引用。 属于 稳定 ABI.
通过解码 UTF-8 编码的字节串 str 的的 size 个字节创建一个 Unicode 对象。 如果编解码器引发了异常则返回 NULL。

PyObject *PyUnicode_DecodeUTF8Stateful(const char *str, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)
返回值：新的引用。 属于 稳定 ABI.
如果 consumed 为 NULL，则行为类似于 PyUnicode_DecodeUTF8()。 如果 consumed 不为 NULL，则末尾的不完整 UTF-8 字节序列将不被视为错误。 这些字节将不会被解码并且已被解码的字节数将存储在 consumed 中。

PyObject *PyUnicode_AsUTF8String(PyObject *unicode)
返回值：新的引用。 属于 稳定 ABI.
使用 UTF-8 编码 Unicode 对象并将结果作为 Python 字节串对象返回。 错误处理方式为 "strict"。 如果编解码器引发了异常则将返回 NULL。

const char *PyUnicode_AsUTF8AndSize(PyObject *unicode, Py_ssize_t *size)
属于 稳定 ABI 自 3.10 版开始.
返回一个指向 Unicode 对象的 UTF-8 编码格式数据的指针，并将已编码数据的大小（以字节为单位）存储在 size 中。 size 参数可以为 NULL；在此情况下数据的大小将不会被存储。 返回的缓冲区总是会添加一个额外的空字节（不包括在 size 中），无论是否存在任何其他的空码位。

在发生错误的情况下，将返回 NULL 附带设置一个异常并且不会存储 size 值。

这将缓存 Unicode 对象中字符串的 UTF-8 表示形式，并且后续调用将返回指向同一缓存区的指针。 调用方不必负责释放该缓冲区。 缓冲区会在 Unicode 对象被作为垃圾回收时被释放并使指向它的指针失效。

在 3.3 版本加入.

在 3.7 版本发生变更: 返回类型现在是 const char * 而不是 char *。

在 3.10 版本发生变更: 此函数是 受限 API 的组成部分。

const char *PyUnicode_AsUTF8(PyObject *unicode)
类似于 PyUnicode_AsUTF8AndSize()，但不会存储大小值。

在 3.3 版本加入.

在 3.7 版本发生变更: 返回类型现在是 const char * 而不是 char *。

UTF-32 编解码器
以下是 UTF-32 编解码器 API:

PyObject *PyUnicode_DecodeUTF32(const char *str, Py_ssize_t size, const char *errors, int *byteorder)
返回值：新的引用。 属于 稳定 ABI.
从 UTF-32 编码的缓冲区数据解码 size 个字节并返回相应的 Unicode 对象。 errors (如果不为 NULL) 定义了错误处理方式。 默认为 "strict"。

如果 byteorder 不为 NULL，解码器将使用给定的字节序进行解码:

*byteorder == -1: little endian
*byteorder == 0:  native order
*byteorder == 1:  big endian
如果 *byteorder 为零，且输入数据的前四个字节为字节序标记 (BOM)，则解码器将切换为该字节序并且 BOM 将不会被拷贝到结果 Unicode 字符串中。 如果 *byteorder 为 -1 或 1，则字节序标记会被拷贝到输出中。

在完成后，*byteorder 将在输入数据的末尾被设为当前字节序。

如果 byteorder 为 NULL，编解码器将使用本机字节序。

如果编解码器引发了异常则返回 NULL。

PyObject *PyUnicode_DecodeUTF32Stateful(const char *str, Py_ssize_t size, const char *errors, int *byteorder, Py_ssize_t *consumed)
返回值：新的引用。 属于 稳定 ABI.
如果 consumed 为 NULL，则行为类似于 PyUnicode_DecodeUTF32()。 如果 consumed 不为 NULL，则 PyUnicode_DecodeUTF32Stateful() 将不把末尾的不完整 UTF-32 字节序列（如字节数不可被四整除）视为错误。 这些字节将不会被解码并且已被解码的字节数将存储在 consumed 中。

PyObject *PyUnicode_AsUTF32String(PyObject *unicode)
返回值：新的引用。 属于 稳定 ABI.
返回使用 UTF-32 编码格式本机字节序的 Python 字节串。 字节串将总是以 BOM 标记打头。 错误处理方式为 "strict"。 如果编解码器引发了异常则返回 NULL。

UTF-16 编解码器
以下是 UTF-16 编解码器的 API:

PyObject *PyUnicode_DecodeUTF16(const char *str, Py_ssize_t size, const char *errors, int *byteorder)
返回值：新的引用。 属于 稳定 ABI.
从 UTF-16 编码的缓冲区数据解码 size 个字节并返回相应的 Unicode 对象。 errors (如果不为 NULL) 定义了错误处理方式。 默认为 "strict"。

如果 byteorder 不为 NULL，解码器将使用给定的字节序进行解码:

*byteorder == -1: little endian
*byteorder == 0:  native order
*byteorder == 1:  big endian
如果 *byteorder 为零，且输入数据的前两个字节为字节序标记 (BOM)，则解码器将切换为该字节序并且 BOM 将不会被拷贝到结果 Unicode 字符串中。 如果 *byteorder 为 -1 或 1，则字节序标记会被拷贝到输出中 (它将是一个 \ufeff 或 \ufffe 字符)。

在完成后，*byteorder 将在输入数据的末尾被设为当前字节序。

如果 byteorder 为 NULL，编解码器将使用本机字节序。

如果编解码器引发了异常则返回 NULL。

PyObject *PyUnicode_DecodeUTF16Stateful(const char *str, Py_ssize_t size, const char *errors, int *byteorder, Py_ssize_t *consumed)
返回值：新的引用。 属于 稳定 ABI.
如果 consumed 为 NULL，则行为类似于 PyUnicode_DecodeUTF16()。 如果 consumed 不为 NULL，则 PyUnicode_DecodeUTF16Stateful() 将不把末尾的不完整 UTF-16 字节序列（如为奇数个字节或为分开的替代对）视为错误。 这些字节将不会被解码并且已被解码的字节数将存储在 consumed 中。

PyObject *PyUnicode_AsUTF16String(PyObject *unicode)
返回值：新的引用。 属于 稳定 ABI.
返回使用 UTF-16 编码格式本机字节序的 Python 字节串。 字节串将总是以 BOM 标记打头。 错误处理方式为 "strict"。 如果编解码器引发了异常则返回 NULL。

UTF-7 编解码器
以下是 UTF-7 编解码器 API:

PyObject *PyUnicode_DecodeUTF7(const char *str, Py_ssize_t size, const char *errors)
返回值：新的引用。 属于 稳定 ABI.
通过解码 UTF-7 编码的字节串 str 的 size 个字节创建一个 Unicode 对象。 如果编解码器引发了异常则返回 NULL。

PyObject *PyUnicode_DecodeUTF7Stateful(const char *str, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)
返回值：新的引用。 属于 稳定 ABI.
如果 consumed 为 NULL，则行为类似于 PyUnicode_DecodeUTF7()。 如果 consumed 不为 NULL，则末尾的不完整 UTF-7 base-64 部分将不被视为错误。 这些字节将不会被解码并且已被解码的字节数将存储在 consumed 中。

Unicode-Escape 编解码器
以下是 "Unicode Escape" 编解码器的 API:

PyObject *PyUnicode_DecodeUnicodeEscape(const char *str, Py_ssize_t size, const char *errors)
返回值：新的引用。 属于 稳定 ABI.
通过解码 Unicode-Escape 编码的字节串 str 的 size 个字节创建一个 Unicode 对象。 如果编解码器引发了异常则返回 NULL。

PyObject *PyUnicode_AsUnicodeEscapeString(PyObject *unicode)
返回值：新的引用。 属于 稳定 ABI.
使用 Unicode-Escape 编码 Unicode 对象并将结果作为字节串对象返回。 错误处理方式为 "strict"。 如果编解码器引发了异常则将返回 NULL。

Raw-Unicode-Escape 编解码器
以下是 "Raw Unicode Escape" 编解码器的 API:

PyObject *PyUnicode_DecodeRawUnicodeEscape(const char *str, Py_ssize_t size, const char *errors)
返回值：新的引用。 属于 稳定 ABI.
通过解码 Raw-Unicode-Escape 编码的字节串 str 的 size 个字节创建一个 Unicode 对象。 如果编解码器引发了异常则返回 NULL。

PyObject *PyUnicode_AsRawUnicodeEscapeString(PyObject *unicode)
返回值：新的引用。 属于 稳定 ABI.
使用 Raw-Unicode-Escape 编码 Unicode 对象并将结果作为字节串对象返回。 错误处理方式为 "strict"。 如果编解码器引发了异常则将返回 NULL。

Latin-1 编解码器
以下是 Latin-1 编解码器的 API: Latin-1 对应于前 256 个 Unicode 码位且编码器在编码期间只接受这些码位。

PyObject *PyUnicode_DecodeLatin1(const char *str, Py_ssize_t size, const char *errors)
返回值：新的引用。 属于 稳定 ABI.
通过解码 Latin-1 编码的字节串 str 的 size 个字节创建一个 Unicode 对象。 如果编解码器引发了异常则返回 NULL。

PyObject *PyUnicode_AsLatin1String(PyObject *unicode)
返回值：新的引用。 属于 稳定 ABI.
使用 Latin-1 编码 Unicode 对象并将结果作为 Python 字节串对象返回。 错误处理方式为 "strict"。 如果编解码器引发了异常则将返回 NULL。

ASCII 编解码器
以下是 ASCII 编解码器的 API。 只接受 7 位 ASCII 数据。 任何其他编码的数据都将导致错误。

PyObject *PyUnicode_DecodeASCII(const char *str, Py_ssize_t size, const char *errors)
返回值：新的引用。 属于 稳定 ABI.
通过解码 ASCII 编码的字节串 str 的 size 个字节创建一个 Unicode 对象。 如果编解码器引发了异常则返回 NULL。

PyObject *PyUnicode_AsASCIIString(PyObject *unicode)
返回值：新的引用。 属于 稳定 ABI.
使用 ASCII 编码 Unicode 对象并将结果作为 Python 字节串对象返回。 错误处理方式为 "strict"。 如果编解码器引发了异常则将返回 NULL。

字符映射编解码器
此编解码器的特殊之处在于它可被用来实现许多不同的编解码器（而且这实际上就是包括在 encodings 包中的大部分标准编解码器的实现方式）。 此编解码器使用映射来编码和解码字符。 所提供的映射对象必须支持 __getitem__() 映射接口；字典和序列均可胜任。

以下是映射编解码器的 API:

PyObject *PyUnicode_DecodeCharmap(const char *str, Py_ssize_t length, PyObject *mapping, const char *errors)
返回值：新的引用。 属于 稳定 ABI.
通过使用给定的 mapping 对象解码已编码字节串 str 的 size 个字节创建一个 Unicode 对象。 如果编解码器引发了异常则返回 NULL。

如果 mapping 为 NULL，则将应用 Latin-1 编码格式。 否则 mapping 必须为字节码位值（0 至 255 范围内的整数）到 Unicode 字符串的映射、整数（将被解读为 Unicode 码位）或 None。 未映射的数据字节 -- 这样的数据将导致 LookupError，以及被映射到 None 的数据，0xFFFE 或 '\ufffe'，将被视为未定义的映射并导致报错。

PyObject *PyUnicode_AsCharmapString(PyObject *unicode, PyObject *mapping)
返回值：新的引用。 属于 稳定 ABI.
使用给定的 mapping 对象编码 Unicode 对象并将结果作为字节串对象返回。 错误处理方式为 "strict"。 如果编解码器引发了异常则将返回 NULL。

mapping 对象必须将整数 Unicode 码位映射到字节串对象、0 至 255 范围内的整数或 None。 未映射的字符码位（将导致 LookupError 的数据）以及映射到 None 的数据将被视为“未定义的映射”并导致报错。

以下特殊的编解码器 API 会将 Unicode 映射至 Unicode。

PyObject *PyUnicode_Translate(PyObject *unicode, PyObject *table, const char *errors)
返回值：新的引用。 属于 稳定 ABI.
通过应用字符映射表来转写字符串并返回结果 Unicode 对象。 如果编解码器引发了异常则返回 NULL。

字符映射表必须将整数 Unicode 码位映射到整数 Unicode 码位或 None (这将删除相应的字符)。

映射表只需提供 __getitem__() 接口；字典和序列均可胜任。 未映射的字符码位（将导致 LookupError 的数据）将保持不变并被原样拷贝。

errors 具有用于编解码器的通常含义。 它可以为 NULL 表示使用默认的错误处理方式。

Windows 中的 MBCS 编解码器
以下是 MBCS 编解码器的 API。 目前它们仅在 Windows 中可用并使用 Win32 MBCS 转换器来实现转换。 请注意 MBCS（或 DBCS）是一类编码格式，而非只有一个。 目标编码格式是由运行编解码器的机器上的用户设置定义的。

PyObject *PyUnicode_DecodeMBCS(const char *str, Py_ssize_t size, const char *errors)
返回值：新的引用。 属于 稳定 ABI on Windows 自 3.7 版开始.
通过解码 MBCS 编码的字节串 str 的 size 个字节创建一个 Unicode 对象。 如果编解码器引发了异常则返回 NULL。

PyObject *PyUnicode_DecodeMBCSStateful(const char *str, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)
返回值：新的引用。 属于 稳定 ABI on Windows 自 3.7 版开始.
如果 consumed 为 NULL，则行为类似于 PyUnicode_DecodeMBCS()。 如果 consumed 不为 NULL，则 PyUnicode_DecodeMBCSStateful() 将不会解码末尾的不完整字节并且已被解码的字节数将存储在 consumed 中。

PyObject *PyUnicode_AsMBCSString(PyObject *unicode)
返回值：新的引用。 属于 稳定 ABI on Windows 自 3.7 版开始.
使用 MBCS 编码 Unicode 对象并将结果作为 Python 字节串对象返回。 错误处理方式为 "strict"。 如果编解码器引发了异常则将返回 NULL。

PyObject *PyUnicode_EncodeCodePage(int code_page, PyObject *unicode, const char *errors)
返回值：新的引用。 属于 稳定 ABI on Windows 自 3.7 版开始.
使用指定的代码页编码 Unicode 对象并返回一个 Python 字节串对象。 如果编解码器引发了异常则返回 NULL。 使用 CP_ACP 代码页来获取 MBCS 解码器。

在 3.3 版本加入.