7.3.3 Buffer Objects

C で実装された Python オブジェクトは、``バッファインタフェース (buffer interface)'' と呼ばれる一連の関数を公開していることがあります。これらの関数は、あるオブジェクトのデータを生 (raw) のバイト列形式で公開するために使います。このオブジェクトの使い手は、バッファインタフェースを使うことで、オブジェクトをあらかじめコピーしておく必要なしに、オブジェクトのデータに直接アクセスできます。

バッファインタフェースをサポートするオブジェクトの例として、文字列型とアレイ (array) 型の二つがあります。文字列オブジェクトは、その内容をバッファインタフェースのバイト単位形式で公開しています。アレイもその内容を公開していますが、注意する必要があるのはアレイの要素は複数バイトの値になりうる、ということです。

バッファインタフェースの使い手の一例として、ファイルオブジェクトの write() メソッドがあります。バッファインタフェースを介してバイト列を公開しているオブジェクトは全て、ファイルへの書き出しができます。オブジェクトのバッファインタフェースを操作し、対象となるオブジェクトからデータを返させる PyArg_ParseTuple() には数多くのデータ書式化コードがあります。

バッファインタフェースに関するより詳しい情報は、 ``バッファオブジェクト構造体'' 節 ( 10.7 節) の、 PyBufferProcs の説明のところにあります。

``バッファオブジェクト'' はヘッダファイル bufferobject.h の中で定義されています (このファイルは Python.h がインクルードしています)。バッファオブジェクトは、 Python プログラミングのレベルからは文字列オブジェクトと非常によく似ているように見えます: スライス、インデクス指定、結合、その他標準の文字列操作をサポートしています。しかし、バッファオブジェクトのデータは二つのデータソース: 何らかのメモリブロックか、バッファインタフェースを公開している別のオブジェクト、のいずれかに由来しています。

バッファオブジェクトは、他のオブジェクトのバッファインタフェースから Python プログラマにデータを公開する方法として便利です。バッファオブジェクトはゼロコピーなスライス機構 (zero-copy slicing mechanism) としても使われます。ブロックメモリを参照するというバッファオブジェクトの機能を使うことで、任意のデータをきわめて簡単に Python プログラマに公開できます。メモリブロックは巨大でもかまいませんし、C 拡張モジュール内の定数配列でもかまいません。また、オペレーティングシステムライブラリ側に渡す前の、操作用の生のブロックメモリでもかまいませんし、構造化されたデータをネイティブのメモリ配置形式でやりとりするためにも使えます。

PyBufferObject: この PyObject のサブタイプはバッファオブジェクトを表現します。

PyTypeObject PyBuffer_Type: Python バッファ型 (buffer type) を表現するPyTypeObject です; Python レイヤにおける buffer や types.BufferType と同じオブジェクトです。

int Py_END_OF_BUFFER: この定数は、PyBuffer_FromObject() またはの PyBuffer_FromReadWriteObject() size パラメタに渡します。このパラメタを渡すと、PyBufferObject は指定された offset からバッファの終わりまでを base オブジェクトとして参照します。このパラメタを使うことで、関数の呼び出し側が base オブジェクトのサイズを調べる必要がなくなります。

int PyBuffer_Check( PyObject *p): 引数がPyBuffer_Type 型のときに真を返します。

PyObject* PyBuffer_FromObject( PyObject *base, Py_ssize_t offset, Py_ssize_t size): 戻り値: 新たな参照.
新たな読み出し専用バッファオブジェクトを返します。base が読み出し専用バッファに必要なバッファプロトコルをサポートしていない場合や、厳密に一つのバッファセグメントを提供していない場合には TypeError を送出し、offset がゼロ以下の場合には ValueError を送出します。バッファオブジェクトはは base オブジェクトに対する参照を保持し、バッファオブジェクトのの内容は base オブジェクトの offset から size バイトのバッファインタフェースへの参照になります。 size が Py_END_OF_BUFFER の場合、新たに作成するバッファオブジェクトの内容は base から公開されているバッファの末尾までにわたります。

PyObject* PyBuffer_FromReadWriteObject( PyObject *base, Py_ssize_t offset, Py_ssize_t size): 戻り値: 新たな参照.
新たな書き込み可能バッファオブジェクトを返します。パラメタおよび例外は PyBuffer_FromObject と同じです。base オブジェクトが書き込み可能バッファに必要なバッファプロトコルを公開していない場合、TypeError を送出します。

PyObject* PyBuffer_FromMemory( void *ptr, Py_ssize_t size): 戻り値: 新たな参照.
メモリ上の指定された場所から指定されたサイズのデータを読み出せる、新たな読み出し専用バッファオブジェクトを返します。この関数が返すバッファオブジェクトが存続する間、ptr で与えられたメモリバッファがデアロケートされないようにするのは呼び出し側の責任です。size がゼロ以下の場合にはValueError を送出します。size には Py_END_OF_BUFFER を指定しては なりません; 指定すると、ValueError を送出します。

PyObject* PyBuffer_FromReadWriteMemory( void *ptr, Py_ssize_t size): 戻り値: 新たな参照.
PyBuffer_FromMemory() に似ていますが、書き込み可能なバッファを返します。

PyObject* PyBuffer_New( Py_ssize_t size): 戻り値: 新たな参照.
size バイトのメモリバッファを独自に維持する新たな書き込み可能バッファオブジェクトを返します。 size がゼロまたは正の値でない場合、ValueError を送出します。(PyObject_AsWriteBuffer() が返すような) メモリバッファは特に整列されていないので注意して下さい。

ご意見やご指摘をお寄せになりたい方は、 このドキュメントについて... をご覧ください。