Unicode 对象和编解码器

Unicode 对象

Unicode 类型

这些是用于 Python 中 Unicode 实现的基本 Unicode 对象类型：

type Py_UNICODE

此类型表示 Python 内部用作保存 Unicode 序数基础的存储类型。 Python 的默认构建对 Py_UNICODE 使用 16 位类型，并在内部将 Unicode 值存储为 UCS2。也可以构建 Python 的 UCS4 版本（最新的 Linux 发行版带有 Python 的 UCS4 版本）。然后这些构建使用 32 位类型的 Py_UNICODE 并在内部将 Unicode 数据存储为 UCS4。在 wchar_t 可用且与所选 Python Unicode 构建变体兼容的平台上，Py_UNICODE 是 wchar_t 的 typedef 别名，以增强本机平台兼容性。在所有其他平台上，Py_UNICODE 是 unsigned short (UCS2) 或 unsigned long (UCS4) 的 typedef 别名。

请注意，UCS2 和 UCS4 Python 构建不是二进制兼容的。在编写扩展或接口时请记住这一点。

type PyUnicodeObject

PyObject 的这个子类型表示 Python Unicode 对象。

PyTypeObject PyUnicode_Type

PyTypeObject 的这个实例表示 Python Unicode 类型。它以 unicode 和 types.UnicodeType 的形式暴露给 Python 代码。

以下 API 是真正的 C 宏，可用于进行快速检查和访问 Unicode 对象的内部只读数据：

int PyUnicode_Check(PyObject *o): 如果对象 o 是 Unicode 对象或 Unicode 子类型的实例，则返回 true。

在 2.2 版更改：允许接受子类型。

int PyUnicode_CheckExact(PyObject *o): 如果对象 o 是 Unicode 对象，但不是子类型的实例，则返回 true。

2.2 版中的新功能。

Py_ssize_t PyUnicode_GET_SIZE(PyObject *o): 返回对象的大小。 o 必须是 PyUnicodeObject（未选中）。

2.5 版更改：此函数返回 int 类型。这可能需要更改您的代码才能正确支持 64 位系统。

Py_ssize_t PyUnicode_GET_DATA_SIZE(PyObject *o): 以字节为单位返回对象内部缓冲区的大小。 o 必须是 PyUnicodeObject（未选中）。

2.5 版更改：此函数返回 int 类型。这可能需要更改您的代码才能正确支持 64 位系统。

Py_UNICODE *PyUnicode_AS_UNICODE(PyObject *o)

返回指向对象内部 Py_UNICODE 缓冲区的指针。 o 必须是 PyUnicodeObject（未选中）。

const char *PyUnicode_AS_DATA(PyObject *o)

返回一个指向对象内部缓冲区的指针。 o 必须是 PyUnicodeObject（未选中）。

int PyUnicode_ClearFreeList(): 清除空闲列表。返回已释放项目的总数。

2.6 版中的新功能。

Unicode 字符属性

Unicode 提供了许多不同的字符属性。最常需要的可通过这些宏获得，这些宏根据 Python 配置映射到 C 函数。

int Py_UNICODE_ISSPACE(Py_UNICODE ch)

根据 ch 是否为空白字符，返回 1 或 0。

int Py_UNICODE_ISLOWER(Py_UNICODE ch)

根据 ch 是否为小写字符，返回 1 或 0。

int Py_UNICODE_ISUPPER(Py_UNICODE ch)

根据 ch 是否为大写字符，返回 1 或 0。

int Py_UNICODE_ISTITLE(Py_UNICODE ch)

根据 ch 是否是标题字符，返回 1 或 0。

int Py_UNICODE_ISLINEBREAK(Py_UNICODE ch)

根据 ch 是否为换行符，返回 1 或 0。

int Py_UNICODE_ISDECIMAL(Py_UNICODE ch)

根据 ch 是否为十进制字符，返回 1 或 0。

int Py_UNICODE_ISDIGIT(Py_UNICODE ch)

根据 ch 是否为数字字符，返回 1 或 0。

int Py_UNICODE_ISNUMERIC(Py_UNICODE ch)

根据 ch 是否为数字字符，返回 1 或 0。

int Py_UNICODE_ISALPHA(Py_UNICODE ch)

根据 ch 是否为字母字符，返回 1 或 0。

int Py_UNICODE_ISALNUM(Py_UNICODE ch)

根据 ch 是否为字母数字字符，返回 1 或 0。

这些 API 可用于快速直接字符转换：

Py_UNICODE Py_UNICODE_TOLOWER(Py_UNICODE ch)

返回转换为小写的字符 ch。

