Unicode 物件和編解碼器¶

Unicode 物件¶

自從 Python 3.3 中實現 PEP 393 以來，Unicode 物件內部使用多種表示形式，以便在記憶體高效的同時處理完整的 Unicode 字元範圍。對於所有碼點都低於 128、256 或 65536 的字串有特殊情況；否則，碼點必須低於 1114112（這是完整的 Unicode 範圍）。

UTF-8 表示是按需建立並快取在 Unicode 物件中的。

備註

Py_UNICODE 表示已在 Python 3.12 中隨棄用的 API 一起移除。有關更多資訊，請參閱 PEP 623。

Unicode 型別¶

這些是 Python 中用於 Unicode 實現的基本 Unicode 物件型別

PyTypeObject PyUnicode_Type¶: 作為穩定 ABI 的一部分。
此 PyTypeObject 例項表示 Python Unicode 型別。它以 str 的形式暴露給 Python 程式碼。

PyTypeObject PyUnicodeIter_Type¶: 作為穩定 ABI 的一部分。
此 PyTypeObject 例項表示 Python Unicode 迭代器型別。它用於迭代 Unicode 字串物件。

type Py_UCS4¶
type Py_UCS2¶
type Py_UCS1¶: 作為穩定 ABI 的一部分。
這些型別是分別用於包含 32 位、16 位和 8 位字元的無符號整數型別的 typedef。處理單個 Unicode 字元時，請使用 Py_UCS4。

在 3.3 版本加入。

type PyASCIIObject¶
type PyCompactUnicodeObject¶
type PyUnicodeObject¶: 這些 PyObject 的子型別表示 Python Unicode 物件。在幾乎所有情況下，它們都不應直接使用，因為所有處理 Unicode 物件的 API 函式都接受並返回 PyObject 指標。

在 3.3 版本加入。

以下 API 是 C 宏和靜態行內函數，用於對 Unicode 物件的內部只讀資料進行快速檢查和訪問

int PyUnicode_Check(PyObject *obj)¶: 如果物件 obj 是 Unicode 物件或 Unicode 子型別的例項，則返回 True。此函式始終成功。

int PyUnicode_CheckExact(PyObject *obj)¶: 如果物件 obj 是 Unicode 物件，但不是子型別的例項，則返回 True。此函式始終成功。

Py_ssize_t PyUnicode_GET_LENGTH(PyObject *unicode)¶: 返回 Unicode 字串的長度，以碼點為單位。unicode 必須是“規範”表示形式的 Unicode 物件（未檢查）。

在 3.3 版本加入。

Py_UCS1 *PyUnicode_1BYTE_DATA(PyObject *unicode)¶
Py_UCS2 *PyUnicode_2BYTE_DATA(PyObject *unicode)¶
Py_UCS4 *PyUnicode_4BYTE_DATA(PyObject *unicode)¶: 返回指向轉換為 UCS1、UCS2 或 UCS4 整數型別的規範表示形式的指標，以進行直接字元訪問。未執行檢查以確定規範表示形式是否具有正確的字元大小；使用 PyUnicode_KIND() 來選擇正確的函式。

在 3.3 版本加入。

PyUnicode_1BYTE_KIND¶
PyUnicode_2BYTE_KIND¶
PyUnicode_4BYTE_KIND¶: 返回 PyUnicode_KIND() 宏的值。

在 3.3 版本加入。

3.12 版本中的變化: PyUnicode_WCHAR_KIND 已被移除。

int PyUnicode_KIND(PyObject *unicode)¶: 返回一個 PyUnicode 型別常量（見上文），該常量指示此 Unicode 物件用於儲存其資料時每個字元使用多少位元組。unicode 必須是“規範”表示形式的 Unicode 物件（未檢查）。

在 3.3 版本加入。

void *PyUnicode_DATA(PyObject *unicode)¶: 返回指向原始 Unicode 緩衝區的一個 void 指標。unicode 必須是“規範”表示形式的 Unicode 物件（未檢查）。

在 3.3 版本加入。

void PyUnicode_WRITE(int kind, void *data, Py_ssize_t index, Py_UCS4 value)¶

將碼點 value 寫入字串中給定的零基 index。

kind 值和 data 指標必須分別透過 PyUnicode_KIND() 和 PyUnicode_DATA() 從字串中獲取。在呼叫 PyUnicode_WRITE() 時，您必須持有該字串的引用。所有 PyUnicode_WriteChar() 的要求也適用。

此函式對其任何要求都不執行檢查，旨在用於迴圈。

在 3.3 版本加入。

Py_UCS4 PyUnicode_READ(int kind, void *data, Py_ssize_t index)¶: 從規範表示形式 data（透過 PyUnicode_DATA() 獲取）讀取一個碼點。不執行檢查或就緒呼叫。

在 3.3 版本加入。

Py_UCS4 PyUnicode_READ_CHAR(PyObject *unicode, Py_ssize_t index)¶: 從 Unicode 物件 unicode 中讀取一個字元，該物件必須採用“規範”表示形式。如果您進行多次連續讀取，此方法比 PyUnicode_READ() 效率低。

在 3.3 版本加入。

Py_UCS4 PyUnicode_MAX_CHAR_VALUE(PyObject *unicode)¶: 返回適合基於 unicode 建立另一個字串的最大碼點，unicode 必須採用“規範”表示形式。這始終是一個近似值，但比迭代字串更高效。

在 3.3 版本加入。

int PyUnicode_IsIdentifier(PyObject *unicode)¶: 作為穩定 ABI 的一部分。
如果字串根據語言定義（名稱 (識別符號和關鍵字) 節）是有效識別符號，則返回 1。否則返回 0。

3.9 版本中的變化: 如果字串未就緒，函式不再呼叫 Py_FatalError()。

unsigned int PyUnicode_IS_ASCII(PyObject *unicode)¶: 如果字串只包含 ASCII 字元，則返回 True。等同於 str.isascii()。

在 3.2 版本加入。

Unicode 字元屬性¶

Unicode 提供了許多不同的字元屬性。最常用的屬性可透過這些宏獲取，這些宏根據 Python 配置對映到 C 函式。

int Py_UNICODE_ISSPACE(Py_UCS4 ch)¶: 根據 ch 是否為空格字元返回 1 或 0。

