Unicode オブジェクトと codec¶

Unicode オブジェクト¶

Python 3.3 で PEP 393 が実装されて以来、Unicode オブジェクトは内部で複数の表現形式を使っています。これにより、メモリ効率を維持しながら Unicode 文字の全範囲を扱えます。すべてのコードポイントが 128 未満、256 未満、または 65536 未満の文字列は特別に扱います。それ以外のコードポイントは 1114112 未満 (Unicode の全範囲) でなければなりません。

UTF-8 表現は必要に応じて作成され、Unicode オブジェクト内にキャッシュされます。

内部バッファには、null 終端の C 文字列との互換性のため、末尾に常に追加の null 文字が含まれます。この追加文字は PyUnicode_GetLength() や、以下の関数の各種 size 引数には数えません。

注釈

Py_UNICODE 表現は、非推奨の API とともに Python 3.12 で削除されました。詳細は PEP 623 を参照してください。

Unicode 型¶

以下は Python の Unicode 実装に用いられている基本 Unicode オブジェクト型です:

PyTypeObject PyUnicode_Type¶: 次に属します: Stable ABI.
この PyTypeObject のインスタンスは Python の Unicode 型を表します。 Python コードには str として公開されています。

PyTypeObject PyUnicodeIter_Type¶: 次に属します: Stable ABI.
この PyTypeObject のインスタンスは Python の Unicode イテレータ型を表します。 Unicode 文字列オブジェクトの反復処理に使われます。

type Py_UCS4¶
type Py_UCS2¶
type Py_UCS1¶: 次に属します: Stable ABI.
これらの型は、それぞれ、32ビット、16ビット、そして8ビットの文字を保持するのに充分な幅を持つ符号なしの整数型のtypedefです。単一のUnicode文字を扱う場合は、 Py_UCS4 を用いてください。

Added in version 3.3.

type PyASCIIObject¶

type PyCompactUnicodeObject¶

type PyUnicodeObject¶

これらの PyObject のサブタイプは Python Unicode オブジェクトを表現します。 Unicode オブジェクトを扱う全ての API 関数は PyObject へのポインタを受け取って PyObject へのポインタを返すので、ほとんどの場合、これらの型を直接使うべきではありません。

Added in version 3.3.

特定のオブジェクトの構造は、次のマクロで判定できます。これらのマクロは失敗しませんが、引数が Python の Unicode オブジェクトでなければ動作は未定義です。

PyUnicode_IS_COMPACT(o)¶: o が PyCompactUnicodeObject 構造体を使っていれば真です。

Added in version 3.3.

PyUnicode_IS_COMPACT_ASCII(o)¶: o が PyASCIIObject 構造体を使っていれば真です。

Added in version 3.3.

以下の API は、Unicode オブジェクトの高速な検査や、内部の読み出し専用データへのアクセスのための C マクロと静的インライン関数です:

int PyUnicode_Check(PyObject *obj)¶: オブジェクト obj が Unicode オブジェクトか Unicode 型のサブタイプのインスタンスである場合に真を返します。この関数は常に成功します。

int PyUnicode_CheckExact(PyObject *obj)¶: オブジェクト obj が Unicode オブジェクトだがサブタイプのインスタンスでない場合に真を返します。この関数は常に成功します。

Py_ssize_t PyUnicode_GET_LENGTH(PyObject *unicode)¶: Unicode 文字列のコードポイントでの長さを返します。 unicode は "正統な" 表現形式の Unicode オブジェクトでなければなりません (ただしチェックはしません)。

Added in version 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() を使って正しい関数を選んでください。

Added in version 3.3.

PyUnicode_1BYTE_KIND¶
PyUnicode_2BYTE_KIND¶
PyUnicode_4BYTE_KIND¶: PyUnicode_KIND() マクロの返り値です。

Added in version 3.3.

バージョン 3.12 で変更: PyUnicode_WCHAR_KIND は削除されました。

int PyUnicode_KIND(PyObject *unicode)¶: この Unicode がデータを保存するのに1文字あたり何バイト使っているかを示す PyUnicode 種別の定数 (上を読んでください) のうち1つを返します。 unicode は "正統な" 表現形式の Unicode オブジェクトでなければなりません (ただしチェックはしません)。

Added in version 3.3.

void *PyUnicode_DATA(PyObject *unicode)¶: 生の Unicode バッファへの void ポインタを返します。 unicode は "正統な" 表現形式の Unicode オブジェクトでなければなりません (ただしチェックはしません)。

Added in version 3.3.

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

文字列のゼロから始まる index の位置に、コードポイント value を書き込みます。

kind の値と data ポインタは、文字列からそれぞれ PyUnicode_KIND() と PyUnicode_DATA() で取得したものでなければなりません。 PyUnicode_WRITE() の呼び出し中は、その文字列への参照を保持する必要があります。 PyUnicode_WriteChar() のすべての要件も適用されます。

この関数は要件が満たされているか一切検査せず、ループ内での使用を想定しています。

Added in version 3.3.

Py_UCS4 PyUnicode_READ(int kind, void *data, Py_ssize_t index)¶: 正統な表現形式の data (PyUnicode_DATA() で取得したもの) からコードポイントを読み取ります。検査は行いません。

PyUnicode_GetLength() が返すインデックスの位置にある、末尾の null 文字を読み取れます。

Added in version 3.3.

Py_UCS4 PyUnicode_READ_CHAR(PyObject *unicode, Py_ssize_t index)¶: Unicode オブジェクト unicode から文字を読み取ります。この Unicode オブジェクトは "正統な" 表現形式でなければなりません。何度も連続して読み取る場合には、このマクロは PyUnicode_READ() よりも非効率的です。

PyUnicode_GetLength() が返すインデックスの位置にある、末尾の null 文字を読み取れます。

Added in version 3.3.

Py_UCS4 PyUnicode_MAX_CHAR_VALUE(PyObject *unicode)¶: unicode に基づいて他の文字列を作るのに適した最大のコードポイントを返します。この Unicode オブジェクトは "正統な" 表現形式でなければなりません。この値は常に概算値ですが、文字列全体を調べるよりも効率的です。

Added in version 3.3.

int PyUnicode_IsIdentifier(PyObject *unicode)¶: 次に属します: Stable ABI.
文字列が、名前 (識別子とキーワード) 節の言語定義における有効な識別子であれば 1 を返します。それ以外の場合は 0 を返します。

バージョン 3.9 で変更: 文字列が使用可能な状態でなくても、Py_FatalError() を呼び出さなくなりました。

unsigned int PyUnicode_IS_ASCII(PyObject *unicode)¶: 文字列に ASCII 文字しか含まれていなければ真を返します。 str.isascii() と等価です。

Added in version 3.2.

Py_hash_t PyUnstable_Unicode_GET_CACHED_HASH(PyObject *str)¶

これは Unstable APIです。マイナーリリースで予告なく変更されることがあります。

PyObject_Hash() が返す str のハッシュ値がキャッシュ済みですぐに取得できれば、その値を返します。それ以外の場合は例外を設定 せずに -1 を返します。

str が文字列でない場合 (つまり PyUnicode_Check(obj) が偽の場合)、動作は未定義です。

この関数が例外で失敗することはありません。

オブジェクトのハッシュ値がいつキャッシュされるかは保証されず、キャッシュされたハッシュ値の有無が文字列の他の性質を示すわけではないことに注意してください。

Unicode 文字プロパティ¶

Unicode は数多くの異なる文字プロパティ (character property) を提供しています。よく使われる文字プロパティは、以下のマクロで利用できます。これらのマクロは 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 がタイトルケース文字 (titlecase character) かどうかに応じて 1 または 0 を返します。

int Py_UNICODE_ISLINEBREAK(Py_UCS4 ch)¶: ch が改行文字かどうかに応じて 1 または 0 を返します。

int Py_UNICODE_ISDECIMAL(Py_UCS4 ch)¶: ch が decimal 文字かどうかに応じて 1 または 0 を返します。