Py_UNICODE Py_UNICODE_TOUPPER(Py_UNICODE ch)

返回转换为大写的字符 ch。

Py_UNICODE Py_UNICODE_TOTITLE(Py_UNICODE ch)

返回转换为标题大小写的字符 ch。

int Py_UNICODE_TODECIMAL(Py_UNICODE ch)

返回转换为十进制正整数的字符 ch。如果这是不可能的，则返回 -1。此宏不会引发异常。

int Py_UNICODE_TODIGIT(Py_UNICODE ch)

返回字符 ch 转换为一位整数。如果这是不可能的，则返回 -1。此宏不会引发异常。

double Py_UNICODE_TONUMERIC(Py_UNICODE ch)

返回转换为双精度的字符 ch。如果这是不可能的，则返回 -1.0。此宏不会引发异常。

普通 Py_UNICODE

要创建 Unicode 对象并访问它们的基本序列属性，请使用以下 API：

PyObject *PyUnicode_FromUnicode(const Py_UNICODE *u, Py_ssize_t size): 从给定大小的 Py_UNICODE 缓冲区 u 创建一个 Unicode 对象。 u 可能是 NULL 这会导致内容未定义。用户有责任填写所需的数据。缓冲区被复制到新对象中。如果缓冲区不是 NULL，则返回值可能是共享对象。因此，仅当 u 为 NULL 时，才允许修改生成的 Unicode 对象。

2.5 版更改：此函数使用 int 类型作为大小。这可能需要更改您的代码才能正确支持 64 位系统。

PyObject *PyUnicode_FromStringAndSize(const char *u, Py_ssize_t size): 从字符缓冲区 u 创建一个 Unicode 对象。字节将被解释为 UTF-8 编码。 u 也可能是 NULL 这会导致内容未定义。用户有责任填写所需的数据。缓冲区被复制到新对象中。如果缓冲区不是 NULL，则返回值可能是共享对象。因此，仅当 u 为 NULL 时，才允许修改生成的 Unicode 对象。

2.6 版中的新功能。

PyObject *PyUnicode_FromString(const char *u): 从 UTF-8 编码的空终止字符缓冲区 u 创建一个 Unicode 对象。

2.6 版中的新功能。

PyObject *PyUnicode_FromFormat(const char *format, ...)

取一个 C printf() 样式的 format 字符串和可变数量的参数，计算生成的 Python unicode 字符串的大小并返回一个字符串，其中包含格式化的值。变量参数必须是 C 类型，并且必须与 format 字符串中的格式字符完全对应。允许使用以下格式字符：

格式字符	类型	评论
`%%`	不适用	The literal % character.
`%c`	整数	单个字符，表示为 C int。
`%d`	整数	完全等同于 `printf("%d")`。
`%u`	无符号整数	完全等同于 `printf("%u")`。
`%ld`	长	完全等同于 `printf("%ld")`。
`%lu`	无符号长	完全等同于 `printf("%lu")`。
`%zd`	py_ssize_t	完全等同于 `printf("%zd")`。
`%zu`	尺寸_t	完全等同于 `printf("%zu")`。
`%i`	整数	完全等同于 `printf("%i")`。
`%x`	整数	完全等同于 `printf("%x")`。
`%s`	字符*	以空字符结尾的 C 字符数组。
`%p`	空白*	C 指针的十六进制表示。大部分等同于 `printf("%p")`，除了它保证以文字 `0x` 开头，而不管平台的 `printf` 产生什么。
`%U`	对象*	一个 Unicode 对象。
`%V`	PyObject, 字符	一个 unicode 对象（可能是 NULL）和一个以空字符结尾的 C 字符数组作为第二个参数（如果第一个参数是 NULL，将使用它）。
`%S`	对象*	调用 `PyObject_Unicode()` 的结果。
`%R`	对象*	调用 `PyObject_Repr()` 的结果。

无法识别的格式字符会导致格式字符串的所有其余部分按原样复制到结果字符串，并丢弃任何额外的参数。

2.6 版中的新功能。

PyObject *PyUnicode_FromFormatV(const char *format, va_list vargs): 与 PyUnicode_FromFormat() 相同，只是它只需要两个参数。

2.6 版中的新功能。

Py_UNICODE *PyUnicode_AsUnicode(PyObject *unicode)

返回指向 Unicode 对象内部 Py_UNICODE 缓冲区的只读指针，如果 unicode 不是 Unicode 对象，则返回 NULL。请注意，生成的 Py_UNICODE* 字符串可能包含嵌入的空字符，这会导致该字符串在大多数 C 函数中使用时被截断。

Py_ssize_t PyUnicode_GetSize(PyObject *unicode): 返回 Unicode 对象的长度。