int Py_UNICODE_ISLOWER(Py_UCS4 ch)¶: 根據 ch 是否為小寫字元返回 1 或 0。

int Py_UNICODE_ISUPPER(Py_UCS4 ch)¶: 根據 ch 是否為大寫字元返回 1 或 0。

int Py_UNICODE_ISTITLE(Py_UCS4 ch)¶: 根據 ch 是否為標題大寫字元返回 1 或 0。

int Py_UNICODE_ISLINEBREAK(Py_UCS4 ch)¶: 根據 ch 是否為換行符返回 1 或 0。

int Py_UNICODE_ISDECIMAL(Py_UCS4 ch)¶: 根據 ch 是否為十進位制字元返回 1 或 0。

int Py_UNICODE_ISDIGIT(Py_UCS4 ch)¶: 根據 ch 是否為數字字元返回 1 或 0。

int Py_UNICODE_ISNUMERIC(Py_UCS4 ch)¶: 根據 ch 是否為數值字元返回 1 或 0。

int Py_UNICODE_ISALPHA(Py_UCS4 ch)¶: 根據 ch 是否為字母字元返回 1 或 0。

int Py_UNICODE_ISALNUM(Py_UCS4 ch)¶: 根據 ch 是否為字母數字字元返回 1 或 0。

int Py_UNICODE_ISPRINTABLE(Py_UCS4 ch)¶: 根據 ch 是否為可列印字元（如同 str.isprintable() 的含義），返回 1 或 0。

這些 API 可用於快速直接字元轉換

Py_UCS4 Py_UNICODE_TOLOWER(Py_UCS4 ch)¶: 返回轉換為小寫的字元 ch。

Py_UCS4 Py_UNICODE_TOUPPER(Py_UCS4 ch)¶: 返回轉換為大寫的字元 ch。

Py_UCS4 Py_UNICODE_TOTITLE(Py_UCS4 ch)¶: 返回轉換為標題大寫的字元 ch。

int Py_UNICODE_TODECIMAL(Py_UCS4 ch)¶: 返回轉換為十進位制正整數的字元 ch。如果不可能，則返回 -1。此函式不引發異常。

int Py_UNICODE_TODIGIT(Py_UCS4 ch)¶: 返回轉換為單數字整數的字元 ch。如果不可能，則返回 -1。此函式不引發異常。

double Py_UNICODE_TONUMERIC(Py_UCS4 ch)¶: 返回轉換為雙精度的字元 ch。如果不可能，則返回 -1.0。此函式不引發異常。

這些 API 可用於處理代理項

int Py_UNICODE_IS_SURROGATE(Py_UCS4 ch)¶: 檢查 ch 是否為代理項（0xD800 <= ch <= 0xDFFF）。

int Py_UNICODE_IS_HIGH_SURROGATE(Py_UCS4 ch)¶: 檢查 ch 是否為高代理項（0xD800 <= ch <= 0xDBFF）。

int Py_UNICODE_IS_LOW_SURROGATE(Py_UCS4 ch)¶: 檢查 ch 是否為低代理項（0xDC00 <= ch <= 0xDFFF）。

Py_UCS4 Py_UNICODE_JOIN_SURROGATES(Py_UCS4 high, Py_UCS4 low)¶: 連線兩個代理碼點並返回單個 Py_UCS4 值。high 和 low 分別是代理對中的前導代理和尾隨代理。high 必須在範圍 [0xD800; 0xDBFF] 內，low 必須在範圍 [0xDC00; 0xDFFF] 內。

建立和訪問 Unicode 字串¶

要建立 Unicode 物件並訪問其基本序列屬性，請使用這些 API

PyObject *PyUnicode_New(Py_ssize_t size, Py_UCS4 maxchar)¶

返回值：新引用。

建立一個新的 Unicode 物件。maxchar 應該是將放入字串中的真正最大碼點。作為近似值，它可以向上舍入到序列 127、255、65535、1114111 中最接近的值。

如果出錯，則設定異常並返回 NULL。

建立後，字串可以透過 PyUnicode_WriteChar()、PyUnicode_CopyCharacters()、PyUnicode_Fill()、PyUnicode_WRITE() 或類似函式填充。由於字串應該是不可變的，因此在修改時請注意不要“使用”結果。特別是，在填充其最終內容之前，字串

不得雜湊，
不得 轉換為 UTF-8 或其他非“規範”表示形式，
不得更改其引用計數，
不得與可能執行上述操作的程式碼共享。

此列表並非詳盡無遺。避免這些用法是您的責任；Python 並不總是檢查這些要求。

為避免意外暴露部分寫入的字串物件，請優先使用 PyUnicodeWriter API，或以下 PyUnicode_From* 函式之一。

在 3.3 版本加入。

PyObject *PyUnicode_FromKindAndData(int kind, const void *buffer, Py_ssize_t size)¶

返回值：新引用。

使用給定的 kind 建立一個新的 Unicode 物件（可能的值是 PyUnicode_1BYTE_KIND 等，由 PyUnicode_KIND() 返回）。buffer 必須指向一個包含 size 個單位的陣列，每個字元 1、2 或 4 位元組，由 kind 給出。

如有必要，輸入 buffer 將被複制並轉換為規範表示形式。例如，如果 buffer 是 UCS4 字串（PyUnicode_4BYTE_KIND），並且它只包含 UCS1 範圍內的碼點，它將被轉換為 UCS1（PyUnicode_1BYTE_KIND）。

在 3.3 版本加入。

PyObject *PyUnicode_FromStringAndSize(const char *str, Py_ssize_t size)¶

返回值: 新引用。 穩定ABI 的一部分。

從 char 緩衝區 str 建立一個 Unicode 物件。位元組將被解釋為 UTF-8 編碼。緩衝區被複制到新物件中。返回值可能是一個共享物件，即不允許修改資料。

此函式在以下情況下引發 SystemError：

大小 < 0,
str 為 NULL 且 size > 0

3.12 版本中的變化: str == NULL 且 size > 0 不再允許。

PyObject *PyUnicode_FromString(const char *str)¶: 返回值: 新引用。 穩定ABI 的一部分。
從 UTF-8 編碼的以 null 結尾的 char 緩衝區 str 建立一個 Unicode 物件。

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

返回值: 新引用。 穩定ABI 的一部分。