int Py_UNICODE_ISDIGIT(Py_UCS4 ch)¶: ch が digit 文字かどうかに応じて 1 または 0 を返します。

int Py_UNICODE_ISNUMERIC(Py_UCS4 ch)¶: ch が数字 (numeric) 文字かどうかに応じて 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)¶: Return the character ch converted to a decimal positive integer. Return -1 if this is not possible. This function does not raise exceptions.

int Py_UNICODE_TODIGIT(Py_UCS4 ch)¶: 文字 ch を 1 桁の整数に変換して返します。変換できなければ -1 を返します。この関数は例外を送出しません。

double Py_UNICODE_TONUMERIC(Py_UCS4 ch)¶: ch を double に変換したものを返します。不可能ならば -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_HIGH_SURROGATE(Py_UCS4 ch)¶: [0x10000; 0x10FFFF] の範囲の Unicode コードポイントに対応する、UTF-16 の上位サロゲート (0xD800 から 0xDBFF) を返します。

Py_UCS4 Py_UNICODE_LOW_SURROGATE(Py_UCS4 ch)¶: [0x10000; 0x10FFFF] の範囲の Unicode コードポイントに対応する、UTF-16 の下位サロゲート (0xDC00 から 0xDFFF) を返します。

Py_UCS4 Py_UNICODE_JOIN_SURROGATES(Py_UCS4 high, Py_UCS4 low)¶: 2 つのサロゲートコードポイントを結合し、1 つの Py_UCS4 値を返します。 high と low は、サロゲートペアのそれぞれ先頭と末尾のサロゲートです。 high は [0xD800; 0xDBFF]、low は [0xDC00; 0xDFFF] の範囲内でなければなりません。

Unicode 文字列の生成とアクセス¶

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* 関数のいずれかを使うことを推奨します。

Added in version 3.3.

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

戻り値: 新しい参照。

与えられた kind (取り得る値は PyUnicode_1BYTE_KIND などの PyUnicode_KIND() が返す値です) の Unicode オブジェクトを生成します。 buffer は、与えられた kind に従って1文字あたり 1, 2, 4 バイトのいずれかを単位として、長さ size の配列へのポインタでなければなりません。

必要に応じて、入力の buffer をコピーして正統な表現形式に変換します。例えば buffer が UCS4 文字列 (PyUnicode_4BYTE_KIND) で、UCS1 の範囲内のコードポイントだけで構成されていれば、UCS1 (PyUnicode_1BYTE_KIND) に変換します。

すべての文字は [U+0000; U+10ffff] の範囲内でなければなりません。 kind が PyUnicode_4BYTE_KIND で、文字列に無効な文字が含まれている場合、動作は未定義です。

Added in version 3.3.

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

戻り値: 新しい参照。 次に属します: Stable ABI.

char 型のバッファ str から Unicode オブジェクトを作成します。バイト列は UTF-8 でエンコードされているものとして解釈します。バッファの内容を新しいオブジェクトにコピーします。戻り値は共有オブジェクトの場合があるため、データの変更は許されません。

次の場合、この関数は SystemError を送出します:

size < 0 の場合。
str が NULL で、size > 0 の場合。

バージョン 3.12 で変更: size > 0 のときに str == NULL を指定できなくなりました。

PyObject *PyUnicode_FromString(const char *str)¶: 戻り値: 新しい参照。 次に属します: Stable ABI.
UTF-8 エンコードされたnull終端のchar 型バッファ str から Unicode オブジェクトを生成します。

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

戻り値: 新しい参照。 次に属します: Stable ABI.

C の printf() 形式の書式文字列 format と可変個数の引数を受け取り、結果の Python Unicode 文字列のサイズを計算し、値を書式化した文字列を返します。可変個数の引数は C の型でなければならず、ASCII でエンコードされた format 文字列の書式指定文字に厳密に対応していなければなりません。

一つの変換指定子は 2 またはそれ以上の文字を含み、その構成要素は以下からなりますが、示した順に出現しなければなりません:

指定子の開始を示す文字 '%' 。
変換フラグ (オプション)。一部の変換型の結果に影響します。
最小フィールド幅 (省略可能)。 '*' (アスタリスク) を指定した場合は、次の引数に実際の幅を 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* であることを指定します。

変換指定子を以下に示します:

変換指定子	型	備考
`%`	n/a	文字 `%` そのもの。
`d`, `i`	長さ修飾子で指定	符号付き C 整数の 10 進表現。
`u`	長さ修飾子で指定	符号なし C 整数の 10 進表現。
`o`	長さ修飾子で指定	符号なし C 整数の 8 進表現。
`x`	長さ修飾子で指定	符号なし C 整数の 16 進表現 (小文字)。
`X`	長さ修飾子で指定	符号なし C 整数の 16 進表現 (大文字)。
`c`	int	1 文字。
`s`	const char* または const wchar_t*	null で終端された C の文字列。
`p`	const void*	C ポインタの 16 進表記。`printf("%p")` とほとんど同じですが、プラットフォームにおける `printf` の定義に関わりなく先頭にリテラル `0x` が付きます。
`A`	PyObject*	`ascii()` の戻り値。
`U`	PyObject*	Unicode オブジェクト。
`V`	PyObject、const char、または const wchar_t*	Unicode オブジェクト (`NULL` でも構いません) と、2 番目の引数として 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" と PyObject* 引数が NULL の場合の "%V" では、バイト数または wchar_t 要素数 (長さ修飾子 l を使う場合) です。 "%A"、"%U"、"%S"、"%R"、および PyObject* 引数が NULL でない場合の "%V" では、文字数です。

注釈

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)¶: 戻り値: 新しい参照。 次に属します: Stable ABI.
ちょうど２つの引数を取ることを除いて、 PyUnicode_FromFormat() と同じです。

PyObject *PyUnicode_FromObject(PyObject *obj)¶

戻り値: 新しい参照。 次に属します: Stable ABI.

必要に応じて、Unicode のサブタイプのインスタンスを、サブタイプではない新しい Unicode オブジェクトにコピーします。 obj がすでにサブタイプではない Unicode オブジェクトの場合は、そのオブジェクトへの新しい強参照を返します。

Unicode やそのサブタイプ以外のオブジェクトでは TypeError が引き起こされます。

PyObject *PyUnicode_FromOrdinal(int ordinal)¶

戻り値: 新しい参照。 次に属します: Stable ABI.

指定された Unicode コードポイント ordinal から Unicode オブジェクトを作成します。

ordinal は range(0x110000) の範囲内でなければなりません。範囲外の場合は ValueError を送出します。

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

戻り値: 新しい参照。 次に属します: Stable ABI.

エンコードされている obj を Unicode オブジェクトにデコードします。

bytes や bytearray や他の bytes-like objects は、与えられた encoding に従ってデコードされ、 errors で定義されたエラーハンドリングが使われます。これらの引数は両方とも NULL にでき、その場合この API はデフォルト値を使います (詳しことは組み込み codec (built-in codec) を参照してください)。

その他のUnicodeオブジェクトを含むオブジェクトは TypeError 例外を引き起こします。

この API は、エラーが生じたときには NULL を返します。呼び出し側は返されたオブジェクトに対し参照カウンタを 1 つ減らす (decref) する責任があります。

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

次に属します: Stable ABI.

文字列 right を p_left の末尾に追加します。 p_left は Unicode オブジェクトへの強参照を指す必要があります。 PyUnicode_Append() はこの参照を解放します (「盗みます」)。

エラー時には *p_left に NULL を設定し、例外を設定します。

成功すると *p_left に結果への新しい強参照を設定します。

void PyUnicode_AppendAndDel(PyObject **p_left, PyObject *right)¶: 次に属します: Stable ABI.
PyUnicode_Append() と同様ですが、right の参照カウントを 1 減らす点だけが異なります。

