buffer 構造体¶

バッファ構造体（または単純に "buffers"）は別のオブジェクトのバイナリデータをPythonプログラマに提供するのに便利です。これはまた、ゼロコピースライシング機構としても使用できます。このメモリブロックを参照する機能を使うことで、どんなデータでもとても簡単にPythonプログラマに提供することができます。メモリは、C 拡張の大きな配列定数かもしれませんし、オペレーティングシステムライブラリに渡す前のメモリブロックかもしれませんし、構造化データをネイティブのインメモリ形式受け渡すのに使用されるかもしれません。

Pythonインタプリタによって提供される多くのデータ型とは異なり、バッファはPyObject ポインタではなく、シンプルなC 構造体です。そのため、作成とコピーが非常に簡単に行えます。バッファの一般的なラッパーが必要なときは、memoryview オブジェクトが作成されます。

エクスポートされるオブジェクトを書く方法の短い説明には、Buffer Object Structures を参照してください。バッファを取得するには、PyObject_GetBuffer() を参照してください。

typePy_buffer¶

次に属します:Stable ABI (すべてのメンバーを含む) (バージョン 3.11 より).

void*buf¶

バッファフィールドが表している論理構造の先頭を指すポインタ。バッファを提供するオブジェクトの下層物理メモリブロック中のどの位置にもなりえます。例えばstrides が負だと、この値はメモリブロックの末尾かもしれません。

連続 配列の場合この値はメモリブロックの先頭を指します。

PyObject*obj¶

エクスポート対象オブジェクトへの新しい参照。この参照は消費者によって所有され、自動的に解放されます（つまり、参照カウントが減少します）し、設定されますNULL byPyBuffer_Release(). このフィールドは、標準のC-API関数の戻り値に相当します。

PyMemoryView_FromBuffer() またはPyBuffer_FillInfo() によってラップされた一時的な バッファである特別なケースでは、このフィールドはNULL です。一般的に、エクスポートオブジェクトはこの方式を使用してはなりません。

Py_ssize_tlen¶

product(shape)*itemsize。contiguous配列では、下層のメモリブロックの長さになります。非contiguous 配列では、contiguous表現にコピーされた場合に論理構造がもつ長さです。

((char*)buf)[0] から((char*)buf)[len-1] の範囲へのアクセスは、連続性 (contiguity) を保証するリクエストによって取得されたバッファに対してのみ許されます。多くの場合に、そのようなリクエストはPyBUF_SIMPLE またはPyBUF_WRITABLE です。

intreadonly¶

バッファが読み出し専用であるか示します。このフィールドはPyBUF_WRITABLE フラグで制御できます。

Py_ssize_titemsize¶

要素一つ分のbyte単位のサイズ。struct.calcsize() を非NULL のformat 値に対して呼び出した結果と同じです。

重要な例外: 消費者がPyBUF_FORMAT フラグを設定することなくバッファを要求した場合、format はNULL に設定されます。しかしitemsize は元のフォーマットに従った値を保持します。

shape が存在する場合、product(shape)*itemsize==len の等式が守られ、利用者はitemsize を buffer を読むために利用できます。

PyBUF_SIMPLE またはPyBUF_WRITABLE で要求した結果、shape がNULL であれば、消費者はitemsize を無視してitemsize==1 と見なさなければなりません。

char*format¶

ANULL terminated string instruct module style syntax describingthe contents of a single item. If this isNULL,"B" (unsigned bytes)is assumed.

このフィールドはPyBUF_FORMAT フラグによって制御されます。

intndim¶

The number of dimensions the memory represents as an n-dimensional array.If it is0,buf points to a single item representinga scalar. In this case,shape,stridesandsuboffsets MUST beNULL.The maximum number of dimensions is given byPyBUF_MAX_NDIM.

Py_ssize_t*shape¶

メモリ上のN次元配列の形を示す、長さがndim であるPy_ssize_t の配列です。shape[0]*...*shape[ndim-1]*itemsize はlen と等しくなければなりません。

shape の値はshape[n]>=0 に制限されます。shape[n]==0 の場合に特に注意が必要です。詳細はcomplex arrays を参照してください。

