タプルオブジェクト (tuple object)
*********************************

type PyTupleObject

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

PyTypeObject PyTuple_Type
    * 次に属します: Stable ABI.*

   この "PyTypeObject" のインスタンスは Python のタプル型を表現します;
   Python レイヤにおける "tuple" と同じオブジェクトです。

int PyTuple_Check(PyObject *p)

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

int PyTuple_CheckExact(PyObject *p)

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

PyObject *PyTuple_New(Py_ssize_t len)
    *戻り値: 新しい参照。** 次に属します: Stable ABI.** Thread safety:
   Atomic.*

   サイズ "len" の新しいタプルオブジェクトを返します。 失敗した場合は
   例外を設定して "NULL" を返します。

PyObject *PyTuple_FromArray(PyObject *const *array, Py_ssize_t size)
    * Thread safety: Atomic.*

   要素数 "size" のタプルを作成し、"array" から新しいタプルに参照をコ
   ピーします。

   "size" が "0" の場合、"array" は "NULL" でも構いません。

   成功した場合は新しい参照を返します。 エラーの場合は例外を設定して
   "NULL" を返します。

   Added in version 3.15.

PyObject *PyTuple_Pack(Py_ssize_t n, ...)
    *戻り値: 新しい参照。** 次に属します: Stable ABI.** Thread safety:
   Atomic.*

   サイズ "n" の新しいタプルオブジェクトを返します。 失敗した場合は例
   外を設定して "NULL" を返します。 タプルの各値は、続く "n" 個の C 引
   数が指す Python オブジェクトで初期化されます。 "PyTuple_Pack(2, a,
   b)" は "Py_BuildValue("(OO)", a, b)" と同等です。

Py_ssize_t PyTuple_Size(PyObject *p)
    * 次に属します: Stable ABI.** Thread safety: Atomic.*

   タプルオブジェクトへのポインタを受け取り、そのタプルのサイズを返し
   ます。 エラーの場合は例外を設定して "-1" を返します。

Py_ssize_t PyTuple_GET_SIZE(PyObject *p)
    * Thread safety: Atomic.*

   "PyTuple_Size()" と同様ですが、エラーチェックを行いません。

PyObject *PyTuple_GetItem(PyObject *p, Py_ssize_t pos)
    *戻り値: 借用参照。** 次に属します: Stable ABI.** Thread safety:
   Safe to call from multiple threads with external synchronization
   only.*

   *p* の指すタプルオブジェクト内の、位置 *pos* にあるオブジェクトを返
   します。 *pos* が負であるか範囲を超えている場合、 "NULL" を返して
   "IndexError" 例外をセットします。

   返される参照はタプル "p" からの借用参照です (つまり、"p" への参照を
   保持している間だけ有効です)。 *強参照* を取得するには、
   "Py_NewRef(PyTuple_GetItem(...))" または "PySequence_GetItem()" を
   使ってください。

PyObject *PyTuple_GET_ITEM(PyObject *p, Py_ssize_t pos)
    *戻り値: 借用参照。** Thread safety: Safe to call from multiple
   threads with external synchronization only.*

   "PyTuple_GetItem()" に似ていますが、引数に対するエラーチェックを行
   いません。

PyObject *PyTuple_GetSlice(PyObject *p, Py_ssize_t low, Py_ssize_t high)
    *戻り値: 新しい参照。** 次に属します: Stable ABI.** Thread safety:
   Atomic.*

   "p" が指すタプルの "low" から "high" までのスライスを返します。 失
   敗した場合は例外を設定して "NULL" を返します。

   Python の式 "p[low:high]" と同等です。 タプルの末尾からのインデック
   ス指定はサポートしていません。

int PyTuple_SetItem(PyObject *p, Py_ssize_t pos, PyObject *o)
    * 次に属します: Stable ABI.** Thread safety: Safe to call from
   multiple threads with external synchronization only.*

   "p" が指すタプルの位置 "pos" に、オブジェクト "o" への参照を挿入し
   ます。 成功した場合は "0" を返します。 "pos" が範囲外の場合は、
   "IndexError" 例外を設定して "-1" を返します。 この関数は、作成した
   ばかりのタプルに値を設定するためだけに使ってください。 既存のタプル
   に使うとスレッドセーフではありません。

   注釈:

     この関数は "o" への参照を「*盗み*」、タプルのその位置にすでにあっ
     た要素への参照を破棄します ("NULL" だった場合を除きます)。

void PyTuple_SET_ITEM(PyObject *p, Py_ssize_t pos, PyObject *o)
    * Thread safety: Safe to call from multiple threads with external
   synchronization only.*

   "PyTuple_SetItem()" と同様ですが、エラーチェックを行いません。 作成
   したばかりのタプルに値を設定するため *だけ* に使ってください。 既存
   のタプルに使うとスレッドセーフではありません。

   Python を デバッグモード または "アサーションを有効にして" ビルドし
   た場合、アサーションによる境界チェックが行われます。

   注釈:

     この関数は "o" への参照を「*盗みます*」。 "PyTuple_SetItem()" と
     異なり、置き換えられる要素への参照は破棄 *しません*。 タプルの位
     置 "pos" にすでに参照があれば、その参照はリークします。

   警告:

     このマクロは、新しく作成したタプルに *だけ* 使ってください。 すで
     に使われているタプル (つまり参照カウントが 1 より大きいタプル) に
     使うと、未定義の動作を引き起こす可能性があります。