PyObject *PyUnicode_BuildEncodingMap(PyObject *string)¶: 戻り値: 新しい参照。 次に属します: Stable ABI.
Return a mapping suitable for decoding a custom single-byte encoding. Given a Unicode string string of up to 256 characters representing an encoding table, returns either a compact internal mapping object or a dictionary mapping character ordinals to byte values. Raises a TypeError and return NULL on invalid input.

Added in version 3.2.

const char *PyUnicode_GetDefaultEncoding(void)¶

次に属します: Stable ABI.

デフォルトの文字列エンコーディングの名前 "utf-8" を返します。 sys.getdefaultencoding() を参照してください。

返された文字列を解放する必要はなく、インタープリタの終了まで有効です。

Py_ssize_t PyUnicode_GetLength(PyObject *unicode)¶

次に属します: Stable ABI (バージョン 3.7 より).

Unicode オブジェクトの長さをコードポイントで返します。

エラー時には例外を設定して -1 を返します。

長さには末尾の null 文字を数えません。

Added in version 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 オブジェクトから他へ文字をコピーします。この関数は必要なときに文字変換を行い、可能な場合は memcpy() へ差し戻します。失敗のときには -1 を返し、例外を設定します。そうでない場合は、コピーした文字数を返します。

文字列はまだ「使用」していないものでなければなりません。詳細は PyUnicode_New() を参照してください。

Added in version 3.3.

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

次に属します: Stable 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)¶

文字列を文字で埋めます: unicode[start:start+length] で fill_char を埋めることになります。

fill_char が文字列の最大文字よりも大きい場合や、文字列2つ以上の参照を持ってた場合は失敗します。

文字列はまだ「使用」していないものでなければなりません。詳細は PyUnicode_New() を参照してください。

書き込んだ文字数を返します。エラー時には -1 を返して例外を送出します。

Added in version 3.3.

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

次に属します: Stable ABI (バージョン 3.7 より).

文字列 unicode のゼロから始まる index の位置に character を書き込みます。成功すると 0、エラー時には例外を設定して -1 を返します。

この関数は unicode が Unicode オブジェクトであること、インデックスが範囲内であること、オブジェクトの参照カウントが 1 であることを検査します。これらの検査を省略し、利用側の責任とする版については PyUnicode_WRITE() を参照してください。

文字列はまだ「使用」していないものでなければなりません。詳細は PyUnicode_New() を参照してください。

Added in version 3.3.

Py_UCS4 PyUnicode_ReadChar(PyObject *unicode, Py_ssize_t index)¶

次に属します: Stable ABI (バージョン 3.7 より).

文字列から文字を読み取ります。エラーチェックを行わない PyUnicode_READ_CHAR() とは対照的に、この関数は unicode が Unicode オブジェクトであること、インデックスが範囲内であることをチェックします。

成功すると文字を返します。エラー時には例外を設定して -1 を返します。

PyUnicode_GetLength() が返すインデックスの位置にある、末尾の null 文字は読み取れません。

Added in version 3.3.

PyObject *PyUnicode_Substring(PyObject *unicode, Py_ssize_t start, Py_ssize_t end)¶: 戻り値: 新しい参照。 次に属します: Stable ABI (バージョン 3.7 より).
文字インデックス start (含む) から end (含まない) までの unicode の部分文字列を返します。負のインデックスはサポートしません。エラー時には例外を設定して NULL を返します。

Added in version 3.3.

Py_UCS4 *PyUnicode_AsUCS4(PyObject *unicode, Py_UCS4 *buffer, Py_ssize_t buflen, int copy_null)¶: 次に属します: Stable ABI (バージョン 3.7 より).
文字列 unicode を UCS4 バッファにコピーします。 copy_null が設定されている場合は null 文字も含めます。エラー時には NULL を返して例外を設定します (特に buflen が unicode の長さより小さい場合は SystemError を設定します)。成功すると buffer を返します。

Added in version 3.3.

Py_UCS4 *PyUnicode_AsUCS4Copy(PyObject *unicode)¶: 次に属します: Stable ABI (バージョン 3.7 より).
文字列 unicode を PyMem_Malloc() でメモリ確保された新しい UCS4 型のバッファにコピーします。これが失敗した場合は、 NULL を返し MemoryError をセットします。返されたバッファは必ず null コードポイントが追加されています。

Added in version 3.3.

ロケールエンコーディング¶

現在のロケールエンコーディングはオペレーティングシステムのテキストをデコードするのに使えます。

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

戻り値: 新しい参照。 次に属します: Stable ABI (バージョン 3.7 より).

Android と VxWorks では UTF-8、それ以外のプラットフォームでは現在のロケールエンコーディングで文字列をデコードします。対応するエラーハンドラは "strict" と "surrogateescape" (PEP 383) です。 errors が NULL の場合、デコーダは "strict" エラーハンドラを使います。 str は null 文字で終端されている必要がありますが、内部に null 文字を含めることはできません。

ファイルシステムのエンコーディングとエラーハンドラで文字列をデコードするには、PyUnicode_DecodeFSDefaultAndSize() を使ってください。

この関数は Python UTF-8 モードを無視します。

参考

Py_DecodeLocale() 関数。

Added in version 3.3.

バージョン 3.7 で変更: この関数は、 Android 以外では現在のロケールエンコーディングを surrogateescape エラーハンドラで使うようになりました。以前は、 Py_DecodeLocale() が surrogateescape で使われ、現在のロケールエンコーディングは strict で使われていました。

PyObject *PyUnicode_DecodeLocale(const char *str, const char *errors)¶: 戻り値: 新しい参照。 次に属します: Stable ABI (バージョン 3.7 より).
PyUnicode_DecodeLocaleAndSize() と同様ですが、文字列の長さを strlen() で計算します。

Added in version 3.3.

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

戻り値: 新しい参照。 次に属します: Stable ABI (バージョン 3.7 より).

Android と VxWorks では UTF-8、それ以外のプラットフォームでは現在のロケールエンコーディングで Unicode オブジェクトをエンコードします。対応するエラーハンドラは "strict" と "surrogateescape" (PEP 383) です。 errors が NULL の場合、エンコーダは "strict" エラーハンドラを使います。 bytes オブジェクトを返します。 unicode の内部に null 文字を含めることはできません。

ファイルシステムのエンコーディングとエラーハンドラで文字列をエンコードするには、PyUnicode_EncodeFSDefault() を使ってください。

この関数は Python UTF-8 モードを無視します。

参考

Py_EncodeLocale() 関数。

Added in version 3.3.

バージョン 3.7 で変更: この関数は、 Android 以外では現在のロケールエンコーディングを surrogateescape エラーハンドラで使うようになりました。以前は、 Py_EncodeLocale() が surrogateescape で使われ、現在のロケールエンコーディングは strict で使われていました。

ファイルシステムエンコーディング¶

ファイルシステムのエンコーディングとエラーハンドラでエンコードとデコードを行う関数です (PEP 383 と PEP 529)。

引数の解析中にファイル名を bytes にエンコードするには、変換関数に PyUnicode_FSConverter() を渡して "O&" コンバータを使ってください:

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

次に属します: Stable ABI.

PyArg_Parse* コンバータです。直接、または os.PathLike インターフェースを通じて取得した str オブジェクトを、PyUnicode_EncodeFSDefault() で bytes にエンコードします。 bytes オブジェクトはそのまま出力します。 result は PyObject* 型 (または PyBytesObject* 型) の C 変数のアドレスでなければなりません。成功すると、その変数に bytes オブジェクトへの新しい強参照を設定し、ゼロ以外の値 (Py_CLEANUP_SUPPORTED) を返します。この参照は使わなくなったら解放する必要があります。結果の内部に null バイトを含めることはできません。失敗すると例外を設定して 0 を返します。

obj が NULL の場合、result が指す変数に格納された強参照を解放し、1 を返します。

Added in version 3.1.

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