接受一個 C printf() 風格的 format 字串和可變數量的引數，計算結果 Python Unicode 字串的大小，並返回一個將值格式化到其中的字串。可變引數必須是 C 型別，並且必須與 format ASCII 編碼字串中的格式字元完全對應。

轉換說明符包含兩個或更多字元，並具有以下元件，這些元件必須按此順序出現

'%' 字元，它標記說明符的開始。
轉換標誌（可選），影響某些轉換型別的結果。
最小欄位寬度（可選）。如果指定為 '*'（星號），則實際寬度在下一個引數中給出，該引數必須是 int 型別，並且要轉換的物件在最小欄位寬度和可選精度之後。
精度（可選），表示為 '.'（點）後跟精度。如果指定為 '*'（星號），則實際精度在下一個引數中給出，該引數必須是 int 型別，並且要轉換的值在精度之後。
長度修飾符（可選）。
轉換型別。

轉換標誌字元是

Flag	含義
`0`	對於數值，轉換將用零填充。
`-`	轉換後的值左對齊（如果同時給出 `0` 標誌，則覆蓋它）。

以下整數轉換（d、i、o、u、x 或 X）的長度修飾符指定引數的型別（預設為 int）

修飾符	型別
`l`	long 或 unsigned long
`ll`	long long 或 unsigned long long
`j`	`intmax_t` 或 `uintmax_t`
`z`	`size_t` 或 `ssize_t`
`t`	`ptrdiff_t`

以下轉換 s 或 V 的長度修飾符 l 指定引數的型別為 const wchar_t*。

轉換說明符是

轉換說明符	型別	註釋
`%`	不適用	字面量 `%` 字元。
`d`, `i`	由長度修飾符指定	有符號 C 整數的十進位制表示。
`u`	由長度修飾符指定	無符號 C 整數的十進位制表示。
`o`	由長度修飾符指定	無符號 C 整數的八進位制表示。
`x`	由長度修飾符指定	無符號 C 整數的十六進位制表示（小寫）。
`X`	由長度修飾符指定	無符號 C 整數的十六進位制表示（大寫）。
`c`	int	單個字元。
`s`	const char* 或 const wchar_t*	以 null 結尾的 C 字元陣列。
`p`	const void*	C 指標的十六進位制表示。與 `printf("%p")` 大致等效，只是它保證以字面量 `0x` 開頭，無論平臺 `printf` 產生什麼。
`A`	PyObject*	呼叫 `ascii()` 的結果。
`U`	PyObject*	一個 Unicode 物件。
`V`	PyObject, const char 或 const wchar_t*	一個 Unicode 物件（可以為 `NULL`）和一個以 null 結尾的 C 字元陣列作為第二個引數（如果第一個引數為 `NULL`，則使用）。
`S`	PyObject*	呼叫 `PyObject_Str()` 的結果。
`R`	PyObject*	呼叫 `PyObject_Repr()` 的結果。
`T`	PyObject*	獲取物件型別的完全限定名；呼叫 `PyType_GetFullyQualifiedName()`。
`#T`	PyObject*	類似於 `T` 格式，但使用冒號（`:`）作為模組名和限定名之間的分隔符。
`N`	PyTypeObject*	獲取型別的完全限定名；呼叫 `PyType_GetFullyQualifiedName()`。
`#N`	PyTypeObject*	類似於 `N` 格式，但使用冒號（`:`）作為模組名和限定名之間的分隔符。

備註

寬度格式化器單位是字元數而不是位元組數。精度格式化器單位是 "%s" 和 "%V"（如果使用了長度修飾符 l）的位元組數或 wchar_t 項數（如果 PyObject* 引數為 NULL），以及 "%A"、"%U"、"%S"、"%R" 和 "%V"（如果 PyObject* 引數不為 NULL）的字元數。

備註

與 C printf() 不同，對於整數轉換（d、i、u、o、x 或 X），即使給出了精度，0 標誌也有效。

3.2 版本中的變化: 增加了對 "%lld" 和 "%llu" 的支援。

3.3 版本中的變化: 增加了對 "%li"、"%lli" 和 "%zi" 的支援。

3.4 版本中的變化: 增加了對 "%s"、"%A"、"%U"、"%V"、"%S"、"%R" 的寬度和精度格式化程式支援。

3.12 版本中的變化: 支援轉換說明符 o 和 X。支援長度修飾符 j 和 t。長度修飾符現在應用於所有整數轉換。長度修飾符 l 現在應用於轉換說明符 s 和 V。支援可變寬度和精度 *。支援標誌 -。

現在，無法識別的格式字元會設定 SystemError。在以前的版本中，它會導致格式字串的其餘部分按原樣複製到結果字串中，並且任何額外的引數都會被丟棄。

3.13 版本中的變化: 增加了對 %T, %#T, %N 和 %#N 格式的支援。

PyObject *PyUnicode_FromFormatV(const char *format, va_list vargs)¶: 返回值: 新引用。 穩定ABI 的一部分。
與 PyUnicode_FromFormat() 相同，只是它只接受兩個引數。

PyObject *PyUnicode_FromObject(PyObject *obj)¶

返回值: 新引用。 穩定ABI 的一部分。

如有必要，將 Unicode 子型別的例項複製到新的真實 Unicode 物件。如果 obj 已經是真實 Unicode 物件（不是子型別），則返回指向該物件的新強引用。

非 Unicode 或其子型別的物件將導致設定 TypeError。

PyObject *PyUnicode_FromOrdinal(int ordinal)¶

返回值: 新引用。 穩定ABI 的一部分。

從給定的 Unicode 碼點 ordinal 建立一個 Unicode 物件。

序數必須在 range(0x110000) 中。如果不在，則會引發 ValueError。

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

返回值: 新引用。 穩定ABI 的一部分。

將編碼物件 obj 解碼為 Unicode 物件。

bytes、bytearray 和其他 bytes-like objects 根據給定的 encoding 和 errors 定義的錯誤處理進行解碼。兩者都可以是 NULL，以便介面使用預設值（有關詳細資訊，請參閱內建編解碼器）。

所有其他物件，包括 Unicode 物件，都會導致設定 TypeError。

如果發生錯誤，API 返回 NULL。呼叫者負責減少返回物件的引用計數。

