バイトオブジェクト

下記の関数は、バイトオブジェクトを期待している引数にバイトオブジェクトでないパラメタを指定して呼び出されると、 TypeError を送出します。

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

type PyBytesObject

この PyObject のサブタイプは、Python バイトオブジェクトを表します。

PyTypeObject PyBytes_Type

次に属します: Stable ABI.

この PyTypeObject のインスタンスは、Python バイト型を表します; Pythonレイヤの bytes と同じオブジェクトです。

int PyBytes_Check(PyObject *o)

オブジェクト o が bytes オブジェクトか bytes 型のサブタイプのインスタンスである場合に真を返します。この関数は常に成功します。

int PyBytes_CheckExact(PyObject *o)

オブジェクト o が bytes オブジェクトだが bytes 型のサブタイプのインスタンスでない場合に真を返します。この関数は常に成功します。

PyObject *PyBytes_FromString(const char *v)

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

成功時に、文字列 v のコピーを値とする新しいバイトオブジェクトを返し、失敗時に NULL を返します。 引数 v は NULL であってはなりません; そのチェックは行われません。

PyObject *PyBytes_FromStringAndSize(const char *v, Py_ssize_t len)

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

成功時に、文字列 v のコピーを値とする長さ len の新しいバイトオブジェクトを返し、失敗時に NULL を返します。 引数 v が NULL の場合、バイトオブジェクトの中身は初期化されていません。

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

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

C 関数の printf() スタイルの format 文字列と可変長の引数を取り、結果のPython バイトオブジェクトのサイズを計算し、値を指定した書式にしたがって変換したバイトオブジェクトを返します。可変長の引数は C のデータ型でなければならず、 format 文字列中のフォーマット文字と厳密に関連付けられていなければなりません。下記のフォーマット文字が使用できます:

書式指定文字	型	備考
%%	n/a	リテラルの % 文字
%c	int	C の整数型で表現される単一のバイト。
%d	int	printf("%d") と同等。 [1]
%u	unsigned int	printf("%u") と同等。 [1]
%ld	long	printf("%ld") と同等。 [1]
%lu	unsigned long	printf("%lu") と同等。 [1]
%zd	Py_ssize_t	printf("%zd") と同等。 [1]
%zu	size_t	printf("%zu") と同等。 [1]
%i	int	printf("%i") と同等。 [1]
%x	int	printf("%x") と同等。 [1]
%s	const char*	null で終端された C の文字列。
%p	const void*	C ポインタの 16 進表記。printf("%p") とほとんど同じですが、プラットフォームにおける printf の定義に関わりなく先頭にリテラル 0x が付きます。

識別できない書式指定文字があった場合、残りの書式文字列はそのまま結果のオブジェクトにコピーされ、残りの引数は無視されます。

[1] (1,2,3,4,5,6,7,8)

整数指定子 (d, u, ld, lu, zd, zu, i, x): 精度が与えられていても、0指定子は有効です。

PyObject *PyBytes_FromFormatV(const char *format, va_list vargs)

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

ちょうど２つの引数を取ることを除いて、 PyBytes_FromFormat() と同じです。

PyObject *PyBytes_FromObject(PyObject *o)

戻り値: 新しい参照。 次に属します: Stable ABI. Thread safety: Safe for concurrent use on the same object.

バッファプロトコルを実装するオブジェクト o のバイト表現を返します。

注釈

オブジェクトがバッファプロトコルを実装している場合、bytes オブジェクトの作成中にそのバッファを変更してはいけません。

Py_ssize_t PyBytes_Size(PyObject *o)

次に属します: Stable ABI. Thread safety: Atomic.

バイトオブジェクト o のバイト単位の長さを返します。

Py_ssize_t PyBytes_GET_SIZE(PyObject *o)

Thread safety: Atomic.

PyBytes_Size() に似ていますが、エラーチェックを行いません。

char *PyBytes_AsString(PyObject *o)

次に属します: Stable ABI. Thread safety: Safe to call from multiple threads with external synchronization only.

o の内容へのポインタを返します。 このポインタは len(o) + 1 バイトからなる o の内部バッファを参照します。 内部に他の null バイトがあるかどうかにかかわらず、バッファの最後のバイトは常に null です。 PyBytes_FromStringAndSize(NULL, size) で作成したばかりのオブジェクトでない限り、データを変更してはいけません。 このバッファを解放してはいけません。 o が bytes オブジェクトでなければ、PyBytes_AsString() は NULL を返し、TypeError を送出します。

char *PyBytes_AS_STRING(PyObject *string)

Thread safety: Safe to call from multiple threads with external synchronization only.

PyBytes_AsString() に似ていますが、エラーチェックを行いません。

int PyBytes_AsStringAndSize(PyObject *obj, char **buffer, Py_ssize_t *length)

次に属します: Stable ABI. Thread safety: Safe to call from multiple threads with external synchronization only.

出力変数 buffer と length を通じて、オブジェクト obj の null 終端された内容を返します。 成功すると 0 を返します。