2.5 版更改：此函数返回 int 类型。这可能需要更改您的代码才能正确支持 64 位系统。

PyObject *PyUnicode_FromEncodedObject(PyObject *obj, const char *encoding, const char *errors)

将编码对象 obj 强制转换为 Unicode 对象并返回引用计数递增的引用。

字符串和其他字符缓冲区兼容对象根据给定的编码并使用错误定义的错误处理进行解码。两者都可以是 NULL 以使接口使用默认值（有关详细信息，请参阅下一节）。

所有其他对象，包括 Unicode 对象，都会导致设置 TypeError。

如果出现错误，API 将返回 NULL。调用者负责定义返回的对象。

PyObject *PyUnicode_FromObject(PyObject *obj)

PyUnicode_FromEncodedObject(obj, NULL, "strict") 的快捷方式，在需要强制转换为 Unicode 时在整个解释器中使用。

如果平台支持 wchar_t 并提供头文件 wchar.h，Python 可以使用以下函数直接与该类型接口。如果 Python 自己的 Py_UNICODE 类型与系统的 wchar_t 相同，则支持得到优化。

wchar_t 支持

wchar_t 对支持它的平台的支持：

PyObject *PyUnicode_FromWideChar(const wchar_t *w, Py_ssize_t size): 从给定大小的 wchar_t 缓冲区 w 创建一个 Unicode 对象。失败时返回 NULL。

2.5 版更改：此函数使用 int 类型作为大小。这可能需要更改您的代码才能正确支持 64 位系统。

Py_ssize_t PyUnicode_AsWideChar(PyUnicodeObject *unicode, wchar_t *w, Py_ssize_t size): 将 Unicode 对象内容复制到 wchar_t 缓冲区 w。最多复制 size wchar_t 个字符（不包括可能的尾随 0 终止字符）。如果出错，返回复制的 wchar_t 个字符或 -1 个字符的数量。请注意，生成的 wchar_t 字符串可能会或可能不会以 0 结尾。如果应用程序需要，调用者有责任确保 wchar_t 字符串以 0 结尾。另请注意，wchar_t* 字符串可能包含空字符，这会导致该字符串在与大多数 C 函数一起使用时被截断。

2.5 版更改：此函数返回 int 类型并使用 int 类型作为 size。这可能需要更改您的代码才能正确支持 64 位系统。

内置编解码器

Python 提供了一组用 C 编写的内置编解码器以提高速度。所有这些编解码器都可以通过以下功能直接使用。

以下许多 API 采用编码和错误两个参数，它们与内置的 unicode() Unicode 对象构造函数具有相同的语义。

将 encoding 设置为 NULL 会导致使用默认编码，即 ASCII。文件系统调用应该使用 Py_FileSystemDefaultEncoding 作为文件名的编码。这个变量应该被视为只读：在某些系统上，它将是一个指向静态字符串的指针，在其他系统上，它会在运行时发生变化（例如当应用程序调用 setlocale 时）。

错误处理由错误设置，错误也可以设置为 NULL 意味着使用为编解码器定义的默认处理。所有内置编解码器的默认错误处理都是“严格的”（ValueError 被提升）。

编解码器都使用类似的接口。为简单起见，仅记录了与以下通用的偏差。

通用编解码器

这些是通用编解码器 API：

PyObject *PyUnicode_Decode(const char *s, Py_ssize_t size, const char *encoding, const char *errors): 通过解码编码字符串 s 的 size 字节来创建一个 Unicode 对象。 encoding和errors与unicode()内置函数中的同名参数含义相同。使用 Python 编解码器注册表查找要使用的编解码器。如果编解码器引发异常，则返回 NULL。

2.5 版更改：此函数使用 int 类型作为大小。这可能需要更改您的代码才能正确支持 64 位系统。

PyObject *PyUnicode_Encode(const Py_UNICODE *s, Py_ssize_t size, const char *encoding, const char *errors): 对给定 size 的 Py_UNICODE 缓冲区 s 进行编码并返回 Python 字符串对象。 encoding和errors与Unicode encode()方法中的同名参数含义相同。使用 Python 编解码器注册表查找要使用的编解码器。如果编解码器引发异常，则返回 NULL。

2.5 版更改：此函数使用 int 类型作为大小。这可能需要更改您的代码才能正确支持 64 位系统。

PyObject *PyUnicode_AsEncodedString(PyObject *unicode, const char *encoding, const char *errors)

编码一个 Unicode 对象并将结果作为 Python 字符串对象返回。 encoding和errors与Unicode encode()方法中的同名参数含义相同。使用 Python 编解码器注册表查找要使用的编解码器。如果编解码器引发异常，则返回 NULL。