void PyUnicode_Append(PyObject **p_left, PyObject *right)¶

作為穩定 ABI 的一部分。

將字串 right 附加到 p_left 的末尾。p_left 必須指向 Unicode 物件的強引用；PyUnicode_Append() 釋放（“竊取”）此引用。

如果出錯，將 *p_left 設定為 NULL 並設定異常。

如果成功，將 *p_left 設定為結果的新強引用。

void PyUnicode_AppendAndDel(PyObject **p_left, PyObject *right)¶: 作為穩定 ABI 的一部分。
此函式類似於 PyUnicode_Append()，唯一的區別是它將 right 的引用計數減一。

PyObject *PyUnicode_BuildEncodingMap(PyObject *string)¶: 返回值: 新引用。 穩定ABI 的一部分。
返回適合解碼自定義單位元組編碼的對映。給定一個最多 256 個字元的 Unicode 字串 string，表示一個編碼表，返回一個緊湊的內部對映物件或一個將字元序數對映到位元組值的字典。在無效輸入時引發 TypeError 並返回 NULL。

在 3.2 版本加入。

const char *PyUnicode_GetDefaultEncoding(void)¶

作為穩定 ABI 的一部分。

返回預設字串編碼的名稱，即 "utf-8"。請參閱 sys.getdefaultencoding()。

返回的字串無需釋放，並且在直譯器關閉之前有效。

Py_ssize_t PyUnicode_GetLength(PyObject *unicode)¶

自 3.7 版本起成為穩定ABI 的一部分。

返回 Unicode 物件的長度，以碼點為單位。

如果出錯，則設定異常並返回 -1。

在 3.3 版本加入。

Py_ssize_t PyUnicode_CopyCharacters(PyObject *to, Py_ssize_t to_start, PyObject *from, Py_ssize_t from_start, Py_ssize_t how_many)¶

將字元從一個 Unicode 物件複製到另一個 Unicode 物件。此函式在必要時執行字元轉換，並儘可能回退到 memcpy()。如果出錯，返回 -1 並設定異常，否則返回複製的字元數。

字串不得已被“使用”。有關詳細資訊，請參閱 PyUnicode_New()。

在 3.3 版本加入。

int PyUnicode_Resize(PyObject **unicode, Py_ssize_t length);¶

作為穩定 ABI 的一部分。

將 Unicode 物件 *unicode 的大小調整為新的 length（以碼點為單位）。

嘗試就地調整字串大小（通常比分配新字串並複製字元更快），或建立新字串。

*unicode 被修改為指向新的（已調整大小的）物件，成功時返回 0。否則，返回 -1 並設定異常，*unicode 保持不變。

該函式不檢查字串內容，結果可能不是規範表示形式的字串。

Py_ssize_t PyUnicode_Fill(PyObject *unicode, Py_ssize_t start, Py_ssize_t length, Py_UCS4 fill_char)¶

用字元填充字串：將 fill_char 寫入 unicode[start:start+length]。

如果 fill_char 大於字串的最大字元，或者字串的引用計數大於 1，則失敗。

字串不得已被“使用”。有關詳細資訊，請參閱 PyUnicode_New()。

返回寫入的字元數，如果出錯則返回 -1 並引發異常。

在 3.3 版本加入。

int PyUnicode_WriteChar(PyObject *unicode, Py_ssize_t index, Py_UCS4 character)¶

自 3.7 版本起成為穩定ABI 的一部分。

將 character 寫入字串 unicode 中零基 index 處。成功時返回 0，出錯時返回 -1 並設定異常。

此函式檢查 unicode 是否為 Unicode 物件，索引是否未越界，以及物件的引用計數是否為一。請參閱 PyUnicode_WRITE() 以獲取跳過這些檢查的版本，使這些檢查成為您的責任。

字串不得已被“使用”。有關詳細資訊，請參閱 PyUnicode_New()。

在 3.3 版本加入。

Py_UCS4 PyUnicode_ReadChar(PyObject *unicode, Py_ssize_t index)¶

自 3.7 版本起成為穩定ABI 的一部分。

從字串中讀取字元。此函式檢查 unicode 是否為 Unicode 物件以及索引是否未越界，這與 PyUnicode_READ_CHAR() 不同，後者不執行錯誤檢查。

成功時返回字元，如果出錯則返回 -1 並設定異常。

在 3.3 版本加入。

PyObject *PyUnicode_Substring(PyObject *unicode, Py_ssize_t start, Py_ssize_t end)¶: 返回值: 新引用。 自 3.7 版本起成為穩定ABI 的一部分。
返回 unicode 的子字串，從字元索引 start（包含）到字元索引 end（不包含）。不支援負數索引。如果發生錯誤，則設定異常並返回 NULL。

在 3.3 版本加入。

Py_UCS4 *PyUnicode_AsUCS4(PyObject *unicode, Py_UCS4 *buffer, Py_ssize_t buflen, int copy_null)¶: 自 3.7 版本起成為穩定ABI 的一部分。
將字串 unicode 複製到 UCS4 緩衝區中，如果 copy_null 設定，則包含一個 null 字元。如果發生錯誤，返回 NULL 並設定異常（特別是，如果 buflen 小於 unicode 的長度，則為 SystemError）。成功時返回 buffer。

在 3.3 版本加入。

Py_UCS4 *PyUnicode_AsUCS4Copy(PyObject *unicode)¶: 自 3.7 版本起成為穩定ABI 的一部分。
將字串 unicode 複製到使用 PyMem_Malloc() 分配的新 UCS4 緩衝區中。如果失敗，返回 NULL 並設定 MemoryError。返回的緩衝區總是附加一個額外的 null 碼點。

在 3.3 版本加入。

區域設定編碼¶

當前區域設定編碼可用於從作業系統解碼文字。

PyObject *PyUnicode_DecodeLocaleAndSize(const char *str, Py_ssize_t length, const char *errors)¶

返回值: 新引用。 自 3.7 版本起成為穩定ABI 的一部分。

在 Android 和 VxWorks 上從 UTF-8 解碼字串，或在其他平臺上從當前區域設定編碼解碼字串。支援的錯誤處理程式是 "strict" 和 "surrogateescape" (PEP 383)。如果 errors 為 NULL，解碼器使用 "strict" 錯誤處理程式。str 必須以 null 字元結尾，但不能包含嵌入的 null 字元。