int _PyTuple_Resize(PyObject **p, Py_ssize_t newsize)
    * Thread safety: Safe to call from multiple threads with external
   synchronization only.*

   タプルのサイズ変更に使えます。 "newsize" はタプルの新しい長さです。
   タプルは *本来* 不変なので、この関数はオブジェクトへの参照が一つだ
   けの場合に限って使ってください。 ほかのコードがそのタプルをすでに知
   っている可能性がある場合は、使っては *いけません*。 タプルは常に末
   尾で伸縮します。 古いタプルを破棄して新しいタプルを作成する操作を、
   より効率的に行うものと考えてください。 成功した場合は "0" を返しま
   す。 呼び出し後の "*p" が呼び出し前と同じ値であると仮定してはいけま
   せん。 "*p" が参照するオブジェクトが置き換えられる場合、元の "*p"
   は破棄されます。 失敗した場合は "-1" を返し、"*p" を "NULL" に設定
   して "MemoryError" または "SystemError" を送出します。


Struct Sequence オブジェクト
****************************

struct sequence オブジェクトは *名前付きタプル*、つまり属性を通じても
要素にアクセスできるシーケンスです。 "collections.namedtuple()" に似て
いますが、インターフェースは多少異なります。

struct sequence を作成するには、まず専用の struct sequence 型を作成す
る必要があります。

PyTypeObject *PyStructSequence_NewType(PyStructSequence_Desc *desc)
    *戻り値: 新しい参照。** 次に属します: Stable ABI.** Thread safety:
   Atomic.*

   後述の *desc* 中のデータから新しい struct sequence 型を生成します。
   返される型のインスタンスは "PyStructSequence_New()" で生成できます
   。

   失敗した場合は例外を設定して "NULL" を返します。

void PyStructSequence_InitType(PyTypeObject *type, PyStructSequence_Desc *desc)
    * Thread safety: Safe to call without external synchronization on
   distinct objects.*

   struct sequence 型である *type* を *desc* をもとにその場で初期化し
   ます。

int PyStructSequence_InitType2(PyTypeObject *type, PyStructSequence_Desc *desc)
    * Thread safety: Safe to call without external synchronization on
   distinct objects.*

   "PyStructSequence_InitType()" と同様ですが、成功した場合は "0" を返
   し、失敗した場合は例外を設定して "-1" を返します。

   Added in version 3.4.

type PyStructSequence_Desc
    * 次に属します: Stable ABI (すべてのメンバーを含む).*

   生成するstruct sequence 型のメタデータを保持します。

   const char *name

      型の完全修飾名。 ヌル終端された UTF-8 エンコードの文字列です。
      モジュール名を含む必要があります。

   const char *doc

      型の docstring へのポインタ。 省略する場合は "NULL"。

   PyStructSequence_Field *fields

      新しい型のフィールド名を持つ、"NULL" 終端の配列へのポインタ。

   int n_in_sequence

      タプルとして使う場合に Python 側から見えるフィールドの数。

type PyStructSequence_Field
    * 次に属します: Stable ABI (すべてのメンバーを含む).*

   struct sequence のフィールドを記述します。 struct sequence はタプル
   をモデルとしているので、すべてのフィールドは PyObject* 型です。
   "PyStructSequence_Desc" の "fields" 配列内のインデックスによって、
   struct sequence のどのフィールドを記述するかが決まります。

   const char *name

      フィールド名。 名前付きフィールドの一覧を終了するには "NULL"、名
      前を付けないフィールドには "PyStructSequence_UnnamedField" を指
      定します。

   const char *doc

      フィールドの docstring。 省略する場合は "NULL"。

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

   フィールド名を名前がないままするための特殊な値。

   バージョン 3.9 で変更: 型が "char *" から変更されました。

PyObject *PyStructSequence_New(PyTypeObject *type)
    *戻り値: 新しい参照。** 次に属します: Stable ABI.** Thread safety:
   Atomic.*

   *type* のインスタンスを生成します。 *type* は
   "PyStructSequence_NewType()" によって事前に生成していなければなりま
   せん。

   失敗した場合は例外を設定して "NULL" を返します。

PyObject *PyStructSequence_GetItem(PyObject *p, Py_ssize_t pos)
    *戻り値: 借用参照。** 次に属します: Stable ABI.** Thread safety:
   Safe to call from multiple threads with external synchronization
   only.*

   "p" が指す struct sequence の位置 "pos" にあるオブジェクトを返しま
   す。 返される参照は struct sequence "p" からの借用参照です (つまり
   、"p" への参照を保持している間だけ有効です)。

   Python を デバッグモード または "アサーションを有効にして" ビルドし
   た場合、アサーションによる境界チェックが行われます。

PyObject *PyStructSequence_GET_ITEM(PyObject *p, Py_ssize_t pos)
    *戻り値: 借用参照。** Thread safety: Safe to call from multiple
   threads with external synchronization only.*

   "PyStructSequence_GetItem()" の別名です。

   バージョン 3.13 で変更: "PyStructSequence_GetItem()" の別名として実
   装されるようになりました。

void PyStructSequence_SetItem(PyObject *p, Py_ssize_t pos, PyObject *o)
    * 次に属します: Stable ABI.** Thread safety: Safe to call from
   multiple threads with external synchronization only.*

   struct sequence *p* の *pos* の位置にあるフィールドに値 *o* を設定
   します。"PyTuple_SET_ITEM()" のように、生成したてのインスタンスに対
   してのみ使用すべきです。

   Python を デバッグモード または "アサーションを有効にして" ビルドし
   た場合、アサーションによる境界チェックが行われます。

   注釈:

     この関数は "o" への参照を「*盗みます*」。

void PyStructSequence_SET_ITEM(PyObject *p, Py_ssize_t *pos, PyObject *o)
    * Thread safety: Safe to call from multiple threads with external
   synchronization only.*

   "PyStructSequence_SetItem()" の別名です。

   バージョン 3.13 で変更: "PyStructSequence_SetItem()" の別名として実
   装されるようになりました。