引数の解析中にファイル名を str にデコードするには、変換関数に PyUnicode_FSDecoder() を渡して "O&" コンバータを使ってください:

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

次に属します: Stable ABI.

PyArg_Parse* コンバータです。直接、または os.PathLike インターフェースを通じて間接的に取得した bytes オブジェクトを、PyUnicode_DecodeFSDefaultAndSize() で str にデコードします。 str オブジェクトはそのまま出力します。 result は PyObject* 型 (または PyUnicodeObject* 型) の C 変数のアドレスでなければなりません。成功すると、その変数に Unicode オブジェクトへの新しい強参照を設定し、ゼロ以外の値 (Py_CLEANUP_SUPPORTED) を返します。この参照は使わなくなったら解放する必要があります。結果の内部に null 文字を含めることはできません。失敗すると例外を設定して 0 を返します。

obj が NULL の場合、result が指すオブジェクトへの強参照を解放し、1 を返します。

Added in version 3.2.

バージョン 3.6 で変更: path-like object を受け入れるようになりました。

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

戻り値: 新しい参照。 次に属します: Stable ABI.

ファイルシステムのエンコーディングとエラーハンドラで文字列をデコードします。

現在のロケールエンコーディングで文字列をデコードするには、PyUnicode_DecodeLocaleAndSize() を使ってください。

参考

Py_DecodeLocale() 関数。

バージョン 3.6 で変更: ファイルシステムのエラーハンドラを使うようになりました。

PyObject *PyUnicode_DecodeFSDefault(const char *str)¶

戻り値: 新しい参照。 次に属します: Stable ABI.

ファイルシステムのエンコーディングとエラーハンドラで null 終端の文字列をデコードします。

文字列の長さが分かっている場合は、PyUnicode_DecodeFSDefaultAndSize() を使ってください。

バージョン 3.6 で変更: ファイルシステムのエラーハンドラを使うようになりました。

PyObject *PyUnicode_EncodeFSDefault(PyObject *unicode)¶

戻り値: 新しい参照。 次に属します: Stable ABI.

ファイルシステムのエンコーディングとエラーハンドラで Unicode オブジェクトをエンコードし、bytes を返します。結果の bytes オブジェクトには null バイトが含まれる場合があることに注意してください。

現在のロケールエンコーディングで文字列をエンコードするには、PyUnicode_EncodeLocale() を使ってください。

参考

Py_EncodeLocale() 関数。

Added in version 3.2.

バージョン 3.6 で変更: ファイルシステムのエラーハンドラを使うようになりました。

wchar_t サポート¶

wchar_t をサポートするプラットフォームでの wchar_t サポート:

PyObject *PyUnicode_FromWideChar(const wchar_t *wstr, Py_ssize_t size)¶: 戻り値: 新しい参照。 次に属します: Stable ABI.
指定された size の wchar_t バッファ wstr から Unicode オブジェクトを作成します。 size に -1 を渡すと、この関数自身が wcslen() を使って長さを計算します。失敗すると NULL を返します。

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

次に属します: Stable ABI.

Unicode オブジェクトの内容を wchar_t バッファ wstr にコピーします。最大で size 個の wchar_t 文字をコピーします (末尾に付く場合がある終端の null 文字を除きます)。コピーした wchar_t 文字の数、またはエラー時には -1 を返します。

wstr が NULL の場合は、代わりに終端の null 文字も含めて unicode 全体を格納するのに必要な size を返します。

結果の wchar_t* 文字列は、null 終端される場合とされない場合があることに注意してください。アプリケーションが null 終端を必要とする場合、wchar_t* 文字列が null 終端されていることを保証するのは呼び出し側の責任です。また、wchar_t* 文字列の内部に null 文字が含まれる場合があり、その場合はほとんどの C 関数で文字列が途中で切れてしまうことにも注意してください。

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

次に属します: Stable ABI (バージョン 3.7 より).

Unicode オブジェクトをワイド文字列に変換します。出力文字列は常に null 文字で終わります。 size が NULL でなければ、ワイド文字の数 (末尾の終端 null 文字を除く) を *size に書き込みます。結果の wchar_t 文字列の内部に null 文字が含まれる場合があり、その場合はほとんどの C 関数で文字列が途中で切れてしまうことに注意してください。 size が NULL で、wchar_t* 文字列の内部に null 文字が含まれている場合は、ValueError を送出します。

成功すると、PyMem_New で割り当てたバッファを返します (PyMem_Free() で解放してください)。エラー時には NULL を返し、*size は未定義です。メモリの割り当てに失敗すると MemoryError を送出します。

Added in version 3.2.

バージョン 3.7 で変更: size が NULL で、wchar_t* 文字列の内部に null 文字が含まれている場合は、ValueError を送出するようになりました。

組み込み codec (built-in codec)¶

Python には、処理速度を高めるために C で書かれた codec が揃えてあります。これら全ての codec は以下の関数を介して直接利用できます。

以下の API の多くが、 encoding と errors という二つの引数をとります。これらのパラメータは、組み込みの文字列コンストラクタである str() における同名のパラメータと同じ意味を持ちます。

encoding に NULL を設定すると、デフォルトのエンコーディングである UTF-8 を使います。ファイルシステムの呼び出しでファイル名をエンコードするには、PyUnicode_FSConverter() を使ってください。これは内部でファイルシステムのエンコーディングとエラーハンドラを使います。

errors で指定するエラー処理もまた、 NULL を指定できます。 NULL を指定すると、codec で定義されているデフォルト処理の使用を意味します。全ての組み込み codec で、デフォルトのエラー処理は "strict" (ValueError を送出する) になっています。

個々の codec は全て同様のインターフェースを使っています。個別の codec の説明では、説明を簡単にするために以下の汎用のインターフェースとの違いだけを説明しています。

汎用 codec¶

次のマクロが用意されています:

Py_UNICODE_REPLACEMENT_CHARACTER¶

Unicode コードポイント U+FFFD (置換文字)。

errors 引数が "replace" の場合、この Unicode 文字をデコード時の置換文字として使います。

以下は汎用 codec の API です:

PyObject *PyUnicode_Decode(const char *str, Py_ssize_t size, const char *encoding, const char *errors)¶: 戻り値: 新しい参照。 次に属します: Stable ABI.
エンコードされた文字列 str の size バイトをデコードし、Unicode オブジェクトを作成します。 encoding と errors の意味は、組み込み関数 str() の同名の引数と同じです。使用する codec は Python の codec レジストリで検索します。 codec が例外を送出した場合は NULL を返します。

PyObject *PyUnicode_AsEncodedString(PyObject *unicode, const char *encoding, const char *errors)¶: 戻り値: 新しい参照。 次に属します: Stable ABI.
Unicode オブジェクトをエンコードし、その結果を Python の bytes オブジェクトとして返します。 encoding および errors は Unicode 型の encode() メソッドに与える同名のパラメータと同じ意味を持ちます。使用する codec の検索は、 Python の codec レジストリを使って行います。 codec が例外を送出した場合には NULL を返します。

UTF-8 Codecs¶

以下は UTF-8 codec の APIです:

PyObject *PyUnicode_DecodeUTF8(const char *str, Py_ssize_t size, const char *errors)¶: 戻り値: 新しい参照。 次に属します: Stable ABI.
UTF-8 でエンコードされた size バイトの文字列 str から Unicode オブジェクトを生成します。codec が例外を送出した場合には NULL を返します。

PyObject *PyUnicode_DecodeUTF8Stateful(const char *str, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)¶: 戻り値: 新しい参照。 次に属します: Stable ABI.
consumed が NULL の場合、 PyUnicode_DecodeUTF8() と同じように動作します。 consumed が NULL でない場合、末尾の不完全な UTF-8 バイト列はエラーとみなされません。これらのバイト列はデコードされず、デコードされたバイト数は consumed に格納されます。

PyObject *PyUnicode_AsUTF8String(PyObject *unicode)¶

戻り値: 新しい参照。 次に属します: Stable ABI.