使用 PyUnicode_DecodeFSDefaultAndSize() 從檔案系統編碼和錯誤處理程式解碼字串。

此函式忽略 Python UTF-8 模式。

參見

Py_DecodeLocale() 函式。

在 3.3 版本加入。

版本 3.7 中的更改: 現在，除 Android 外，該函式還為 surrogateescape 錯誤處理程式使用當前區域設定編碼。以前，Py_DecodeLocale() 用於 surrogateescape，而當前區域設定編碼用於 strict。

PyObject *PyUnicode_DecodeLocale(const char *str, const char *errors)¶: 返回值: 新引用。 自 3.7 版本起成為穩定ABI 的一部分。
類似於 PyUnicode_DecodeLocaleAndSize()，但使用 strlen() 計算字串長度。

在 3.3 版本加入。

PyObject *PyUnicode_EncodeLocale(PyObject *unicode, const char *errors)¶

返回值: 新引用。 自 3.7 版本起成為穩定ABI 的一部分。

在 Android 和 VxWorks 上將 Unicode 物件編碼為 UTF-8，或在其他平臺上編碼為當前區域設定編碼。支援的錯誤處理程式是 "strict" 和 "surrogateescape" (PEP 383)。如果 errors 為 NULL，編碼器使用 "strict" 錯誤處理程式。返回 bytes 物件。unicode 不能包含嵌入的 null 字元。

使用 PyUnicode_EncodeFSDefault() 將字串編碼為檔案系統編碼和錯誤處理程式。

此函式忽略 Python UTF-8 模式。

參見

Py_EncodeLocale() 函式。

在 3.3 版本加入。

版本 3.7 中的更改: 現在，除 Android 外，該函式還為 surrogateescape 錯誤處理程式使用當前區域設定編碼。以前，Py_EncodeLocale() 用於 surrogateescape，而當前區域設定編碼用於 strict。

檔案系統編碼¶

對檔案系統編碼和錯誤處理程式 (PEP 383 和 PEP 529) 進行編碼和解碼的函式。

在引數解析期間將檔名編碼為 bytes 時，應使用 "O&" 轉換器，並將 PyUnicode_FSConverter() 作為轉換函式傳遞

int PyUnicode_FSConverter(PyObject *obj, void *result)¶

作為穩定 ABI 的一部分。

PyArg_Parse* 轉換器: 使用 PyUnicode_EncodeFSDefault() 將 str 物件（直接或透過 os.PathLike 介面獲得）編碼為 bytes；bytes 物件按原樣輸出。result 必須是型別為 PyObject*（或 PyBytesObject*）的 C 變數的地址。成功時，將變數設定為對位元組物件的新強引用，該引用在不再使用時必須釋放，並返回非零值 (Py_CLEANUP_SUPPORTED)。結果中不允許嵌入 null 位元組。失敗時，返回 0 並設定異常。

如果 obj 為 NULL，函式將釋放 result 指向的變數中儲存的強引用並返回 1。

在 3.1 版本加入。

在 3.6 版本發生變更: 接受 path-like object。

在引數解析期間將檔名解碼為 str 時，應使用 "O&" 轉換器，並將 PyUnicode_FSDecoder() 作為轉換函式傳遞

int PyUnicode_FSDecoder(PyObject *obj, void *result)¶

作為穩定 ABI 的一部分。

PyArg_Parse* 轉換器: 使用 PyUnicode_DecodeFSDefaultAndSize() 將 bytes 物件（直接或間接透過 os.PathLike 介面獲得）解碼為 str；str 物件按原樣輸出。result 必須是型別為 PyObject*（或 PyUnicodeObject*）的 C 變數的地址。成功時，將變數設定為對 Unicode 物件的新強引用，該引用在不再使用時必須釋放，並返回非零值 (Py_CLEANUP_SUPPORTED)。結果中不允許嵌入 null 字元。失敗時，返回 0 並設定異常。

如果 obj 為 NULL，釋放對 result 指向的物件的強引用並返回 1。

在 3.2 版本加入。

在 3.6 版本發生變更: 接受 path-like object。

PyObject *PyUnicode_DecodeFSDefaultAndSize(const char *str, Py_ssize_t size)¶

返回值: 新引用。 穩定ABI 的一部分。

從檔案系統編碼和錯誤處理程式解碼字串。

如果需要從當前區域設定編碼解碼字串，請使用 PyUnicode_DecodeLocaleAndSize()。

參見

Py_DecodeLocale() 函式。

版本 3.6 中的更改: 現在使用檔案系統錯誤處理程式。

PyObject *PyUnicode_DecodeFSDefault(const char *str)¶

返回值: 新引用。 穩定ABI 的一部分。

從檔案系統編碼和錯誤處理程式解碼以 null 結尾的字串。

如果已知字串長度，請使用 PyUnicode_DecodeFSDefaultAndSize()。

版本 3.6 中的更改: 現在使用檔案系統錯誤處理程式。

PyObject *PyUnicode_EncodeFSDefault(PyObject *unicode)¶

返回值: 新引用。 穩定ABI 的一部分。

將 Unicode 物件編碼為檔案系統編碼和錯誤處理程式，並返回 bytes。請注意，生成的 bytes 物件可以包含 null 位元組。

如果需要將字串編碼為當前區域設定編碼，請使用 PyUnicode_EncodeLocale()。

參見

Py_EncodeLocale() 函式。

在 3.2 版本加入。

版本 3.6 中的更改: 現在使用檔案系統錯誤處理程式。

wchar_t 支援¶

對支援 wchar_t 的平臺提供 wchar_t 支援

PyObject *PyUnicode_FromWideChar(const wchar_t *wstr, Py_ssize_t size)¶: 返回值: 新引用。 穩定ABI 的一部分。
從給定 size 的 wchar_t 緩衝區 wstr 建立一個 Unicode 物件。將 -1 作為 size 傳遞表示函式必須自行計算長度，使用 wcslen()。失敗時返回 NULL。

Py_ssize_t PyUnicode_AsWideChar(PyObject *unicode, wchar_t *wstr, Py_ssize_t size)¶

作為穩定 ABI 的一部分。