length が NULL の場合、bytes オブジェクトの内部に null バイトが含まれていてはいけません。 含まれている場合は -1 を返し、ValueError を送出します。

buffer は obj の内部バッファを参照します。 このバッファには末尾に追加の null バイトが含まれます (length には数えません)。 PyBytes_FromStringAndSize(NULL, size) で作成したばかりのオブジェクトでない限り、データを変更してはいけません。 このバッファを解放してはいけません。 obj が bytes オブジェクトでなければ、PyBytes_AsStringAndSize() は -1 を返し、TypeError を送出します。

バージョン 3.5 で変更: 以前は bytes オブジェクトにヌルバイトが埋め込まれていたときに TypeError を送出していました。

void PyBytes_Concat(PyObject **bytes, PyObject *newpart)

次に属します: Stable ABI. Thread safety: Safe for concurrent use on the same object.

bytes の内容に newpart の内容を追加した新しい bytes オブジェクトを *bytes に作成します。 呼び出し側はこの新しい参照を所有します。 bytes の元の値への参照は「盗まれます」。 新しいオブジェクトを作成できない場合も、bytes の元の参照は「盗まれ」、*bytes の値は NULL に設定され、適切な例外が設定されます。

注釈

newpart がバッファプロトコルを実装している場合、新しい bytes オブジェクトの作成中にそのバッファを変更してはいけません。

void PyBytes_ConcatAndDel(PyObject **bytes, PyObject *newpart)

次に属します: Stable ABI. Thread safety: Safe for concurrent use on the same object.

bytes の内容に newpart の内容を追加した新しい bytes オブジェクトを *bytes に作成します。 この関数は newpart への 強参照 を解放します (つまり参照カウントを減らします)。

注釈

newpart がバッファプロトコルを実装している場合、新しい bytes オブジェクトの作成中にそのバッファを変更してはいけません。

PyObject *PyBytes_Join(PyObject *sep, PyObject *iterable)

Thread safety: Safe for concurrent use on the same object.

Python の sep.join(iterable) と同様です。

sep は Python の bytes オブジェクトでなければなりません。 (PyUnicode_Join() は区切り文字として NULL を受け取り、空白として扱いますが、PyBytes_Join() は区切り文字に NULL を受け付けません。)

iterable は バッファプロトコル を実装するオブジェクトを生成するイテラブルオブジェクトでなければなりません。

成功すると新しい bytes オブジェクトを返します。 エラー時には例外を設定して NULL を返します。

Added in version 3.14.

注釈

iterable のオブジェクトがバッファプロトコルを実装している場合、新しい bytes オブジェクトの作成中にそれらのバッファを変更してはいけません。

int _PyBytes_Resize(PyObject **bytes, Py_ssize_t newsize)

Thread safety: Safe to call without external synchronization on distinct objects.

bytes オブジェクトのサイズを変更します。 newsize が bytes オブジェクトの新しい長さになります。 新しい bytes オブジェクトを作成して古いものを破棄する操作を、より効率よく行うものと考えることができます。 既存の bytes オブジェクトのアドレスを左辺値 (書き込みが行われる可能性があります) として渡し、希望する新しいサイズを指定します。 成功すると *bytes はサイズ変更後の bytes オブジェクトを保持し、0 を返します。 *bytes のアドレスは入力時の値と異なる場合があります。 再割り当てに失敗すると、*bytes の元の bytes オブジェクトを解放し、*bytes に NULL を設定し、MemoryError を設定して -1 を返します。

PyObject *PyBytes_Repr(PyObject *bytes, int smartquotes)

次に属します: Stable ABI. Thread safety: Atomic.

bytes の文字列表現を取得します。 現在、この関数は Python の bytes.__repr__() の実装に使われています。

この関数は型チェックを行いません。 bytes に bytes オブジェクト以外のオブジェクトや NULL を渡すと、動作は未定義です。

smartquotes が真の場合、bytes にシングルクォートが含まれていれば、その表現にはシングルクォートの代わりにダブルクォートで囲んだ文字列を使います。 例えば、バイト文字列 'Python' の表現は、smartquotes が真なら b"'Python'"、偽なら b'\'Python\'' となります。

成功すると、この関数は表現を格納した str オブジェクトへの 強参照 を返します。 失敗すると例外を設定して NULL を返します。

PyObject *PyBytes_DecodeEscape(const char *s, Py_ssize_t len, const char *errors, Py_ssize_t unicode, const char *recode_encoding)

次に属します: Stable ABI. Thread safety: Atomic.

バックスラッシュでエスケープされた文字列 s のエスケープを解除します。 s は NULL であってはなりません。 len は s のサイズでなければなりません。

errors は "strict"、"replace"、"ignore" のいずれかでなければなりません。 errors が NULL の場合、デフォルトで "strict" を使います。

成功すると、この関数はエスケープを解除した文字列を格納する Python の bytes オブジェクトへの 強参照 を返します。 失敗すると例外を設定して NULL を返します。

バージョン 3.9 で変更: unicode と recode_encoding は使われなくなりました。