shepe (形状) 配列は利用者からは読み出し専用です。

Py_ssize_t*strides¶

各次元において新しい値を得るためにスキップするバイト数を示す、長さndim のPy_ssize_t の配列。

ストライド値は、任意の整数を指定できます。規定の配列では、ストライドは通常でいけば有効です。しかし利用者は、strides[n]<=0 のケースを処理することができる必要があります。詳細についてはcomplex arrays を参照してください。

消費者にとって、この strides 配列は読み出し専用です。

Py_ssize_t*suboffsets¶

Py_ssize_t 型の要素を持つ長さndim の配列。suboffsets[n]>=0 の場合は、 n 番目の次元に沿って保存されている値はポインタで、 suboffset 値は各ポインタの参照を解決した後に何バイト加えればいいかを示しています。suboffset の値が負の数の場合は、ポインタの参照解決は不要 (連続したメモリブロック内に直接配置されいる) ということになります。

全ての suboffset が負数の場合 (つまり参照解決が不要) な場合、このフィールドはNULL (デフォルト値) でなければなりません。

この種の配列表現は Python Imaging Library (PIL) で使われています。このような配列で要素にアクセスする方法についてさらに詳しことはcomplex arrays を参照してください。

消費者にとって、suboffsets 配列は読み出し専用です。

void*internal¶

バッファを提供する側のオブジェクトが内部的に利用するための変数です。例えば、提供側はこの変数に整数型をキャストして、shape, strides, suboffsets といった配列をバッファを開放するときに同時に解放するべきかどうかを管理するフラグに使うことができるでしょう。バッファを受け取る側は、この値を決して変更してはなりません。

Constants:

PyBUF_MAX_NDIM¶

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

The maximum number of dimensions the memory represents.Exporters MUST respect this limit, consumers of multi-dimensionalbuffers SHOULD be able to handle up toPyBUF_MAX_NDIM dimensions.Currently set to 64.

バッファリクエストのタイプ¶

バッファは通常、PyObject_GetBuffer() を使うことで、エクスポートするオブジェクトにバッファリクエストを送ることで得られます。メモリの論理的な構造の複雑性は多岐にわたるため、消費者はflags 引数を使って、自身が扱えるバッファの種類を指定します。

Py_buffer の全フィールドは、リクエストの種類によって曖昧さを残さずに定義されます。

複雑な配列¶

ptr=(char*)buf+indices[0]*strides[0]+...+indices[n-1]*strides[n-1];item=*((typeof(item)*)ptr);

defverify_structure(memlen,itemsize,ndim,shape,strides,offset):"""Verify that the parameters represent a valid array within       the bounds of the allocated memory:           char *mem: start of the physical memory block           memlen: length of the physical memory block           offset: (char *)buf - mem    """ifoffset%itemsize:returnFalseifoffset<0oroffset+itemsize>memlen:returnFalseifany(v%itemsizeforvinstrides):returnFalseifndim<=0:returnndim==0andnotshapeandnotstridesif0inshape:returnTrueimin=sum(strides[j]*(shape[j]-1)forjinrange(ndim)ifstrides[j]<=0)imax=sum(strides[j]*(shape[j]-1)forjinrange(ndim)ifstrides[j]>0)return0<=offset+iminandoffset+imax+itemsize<=memlen

void*get_item_pointer(intndim,void*buf,Py_ssize_t*strides,Py_ssize_t*suboffsets,Py_ssize_t*indices){char*pointer=(char*)buf;inti;for(i=0;i<ndim;i++){pointer+=strides[i]*indices[i];if(suboffsets[i]>=0){pointer=*((char**)pointer)+suboffsets[i];}}return(void*)pointer;}

バッファ関連の関数¶

intPyObject_CheckBuffer(PyObject*obj)¶

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

obj がbuffer インターフェースをサポートしている場合は1 を返し、そうでない場合は0 を返します。1 を返したとしても、PyObject_GetBuffer() が成功することは保証されません。この関数は常に成功します。

intPyObject_GetBuffer(PyObject*exporter,Py_buffer*view,intflags)¶

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