將 Unicode 物件內容複製到 wchar_t 緩衝區 wstr 中。最多複製 size 個 wchar_t 字元（不包括可能存在的尾隨 null 終止符）。返回複製的 wchar_t 字元數，或在發生錯誤時返回 -1。

當 wstr 為 NULL 時，改為返回儲存所有 unicode（包括終止 null）所需的 size。

請注意，生成的 wchar_t* 字串可能以 null 結尾，也可能不以 null 結尾。呼叫者有責任確保 wchar_t* 字串在應用程式需要時以 null 結尾。此外，請注意 wchar_t* 字串可能包含 null 字元，這會導致在與大多數 C 函式一起使用時字串被截斷。

wchar_t *PyUnicode_AsWideCharString(PyObject *unicode, Py_ssize_t *size)¶

自 3.7 版本起成為穩定ABI 的一部分。

將 Unicode 物件轉換為寬字元字串。輸出字串總是以 null 字元結尾。如果 size 不為 NULL，則將寬字元數（不包括尾隨 null 終止符）寫入 *size。請注意，生成的 wchar_t 字串可能包含 null 字元，這會導致在與大多數 C 函式一起使用時字串被截斷。如果 size 為 NULL 且 wchar_t* 字串包含 null 字元，則會引發 ValueError。

成功時返回由 PyMem_New 分配的緩衝區（使用 PyMem_Free() 釋放）。錯誤時，返回 NULL 且 *size 未定義。如果記憶體分配失敗，則引發 MemoryError。

在 3.2 版本加入。

版本 3.7 中的更改: 如果 size 為 NULL 且 wchar_t* 字串包含 null 字元，則引發 ValueError。

內建編解碼器¶

Python 提供了一組用 C 編寫的內建編解碼器，以提高速度。所有這些編解碼器都可以透過以下函式直接使用。

以下許多 API 都接受編碼和錯誤這兩個引數，它們與內建的 str() 字串物件建構函式中的同名引數具有相同的語義。

將編碼設定為 NULL 會導致使用預設編碼 UTF-8。檔案系統呼叫應使用 PyUnicode_FSConverter() 對檔名進行編碼。這在內部使用檔案系統編碼和錯誤處理程式。

錯誤處理由 errors 設定，也可以設定為 NULL，這意味著使用編解碼器定義的預設處理。所有內建編解碼器的預設錯誤處理都是“嚴格”（引發 ValueError）。

所有編解碼器都使用相似的介面。為簡單起見，僅記錄了與以下通用介面的偏差。

通用編解碼器¶

提供以下宏

Py_UNICODE_REPLACEMENT_CHARACTER¶

Unicode 碼點 U+FFFD (替換字元)。

如果 errors 引數設定為“替換”，此 Unicode 字元將用作解碼期間的替換字元。

這些是通用編解碼器 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 位元組物件返回。錯誤處理是“嚴格”的。如果編解碼器引發異常，則返回 NULL。

如果字串包含代理碼點（U+D800 - U+DFFF），則函式失敗。

const char *PyUnicode_AsUTF8AndSize(PyObject *unicode, Py_ssize_t *size)¶

自 3.10 版本以來，作為穩定 ABI 的一部分。

返回指向 Unicode 物件的 UTF-8 編碼的指標，並將編碼表示的大小（以位元組為單位）儲存在 size 中。size 引數可以為 NULL；在這種情況下，不會儲存大小。返回的緩衝區總是附加一個額外的 null 位元組（不包含在 size 中），無論是否存在其他 null 碼點。

發生錯誤時，設定異常，將 size 設定為 -1 (如果它不為 NULL) 並返回 NULL。

如果字串包含代理碼點（U+D800 - U+DFFF），則函式失敗。

這會將字串的 UTF-8 表示快取到 Unicode 物件中，後續呼叫將返回指向同一緩衝區的指標。呼叫方無需負責釋放緩衝區。當 Unicode 物件被垃圾回收時，緩衝區將被釋放，指向它的指標將失效。

在 3.3 版本加入。

版本 3.7 中的更改: 返回型別現在是 const char * 而不是 char *。

版本 3.10 中的更改: 此函式是受限 C API 的一部分。

const char *PyUnicode_AsUTF8(PyObject *unicode)¶: 與 PyUnicode_AsUTF8AndSize() 相同，但不儲存大小。

警告

此函式對嵌入在 unicode 中的空字元沒有特殊行為。因此，包含空字元的字串將保留在返回的字串中，某些 C 函式可能會將其解釋為字串的結尾，從而導致截斷。如果截斷是一個問題，建議使用 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）定義錯誤處理。它預設為“嚴格”。

如果 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 標記開頭。錯誤處理是“嚴格”的。如果編解碼器引發異常，則返回 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）定義錯誤處理。它預設為“嚴格”。

如果 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 標記開頭。錯誤處理是“嚴格”的。如果編解碼器引發異常，則返回 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 物件，並將結果作為位元組物件返回。錯誤處理是“嚴格”的。如果編解碼器引發異常，則返回 NULL。

Raw-Unicode-Escape 編解碼器¶

這些是“原始 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 物件，並將結果作為位元組物件返回。錯誤處理是“嚴格”的。如果編解碼器引發異常，則返回 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 位元組物件返回。錯誤處理是“嚴格”的。如果編解碼器引發異常，則返回 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 位元組物件返回。錯誤處理是“嚴格”的。如果編解碼器引發異常，則返回 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 物件，並將結果作為位元組物件返回。錯誤處理是“嚴格”的。如果編解碼器引發異常，則返回 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)¶: 返回值：新引用。 自 3.7 版本起，作為 Windows 上穩定 ABI 的一部分。
透過解碼 MBCS 編碼字串 str 的 size 位元組來建立 Unicode 物件。如果編解碼器引發異常，則返回 NULL。

PyObject *PyUnicode_DecodeMBCSStateful(const char *str, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)¶: 返回值：新引用。 自 3.7 版本起，作為 Windows 上穩定 ABI 的一部分。
如果 consumed 為 NULL，則行為與 PyUnicode_DecodeMBCS() 相同。如果 consumed 不為 NULL，PyUnicode_DecodeMBCSStateful() 將不會解碼尾隨的前導位元組，並且已解碼的位元組數將儲存在 consumed 中。