UTF-8 编解码器

这些是 UTF-8 编解码器 API：

PyObject *PyUnicode_DecodeUTF8(const char *s, Py_ssize_t size, const char *errors): 通过解码 UTF-8 编码字符串 s 的 size 字节来创建一个 Unicode 对象。如果编解码器引发异常，则返回 NULL。

2.5 版更改：此函数使用 int 类型作为大小。这可能需要更改您的代码才能正确支持 64 位系统。

PyObject *PyUnicode_DecodeUTF8Stateful(const char *s, Py_ssize_t size, const char *errors, Py_ssize_t *consumed): 如果 consumed 是 NULL，则行为类似于 PyUnicode_DecodeUTF8()。如果 consumed 不是 NULL，尾随不完整的 UTF-8 字节序列将不会被视为错误。这些字节不会被解码，已经解码的字节数将存储在 consumed 中。

2.4 版中的新功能。

2.5 版更改：此函数使用 int 类型作为大小。这可能需要更改您的代码才能正确支持 64 位系统。

PyObject *PyUnicode_EncodeUTF8(const Py_UNICODE *s, Py_ssize_t size, const char *errors): 使用 UTF-8 对给定 size 的 Py_UNICODE 缓冲区 s 进行编码，并返回 Python 字符串对象。如果编解码器引发异常，则返回 NULL。

2.5 版更改：此函数使用 int 类型作为大小。这可能需要更改您的代码才能正确支持 64 位系统。

PyObject *PyUnicode_AsUTF8String(PyObject *unicode)

使用 UTF-8 对 Unicode 对象进行编码，并将结果作为 Python 字符串对象返回。错误处理是“严格的”。如果编解码器引发异常，则返回 NULL。

UTF-32 编解码器

这些是 UTF-32 编解码器 API：

PyObject *PyUnicode_DecodeUTF32(const char *s, Py_ssize_t size, const char *errors, int *byteorder)

从 UTF-32 编码的缓冲区字符串中解码 size 字节并返回相应的 Unicode 对象。 errors（如果非NULL）定义错误处理。它默认为“严格”。

如果 byteorder 是非 NULL，解码器开始使用给定的字节顺序解码：

*byteorder == -1: little endian
*byteorder == 0:  native order
*byteorder == 1:  big endian

如果 *byteorder 为零，并且输入数据的前四个字节是字节顺序标记 (BOM)，则解码器切换到此字节顺序，并且不会将 BOM 复制到生成的 Unicode 字符串中。如果 *byteorder 是 -1 或 1，任何字节顺序标记都会被复制到输出。

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

在 BMP 之外的窄构建代码点将被解码为代理对。

如果 byteorder 是 NULL，则编解码器以原生顺序模式启动。

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

2.6 版中的新功能。

PyObject *PyUnicode_DecodeUTF32Stateful(const char *s, Py_ssize_t size, const char *errors, int *byteorder, Py_ssize_t *consumed): 如果 consumed 是 NULL，则行为类似于 PyUnicode_DecodeUTF32()。如果 consumed 不是 NULL，则 PyUnicode_DecodeUTF32Stateful() 不会将尾随不完整的 UTF-32 字节序列（例如不能被四整除的字节数）视为一个错误。这些字节不会被解码，已经解码的字节数将存储在 consumed 中。

2.6 版中的新功能。

PyObject *PyUnicode_EncodeUTF32(const Py_UNICODE *s, Py_ssize_t size, const char *errors, int byteorder)

返回一个 Python 字节对象，其中包含 s 中 Unicode 数据的 UTF-32 编码值。输出按照以下字节顺序写入：

byteorder == -1: little endian
byteorder == 0:  native byte order (writes a BOM mark)
byteorder == 1:  big endian

如果 byteorder 为 0，则输出字符串将始终以 Unicode BOM 标记 (U+FEFF) 开头。在其他两种模式中，没有预先添加 BOM 标记。

如果未定义 Py_UNICODE_WIDE，则代理对将作为单个代码点输出。

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

2.6 版中的新功能。

PyObject *PyUnicode_AsUTF32String(PyObject *unicode): 以本机字节顺序使用 UTF-32 编码返回 Python 字符串。该字符串始终以 BOM 标记开头。错误处理是“严格的”。如果编解码器引发异常，则返回 NULL。

2.6 版中的新功能。

UTF-16 编解码器

这些是 UTF-16 编解码器 API：

PyObject *PyUnicode_DecodeUTF16(const char *s, Py_ssize_t size, const char *errors, int *byteorder)