UTF-8 で Unicode オブジェクトをエンコードし、結果を Python バイト列オブジェクトとして返します。エラー処理は "strict" です。 codec が例外を送出した場合には NULL を返します。

文字列にサロゲートコードポイント (U+D800 - U+DFFF) が含まれていると、この関数は失敗します。

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

次に属します: Stable ABI (バージョン 3.10 より).

Unicode オブジェクトを UTF-8 でエンコードしたものへのポインタを返し、エンコードされた表現形式でのサイズ (バイト単位) を size に格納します。 size 引数は NULL でも構いません; その場合はサイズは格納されません。返されるバッファには、 null コードポイントがあるかどうかに関わらず、常に null バイトが終端に付加されています (これは size には勘定されません)。

エラー時には例外を設定し、size が NULL でなければ -1 を格納して、NULL を返します。

文字列にサロゲートコードポイント (U+D800 - U+DFFF) が含まれていると、この関数は失敗します。

この関数は Unicode オブジェクト内に文字列の UTF-8 表現をキャッシュし、それ以降の呼び出しでは同じバッファへのポインタを返します。呼び出し側がバッファを解放する必要はありません。 Unicode オブジェクトがガベージコレクションで回収されるとバッファは解放され、それを指すポインタは無効になります。

Added in version 3.3.

バージョン 3.7 で変更: 戻り値の型が char * から const char * に変更されました。

バージョン 3.10 で変更: この関数が制限付き API の一部になりました。

const char *PyUnicode_AsUTF8(PyObject *unicode)¶: PyUnicode_AsUTF8AndSize() とほぼ同じですが、サイズを格納しません。

警告

この関数は、unicode の内部に含まれる null 文字を特別に扱いません。そのため、返された文字列にも null 文字が残り、一部の C 関数はそれを文字列の末尾と解釈するため、途中で切れてしまう場合があります。これが問題になる場合は、代わりに PyUnicode_AsUTF8AndSize() を使うことを推奨します。

Added in version 3.3.

バージョン 3.7 で変更: 戻り値の型が char * から const char * に変更されました。

UTF-32 Codecs¶

以下は UTF-32 codec API です:

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

戻り値: 新しい参照。 次に属します: Stable ABI.

UTF-32 でエンコードされたバッファ文字列から size バイトをデコードし、 Unicodeオブジェクトとして返します。 errors は (NULL でないなら) エラーハンドラを指定します。デフォルトは "strict" です。

byteorder が NULL でない時、デコーダは与えられたバイトオーダーでデコードを開始します。

*byteorder == -1: リトルエンディアン
*byteorder == 0:  ネイティブのバイト順
*byteorder == 1:  ビッグエンディアン

*byteorder が 0 で、入力データの最初の 4 バイトが byte order mark (BOM) ならば、デコーダはこのバイトオーダーに切り替え、BOM は結果の Unicode 文字列にコピーされません。 *byteorder が -1 または 1 ならば、全ての byte order mark は出力にコピーされます。

デコードが完了した後、入力データの終端に来た時点でのバイトオーダーを *byteorder にセットします。

byteorder が NULL のとき、 codec は native order モードで開始します。

codec が例外を発生させたときは NULL を返します。

PyObject *PyUnicode_DecodeUTF32Stateful(const char *str, Py_ssize_t size, const char *errors, int *byteorder, Py_ssize_t *consumed)¶: 戻り値: 新しい参照。 次に属します: Stable ABI.
consumed が NULL のとき、 PyUnicode_DecodeUTF32() と同じように振る舞います。 consumed が NULL でないとき、 PyUnicode_DecodeUTF32Stateful() は末尾の不完全な (4 で割り切れない長さのバイト列などの) UTF-32 バイト列をエラーとして扱いません。末尾の不完全なバイト列はデコードされず、デコードされたバイト数が consumed に格納されます。

PyObject *PyUnicode_AsUTF32String(PyObject *unicode)¶: 戻り値: 新しい参照。 次に属します: Stable ABI.
ネイティブバイトオーダーで UTF-32 エンコーディングされた Python バイト文字列を返します。文字列は常に BOM マークで始まります。エラーハンドラは "strict" です。 codec が例外を発生させたときは NULL を返します。

UTF-16 Codecs¶

以下は UTF-16 codec の APIです:

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

戻り値: 新しい参照。 次に属します: Stable ABI.

UTF-16 でエンコードされたバッファ s から size バイトだけデコードして、結果を Unicode オブジェクトで返します。 errors は (NULL でない場合) エラー処理方法を定義します。デフォルト値は "strict" です。

byteorder が NULL でない時、デコーダは与えられたバイトオーダーでデコードを開始します。

*byteorder == -1: リトルエンディアン
*byteorder == 0:  ネイティブのバイト順
*byteorder == 1:  ビッグエンディアン

*byteorder が 0 で、入力データの先頭2バイトがバイトオーダーマーク (BOM) だった場合、デコーダは BOM が示すバイトオーダーに切り替え、そのBOMを結果の Unicode 文字列にコピーしません。 *byteorder が -1 か 1 だった場合、すべてのBOMは出力へコピーされます (出力では \ufeff か \ufffe のどちらかになるでしょう)。

デコードが完了した後、入力データの終端に来た時点でのバイトオーダーを *byteorder にセットします。

byteorder が NULL のとき、 codec は native order モードで開始します。

codec が例外を発生させたときは NULL を返します。

PyObject *PyUnicode_DecodeUTF16Stateful(const char *str, Py_ssize_t size, const char *errors, int *byteorder, Py_ssize_t *consumed)¶: 戻り値: 新しい参照。 次に属します: Stable ABI.
consumed が NULL の場合、 PyUnicode_DecodeUTF16() と同じように動作します。 consumed が NULL でない場合、 PyUnicode_DecodeUTF16Stateful() は末尾の不完全な UTF-16 バイト列 (奇数長のバイト列や分割されたサロゲートペア) をエラーとみなしません。これらのバイト列はデコードされず、デコードされたバイト数を consumed に返します。

PyObject *PyUnicode_AsUTF16String(PyObject *unicode)¶: 戻り値: 新しい参照。 次に属します: Stable ABI.
ネイティブバイトオーダーで UTF-16 エンコーディングされた Python バイト文字列を返します。文字列は常に BOM マークで始まります。エラーハンドラは "strict" です。 codec が例外を発生させたときは NULL を返します。

UTF-7 Codecs¶

以下は UTF-7 codec の API です:

PyObject *PyUnicode_DecodeUTF7(const char *str, Py_ssize_t size, const char *errors)¶: 戻り値: 新しい参照。 次に属します: Stable ABI.
UTF-7 でエンコードされた文字列 str の size バイトをデコードし、Unicode オブジェクトを作成します。 codec が例外を送出した場合は NULL を返します。

PyObject *PyUnicode_DecodeUTF7Stateful(const char *str, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)¶: 戻り値: 新しい参照。 次に属します: Stable ABI.
consumed が NULL のとき、 PyUnicode_DecodeUTF7() と同じように動作します。 consumed が NULL でないとき、末尾の不完全な UTF-7 base-64 部分をエラーとしません。不完全な部分のバイト列はデコードせずに、デコードしたバイト数を consumed に格納します。

Unicode-Escape Codecs¶

以下は "Unicode Escape" codec の API です:

PyObject *PyUnicode_DecodeUnicodeEscape(const char *str, Py_ssize_t size, const char *errors)¶: 戻り値: 新しい参照。 次に属します: Stable ABI.
Unicode-Escape でエンコードされた文字列 str の size バイトをデコードし、Unicode オブジェクトを作成します。 codec が例外を送出した場合は NULL を返します。

PyObject *PyUnicode_AsUnicodeEscapeString(PyObject *unicode)¶: 戻り値: 新しい参照。 次に属します: Stable ABI.
Unicode-Escape を使い Unicode オブジェクトをエンコードし、結果を bytes オブジェクトとして返します。エラー処理は "strict" です。 codec が例外を送出した場合には NULL を返します。