PyObject *PyUnicode_DecodeCodePageStateful(int code_page, const char *str, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)¶: 返回值：新引用。 自 3.7 版本起，作為 Windows 上穩定 ABI 的一部分。
類似於 PyUnicode_DecodeMBCSStateful()，但使用 code_page 指定的內碼表。

PyObject *PyUnicode_AsMBCSString(PyObject *unicode)¶: 返回值：新引用。 自 3.7 版本起，作為 Windows 上穩定 ABI 的一部分。
使用 MBCS 編碼 Unicode 物件，並將結果作為 Python 位元組物件返回。錯誤處理是“嚴格”的。如果編解碼器引發異常，則返回 NULL。

PyObject *PyUnicode_EncodeCodePage(int code_page, PyObject *unicode, const char *errors)¶: 返回值：新引用。 自 3.7 版本起，作為 Windows 上穩定 ABI 的一部分。
使用指定的內碼表編碼 Unicode 物件並返回一個 Python 位元組物件。如果編解碼器引發異常，則返回 NULL。使用 CP_ACP 內碼表獲取 MBCS 編碼器。

在 3.3 版本加入。

方法和槽函式¶

以下 API 能夠處理作為輸入的 Unicode 物件和字串（在描述中我們將其稱為字串），並酌情返回 Unicode 物件或整數。

如果發生異常，它們都返回 NULL 或 -1。

PyObject *PyUnicode_Concat(PyObject *left, PyObject *right)¶: 返回值: 新引用。 穩定ABI 的一部分。
連線兩個字串，生成一個新的 Unicode 字串。

PyObject *PyUnicode_Split(PyObject *unicode, PyObject *sep, Py_ssize_t maxsplit)¶

返回值: 新引用。 穩定ABI 的一部分。

將字串拆分為 Unicode 字串列表。如果 sep 為 NULL，則在所有空白子字串處進行拆分。否則，在給定分隔符處進行拆分。最多進行 maxsplit 次拆分。如果為負數，則不設定限制。分隔符不包含在結果列表中。

如果出錯，則返回 NULL 並設定異常。

等同於 str.split()。

PyObject *PyUnicode_RSplit(PyObject *unicode, PyObject *sep, Py_ssize_t maxsplit)¶

返回值: 新引用。 穩定ABI 的一部分。

類似於 PyUnicode_Split()，但拆分將從字串末尾開始進行。

如果出錯，則返回 NULL 並設定異常。

等同於 str.rsplit()。

PyObject *PyUnicode_Splitlines(PyObject *unicode, int keepends)¶: 返回值: 新引用。 穩定ABI 的一部分。
將 Unicode 字串按行分隔符拆分，返回一個 Unicode 字串列表。CRLF 被視為一個行分隔符。如果 keepends 為 0，則行分隔符不包含在結果字串中。

PyObject *PyUnicode_Partition(PyObject *unicode, PyObject *sep)¶

返回值: 新引用。 穩定ABI 的一部分。

將 Unicode 字串在 sep 的第一次出現處拆分，並返回一個 3 元組，其中包含分隔符之前的部分、分隔符本身以及分隔符之後的部分。如果未找到分隔符，則返回一個 3 元組，其中包含字串本身，後跟兩個空字串。

sep 不得為空。

如果出錯，則返回 NULL 並設定異常。

等同於 str.partition()。

PyObject *PyUnicode_RPartition(PyObject *unicode, PyObject *sep)¶

返回值: 新引用。 穩定ABI 的一部分。

類似於 PyUnicode_Partition()，但將 Unicode 字串在 sep 的最後一次出現處拆分。如果未找到分隔符，則返回一個 3 元組，其中包含兩個空字串，後跟字串本身。

sep 不得為空。

如果出錯，則返回 NULL 並設定異常。

等同於 str.rpartition()。

PyObject *PyUnicode_Join(PyObject *separator, PyObject *seq)¶: 返回值: 新引用。 穩定ABI 的一部分。
使用給定的 separator 連線字串序列，並返回生成的 Unicode 字串。

Py_ssize_t PyUnicode_Tailmatch(PyObject *unicode, PyObject *substr, Py_ssize_t start, Py_ssize_t end, int direction)¶: 作為穩定 ABI 的一部分。
如果 substr 在給定尾端與 unicode[start:end] 匹配（direction == -1 表示字首匹配，direction == 1 表示字尾匹配），則返回 1，否則返回 0。如果發生錯誤，則返回 -1。

Py_ssize_t PyUnicode_Find(PyObject *unicode, PyObject *substr, Py_ssize_t start, Py_ssize_t end, int direction)¶: 作為穩定 ABI 的一部分。
使用給定的 direction（direction == 1 表示向前搜尋，direction == -1 表示向後搜尋）返回 substr 在 unicode[start:end] 中的第一個位置。返回值是第一個匹配項的索引；值 -1 表示未找到匹配項，-2 表示發生錯誤並且已設定異常。

Py_ssize_t PyUnicode_FindChar(PyObject *unicode, Py_UCS4 ch, Py_ssize_t start, Py_ssize_t end, int direction)¶: 自 3.7 版本起成為穩定ABI 的一部分。
使用給定的 direction（direction == 1 表示向前搜尋，direction == -1 表示向後搜尋）返回字元 ch 在 unicode[start:end] 中的第一個位置。返回值是第一個匹配項的索引；值 -1 表示未找到匹配項，-2 表示發生錯誤並且已設定異常。

在 3.3 版本加入。

3.7 版本發生變化: start 和 end 現在經過調整，行為類似於 unicode[start:end]。

Py_ssize_t PyUnicode_Count(PyObject *unicode, PyObject *substr, Py_ssize_t start, Py_ssize_t end)¶: 作為穩定 ABI 的一部分。
返回 substr 在 unicode[start:end] 中不重疊出現的次數。如果發生錯誤，則返回 -1。

PyObject *PyUnicode_Replace(PyObject *unicode, PyObject *substr, PyObject *replstr, Py_ssize_t maxcount)¶: 返回值: 新引用。 穩定ABI 的一部分。
將 unicode 中最多 maxcount 次出現的 substr 替換為 replstr，並返回生成的 Unicode 物件。maxcount == -1 表示替換所有出現。

int PyUnicode_Compare(PyObject *left, PyObject *right)¶

作為穩定 ABI 的一部分。

比較兩個字串，並分別返回 -1、0、1 表示小於、等於和大於。