从 UTF-16 编码的缓冲区字符串中解码 size 字节并返回相应的 Unicode 对象。 errors（如果非NULL）定义错误处理。它默认为“严格”。

如果 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。

2.5 版更改：此函数使用 int 类型作为大小。这可能需要更改您的代码才能正确支持 64 位系统。

PyObject *PyUnicode_DecodeUTF16Stateful(const char *s, Py_ssize_t size, const char *errors, int *byteorder, Py_ssize_t *consumed): 如果 consumed 是 NULL，则行为类似于 PyUnicode_DecodeUTF16()。如果 consumed 不是 NULL，PyUnicode_DecodeUTF16Stateful() 将不会处理尾随不完整的 UTF-16 字节序列（例如奇数字节或拆分代理对) 作为错误。这些字节不会被解码，已经解码的字节数将存储在 consumed 中。

2.4 版中的新功能。

2.5 版更改：此函数使用大小的 int 类型和消耗的 int * 类型。这可能需要更改您的代码才能正确支持 64 位系统。

PyObject *PyUnicode_EncodeUTF16(const Py_UNICODE *s, Py_ssize_t size, const char *errors, int byteorder)

返回一个 Python 字符串对象，其中包含 s 中 Unicode 数据的 UTF-16 编码值。输出按照以下字节顺序写入：

byteorder == -1: little endian
byteorder == 0:  native byte order (writes a BOM mark)
byteorder == 1:  big endian

如果 byteorder 为 0，则输出字符串将始终以 Unicode BOM 标记 (U+FEFF) 开头。在其他两种模式中，没有预先添加 BOM 标记。

如果定义了 Py_UNICODE_WIDE，则单个 Py_UNICODE 值可能会表示为代理对。如果未定义，则每个 Py_UNICODE 值都被解释为 UCS-2 字符。

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

2.5 版更改：此函数使用 int 类型作为大小。这可能需要更改您的代码才能正确支持 64 位系统。

PyObject *PyUnicode_AsUTF16String(PyObject *unicode)

以本机字节顺序使用 UTF-16 编码返回 Python 字符串。该字符串始终以 BOM 标记开头。错误处理是“严格的”。如果编解码器引发异常，则返回 NULL。

UTF-7 编解码器

这些是 UTF-7 编解码器 API：

PyObject *PyUnicode_DecodeUTF7(const char *s, Py_ssize_t size, const char *errors)

通过解码 UTF-7 编码字符串 s 的 size 字节来创建一个 Unicode 对象。如果编解码器引发异常，则返回 NULL。

PyObject *PyUnicode_DecodeUTF7Stateful(const char *s, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)

如果 consumed 是 NULL，则行为类似于 PyUnicode_DecodeUTF7()。如果 consumed 不是 NULL，尾随不完整的 UTF-7 base-64 部分将不会被视为错误。这些字节不会被解码，已经解码的字节数将存储在 consumed 中。

PyObject *PyUnicode_EncodeUTF7(const Py_UNICODE *s, Py_ssize_t size, int base64SetO, int base64WhiteSpace, const char *errors)

使用 UTF-7 编码给定大小的 Py_UNICODE 缓冲区并返回 Python 字节对象。如果编解码器引发异常，则返回 NULL。

如果 base64SetO 非零，“Set O”（没有其他特殊含义的标点符号）将以 base-64 编码。如果 base64WhiteSpace 非零，空格将被编码为 base-64。对于 Python“utf-7”编解码器，两者都设置为零。

Unicode 转义编解码器

这些是“Unicode Escape”编解码器 API：

PyObject *PyUnicode_DecodeUnicodeEscape(const char *s, Py_ssize_t size, const char *errors): 通过解码 Unicode-Escape 编码字符串 s 的 size 字节来创建 Unicode 对象。如果编解码器引发异常，则返回 NULL。

2.5 版更改：此函数使用 int 类型作为大小。这可能需要更改您的代码才能正确支持 64 位系统。

PyObject *PyUnicode_EncodeUnicodeEscape(const Py_UNICODE *s, Py_ssize_t size): 使用 Unicode-Escape 对给定 size 的 Py_UNICODE 缓冲区进行编码，并返回 Python 字符串对象。如果编解码器引发异常，则返回 NULL。

2.5 版更改：此函数使用 int 类型作为大小。这可能需要更改您的代码才能正确支持 64 位系统。

PyObject *PyUnicode_AsUnicodeEscapeString(PyObject *unicode)

使用 Unicode-Escape 对 Unicode 对象进行编码，并将结果作为 Python 字符串对象返回。错误处理是“严格的”。如果编解码器引发异常，则返回 NULL。