Raw-Unicode-Escape Codecs¶

以下は "Raw Unicode Escape" codec の APIです:

PyObject *PyUnicode_DecodeRawUnicodeEscape(const char *str, Py_ssize_t size, const char *errors)¶: 戻り値: 新しい参照。 次に属します: Stable ABI.
Raw-Unicode-Escape でエンコードされた文字列 str の size バイトをデコードし、Unicode オブジェクトを作成します。 codec が例外を送出した場合は NULL を返します。

PyObject *PyUnicode_AsRawUnicodeEscapeString(PyObject *unicode)¶: 戻り値: 新しい参照。 次に属します: Stable ABI.
Raw-Unicode-Escape を使い Unicode オブジェクトをエンコードし、結果を bytes オブジェクトとして返します。エラー処理は "strict" です。 codec が例外を送出した場合には NULL を返します。

Latin-1 Codecs¶

以下は Latin-1 codec の APIです: Latin-1 は、 Unicode 序数の最初の 256 個に対応し、エンコード時にはこの 256 個だけを受理します。

PyObject *PyUnicode_DecodeLatin1(const char *str, Py_ssize_t size, const char *errors)¶: 戻り値: 新しい参照。 次に属します: Stable ABI.
Latin-1 でエンコードされた size バイトの文字列 str から Unicode オブジェクトを生成します。codec が例外を送出した場合には NULL を返します。

PyObject *PyUnicode_AsLatin1String(PyObject *unicode)¶: 戻り値: 新しい参照。 次に属します: Stable ABI.
Latin-1 で Unicode オブジェクトをエンコードし、結果を Python bytes オブジェクトとして返します。エラー処理は "strict" です。 codec が例外を送出した場合には NULL を返します。

ASCII Codecs¶

以下は ASCII codec の APIです。 7 ビットの ASCII データだけを受理します。その他のコードはエラーになります。

PyObject *PyUnicode_DecodeASCII(const char *str, Py_ssize_t size, const char *errors)¶: 戻り値: 新しい参照。 次に属します: Stable ABI.
ASCII でエンコードされた文字列 str の size バイトをデコードし、Unicode オブジェクトを作成します。 codec が例外を送出した場合は NULL を返します。

PyObject *PyUnicode_AsASCIIString(PyObject *unicode)¶: 戻り値: 新しい参照。 次に属します: Stable ABI.
ASCII で Unicode オブジェクトをエンコードし、結果を Python bytes オブジェクトとして返します。エラー処理は "strict" です。 codec が例外を送出した場合には NULL を返します。

Character Map Codecs¶

この codec は、多くの様々な codec を実装する際に使われるという点で特殊な codec です (実際、 encodings パッケージに入っている標準 codecs のほとんどは、この codec を使っています)。この codec は、文字のエンコードやデコードに対応表を使います。提供される対応表のオブジェクトは __getitem__() マッピングインターフェースをサポートしていなければなりません; 辞書やシーケンスがそれに適しています。

以下は mapping codec の APIです:

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

戻り値: 新しい参照。 次に属します: Stable ABI.

与えられた mapping オブジェクトを使って、 size バイトのエンコードされた文字列 str をデコードして Unicode オブジェクトを作成します。 codec が例外を発生させたときは NULL を返します。

mapping が NULL の場合は Latin-1 でデコードします。それ以外の場合、mapping はバイト値 (0 から 255 の範囲の整数) を、Unicode 文字列、整数 (Unicode の序数として解釈)、または None に対応づける必要があります。対応のないバイト、つまり LookupError を引き起こすバイトや、None、0xFFFE、'\ufffe' に対応づけられたバイトは、未定義の対応として扱い、エラーになります。

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

戻り値: 新しい参照。 次に属します: Stable ABI.

Unicode オブジェクトを mapping に指定されたオブジェクトを使ってエンコードし、結果を bytes オブジェクトとして返します。エラー処理は "strict" です。 codec が例外を送出した場合には NULL を返します。

mapping オブジェクトは、Unicode の序数を表す整数を、bytes オブジェクト、0 から 255 の範囲の整数、または None に対応づける必要があります。対応のない文字の序数 (LookupError を引き起こすもの) や、None に対応づけられたものは「未定義の対応」として扱い、エラーになります。

以下の codec API は Unicode から Unicode への対応付けを行う特殊なものです。

PyObject *PyUnicode_Translate(PyObject *unicode, PyObject *table, const char *errors)¶

戻り値: 新しい参照。 次に属します: Stable ABI.

文字列に文字対応表 table を適用して変換し、変換結果を Unicode オブジェクトで返します。codec が例外を発行した場合には NULL を返します。

対応表は、Unicode 序数を表す整数を Unicode 序数を表す整数または None (その文字を削除する) に対応付けなければなりません。

対応表には __getitem__() インターフェースだけが必要で、辞書やシーケンスを使えます。対応のない文字の序数 (LookupError を引き起こすもの) は変更せず、そのままコピーします。

errors は codecs で通常使われるのと同じ意味を持ちます。 errors は NULL にしてもよく、デフォルトエラー処理の使用を意味します。

Windows 用の MBCS codec¶

以下は MBCS codec の API です。この codec は現在のところ、 Windows 上だけで利用でき、変換の実装には Win32 MBCS 変換機構 (Win32 MBCS converter) を使っています。 MBCS (または DBCS) はエンコード方式の種類 (class) を表す言葉で、単一のエンコード方式を表すわけでなないので注意してください。利用されるエンコード方式 (target encoding) は、 codec を動作させているマシン上のユーザ設定で定義されています。

PyObject *PyUnicode_DecodeMBCS(const char *str, Py_ssize_t size, const char *errors)¶: 戻り値: 新しい参照。 次に属します: Stable ABI on Windows (バージョン 3.7 より).
MBCS でエンコードされた文字列 str の size バイトをデコードし、Unicode オブジェクトを作成します。 codec が例外を送出した場合は NULL を返します。

PyObject *PyUnicode_DecodeMBCSStateful(const char *str, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)¶: 戻り値: 新しい参照。 次に属します: Stable ABI on Windows (バージョン 3.7 より).
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)¶: 戻り値: 新しい参照。 次に属します: Stable ABI on Windows (バージョン 3.7 より).
PyUnicode_DecodeMBCSStateful() と同様ですが、code_page で指定したコードページを使います。

PyObject *PyUnicode_AsMBCSString(PyObject *unicode)¶: 戻り値: 新しい参照。 次に属します: Stable ABI on Windows (バージョン 3.7 より).
MBCS で Unicode オブジェクトをエンコードし、結果を Python バイト列オブジェクトとして返します。エラー処理は "strict" です。 codec が例外を送出した場合には NULL を返します。

PyObject *PyUnicode_EncodeCodePage(int code_page, PyObject *unicode, const char *errors)¶: 戻り値: 新しい参照。 次に属します: Stable ABI on Windows (バージョン 3.7 より).
指定されたコードページで Unicode オブジェクトをエンコードし、Python の bytes オブジェクトを返します。 codec が例外を送出した場合は NULL を返します。 MBCS エンコーダを使うには、コードページに CP_ACP を指定してください。

Added in version 3.3.

メソッドおよびスロット関数 (slot function)¶

以下の API は Unicode オブジェクトおよび文字列を入力に取り (説明では、どちらも文字列と表記しています)、場合に応じて Unicode オブジェクトか整数を返す機能を持っています。

これらの関数は全て、例外が発生した場合には NULL または -1 を返します。

PyObject *PyUnicode_Concat(PyObject *left, PyObject *right)¶: 戻り値: 新しい参照。 次に属します: Stable ABI.
二つの文字列を結合して、新たな Unicode 文字列を生成します。

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

戻り値: 新しい参照。 次に属します: Stable ABI.