此函式在失敗時返回 -1，因此應呼叫 PyErr_Occurred() 來檢查錯誤。

參見

PyUnicode_Equal() 函式。

int PyUnicode_Equal(PyObject *a, PyObject *b)¶

自 3.14 版本以來，作為穩定 ABI 的一部分。

測試兩個字串是否相等

如果 a 等於 b，則返回 1。
如果 a 不等於 b，則返回 0。
如果 a 或 b 不是 str 物件，則設定 TypeError 異常並返回 -1。

如果 a 和 b 是 str 物件，則該函式總是成功的。

該函式適用於 str 子類，但不遵循自定義的 __eq__() 方法。

參見

PyUnicode_Compare() 函式。

在 3.14 版本加入。

int PyUnicode_EqualToUTF8AndSize(PyObject *unicode, const char *string, Py_ssize_t size)¶

自 3.13 版本起成為穩定 ABI 的一部分。

比較一個 Unicode 物件與一個 char 緩衝區（該緩衝區被解釋為 UTF-8 或 ASCII 編碼），如果它們相等則返回 true (1)，否則返回 false (0)。如果 Unicode 物件包含代理程式碼點（U+D800 - U+DFFF）或者 C 字串不是有效的 UTF-8，則返回 false (0)。

此函式不會引發異常。

在 3.13 版本加入。

int PyUnicode_EqualToUTF8(PyObject *unicode, const char *string)¶: 自 3.13 版本起成為穩定 ABI 的一部分。
類似於 PyUnicode_EqualToUTF8AndSize()，但使用 strlen() 計算 string 的長度。如果 Unicode 物件包含空字元，則返回 false (0)。

在 3.13 版本加入。

int PyUnicode_CompareWithASCIIString(PyObject *unicode, const char *string)¶

作為穩定 ABI 的一部分。

比較 Unicode 物件 unicode 和 string，並分別返回 -1、0、1 表示小於、等於和大於。最好只傳遞 ASCII 編碼的字串，但如果輸入字串包含非 ASCII 字元，該函式會將其解釋為 ISO-8859-1。

此函式不會引發異常。

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

返回值: 新引用。 穩定ABI 的一部分。

富比較兩個 Unicode 字串並返回以下之一：

如果引發異常，則為 NULL
對於成功的比較，為 Py_True 或 Py_False
如果型別組合未知，則為 Py_NotImplemented

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

PyObject *PyUnicode_Format(PyObject *format, PyObject *args)¶: 返回值: 新引用。 穩定ABI 的一部分。
從 format 和 args 返回一個新的字串物件；這類似於 format % args。

int PyUnicode_Contains(PyObject *unicode, PyObject *substr)¶

作為穩定 ABI 的一部分。

檢查 substr 是否包含在 unicode 中，並相應地返回 true 或 false。

substr 必須強制轉換為一個元素 Unicode 字串。如果發生錯誤，則返回 -1。

void PyUnicode_InternInPlace(PyObject **p_unicode)¶

作為穩定 ABI 的一部分。

就地intern引數 *p_unicode。該引數必須是指向 Python Unicode 字串物件的指標變數的地址。如果存在與 *p_unicode 相同的現有interned字串，則將其設定為 *p_unicode（釋放對舊字串物件的引用並建立對interned字串物件的新強引用），否則它保持 *p_unicode 不變並intern它。

（澄清：儘管有很多關於引用的討論，但請將此函式視為引用中立的。您必須擁有傳入的物件；呼叫後，您不再擁有傳入的引用，但您新擁有結果。）

此函式從不引發異常。發生錯誤時，它會保持其引數不變而不進行內部化。

str 子類的例項可能未被內部化，也就是說，PyUnicode_CheckExact(*p_unicode) 必須為真。如果不是，那麼——與任何其他錯誤一樣——引數保持不變。

請注意，內部化字串並非“不朽”。您必須保留對結果的引用才能從內部化中受益。

PyObject *PyUnicode_InternFromString(const char *str)¶

返回值: 新引用。 穩定ABI 的一部分。

PyUnicode_FromString() 和 PyUnicode_InternInPlace() 的組合，適用於靜態分配的字串。

返回對已內部化的新 Unicode 字串物件或具有相同值的早期內部化字串物件的新（“擁有”）引用。

Python 可能會保留對結果的引用，或使其不朽，從而阻止其及時進行垃圾回收。對於內部化無限數量的不同字串（例如來自使用者輸入的字串），請優先直接呼叫 PyUnicode_FromString() 和 PyUnicode_InternInPlace()。

unsigned int PyUnicode_CHECK_INTERNED(PyObject *str)¶: 如果 str 已內部化，則返回非零值，否則返回零。str 引數必須是字串；不進行此檢查。此函式總是成功的。

CPython 實現細節: 非零返回值可能包含有關字串如何內部化的附加資訊。此類非零值的含義以及每個特定字串的內部化相關細節可能會在 CPython 版本之間發生變化。

PyUnicodeWriter¶

PyUnicodeWriter API 可用於建立 Python str 物件。

在 3.14 版本加入。

type PyUnicodeWriter¶

一個 Unicode 寫入器例項。

該例項必須在成功時透過 PyUnicodeWriter_Finish() 銷燬，或在錯誤時透過 PyUnicodeWriter_Discard() 銷燬。

PyUnicodeWriter *PyUnicodeWriter_Create(Py_ssize_t length)¶

建立一個 Unicode 寫入器例項。

length 必須大於或等於 0。

如果 length 大於 0，則預分配一個 length 字元的內部緩衝區。

設定異常並在出錯時返回 NULL。

PyObject *PyUnicodeWriter_Finish(PyUnicodeWriter *writer)¶

返回最終的 Python str 物件並銷燬寫入器例項。

設定異常並在出錯時返回 NULL。

此呼叫後，寫入器例項無效。

void PyUnicodeWriter_Discard(PyUnicodeWriter *writer)¶

丟棄內部 Unicode 緩衝區並銷燬寫入器例項。

如果 writer 為 NULL，則不執行任何操作。

此呼叫後，寫入器例項無效。

int PyUnicodeWriter_WriteChar(PyUnicodeWriter *writer, Py_UCS4 ch)¶

將單個 Unicode 字元 ch 寫入 writer。