exporter にflags で指定された方法でview を埋めるように要求します。もし exporter が指定されたとおりにバッファを提供できない場合、BufferError を送出し、view->obj をNULL に設定した上で、-1 を返さなければなりません。

成功したときは、view を埋め、view->obj にexporter への新しい参照を設定し、0を返します。チェイン状のバッファプロバイダがリクエストを単一のオブジェクトにリダイレクトするケースでは、view->obj はexporter の代わりにこのオブジェクトを参照します (バッファオブジェクト構造体 を参照してください)。

malloc() とfree() のように、呼び出しに成功したPyObject_GetBuffer() と対になるPyBuffer_Release() の呼び出しがなけれなればなりません。従って、バッファの利用が済んだらPyBuffer_Release() が厳密に1回だけ呼び出されなければなりません。

voidPyBuffer_Release(Py_buffer*view)¶

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

Release the bufferview and release thestrong reference(i.e. decrement the reference count) to the view's supporting object,view->obj. This function MUST be called when the bufferis no longer being used, otherwise reference leaks may occur.

PyObject_GetBuffer() を通して取得していないバッファに対してこの関数を呼び出すのは間違いです。

Py_ssize_tPyBuffer_SizeFromFormat(constchar*format)¶

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

Return the implieditemsize fromformat.On error, raise an exception and return -1.

Added in version 3.9.

intPyBuffer_IsContiguous(constPy_buffer*view,charorder)¶

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

view で定義されているメモリが、 C スタイル (order =='C') のときか、 Fortran スタイル (order =='F')連続 のときか、そのいずれか (order =='A') であれば1 を返します。それ以外の場合は0 を返します。この関数は常に成功します。

void*PyBuffer_GetPointer(constPy_buffer*view,constPy_ssize_t*indices)¶

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

与えられたview 内にあるindices が指すメモリ領域を取得します。indices はview->ndim 個のインデックスからなる配列を指していなければなりません。

intPyBuffer_FromContiguous(constPy_buffer*view,constvoid*buf,Py_ssize_tlen,charfort)¶

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

連続するlen バイトをbuf からview にコピーします。fort には'C' か'F' を指定できます（それぞれC言語スタイルとFortranスタイルの順序を表します)。成功時には0、エラー時には-1 を返します。

intPyBuffer_ToContiguous(void*buf,constPy_buffer*src,Py_ssize_tlen,charorder)¶

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

src からlen バイトを連続表現でbuf 上にコピーします。order は'C' または'F' または'A' (C スタイル順序または Fortran スタイル順序またはそれ以外) が指定できます。成功したら0 が返り、エラーなら-1 が返ります。

len !=src->len の場合、この関数は失敗します。

intPyObject_CopyData(PyObject*dest,PyObject*src)¶

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

Copy data fromsrc todest buffer. Can convert between C-style andor Fortran-style buffers.

成功したら0 が、エラー時には-1 が返されます。

voidPyBuffer_FillContiguousStrides(intndims,Py_ssize_t*shape,Py_ssize_t*strides,intitemsize,charorder)¶

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

strides 配列を、itemsize の大きさの要素がバイト単位の、shape の形をした連続な (order が'C' なら C-style 、'F' なら Fortran-style の) 多次元配列として埋める。

intPyBuffer_FillInfo(Py_buffer*view,PyObject*exporter,void*buf,Py_ssize_tlen,intreadonly,intflags)¶

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

サイズがlen のbuf をreadonly に従った書き込み可/不可の設定で公開するバッファリクエストを処理します。buf は符号無しバイトの列として解釈されます。

flags 引数はリクエストのタイプを示します。この関数は、buf が読み出し専用と指定されていて、flags にPyBUF_WRITABLE が設定されていない限り、常にフラグに指定された通りにview を埋めます。

On success, setview->obj to a new reference toexporter andreturn 0. Otherwise, raiseBufferError, setview->obj toNULL and return-1;

この関数をgetbufferproc の一部として使う場合には、exporter はエクスポートするオブジェクトに設定しなければならず、さらにflags は変更せずに渡さなければなりません。そうでない場合は、exporter はNULL でなければなりません。