文字列を分割し、Unicode 文字列のリストを返します。 sep が NULL の場合は、すべての空白部分で分割します。それ以外の場合は、指定された区切り文字列で分割します。分割回数は最大で maxsplit 回です。負の値なら回数に制限はありません。結果のリストには区切り文字列を含めません。

エラー時には例外を設定して NULL を返します。

str.split() と等価です。

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

戻り値: 新しい参照。 次に属します: Stable ABI.

PyUnicode_Split() と同様ですが、文字列の末尾から分割します。

エラー時には例外を設定して NULL を返します。

str.rsplit() と等価です。

PyObject *PyUnicode_Splitlines(PyObject *unicode, int keepends)¶: 戻り値: 新しい参照。 次に属します: Stable ABI.
Unicode 文字列を改行位置で分割し、Unicode 文字列のリストを返します。 CRLF は 1 つの改行とみなします。 keepends が 0 の場合、結果の文字列に改行文字を含めません。

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

戻り値: 新しい参照。 次に属します: Stable ABI.

Unicode 文字列を sep が最初に現れる位置で分割し、区切り文字列より前の部分、区切り文字列自体、その後の部分を含む 3 要素のタプルを返します。区切り文字列が見つからなければ、元の文字列と、その後に 2 つの空文字列を含む 3 要素のタプルを返します。

sep は空であってはなりません。

エラー時には例外を設定して NULL を返します。

str.partition() と等価です。

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

戻り値: 新しい参照。 次に属します: Stable ABI.

PyUnicode_Partition() と同様ですが、Unicode 文字列を sep が最後に現れる位置で分割します。区切り文字列が見つからなければ、2 つの空文字列と、その後に元の文字列を含む 3 要素のタプルを返します。

sep は空であってはなりません。

エラー時には例外を設定して NULL を返します。

str.rpartition() と等価です。

PyObject *PyUnicode_Join(PyObject *separator, PyObject *seq)¶: 戻り値: 新しい参照。 次に属します: Stable ABI.
指定した separator で文字列からなるシーケンスを連結 (join) し、連結結果を Unicode 文字列で返します。

Py_ssize_t PyUnicode_Tailmatch(PyObject *unicode, PyObject *substr, Py_ssize_t start, Py_ssize_t end, int direction)¶: 次に属します: Stable ABI.
substr が unicode[start:end] の指定された側の端と一致すれば 1、それ以外なら 0 を返します (direction == -1 は前方一致、direction == 1 は後方一致を意味します)。エラーが発生した場合は -1 を返します。

Py_ssize_t PyUnicode_Find(PyObject *unicode, PyObject *substr, Py_ssize_t start, Py_ssize_t end, int direction)¶: 次に属します: Stable ABI.
unicode[start:end] 中に substr が最初に出現する場所を返します。このとき指定された検索方向 direction (direction == 1 は順方向検索、 direction == -1 は逆方向検索) で検索します。戻り値は最初にマッチが見つかった場所のインデックスです; 戻り値 -1 はマッチが見つからなかったことを表し、 -2 はエラーが発生して例外情報が設定されていることを表します。

Py_ssize_t PyUnicode_FindChar(PyObject *unicode, Py_UCS4 ch, Py_ssize_t start, Py_ssize_t end, int direction)¶: 次に属します: Stable ABI (バージョン 3.7 より).
unicode[start:end] 中に文字 ch が最初に出現する場所を返します。このとき指定された検索方向 direction (direction == 1 は順方向検索、 direction == -1 は逆方向検索) で検索します。戻り値は最初にマッチが見つかった場所のインデックスです; 戻り値 -1 はマッチが見つからなかったことを表し、 -2 はエラーが発生して例外情報が設定されていることを表します。

Added in version 3.3.

バージョン 3.7 で変更: unicode[start:end] と同じ動作になるよう、start と end を調整するようになりました。

Py_ssize_t PyUnicode_Count(PyObject *unicode, PyObject *substr, Py_ssize_t start, Py_ssize_t end)¶: 次に属します: Stable ABI.
unicode[start:end] に substr が重複することなく出現する回数を返します。エラーが発生した場合には -1 を返します。

PyObject *PyUnicode_Replace(PyObject *unicode, PyObject *substr, PyObject *replstr, Py_ssize_t maxcount)¶: 戻り値: 新しい参照。 次に属します: Stable ABI.
unicode 中に出現する substr を最大で maxcount 個 replstr に置換し、置換結果である Unicode オブジェクトを返します。 maxcount == -1 にすると、文字列中に現れる全ての substr を置換します。

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

次に属します: Stable ABI.

二つの文字列を比較して、左引数が右引数より小さい場合、左右引数が等価の場合、左引数が右引数より大きい場合に対して、それぞれ -1, 0, 1 を返します。

この関数は、失敗したときに -1 を返すので、 PyErr_Occurred() を呼び出して、エラーをチェックすべきです。

参考

PyUnicode_Equal() 関数。

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

次に属します: Stable ABI (バージョン 3.14 より).

2 つの文字列が等しいか調べます:

a と b が等しければ 1 を返します。
a と b が等しくなければ 0 を返します。
a または b が str オブジェクトでなければ、TypeError 例外を設定して -1 を返します。

a と b が str オブジェクトであれば、この関数は常に成功します。

この関数は str のサブクラスにも使えますが、独自の __eq__() メソッドは考慮しません。

参考

PyUnicode_Compare() 関数。

Added in version 3.14.

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

次に属します: Stable ABI (バージョン 3.13 より).

Unicode オブジェクトと、UTF-8 または ASCII でエンコードされていると解釈する char 型バッファを比較し、等しければ真 (1)、それ以外なら偽 (0) を返します。 Unicode オブジェクトにサロゲートコードポイント (U+D800 - U+DFFF) が含まれている場合や、C 文字列が有効な UTF-8 でない場合は、偽 (0) を返します。

この関数は例外を送出しません。

Added in version 3.13.

int PyUnicode_EqualToUTF8(PyObject *unicode, const char *string)¶: 次に属します: Stable ABI (バージョン 3.13 より).
PyUnicode_EqualToUTF8AndSize() と同様ですが、string の長さを strlen() で計算します。 Unicode オブジェクトに null 文字が含まれている場合は、偽 (0) を返します。

Added in version 3.13.

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

次に属します: Stable ABI.

Unicode オブジェクト unicode と string を比較して、左引数が右引数より小さい場合、左右引数が等価の場合、左引数が右引数より大きい場合に対して、それぞれ -1, 0, 1 を返します。 ASCII エンコードされた文字列だけを渡すのが最も良いですが、入力文字列に非 ASCII 文字が含まれている場合は ISO-8859-1 として解釈します。

この関数は例外を送出しません。

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

戻り値: 新しい参照。 次に属します: Stable 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)¶: 戻り値: 新しい参照。 次に属します: Stable ABI.
新たな文字列オブジェクトを format および args から生成して返します; このメソッドは format % args のようなものです。

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

次に属します: Stable ABI.

substr が unicode 内にあるか調べ、その結果に応じて真または偽を返します。

substr は単要素の Unicode 文字に型強制できなければなりません。エラーが生じた場合には -1 を返します。

void PyUnicode_InternInPlace(PyObject **p_unicode)¶

次に属します: Stable ABI.

引数 *p_unicode をその場でインターンします。引数は、Python の Unicode 文字列オブジェクトを指すポインタ変数のアドレスでなければなりません。 *p_unicode と同じ文字列がすでにインターンされていれば、*p_unicode をその文字列に設定します (元の文字列オブジェクトへの参照を解放し、インターン済み文字列オブジェクトへの新しい強参照を作成します)。それ以外の場合は *p_unicode を変更せず、その文字列をインターンします。

(補足: 参照についての説明が多いですが、この関数は参照の数を変えないと考えてください。渡すオブジェクトへの参照を所有している必要があります。呼び出し後は渡した参照を所有しなくなり、代わりに結果への参照を新たに所有します。)