原始 Unicode 转义编解码器

这些是“原始 Unicode 转义”编解码器 API：

PyObject *PyUnicode_DecodeRawUnicodeEscape(const char *s, Py_ssize_t size, const char *errors): 通过解码 Raw-Unicode-Escape 编码字符串 s 的 size 字节来创建 Unicode 对象。如果编解码器引发异常，则返回 NULL。

2.5 版更改：此函数使用 int 类型作为大小。这可能需要更改您的代码才能正确支持 64 位系统。

PyObject *PyUnicode_EncodeRawUnicodeEscape(const Py_UNICODE *s, Py_ssize_t size, const char *errors): 使用 Raw-Unicode-Escape 对给定 size 的 Py_UNICODE 缓冲区进行编码，并返回 Python 字符串对象。如果编解码器引发异常，则返回 NULL。

2.5 版更改：此函数使用 int 类型作为大小。这可能需要更改您的代码才能正确支持 64 位系统。

PyObject *PyUnicode_AsRawUnicodeEscapeString(PyObject *unicode)

使用 Raw-Unicode-Escape 对 Unicode 对象进行编码，并将结果作为 Python 字符串对象返回。错误处理是“严格的”。如果编解码器引发异常，则返回 NULL。

拉丁 1 编解码器

这些是 Latin-1 编解码器 API：Latin-1 对应于前 256 个 Unicode 序数，编解码器在编码期间只接受这些。

PyObject *PyUnicode_DecodeLatin1(const char *s, Py_ssize_t size, const char *errors): 通过解码 Latin-1 编码字符串 s 的 size 字节来创建 Unicode 对象。如果编解码器引发异常，则返回 NULL。

2.5 版更改：此函数使用 int 类型作为大小。这可能需要更改您的代码才能正确支持 64 位系统。

PyObject *PyUnicode_EncodeLatin1(const Py_UNICODE *s, Py_ssize_t size, const char *errors): 使用 Latin-1 对给定 size 的 Py_UNICODE 缓冲区进行编码，并返回 Python 字符串对象。如果编解码器引发异常，则返回 NULL。

2.5 版更改：此函数使用 int 类型作为大小。这可能需要更改您的代码才能正确支持 64 位系统。

PyObject *PyUnicode_AsLatin1String(PyObject *unicode)

使用 Latin-1 对 Unicode 对象进行编码，并将结果作为 Python 字符串对象返回。错误处理是“严格的”。如果编解码器引发异常，则返回 NULL。

ASCII 编解码器

这些是 ASCII 编解码器 API。仅接受 7 位 ASCII 数据。所有其他代码都会产生错误。

PyObject *PyUnicode_DecodeASCII(const char *s, Py_ssize_t size, const char *errors): 通过解码 ASCII 编码字符串 s 的 size 字节来创建一个 Unicode 对象。如果编解码器引发异常，则返回 NULL。

2.5 版更改：此函数使用 int 类型作为大小。这可能需要更改您的代码才能正确支持 64 位系统。

PyObject *PyUnicode_EncodeASCII(const Py_UNICODE *s, Py_ssize_t size, const char *errors): 使用 ASCII 编码给定 size 的 Py_UNICODE 缓冲区并返回 Python 字符串对象。如果编解码器引发异常，则返回 NULL。

2.5 版更改：此函数使用 int 类型作为大小。这可能需要更改您的代码才能正确支持 64 位系统。

PyObject *PyUnicode_AsASCIIString(PyObject *unicode)

使用 ASCII 编码 Unicode 对象并将结果作为 Python 字符串对象返回。错误处理是“严格的”。如果编解码器引发异常，则返回 NULL。

字符映射编解码器

这个编解码器的特殊之处在于它可以用来实现许多不同的编解码器（实际上这是为了获得 encodings 包中包含的大多数标准编解码器所做的）。编解码器使用映射来编码和解码字符。

解码映射必须将单个字符串字符映射到单个 Unicode 字符、整数（然后被解释为 Unicode 序数）或 None（意思是“未定义的映射”并导致错误）。

编码映射必须将单个 Unicode 字符映射到单个字符串字符、整数（然后被解释为 Latin-1 序数）或 None（意思是“未定义的映射”并导致错误）。

提供的映射对象必须只支持 __getitem__ 映射接口。

如果字符查找失败并出现 LookupError，则该字符将按原样复制，这意味着其序数值将被解释为 Unicode 或 Latin-1 序数。因此，映射只需要包含将字符映射到不同代码点的那些映射。

这些是映射编解码器 API：