この関数は例外を送出しません。エラー時には、引数を変更せず、インターンもしません。

str のサブクラスのインスタンスはインターンできません。つまり PyUnicode_CheckExact(*p_unicode) が真でなければなりません。真でなければ、他のエラーと同様に引数を変更しません。

Note that interned strings are not “immortal”. You must keep a reference to the result to benefit from interning.

PyObject *PyUnicode_InternFromString(const char *str)¶

戻り値: 新しい参照。 次に属します: Stable ABI.

PyUnicode_FromString() と PyUnicode_InternInPlace() を組み合わせたもので、静的に割り当てられた文字列用です。

新しく作成してインターンした Unicode 文字列オブジェクト、または同じ値を持つ以前にインターン済みの文字列オブジェクトへの、新しい (「所有する」) 参照を返します。

Python が結果への参照を保持したり、結果を不死にしたりすることで、すぐにはガベージコレクションで回収されない場合があります。ユーザー入力など、異なる文字列を上限なくインターンする場合は、PyUnicode_FromString() と PyUnicode_InternInPlace() を直接呼び出すことを推奨します。

unsigned int PyUnicode_CHECK_INTERNED(PyObject *str)¶: str がインターン済みならゼロ以外の値、そうでなければゼロを返します。 str 引数は文字列でなければなりませんが、検査は行いません。この関数は常に成功します。

ゼロ以外の戻り値には、文字列が どのように インターンされているかについての追加情報が含まれる場合があります。これらの値の意味や、各文字列のインターンに関する詳細は、CPython のバージョンによって変わる可能性があります。

PyUnicodeWriter¶

PyUnicodeWriter API を使って Python の str オブジェクトを作成できます。

Added in version 3.14.

type PyUnicodeWriter¶

Unicode ライターのインスタンスです。

成功時には PyUnicodeWriter_Finish()、エラー時には PyUnicodeWriter_Discard() でインスタンスを破棄する必要があります。

この API は スレッドセーフではありません。複数のスレッドでライターを共有するには、クリティカルセクションまたはロックが必要です。

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 を 1 文字、writer に書き込みます。

成功すると 0 を返します。エラー時には例外を設定し、ライターは変更せずに -1 を返します。

int PyUnicodeWriter_WriteUTF8(PyUnicodeWriter *writer, const char *str, Py_ssize_t size)¶

文字列 str を UTF-8 の strict モードでデコードし、結果を writer に書き込みます。

size はバイト単位の文字列の長さです。 size が -1 の場合は strlen(str) を呼び出して文字列の長さを取得します。

成功すると 0 を返します。エラー時には例外を設定し、ライターは変更せずに -1 を返します。

PyUnicodeWriter_DecodeUTF8Stateful() も参照してください。

int PyUnicodeWriter_WriteASCII(PyUnicodeWriter *writer, const char *str, Py_ssize_t size)¶

ASCII 文字列 str を writer に書き込みます。

size はバイト単位の文字列の長さです。 size が -1 の場合は strlen(str) を呼び出して文字列の長さを取得します。

str は ASCII 文字だけを含む必要があります。非 ASCII 文字が含まれている場合、動作は未定義です。

成功すると 0 を返します。エラー時には例外を設定し、ライターは変更せずに -1 を返します。

int PyUnicodeWriter_WriteWideChar(PyUnicodeWriter *writer, const wchar_t *str, Py_ssize_t size)¶

ワイド文字列 str を writer に書き込みます。

size はワイド文字の数です。 size が -1 の場合は wcslen(str) を呼び出して文字列の長さを取得します。

成功すると 0 を返します。エラー時には例外を設定し、ライターは変更せずに -1 を返します。

int PyUnicodeWriter_WriteUCS4(PyUnicodeWriter *writer, const Py_UCS4 *str, Py_ssize_t size)¶

UCS4 文字列 str を writer に書き込みます。

size は UCS4 文字の数です。

すべての文字は [U+0000; U+10ffff] の範囲内でなければなりません。文字列に無効な文字が含まれている場合、動作は未定義です。

成功すると 0 を返します。エラー時には例外を設定し、ライターは変更せずに -1 を返します。

int PyUnicodeWriter_WriteStr(PyUnicodeWriter *writer, PyObject *obj)¶

obj に対して PyObject_Str() を呼び出し、結果を writer に書き込みます。

成功すると 0 を返します。エラー時には例外を設定し、ライターは変更せずに -1 を返します。

__str__() メソッドをオーバーライドする str サブクラスを書き込むには、PyUnicode_FromObject() を使って元の文字列を取得できます。

int PyUnicodeWriter_WriteRepr(PyUnicodeWriter *writer, PyObject *obj)¶

obj に対して PyObject_Repr() を呼び出し、結果を writer に書き込みます。

obj が NULL の場合は、文字列 "<NULL>" を writer に書き込みます。

成功すると 0 を返します。エラー時には例外を設定し、ライターは変更せずに -1 を返します。

バージョン 3.14.4 で変更: NULL のサポートが追加されました。

int PyUnicodeWriter_WriteSubstring(PyUnicodeWriter *writer, PyObject *str, Py_ssize_t start, Py_ssize_t end)¶

部分文字列 str[start:end] を writer に書き込みます。

str は Python の str オブジェクトでなければなりません。 start は 0 以上かつ end 以下、end は str の長さ以下でなければなりません。

成功すると 0 を返します。エラー時には例外を設定し、ライターは変更せずに -1 を返します。

int PyUnicodeWriter_Format(PyUnicodeWriter *writer, const char *format, ...)¶

PyUnicode_FromFormat() と同様ですが、出力を直接 writer に書き込みます。

成功すると 0 を返します。エラー時には例外を設定し、ライターは変更せずに -1 を返します。

int PyUnicodeWriter_DecodeUTF8Stateful(PyUnicodeWriter *writer, const char *string, Py_ssize_t length, const char *errors, Py_ssize_t *consumed)¶

エラーハンドラ errors を使って文字列 str を UTF-8 からデコードし、結果を writer に書き込みます。

size はバイト単位の文字列の長さです。 size が -1 の場合は strlen(str) を呼び出して文字列の長さを取得します。

errors は "replace" などのエラーハンドラの名前です。 errors が NULL の場合は strict エラーハンドラを使います。

consumed が NULL でなければ、成功時に *consumed にデコードしたバイト数を設定します。 consumed が NULL の場合は、末尾の不完全な UTF-8 バイト列をエラーとして扱います。

成功すると 0 を返します。エラー時には例外を設定し、ライターは変更せずに -1 を返します。

PyUnicodeWriter_WriteUTF8() も参照してください。

非推奨の API¶

以下の API は非推奨です。

type Py_UNICODE¶: これは wchar_t の typedef であり、プラットフォームに応じて 16 ビットまたは 32 ビットの型になります。代わりに wchar_t を直接使ってください。

バージョン 3.3 で変更: 以前のバージョンでは、Pythonをビルドした際に "narrow" または "wide" Unicode バージョンのどちらを選択したかによって、 16ビットか32ビットのどちらかの型になっていました。

バージョン 3.13 で非推奨、バージョン 3.15 で削除.

int PyUnicode_READY(PyObject *unicode)¶: 何もせずに 0 を返します。この API は後方互換性のためだけに残されていますが、削除する予定はありません。

Added in version 3.3.

バージョン 3.10 で非推奨: Python 3.12 以降、この API は何もしません。以前は、古い API (PyUnicode_FromUnicode() など) で作成した文字列ごとに呼び出す必要がありました。

unsigned int PyUnicode_IS_READY(PyObject *unicode)¶: 何もせずに 1 を返します。この API は後方互換性のためだけに残されていますが、削除する予定はありません。

Added in version 3.3.

バージョン 3.14 で非推奨: Python 3.12 以降、この API は何もしません。以前は、PyUnicode_READY() が必要かどうかを調べるために呼び出せました。

Unicode オブジェクトと codec¶