PyObject *PyUnicode_DecodeCharmap(const char *s, Py_ssize_t size, PyObject *mapping, const char *errors): 通过使用给定的 mapping 对象解码编码字符串 s 的 size 字节来创建 Unicode 对象。如果编解码器引发异常，则返回 NULL。如果 mapping 是 NULL 将进行 latin-1 解码。否则它可以是字典映射字节或 unicode 字符串，它被视为查找表。大于字符串长度和 U+FFFE“字符”的字节值被视为“未定义映射”。

在 2.4 版更改：允许 unicode 字符串作为映射参数。

2.5 版更改：此函数使用 int 类型作为大小。这可能需要更改您的代码才能正确支持 64 位系统。

PyObject *PyUnicode_EncodeCharmap(const Py_UNICODE *s, Py_ssize_t size, PyObject *mapping, const char *errors): 使用给定的 mapping 对象对给定的 size 的 Py_UNICODE 缓冲区进行编码，并返回一个 Python 字符串对象。如果编解码器引发异常，则返回 NULL。

2.5 版更改：此函数使用 int 类型作为大小。这可能需要更改您的代码才能正确支持 64 位系统。

PyObject *PyUnicode_AsCharmapString(PyObject *unicode, PyObject *mapping)

使用给定的 mapping 对象对 Unicode 对象进行编码，并将结果作为 Python 字符串对象返回。错误处理是“严格的”。如果编解码器引发异常，则返回 NULL。

以下编解码器 API 的特殊之处在于将 Unicode 映射到 Unicode。

PyObject *PyUnicode_TranslateCharmap(const Py_UNICODE *s, Py_ssize_t size, PyObject *table, const char *errors)

通过向其应用字符映射 table 来转换给定 size 的 Py_UNICODE 缓冲区并返回生成的 Unicode 对象。当编解码器引发异常时返回 NULL。

mapping 表必须将 Unicode 序数整数映射到 Unicode 序数整数或 None（导致字符删除）。

映射表只需提供__getitem__()接口；字典和序列运行良好。未映射的字符序数（导致 LookupError）保持不变并按原样复制。

2.5 版更改：此函数使用 int 类型作为大小。这可能需要更改您的代码才能正确支持 64 位系统。

适用于 Windows 的 MBCS 编解码器

这些是 MBCS 编解码器 API。它们目前仅在 Windows 上可用并使用 Win32 MBCS 转换器来实现转换。请注意，MBCS（或 DBCS）是一类编码，而不仅仅是一种。目标编码由运行编解码器的机器上的用户设置定义。

PyObject *PyUnicode_DecodeMBCS(const char *s, Py_ssize_t size, const char *errors): 通过解码 MBCS 编码字符串 s 的 size 字节来创建 Unicode 对象。如果编解码器引发异常，则返回 NULL。

2.5 版更改：此函数使用 int 类型作为大小。这可能需要更改您的代码才能正确支持 64 位系统。

PyObject *PyUnicode_DecodeMBCSStateful(const char *s, int size, const char *errors, int *consumed): 如果 consumed 是 NULL，则行为类似于 PyUnicode_DecodeMBCS()。如果 consumed 不是 NULL，则 PyUnicode_DecodeMBCSStateful() 将不会解码尾随前导字节，并且已解码的字节数将存储在 consumed 中。

2.5 版中的新功能。

PyObject *PyUnicode_EncodeMBCS(const Py_UNICODE *s, Py_ssize_t size, const char *errors): 使用 MBCS 对给定 size 的 Py_UNICODE 缓冲区进行编码并返回 Python 字符串对象。如果编解码器引发异常，则返回 NULL。

2.5 版更改：此函数使用 int 类型作为大小。这可能需要更改您的代码才能正确支持 64 位系统。

PyObject *PyUnicode_AsMBCSString(PyObject *unicode)

使用 MBCS 对 Unicode 对象进行编码，并将结果作为 Python 字符串对象返回。错误处理是“严格的”。如果编解码器引发异常，则返回 NULL。

方法和插槽

方法和槽函数

以下 API 能够处理输入时的 Unicode 对象和字符串（我们在描述中将它们称为字符串）并适当地返回 Unicode 对象或整数。

如果发生异常，它们都返回 NULL 或 -1。

PyObject *PyUnicode_Concat(PyObject *left, PyObject *right)

连接两个字符串，给出一个新的 Unicode 字符串。

PyObject *PyUnicode_Split(PyObject *s, PyObject *sep, Py_ssize_t maxsplit): 拆分一个字符串，给出一个 Unicode 字符串列表。如果 sep 是 NULL，将在所有空白子串上进行拆分。否则，在给定的分隔符处发生拆分。最多会完成 maxsplit 次分割。如果为负，则不设置限制。结果列表中不包含分隔符。

2.5 版更改：此函数使用 int 类型用于 maxsplit。这可能需要更改您的代码才能正确支持 64 位系统。

PyObject *PyUnicode_Splitlines(PyObject *s, int keepend)

在换行符处拆分 Unicode 字符串，返回 Unicode 字符串列表。 CRLF 被认为是一个换行符。如果 keepend 是 0，则结果字符串中不包含换行符。

PyObject *PyUnicode_Translate(PyObject *str, PyObject *table, const char *errors)

通过向字符串应用字符映射表来翻译字符串并返回结果 Unicode 对象。

映射表必须将 Unicode 序数整数映射到 Unicode 序数整数或 None（导致字符删除）。

映射表只需提供__getitem__()接口；字典和序列运行良好。未映射的字符序数（导致 LookupError）保持不变并按原样复制。

errors 具有编解码器的通常含义。它可能是 NULL 表示使用默认错误处理。

PyObject *PyUnicode_Join(PyObject *separator, PyObject *seq)

使用给定的 separator 连接字符串序列并返回结果 Unicode 字符串。

Py_ssize_t PyUnicode_Tailmatch(PyObject *str, PyObject *substr, Py_ssize_t start, Py_ssize_t end, int direction): 如果 substr 在给定的尾端匹配 str[start:end]，则返回 1（direction == -1 表示进行前缀匹配， direction == 1 后缀匹配），否则为 0。如果发生错误，则返回 -1。

2.5 版更改：该函数使用 int 类型用于 start 和 end。这可能需要更改您的代码才能正确支持 64 位系统。

Py_ssize_t PyUnicode_Find(PyObject *str, PyObject *substr, Py_ssize_t start, Py_ssize_t end, int direction): 使用给定的 direction 返回 str[start:end] 中 substr 的第一个位置（direction == 1 表示做一个前向搜索，direction == -1 向后搜索）。返回值是第一个匹配的索引； -1 的值表示未找到匹配项，-2 表示发生错误并设置了异常。

2.5 版更改：该函数使用 int 类型用于 start 和 end。这可能需要更改您的代码才能正确支持 64 位系统。

Py_ssize_t PyUnicode_Count(PyObject *str, PyObject *substr, Py_ssize_t start, Py_ssize_t end): 返回 str[start:end] 中 substr 的非重叠出现次数。如果发生错误，则返回 -1。

2.5 版更改：此函数返回 int 类型并使用 int 类型作为 start 和 end。这可能需要更改您的代码才能正确支持 64 位系统。

PyObject *PyUnicode_Replace(PyObject *str, PyObject *substr, PyObject *replstr, Py_ssize_t maxcount): 将 str 中 substr 的最多 maxcount 次替换为 replstr，并返回生成的 Unicode 对象。 maxcount == -1 表示替换所有出现。

2.5 版更改：该函数使用 int 类型作为 maxcount。这可能需要更改您的代码才能正确支持 64 位系统。

int PyUnicode_Compare(PyObject *left, PyObject *right)

比较两个字符串并分别返回 -1、0、1 的小于、等于和大于。

int PyUnicode_RichCompare(PyObject *left, PyObject *right, int op)

Rich 比较两个 unicode 字符串并返回以下值之一：

NULL 以防引发异常
Py_True 或 Py_False 用于成功比较
Py_NotImplemented 如果类型组合未知

请注意，Py_EQ 和 Py_NE 比较可能会导致 UnicodeWarning，以防将参数转换为 Unicode 失败并显示 UnicodeDecodeError。

op 的可能值为 Py_GT、Py_GE、Py_EQ、Py_NE、Py_LT 和 Py_LE。

PyObject *PyUnicode_Format(PyObject *format, PyObject *args)

从 format 和 args 返回一个新的字符串对象；这类似于 format % args。

int PyUnicode_Contains(PyObject *container, PyObject *element)

检查 element 是否包含在 container 中并相应返回 true 或 false。

element 必须强制转换为一个元素的 Unicode 字符串。如果出现错误，则返回 -1。

Unicode 对象和编解码器 — Python 文档

目录

Unicode 对象和编解码器

Unicode 对象

Unicode 类型

Unicode 字符属性

普通 Py_UNICODE

wchar_t 支持

内置编解码器

通用编解码器

UTF-8 编解码器

UTF-32 编解码器

UTF-16 编解码器

UTF-7 编解码器

Unicode 转义编解码器

原始 Unicode 转义编解码器

拉丁 1 编解码器

ASCII 编解码器

字符映射编解码器

适用于 Windows 的 MBCS 编解码器

方法和插槽

方法和槽函数