3. データモデル

3.1. オブジェクト、値、および型

オブジェクト は、Python がデータを抽象化したものです。 Python プログラム内のすべてのデータは、オブジェクトまたはオブジェクト間の関係として表されます。 コードもオブジェクトで表されます。

すべてのオブジェクトは、同一性 (identity)、型、値をもっています。 同一性 は生成されたあとは変更されません。これはオブジェクトのアドレスのようなものだと考えられるかもしれません。 is 演算子は2つのオブジェクトの同一性を比較します。 id() 関数は同一性を表す整数を返します。

CPython では、id(x) は x が格納されているメモリ上のアドレスを返します。

オブジェクトの型はオブジェクトがサポートする操作 (例: len() をサポートするか) と、オブジェクトが取りうる値を決定します。 type() 関数はオブジェクトの型 (型自体もオブジェクトです) を返します。同一性と同じく、オブジェクトの型(type) も変更不可能です。 [1]

オブジェクトによっては 値 を変更することが可能です。値を変更できるオブジェクトのことを mutable と呼びます。生成後に値を変更できないオブジェクトのことを immutable と呼びます。(mutable なオブジェクトへの参照を格納している immutableなコンテナオブジェクトの値は、その格納しているオブジェクトの値が変化した時に変化しますが、コンテナがどのオブジェクトを格納しているのかが変化しないのであれば immutable だと考えることができます。したがって、immutable かどうかは値が変更可能かどうかと完全に一致するわけではありません) オブジェクトが mutable かどうかはその型によって決まります。例えば、数値型、文字列型とタプル型のインスタンスは immutable で、dict や list は mutable です。

オブジェクトを明示的に破壊することはできません; しかし、オブジェクトに到達不能 (unreachable) になると、ガベージコレクション (garbage-collection) によって処理されるかもしれません。ガベージコレクションを遅らせたり、全く行わない実装も許されています --- 到達可能なオブジェクトを処理してしまわないかぎり、ガベージコレクションをどう実装するかは実装品質の問題です。

現在の CPython 実装では参照カウント (reference-counting) 方式を使っており、(オプションとして) 循環参照を行っているガベージオブジェクトを遅延検出します。この実装ではほとんどのオブジェクトを到達不能になると同時に処理することができますが、循環参照を含むガベージオブジェクトの収集が確実に行われるよう保証しているわけではありません。循環参照を持つガベージオブジェクト収集の制御については、 gc モジュールを参照してください。 CPython以外の実装は別の方式を使っており、CPythonも将来は別の方式を使うかもしれません。オブジェクトが到達不能になったときに即座に終了処理されることに頼らないでください (ですからファイルは必ず明示的に閉じてください)。

実装が提供するトレース機能やデバッグ機能を使うと、通常なら回収できるオブジェクトが生存し続ける場合があります。 また、try...except 文で例外を捕捉することによっても、オブジェクトが生存し続ける場合があります。

開いているファイルやウィンドウなど、外部リソースへの参照を保持するオブジェクトもあります。 これらのリソースはオブジェクトがガベージコレクションで回収される際に解放されるものとされていますが、ガベージコレクションの実行は保証されません。 そのため、こうしたオブジェクトは通常 close() メソッドなど、外部リソースを明示的に解放する手段も提供します。 プログラムでは、このようなオブジェクトを明示的に閉じることを強く推奨します。 try...finally 文や with 文を使うと、これを簡単に実現できます。

ほかのオブジェクトへの参照を含むオブジェクトは コンテナ と呼ばれます。 例えばタプル、リスト、辞書です。 参照はコンテナの値の一部です。 コンテナの値というと、通常は格納されたオブジェクトの同一性ではなく値を指します。 一方、コンテナの変更可能性については、直接格納されたオブジェクトの同一性だけを指します。 したがって、タプルのような変更不能なコンテナが変更可能なオブジェクトへの参照を含む場合、参照先が変更されるとコンテナの値も変わります。

型は、オブジェクトの振る舞いのほぼすべてに影響します。 オブジェクトの同一性が持つ意味さえ、ある意味では型に左右されます。 変更不能な型では、新しい値を計算する操作が、実際には同じ型と値を持つ既存のオブジェクトへの参照を返すことがありますが、変更可能なオブジェクトではこれは許されません。 例えば a = 1; b = 1 の後、a と b が値 1 を持つ同じオブジェクトを参照するかどうかは実装によって異なります。 int は変更不能な型なので、1 への参照を再利用できるためです。 この動作は実装に依存するため、頼るべきではありませんが、オブジェクトの同一性を調べる際には知っておく必要があります。 一方、c = []; d = [] の後では、c と d はそれぞれ別々に新しく作成された空リストを参照することが保証されます。 (e = f = [] は e と f の両方に 同じ オブジェクトを代入することに注意してください。)

3.2. 標準型の階層

以下は Python に組み込まれている型のリストです。(実装によって、C、Java、またはその他の言語で書かれた) 拡張モジュールで、その他の型が定義されていることがあります。新たな型 (有理数や、整数を効率的に記憶する配列、など) の追加は、たいてい標準ライブラリを通して提供されますが、将来のバージョンの Python では、型の階層構造にこのような追加がなされるかもしれません。

以下に説明する型のいくつかには、 '特殊属性 (special attribute)' を列挙した段落があります。これらの属性は実装へのアクセス手段を提供するもので、一般的な用途に利用するためのものではありません。特殊属性の定義は将来変更される可能性があります。

3.2.1. None

この型には単一の値しかありません。この値を持つオブジェクトはただ一つしか存在しません。このオブジェクトは組み込み名 None でアクセスされます。このオブジェクトは、様々な状況で値が存在しないことをしめします。例えば、明示的に値を返さない関数は None を返します。 None の真値 (truth value) は偽 (false) です。

3.2.2. NotImplemented

この型には値が 1 つしかなく、その値を持つオブジェクトも 1 つだけです。 このオブジェクトには組み込み名 NotImplemented でアクセスします。 数値演算や拡張比較のメソッドは、与えられた被演算子に対する演算を実装していない場合、この値を返す必要があります。 (その場合、インタープリタは演算子に応じて、反射演算やその他の代替処理を試みます。) ブール値を求める文脈で評価してはいけません。

詳細は 算術演算の実装 を参照してください。

バージョン 3.9 で変更: ブール値を求める文脈で NotImplemented を評価することが非推奨になりました。

バージョン 3.14 で変更: ブール値を求める文脈で NotImplemented を評価すると、TypeError が送出されるようになりました。 以前は True と評価され、Python 3.9 以降では DeprecationWarning も発生していました。

3.2.3. Ellipsis

この型には単一の値しかありません。この値を持つオブジェクトはただ一つしか存在しません。このオブジェクトはリテラル ... またはPythonで決められている名前 Ellipsis でアクセスされます。真理値は真 (true)です。

3.2.4. numbers.Number

数値リテラルによって作成されたり、算術演算や組み込みの算術関数によって返されるオブジェクトです。数値オブジェクトは変更不能です; 一度値が生成されると、二度と変更されることはありません。Python の数値オブジェクトはいうまでもなく数学で言うところの数値と強く関係していますが、コンピュータ内で数値を表現する際に伴う制限を受けています。

__repr__() と __str__() から計算された数値クラスの文字列表現には次のような特性があります:

  • その文字列は、クラスコンストラクタに渡したときに、元の数値の値を持つオブジェクトを生成する有効な数値リテラルです。

  • できるなら、10を底として表現されます。

  • 小数点の前にある 1 つのゼロを除いて、上に連なるゼロは表示されません。

  • 小数点の後にある 1 つのゼロを除いて、下に連なるゼロは表示されません。

  • 符号は数値が負数のときのみ表示されます。

Python は整数、浮動小数点数、複素数を区別します。

3.2.4.1. numbers.Integral (整数)

整数型は、整数(正の数および負の数)を表す数学的集合内における要素を表現する型です。

注釈

整数表現に関する規則は、負の整数を含むシフト演算やマスク演算において、最も有意義な解釈ができるように意図されています。

整数には 2 種類あります:

整数 (int)

無制限の範囲の数を表現しますが、利用可能な (仮想) メモリサイズの制限のみを受けます。シフト演算やマスク演算のために2進数表現を持つと想定されます。負の数は符号ビットが左に無限に延びているような錯覚を与える 2 の補数表現の変型で表されます。

ブール値 (bool)

真偽値の False と True を表します。False と True を表す 2 つのオブジェクトのみがブール値オブジェクトです。ブール型は整数型の派生型であり、ほとんどの状況でそれぞれ 0 と 1 のように振る舞いますが、例外として文字列に変換されたときはそれぞれ "False" および "True" という文字列が返されます。

3.2.4.2. numbers.Real (float) (実数)

マシンレベルの倍精度浮動小数点数を表します。 表現できる範囲やオーバーフローの扱いは、基盤となるマシンのアーキテクチャ (および C や Java の実装) に依存します。 Python は単精度浮動小数点数をサポートしていません。 単精度を使う通常の理由であるプロセッサやメモリの使用量の節約は、Python のオブジェクトを使うオーバーヘッドに比べるとわずかです。 そのため、2 種類の浮動小数点数で言語を複雑にする理由がありません。

3.2.4.3. numbers.Complex (complex)

複素数を、マシンレベルの倍精度浮動小数点数のペアとして表します。 浮動小数点数と同じ注意事項が当てはまります。 複素数 z の実部と虚部は、読み取り専用属性 z.real と z.imag で取得できます。

3.2.5. シーケンス型 (sequence)

非負の数をインデックスとする、順序のある有限の集まりを表します。 組み込み関数 len() はシーケンスの要素数を返します。 シーケンスの長さが n の場合、インデックスには 0, 1, ..., n-1 を使います。 シーケンス a の要素 i は a[i] で選択します。 組み込みシーケンスを含む一部のシーケンスは、負の添字にシーケンスの長さを加えて解釈します。 例えば a[-2] は a[n-2] と等しく、長さ n のシーケンス a の末尾から 2 番目の要素です。

結果の値は、シーケンスの要素数より小さい非負の整数でなければなりません。 そうでなければ IndexError が送出されます。

シーケンスはスライスもサポートしています。 a[start:stop] は、インデックス k が start <= k < stop を満たす要素をすべて選択します。 式として使うと、スライスの結果は元と同じ型のシーケンスになります。 負の添字に関する上記の説明は、負のスライス位置にも当てはまります。 スライス位置が 0 より小さい場合やシーケンスの長さより大きい場合も、エラーにはなりません。

start を省略した場合や None を指定した場合、スライスは start が 0 であるかのように動作します。 stop を省略した場合や None を指定した場合、スライスは stop がシーケンスの長さに等しいものとして動作します。

シーケンスによっては、第三の "ステップ (step)" パラメタを持つ "拡張スライス (extended slice)" もサポートしています: a[i:j:k] は、 x = i + n*k, n >= 0 かつ i <= x < j であるようなインデクス x を持つような a 全ての要素を選択します。

シーケンスは、変更可能なものか、そうでないかで区別されています:

3.2.5.1. 変更不能なシーケンス (immutable sequence)

変更不能なシーケンス型のオブジェクトは、一度生成されるとその値を変更することができません。 (オブジェクトに他のオブジェクトへの参照が入っている場合、参照されているオブジェクトは変更可能なオブジェクトでもよく、その値は変更される可能性があります; しかし、変更不能なオブジェクトが直接参照しているオブジェクトの集合自体は、変更することができません。)

以下の型は変更不能なシーケンス型です:

文字列型 (string)

文字列 (str) は、文字、より厳密には Unicode コードポイント を表す値のシーケンスです。 0 から 0x10FFFF までのすべてのコードポイントを文字列で表せます。

Python には 文字 専用の型がありません。 代わりに、文字列内の各コードポイントは長さ 1 の文字列オブジェクトで表されます。

組み込み関数 ord() は、文字列で表されたコードポイントを 0 から 0x10FFFF までの整数に変換します。 chr() は、その範囲の整数を対応する長さ 1 の文字列オブジェクトに変換します。 str.encode() を使うと、指定したテキストエンコーディングで str を bytes に変換できます。 逆の変換には bytes.decode() を使えます。

タプル型 (tuple)

tuple の要素には任意の Python オブジェクトを使えます。 2 個以上の要素を持つタプルは、式をコンマで区切って並べることで作成します。 1 要素のタプル (singleton) は式の末尾にコンマを付けて作成できます (丸括弧は式のグループ化にも使う必要があるため、式だけではタプルになりません)。 空のタプルは、中身のない丸括弧のペアで作成できます。

bytes

bytes オブジェクトは変更不能な配列です。 要素は 8 ビットのバイトで、0 <= x < 256 の範囲の整数で表されます。 バイト列リテラル (b'abc' など) や組み込みの bytes() コンストラクタで bytes オブジェクトを作成できます。 また、bytes オブジェクトは decode() メソッドで文字列にデコードできます。

3.2.5.2. 変更可能なシーケンス型 (mutable sequence)

変更可能なシーケンスは、作成した後で変更することができます。変更可能なシーケンスでは、添字表記やスライス表記を使って指定された要素に代入を行うことができ、 del (delete) 文を使って要素を削除することができます。

注釈

collections モジュールと array モジュールも、変更可能なシーケンス型の例を提供します。

Python に最初から組み込まれている変更可能なシーケンス型は、今のところ二つです:

リスト型 (list)

リストの要素は任意の Python オブジェクトにできます。リストは、角括弧の中にカンマで区切られた式を並べて作ります。 (長さが 0 や 1 のシーケンスを作るために特殊な場合分けは必要ないことに注意してください。)

バイト配列

bytearray オブジェクトは変更可能な配列です。組み込みの bytearray() コンストラクタによって作成されます。変更可能なことを除けば (つまりハッシュ化できない)、 byte array は変更不能な bytes オブジェクトと同じインターフェースと機能を提供します。

3.2.6. 集合型

集合型は、順序のない、ユニークで不変なオブジェクトの有限集合を表現します。そのため、(配列の)添字を使ったインデックスアクセスはできません。ただし、イテレートは可能で、組み込み関数 len() は集合の要素数を返します。集合型の一般的な使い方は、集合に属しているかの高速なテスト、シーケンスからの重複の排除、共通集合・和集合・差・対称差といった数学的な演算の計算です。

集合の要素には、辞書のキーと同じ不変性の規則が適用されます。 数値型は通常の数値比較の規則に従います。 2 つの数値が等しいと比較される場合 (例えば 1 と 1.0)、集合にはそのうち 1 つだけを含められます。

現在、2つの組み込み集合型があります:

集合型

可変な集合型です。組み込みの set() コンストラクタで作成され、後から add() などのいくつかのメソッドで更新できます。

Frozen set 型

不変な集合型です。組み込みの frozenset() コンストラクタによって作成されます。 frozenset は不変で ハッシュ可能 なので、別の集合型の要素になったり、辞書のキーにすることができます。

3.2.7. マッピング型 (mapping)

任意のインデクス集合でインデクス化された、オブジェクトからなる有限の集合を表現します。添字表記 a[k] は、 k でインデクス指定された要素を a から選択します; 選択された要素は式の中で使うことができ、代入や del 文の対象にすることができます。組み込み関数 len() は、マッピング内の要素数を返します。

組み込みのマッピング型は 2 種類あります。

3.2.7.1. 辞書型 (dictionary)

ほぼ任意の値をインデックスとする、オブジェクトの有限の集まりを表します。 キーに使えないのは、リスト、辞書、またはオブジェクトの同一性ではなく値で比較されるほかの変更可能な型を含む値です。 辞書を効率的に実装するには、キーのハッシュ値が変わらないことが必要だからです。 キーに使う数値型は通常の数値比較の規則に従います。 2 つの数値が等しいと比較される場合 (例えば 1 と 1.0)、どちらも同じ辞書エントリーのインデックスとして使えます。

辞書は挿入の順序を保持します。つまり、キーは辞書に追加された順番に生成されていきます。既存のキーを置き換えても、キーの順序は変わりません。キーを削除したのちに再挿入すると、元の場所ではなく辞書の最後に追加されます。

辞書は変更可能です。 {} 記法で作成できます (辞書表示 を参照)。

拡張モジュール dbm.ndbm 、 dbm.gnu は、 collections モジュールのように、別のマッピング型の例を提供しています。

バージョン 3.7 で変更: Python 3.6 より前のバージョンでは、辞書は挿入順序を保持しませんでした。 CPython 3.6 では挿入順序を保持していましたが、当時は言語仕様の保証ではなく実装の詳細とされていました。

3.2.7.2. 凍結辞書

変更不能な辞書を表します。 組み込みの frozendict() コンストラクタで作成します。 すべてのキーと値がハッシュ可能であれば frozendict も ハッシュ可能 で、その場合は集合の要素や別のマッピングのキーとして使えます。 frozendict は dict のサブクラスではなく、object を直接継承しています。

Added in version 3.15.

3.2.8. 呼び出し可能型 (callable type)

関数呼び出し操作 (呼び出し (call) 参照) を行うことができる型です:

3.2.8.1. ユーザ定義関数 (user-defined function)

ユーザ定義関数オブジェクトは、関数定義を行うことで生成されます (関数定義 参照)。関数は、仮引数 (formal parameter) リストと同じ数の要素が入った引数リストとともに呼び出されます。

3.2.8.1.1. 読み取り専用の特殊属性

属性

意味
function.__builtins__

関数の組み込み名前空間を保持する 辞書 への参照。

Added in version 3.10.
function.__globals__

関数の グローバル変数 を保持する 辞書 への参照です。 関数が定義されたモジュールのグローバル名前空間です。
function.__closure__

None、または関数の コードオブジェクト の co_freevars 属性に指定された名前の束縛を保持するセルからなる tuple。

セルオブジェクトは属性 cell_contents を持っています。 これはセルの値を設定するのに加えて、セルの値を得るのにも使えます。
3.2.8.1.2. 書き込み可能な特殊属性

これらの属性のほとんどは、代入される値の型を検査します。

属性

意味
function.__doc__

関数のドキュメンテーション文字列です。ドキュメンテーションがない場合は None になります。
function.__name__

関数の名前。 __name__ 属性 も参照してください。
function.__qualname__

関数の 修飾名。 __qualname__ 属性 も参照してください。

Added in version 3.3.
function.__module__

関数が定義されているモジュールの名前です。モジュール名がない場合は None になります。
function.__defaults__

デフォルト値を持つ位置 仮引数 のデフォルト値を含む tuple。 該当する引数がなければ None です。
function.__code__

コンパイルされた関数本体を表す コードオブジェクト。
function.__dict__

任意の関数属性を保持する名前空間。 __dict__ 属性 も参照してください。
function.__annotations__

引数 のアノテーションを含む 辞書 です。 キーは引数名で、戻り値のアノテーションがある場合はそのキーが 'return' になります。 object.__annotations__ も参照してください。

バージョン 3.14 で変更: アノテーションが 遅延評価 されるようになりました。 PEP 649 を参照してください。
function.__annotate__

この関数の アノテーション関数。 アノテーションがない場合は None です。 object.__annotate__ を参照してください。

Added in version 3.14.
function.__kwdefaults__

キーワード専用 引数 のデフォルト値を含む 辞書。
function.__type_params__

ジェネリック関数 の 型パラメータ を含む tuple。

Added in version 3.12.

関数オブジェクトでは任意の属性の取得や設定もでき、例えば関数にメタデータを付加するために使えます。 このような属性の取得と設定には、通常の属性と同じドット記法を使います。

現在の CPython 実装は、ユーザー定義関数の属性だけをサポートしています。 将来は 組み込み関数 の属性もサポートされるかもしれません。

関数の定義に関する追加情報は、その コードオブジェクト (__code__ 属性でアクセス可能) から取得できます。

3.2.8.2. インスタンスメソッド

インスタンスメソッドオブジェクトは、クラス、クラスインスタンスと任意の呼び出し可能オブジェクト (通常はユーザ定義関数) を結びつけます。

読み取り専用の特殊属性。

method.__self__

メソッドが 束縛 されているクラスのインスタンスオブジェクトを参照します。
method.__func__

元の 関数オブジェクト を参照します。
method.__doc__

メソッドのドキュメント (method.__func__.__doc__ と同じ)。 元の関数にドキュメンテーション文字列があれば 文字列、なければ None です。
method.__name__

メソッドの名前 (method.__func__.__name__ と同じ)。
method.__module__

メソッドが定義されたモジュールの名前。 取得できない場合は None です。

メソッドは、基となる 関数オブジェクト の任意の属性へのアクセスもサポートしていますが、設定はできません。

クラスの属性を (そのクラスのインスタンスを通じて取得する場合も含めて) 取得するとき、属性がユーザー定義の 関数オブジェクト または classmethod オブジェクトであれば、ユーザー定義メソッドオブジェクトが作成される場合があります。

クラスのインスタンスを通じてクラスのユーザー定義 関数オブジェクト を取得し、インスタンスメソッドオブジェクトが作成されると、その __self__ 属性はそのインスタンスになります。 このメソッドオブジェクトは 束縛されている といいます。 作成されたメソッドの __func__ 属性は元の関数オブジェクトです。

クラスまたはインスタンスから classmethod オブジェクトを取得してインスタンスメソッドオブジェクトが作成されると、その __self__ 属性はクラス自身になります。 __func__ 属性はクラスメソッドの基となる関数オブジェクトです。

インスタンスメソッドオブジェクトを呼び出すと、引数リストの先頭にクラスのインスタンス (__self__) を挿入して、基となる関数 (__func__) を呼び出します。 例えば、C が関数 f() の定義を含むクラスで、x が C のインスタンスである場合、x.f(1) の呼び出しは C.f(x, 1) の呼び出しと同じです。

インスタンスメソッドオブジェクトが classmethod オブジェクトから作られた場合、__self__ に格納される「クラスのインスタンス」は、実際にはクラス自身です。 そのため、基となる関数を f とすると、x.f(1) と C.f(1) のどちらの呼び出しも f(C,1) の呼び出しと同じです。

クラスのインスタンスの属性であるユーザー定義関数は、束縛メソッドに変換されないことに注意してください。 この変換が行われるのは、関数がクラスの属性である場合 だけ です。

3.2.8.3. ジェネレータ関数 (generator function)

yield 式 (Yield 式 を参照) を含む関数やメソッドを ジェネレータ関数 と呼びます。 このような関数を呼び出すと、関数本体の実行に使える イテレータ オブジェクトが常に返されます。 イテレータの iterator.__next__() メソッドを呼び出すと、yield 式で値を返すところまで関数が実行されます。 関数が return 文を実行するか本体の末尾に達すると、StopIteration 例外が送出され、イテレータは返す値の終わりに達します。

3.2.8.4. コルーチン関数 (coroutine function)

async def を使用して定義された関数やメソッドを コルーチン関数 (coroutine function) と呼びます。 呼び出された時、そのような関数は coroutine オブジェクトを返します。 コルーチン関数は async with や async for 文だけでなく await 式を持つことが出来ます。 コルーチンオブジェクト を参照してください。

3.2.8.5. 非同期ジェネレータ関数 (asynchronous generator function)

async def で定義され、yield 式を含む関数やメソッドを 非同期ジェネレータ関数 と呼びます。 このような関数を呼び出すと、async for 文で関数本体を実行するための 非同期イテレータ オブジェクトが返されます。

非同期イテレータの aiterator.__anext__ メソッドを呼び出すと、awaitable が返されます。 それを await すると、yield 式で値を返すところまで関数が実行されます。 関数が値のない return 文を実行するか本体の末尾に達すると、StopAsyncIteration 例外が送出され、非同期イテレータは yield する値の終わりに達します。

3.2.8.6. 組み込み関数 (built-in function)

組み込み関数オブジェクトは C 関数のラッパーです。 例えば len() や math.sin() があります (math は標準の組み込みモジュールです)。 引数の数と型は C 関数が決定します。 読み取り専用の特殊属性は次のとおりです。

  • __doc__ は関数のドキュメンテーション文字列で、ない場合は None です。 function.__doc__ を参照してください。

  • __name__ は関数の名前です。 function.__name__ を参照してください。

  • __self__ は関数が定義されたモジュールオブジェクトで、ない場合は None です。

  • __module__ は関数が定義されたモジュールの名前で、ない場合は None です。 function.__module__ を参照してください。

3.2.8.7. 組み込みメソッド (built-in method)

実際には組み込み関数の別の形で、暗黙の追加引数として C 関数に渡されるオブジェクトを保持しています。 例えば alist がリストオブジェクトであるとき、alist.append() は組み込みメソッドです。 この場合、読み取り専用の特殊属性 __self__ は alist が指すオブジェクトに設定されます。 (この属性の意味は ほかのインスタンスメソッド と同じです。)

3.2.8.8. クラス

クラスは呼び出し可能です。 通常、クラスオブジェクトは自身の新しいインスタンスを作成するファクトリとして動作しますが、__new__() をオーバーライドするクラス型では異なる動作も可能です。 呼び出しの引数は __new__() に渡され、通常は新しいインスタンスを初期化する __init__() にも渡されます。

3.2.8.9. クラスのインスタンス

任意のクラスのインスタンスは、クラスで __call__() メソッドを定義することで呼び出し可能になります。

3.2.9. モジュール

モジュールは Python コードをまとめる基本単位で、import 文、importlib.import_module() などの関数、または組み込み関数 __import__() によって呼び出される インポートシステム が作成します。 モジュールオブジェクトには 辞書 オブジェクトで実装された名前空間があります (モジュール内で定義された関数の __globals__ 属性が参照する辞書です)。 属性の参照はこの辞書内の検索に変換されます。 例えば m.x は m.__dict__["x"] と同じです。 モジュールオブジェクトは、初期化に使われたコードオブジェクトを保持しません (初期化が終われば不要なためです)。

属性の代入を行うと、モジュールの名前空間辞書の内容を更新します。例えば、 m.x = 1 は m.__dict__["x"] = 1 と同じです。

3.2.9.2. モジュールオブジェクトのその他の書き込み可能な属性

上記のインポート関連属性に加え、モジュールオブジェクトには次の書き込み可能な属性もあります。

module.__doc__

モジュールのドキュメンテーション文字列。 存在しない場合は None です。 __doc__ 属性 も参照してください。

module.__annotations__

モジュール本体の実行中に収集された 変数アノテーション を含む辞書です。 __annotations__ を扱う際の推奨事項は annotationlib を参照してください。

バージョン 3.14 で変更: アノテーションが 遅延評価 されるようになりました。 PEP 649 を参照してください。

module.__annotate__

このモジュールの アノテーション関数。 アノテーションがない場合は None です。 __annotate__ 属性も参照してください。

Added in version 3.14.

module.__lazy_modules__

完全修飾されたモジュール名の文字列を含むコンテナ (__contains__() を実装したオブジェクト) です。 モジュールスコープで定義すると、そのモジュール内の通常の import 文は、対象モジュール名がこのコンテナに含まれる場合、lazy キーワードを付けたかのように 遅延インポート として扱われます。 関数内、クラス本体内、try/except/finally ブロック内のインポートには影響しません。

詳細と例は __lazy_modules__ による互換性の確保 を参照してください。

Added in version 3.15.

3.2.9.3. モジュール辞書

モジュールオブジェクトには、次の読み取り専用の特殊属性もあります。

module.__dict__

モジュールの名前空間を表す辞書オブジェクトです。 ここに挙げた属性の中で唯一、__dict__ はモジュール内からグローバル変数としてアクセスできません。 モジュールオブジェクトの属性としてのみアクセスできます。

CPython がモジュール辞書を削除する方法により、モジュール辞書が生きた参照を持っていたとしてもその辞書はモジュールがスコープから外れた時に削除されます。これを避けるには、辞書をコピーするか、辞書を直接使っている間モジュールを保持してください。

3.2.10. カスタムクラス型

カスタムクラス型は、通常はクラス定義によって作成されます (クラス定義 を参照)。 クラスは辞書オブジェクトで実装された名前空間を持ちます。 クラス属性の参照はこの辞書内の検索に変換され、例えば C.x は C.__dict__["x"] に変換されます (ただし、属性を別の方法で探すためのフックがいくつかあります)。 属性名が見つからない場合は、基底クラスでの検索に進みます。 基底クラスの検索には C3 メソッド解決順序を使います。 これは、共通の祖先へと至る継承経路が複数ある「ダイヤモンド」型の継承構造でも正しく動作します。 Python が使う C3 MRO の詳細は Python 2.3 のメソッド解決順序 を参照してください。

クラス (例えば C) の属性参照の結果がクラスメソッドオブジェクトである場合、__self__ 属性が C であるインスタンスメソッドオブジェクトに変換されます。 staticmethod オブジェクトである場合は、その静的メソッドオブジェクトがラップしているオブジェクトに変換されます。 クラスから取得した属性が、実際に __dict__ に格納されているものと異なる場合については、デスクリプタ (descriptor) の実装 も参照してください。

クラス属性を代入すると、そのクラスの辞書だけが更新され、基底クラスの辞書は更新しません。

クラスオブジェクトを呼び出す (上記を参照) と、クラスインスタンスを生成します (下記を参照)。

3.2.10.1. 特殊属性

属性

意味
type.__name__

クラスの名前。 __name__ 属性 も参照してください。
type.__qualname__

クラスの 修飾名。 __qualname__ 属性 も参照してください。
type.__module__

クラスが定義されているモジュールの名前。
type.__dict__

クラスの名前空間の読み取り専用ビューを提供する マッピングプロキシ。 __dict__ 属性 も参照してください。
type.__bases__

クラスの基底クラスを含む tuple です。 ほとんどの場合、class X(A, B, C) と定義したクラスの X.__bases__ は (A, B, C) と完全に等しくなります。
type.__base__

継承関係の中で、インスタンスのメモリレイアウトを決める単一の基底クラスです。 この属性は C レベルの tp_base に対応します。
type.__doc__

クラスのドキュメンテーション文字列。 未定義の場合は None です。 サブクラスには継承されません。
type.__annotations__

クラス本体の実行中に収集された 変数アノテーション を含む辞書です。 __annotations__ 属性 も参照してください。

__annotations__ を扱う際の推奨事項は annotationlib を参照してください。 この属性に直接アクセスせず、annotationlib.get_annotations() を使ってください。

警告

クラスオブジェクトの __annotations__ 属性に直接アクセスすると、別のクラスのアノテーションが返される場合があります。 具体的には、クラス自身、基底クラス、メタクラスのいずれかが from __future__ import annotations の下で定義された場合の一部が該当します。 詳細は 749 を参照してください。

この属性は一部の組み込みクラスには存在しません。 __annotations__ を持たないユーザー定義クラスでは空の辞書です。

バージョン 3.14 で変更: アノテーションが 遅延評価 されるようになりました。 PEP 649 を参照してください。
type.__annotate__()

このクラスの アノテーション関数。 アノテーションがない場合は None です。 __annotate__ 属性 も参照してください。

Added in version 3.14.
type.__type_params__

ジェネリッククラス の 型パラメータ を含む tuple。

Added in version 3.12.
type.__static_attributes__

クラス本体内のいずれかの関数で self.X を通じて代入される、このクラスの属性の名前を含む tuple。

Added in version 3.13.
type.__firstlineno__

デコレーターを含むクラス定義の最初の行の行番号です。 __module__ 属性を設定すると、型の辞書から __firstlineno__ 項目が削除されます。

Added in version 3.13.
type.__mro__

メソッド解決時に基底クラスを探す際の対象となるクラスの tuple。

3.2.10.2. 特殊メソッド

上記の特殊属性に加え、すべての Python クラスで次の 2 つのメソッドを利用できます。

type.mro()

メタクラスはこのメソッドをオーバーライドし、そのインスタンスのメソッド解決順序をカスタマイズできます。 クラスのインスタンス化の際に呼び出され、結果は __mro__ に格納されます。

type.__subclasses__()

Each class keeps a list of weak references to its immediate subclasses. This method returns a list of all those references still alive. The list is in definition order. Example:

>>> class A: pass
>>> class B(A): pass
>>> A.__subclasses__()
[<class 'B'>]

3.2.11. クラスインスタンス (class instance)

クラスインスタンスはクラスオブジェクトを呼び出すことで作成されます (上記を参照)。 クラスインスタンスは辞書で実装された名前空間を持ち、属性の参照はまずそこで検索されます。 見つからず、インスタンスのクラスにその名前の属性があれば、クラス属性での検索に進みます。 見つかったクラス属性がユーザー定義関数オブジェクトであれば、__self__ 属性がそのインスタンスであるインスタンスメソッドオブジェクトに変換されます。 静的メソッドやクラスメソッドのオブジェクトも変換されます。 上記の「クラス」を参照してください。 インスタンスを通じて取得したクラスの属性が、クラスの __dict__ に実際に格納されているオブジェクトと異なる場合については、デスクリプタ (descriptor) の実装 も参照してください。 クラス属性が見つからず、オブジェクトのクラスに __getattr__() メソッドがあれば、属性を取得するためにそのメソッドが呼び出されます。

属性の代入や削除を行うと、インスタンスの辞書を更新しますが、クラスの辞書を更新することはありません。クラスで __setattr__() や __delattr__() メソッドが定義されている場合、直接インスタンスの辞書を更新する代わりにこれらのメソッドが呼び出されます。

クラスインスタンスは、ある特定の名前のメソッドを持っている場合、数値型やシーケンス型、あるいはマップ型のように振舞うことができます。 特殊メソッド名 を参照してください。

3.2.11.1. 特殊属性

object.__class__

クラスインスタンスが属しているクラスです。

object.__dict__

オブジェクトの書き込み可能な属性を格納する辞書、またはその他のマッピングオブジェクトです。 すべてのインスタンスが __dict__ 属性を持つわけではありません。 詳細は __slots__ を参照してください。

3.2.12. I/O オブジェクト (ファイルオブジェクトの別名)

file object は開かれたファイルを表します。ファイルオブジェクトを作るための様々なショートカットがあります: open() 組み込み関数、 os.popen() 、 os.fdopen() 、ソケットオブジェクトの makefile() メソッド (あるいは拡張モジュールから提供される他の関数やメソッド) 。

ファイルオブジェクトは、汎用的なコードから使いやすくするために、以下に挙げる共通のメソッドを実装します。 with文とコンテキストマネージャ であることが期待されます。

オブジェクト sys.stdin 、 sys.stdout および sys.stderr は、インタプリタの標準入力、標準出力、および標準エラー出力ストリームに対応するファイルオブジェクトに初期化されます。これらはすべてテキストモードで開かれ、 io.TextIOBase 抽象クラスによって定義されたインターフェースに従います。

file.read(size=-1, /)

ファイルから最大 size のデータを取得します。 size を省略するか -1 にすると、利用可能なデータをすべて取得できます。

file.write(data, /)

data をファイルに格納します。

file.close()

バッファをすべてフラッシュし、内部のファイルを閉じます。

3.2.13. 内部型 (internal type)

インタプリタが内部的に使っているいくつかの型は、ユーザに公開されています。これらの定義は将来のインタプリタのバージョンでは変更される可能性がありますが、ここでは記述の完全性のために触れておきます。

3.2.13.1. コードオブジェクト

コードオブジェクトは バイトコンパイルされた (byte-compiled) 実行可能な Python コード、別名 バイトコード を表現します。コードオブジェクトと関数オブジェクトの違いは、関数オブジェクトが関数のグローバル変数 (関数を定義しているモジュールのグローバル) に対して明示的な参照を持っているのに対し、コードオブジェクトにはコンテキストがないということです; また、関数オブジェクトではデフォルト引数値を記憶できますが、コードオブジェクトではできません (実行時に計算される値を表現するため)。関数オブジェクトと違い、コードオブジェクトは変更不可能で、変更可能なオブジェクトへの参照を (直接、間接に関わらず) 含みません。

3.2.13.1.1. 読み取り専用の特殊属性
codeobject.co_name

関数名
codeobject.co_qualname

関数の完全修飾名

Added in version 3.11.
codeobject.co_argcount

関数の位置 引数 の総数 (位置専用引数とデフォルト値を持つ引数を含む)
codeobject.co_posonlyargcount

関数の位置専用 引数 の数 (デフォルト値を持つ引数を含む)
codeobject.co_kwonlyargcount

関数のキーワード専用 引数 の数 (デフォルト値を持つ引数を含む)
codeobject.co_nlocals

関数で使う ローカル変数 の数 (引数を含む)
codeobject.co_varnames

関数のローカル変数名を含む tuple (引数名から始まる)
codeobject.co_cellvars

関数内の少なくとも 1 つの 入れ子のスコープ から参照される ローカル変数 の名前を含む tuple
codeobject.co_freevars

入れ子のスコープ が外側のスコープから参照する 自由 (クロージャー) 変数 の名前を含む tuple。 function.__closure__ も参照してください。

グローバル名や組み込み名への参照は 含まれません。
codeobject.co_code

関数内の バイトコード 命令列を表すバイト列
codeobject.co_consts

関数内の バイトコード で使うリテラルを含む tuple
codeobject.co_names

関数内の バイトコード で使う名前を含む tuple
codeobject.co_filename

コードのコンパイル元となったファイルの名前
codeobject.co_firstlineno

関数の最初の行の行番号
codeobject.co_linetable

エンコードされたソース位置情報を含む bytes オブジェクトです。 正確な形式は実装の詳細であり、Python のバージョン間で変わる場合があります。 行や位置の情報にアクセスするには、サポートされている co_lines() と co_positions() を使ってください。 コードオブジェクトの一部を変更したコピーを作るには、replace() を使ってください。

Added in version 3.10.
codeobject.co_stacksize

コードオブジェクトに必要なスタックサイズ
codeobject.co_flags

インタープリタ用の複数のフラグを符号化した 整数。

co_flags には次のフラグビットが定義されています。 関数が *arguments 構文で任意個数の位置引数を受け付ける場合はビット 0x04、**keywords 構文で任意のキーワード引数を受け付ける場合はビット 0x08、関数がジェネレータの場合はビット 0x20 が設定されます。 設定されうる各フラグの意味の詳細は コードオブジェクトのビットフラグ を参照してください。

from __future__ import division のような future 機能の宣言も、co_flags のビットを使って、その機能を有効にしてコードオブジェクトをコンパイルしたかどうかを示します。 compiler_flag を参照してください。

co_flags のほかのビットは、内部用に予約されています。

コードオブジェクトが関数を表し、ドキュメンテーション文字列を持つ場合、co_flags の CO_HAS_DOCSTRING ビットが設定され、co_consts の最初の要素が関数のドキュメンテーション文字列になります。

3.2.13.1.2. コードオブジェクトのメソッド
codeobject.co_positions()

コードオブジェクト内の各 バイトコード 命令のソースコード上の位置を反復するイテラブルを返します。

イテレータは (start_line, end_line, start_column, end_column) を含む tuple を返します。 i 番目のタプルは、i 番目のコード単位にコンパイルされたソースコードの位置に対応します。 列の情報は、そのソース行を UTF-8 で表したときの 0 始まりのバイトオフセットです。

位置情報がない場合もあります。 例えば次の場合が該当しますが、これらに限りません。

  • -X no_debug_ranges を指定してインタープリタを実行した場合。

  • -X no_debug_ranges を指定してコンパイルされた pyc ファイルを読み込んだ場合。

  • コンパイラが生成した補助的な命令に対応する位置のタプル。

  • 実装固有の制限によって表現できない行番号や列番号。

この場合、タプルの一部またはすべての要素が None になることがあります。

Added in version 3.11.

注釈

この機能はコードオブジェクトに列位置を格納する必要があるため、コンパイルされた Python ファイルのディスク使用量やインタープリタのメモリ使用量がわずかに増える場合があります。 追加情報の格納やトレースバックへの追加情報の表示を無効にするには、コマンドラインフラグ -X no_debug_ranges または環境変数 PYTHONNODEBUGRANGES を使えます。

codeobject.co_lines()

連続する バイトコード の範囲についての情報を yield するイテレータを返します。 各要素は (start, end, lineno) の tuple です。

  • start (int) は バイトコード の範囲の開始オフセットを表します (この位置を含みます)。

  • end (int) は バイトコード の範囲の終了オフセットを表します (この位置は含みません)。

  • lineno は バイトコード の範囲の行番号を表す int です。 その範囲のバイトコードに行番号がない場合は None です。

yield される要素には次の性質があります。

  • 最初の範囲の start は 0 です。

  • (start, end) の範囲は後戻りせず、連続しています。 つまり、隣り合う tuple のペアでは、2 番目の start は 1 番目の end と等しくなります。

  • 逆向きの範囲はありません。 すべての 3 要素のタプルで end >= start が成り立ちます。

  • 最後に yield される tuple の end は バイトコード のサイズに等しくなります。

start == end となる幅 0 の範囲も許されます。 幅 0 の範囲は、ソースコードには存在するものの バイトコード コンパイラによって削除された行に使われます。

Added in version 3.10.

参考

PEP 626 - デバッグやその他のツールのための正確な行番号。

co_lines() メソッドを導入した PEP。

codeobject.replace(**kwargs)

指定されたフィールドに新しい値を設定した、コードオブジェクトのコピーを返します。

コードオブジェクトは、汎用関数 copy.replace() でもサポートされています。

Added in version 3.8.

3.2.13.2. フレーム (frame) オブジェクト

フレームオブジェクトは実行フレームを表します。 トレースバックオブジェクト に含まれることがあるほか、登録されたトレース関数にも渡されます。

3.2.13.2.1. 読み取り専用の特殊属性
frame.f_back

前のスタックフレーム (呼び出し元の方向) を指します。 スタックの最下層のフレームであれば None です。
frame.f_code

このフレームで実行している コードオブジェクト。 この属性にアクセスすると、引数 obj と "f_code" を伴う 監査イベント object.__getattr__ が発生します。
frame.f_locals

フレームが ローカル変数 の検索に使うマッピングです。 フレームが 最適化されたスコープ を参照している場合、書き込みが元のスコープに反映されるプロキシオブジェクトを返すことがあります。

バージョン 3.13 で変更: 最適化されたスコープではプロキシを返すようになりました。
frame.f_globals

フレームが グローバル変数 の検索に使う辞書
frame.f_builtins

フレームが 組み込み名 の検索に使う辞書
frame.f_lasti

フレームオブジェクト内の正確な命令位置 (コードオブジェクト の バイトコード 列に対するインデックス)
frame.f_generator

このフレームを所有する ジェネレータ または コルーチン オブジェクト。 通常の関数のフレームの場合は None です。

Added in version 3.14.
3.2.13.2.2. 書き込み可能な特殊属性
frame.f_trace

None でなければ、コード実行中のさまざまなイベントで呼び出される関数です (デバッガが使います)。 通常、新しいソース行ごとにイベントが発生します (f_trace_lines を参照)。
frame.f_trace_lines

この属性を False に設定すると、ソース行ごとのトレースイベントの発生を無効にします。
frame.f_trace_opcodes

この属性を True に設定すると、オペコードごとのイベントを要求できるようになります。 トレース関数が送出した例外がトレース対象の関数に伝わると、インタープリタの動作が未定義になる可能性があることに注意してください。
frame.f_lineno

フレームの現在の行番号です。 トレース関数内からこの属性に書き込むと、指定した行にジャンプします (最も内側のフレームでのみ可能です)。 デバッガはこの属性への書き込みによって、ジャンプコマンド (次に実行する文の設定) を実装できます。
3.2.13.2.3. フレームオブジェクトのメソッド

フレームオブジェクトはメソッドを一つサポートします:

frame.clear()

フレームが保持する ローカル変数 への参照をすべてクリアします。 フレームが ジェネレータ に属していた場合は、そのジェネレータの終了処理も行います。 これにより、フレームオブジェクトを含む循環参照を解消できます。 例えば 例外 を捕捉し、後で使うために トレースバック を保存した場合に役立ちます。

フレームが実行中または中断中の場合は RuntimeError が送出されます。

Added in version 3.4.

バージョン 3.13 で変更: 中断中のフレームをクリアしようとすると RuntimeError が送出されるようになりました (実行中のフレームでは以前から送出されていました)。

3.2.13.3. トレースバック (traceback) オブジェクト

トレースバックオブジェクトは 例外 のスタックトレースを表します。 例外が発生すると暗黙的に作成されますが、types.TracebackType を呼び出して明示的に作成することもできます。

バージョン 3.7 で変更: Python コードからトレースバックオブジェクトを明示的にインスタンス化できるようになりました。

暗黙的に作成されるトレースバックでは、例外ハンドラを探して実行スタックを巻き戻す際、各段階で現在のトレースバックの先頭にトレースバックオブジェクトが挿入されます。 例外ハンドラに入ると、プログラムからスタックトレースを利用できるようになります (try 文 を参照)。 sys.exc_info() が返すタプルの第 3 要素、または捕捉した例外の __traceback__ 属性としてアクセスできます。

プログラムに適切なハンドラがない場合、スタックトレースは読みやすく整形されて標準エラーストリームに書き出されます。 対話型インタープリタでは、sys.last_traceback としてユーザーからもアクセスできます。

明示的に作成するトレースバックでは、tb_next 属性をどのようにつないで完全なスタックトレースを構成するかは、作成者が決めます。

読み取り専用の特殊属性。

traceback.tb_frame

現在の階層の実行 フレーム を指します。

この属性にアクセスすると、引数 obj と "tb_frame" を伴う 監査イベント object.__getattr__ が発生します。
traceback.tb_lineno

例外が発生した行番号を示します。
traceback.tb_lasti

正確な命令位置を示します。

一致する except 節がない try 文や、finally 節を持つ try 文で例外が発生した場合、トレースバックの行番号と最後の命令は、その フレームオブジェクト の行番号とは異なることがあります。

traceback.tb_next

書き込み可能な特殊属性 tb_next は、スタックトレースの次の階層 (例外が発生したフレームの方向) を指します。 次の階層がなければ None です。

バージョン 3.7 で変更: この属性に書き込めるようになりました。

3.2.13.4. スライス (slice) オブジェクト

スライスオブジェクトは、 __getitem__() メソッドのためのスライスを表すのに使われます。スライスオブジェクトは組み込みの slice() 関数でも生成されます。

Added in version 3.15: slice() 型が 添字表記 をサポートするようになりました。 例えば型アノテーションに slice[float] と記述し、float オブジェクトを含むスライスを示せます。

読み出し専用の特殊属性: start は下限です; stop は上限です; step はステップの値です; それぞれ省略された場合は None となっています。これらの属性は任意の型を持てます。

スライスオブジェクトはメソッドを一つサポートします:

slice.indices(self, length)

このメソッドは単一の整数引数 length を取り、スライスオブジェクトが length 要素のシーケンスに適用されたときに表現する、スライスに関する情報を計算します。このメソッドは 3 つの整数からなるタプルを返します; それぞれ start および stop のインデックスと、step すなわちスライスのまたぎ幅です。インデックス値がないか、範囲外の値であれば、通常のスライスと変わらないやりかたで扱われます。

3.2.13.5. 静的メソッド (static method) オブジェクト

静的メソッドは、上で説明したような関数オブジェクトからメソッドオブジェクトへの変換を阻止するための方法を提供します。静的メソッドオブジェクトは他の何らかのオブジェクト、通常はユーザ定義メソッドオブジェクトを包むラッパです。静的メソッドをクラスやクラスインスタンスから取得すると、実際に返されるオブジェクトはラップされたオブジェクトになり、それ以上は変換の対象にはなりません。静的メソッドオブジェクトは通常呼び出し可能なオブジェクトをラップしますが、静的オブジェクト自体は呼び出し可能です。静的オブジェクトは組み込みコンストラクタ staticmethod() で生成されます。

3.2.13.6. クラスメソッドオブジェクト

クラスメソッドオブジェクトは、静的メソッドオブジェクトと同様に、別のオブジェクトをラップして、そのオブジェクトをクラスやクラスインスタンスから取得する方法を変えます。 取得時のクラスメソッドオブジェクトの動作については、上記の インスタンスメソッド で説明しています。 クラスメソッドオブジェクトは、組み込みの classmethod() コンストラクタで作成します。

3.3. 特殊メソッド名

クラスは、特殊な名前のメソッドを定義して、特殊な構文 (算術演算や添え字表記、スライス表記など) による特定の演算を実装できます。これは、Python の演算子オーバロード (operator overloading) へのアプローチです。これにより、クラスは言語の演算子に対する独自の振る舞いを定義できます。例えば、あるクラスが __getitem__() という名前のメソッドを定義しており、 x がこのクラスのインスタンスであるとすると、 x[i] は type(x).__getitem__(x, i) とほぼ等価です。特に注釈のない限り、適切なメソッドが定義されていないとき、このような演算を試みると例外 (たいていは AttributeError か TypeError) が送出されます。

特殊メソッドに None を設定することは、それに対応する演算が利用できないことを意味します。 例えば、クラスの __iter__() を None に設定した場合、そのクラスはイテラブルにはならず、そのインスタンスに対し iter() を呼び出すと (__getitem__() に処理が戻されずに) TypeError を送出します。 [2]

組み込み型をエミュレートするクラスを実装する際は、モデル化するオブジェクトにとって意味のある範囲に限ってエミュレーションを実装することが重要です。 例えば、個々の要素の取得は適切でも、スライスの取得には意味がないシーケンスもあります。 (W3C の Document Object Model の NodeList インターフェースがその一例です。)

3.3.1. 基本的なカスタマイズ

object.__new__(cls[, ...])

クラス cls の新しいインスタンスを作るために呼び出されます。 __new__() は静的メソッドで、インスタンスを生成する対象のクラスを最初の引数に取ります (特別扱いされるため、静的メソッドであると明示的に宣言する必要はありません)。 残りの引数は、オブジェクトのコンストラクタ式 (クラスの呼び出し) に渡されたものです。 __new__() は新しいオブジェクトのインスタンス (通常は cls のインスタンス) を返す必要があります。

典型的な実装では、クラスの新たなインスタンスを生成するときには super().__new__(cls[, ...]) に適切な引数を指定してスーパクラスの __new__() メソッドを呼び出し、新たに生成されたインスタンスに必要な変更を加えてから返します。

もし __new__() が オブジェクトの作成中に呼び出され、cls のインスタンスを返した場合には、 __init__(self[, ...]) のようにして新しいインスタンスの __init__() が呼び出されます。このとき、 self は新たに生成されたインスタンスで、残りの引数はオブジェクトコンストラクタに渡された引数と同じになります。

__new__() が cls のインスタンスを返さない場合、インスタンスの __init__() メソッドは呼び出されません。

__new__() の主な目的は、変更不能な型 (int, str, tuple など) のサブクラスでインスタンス生成をカスタマイズすることにあります。また、クラス生成をカスタマイズするために、カスタムのメタクラスでよくオーバーライドされます。

object.__init__(self[, ...])

インスタンスが (__new__() によって) 生成された後、それが呼び出し元に返される前に呼び出されます。引数はクラスのコンストラクタ式に渡したものです。基底クラスとその派生クラスがともに __init__() メソッドを持つ場合、派生クラスの __init__() メソッドは基底クラスの __init__() メソッドを明示的に呼び出して、インスタンスの基底クラス部分が適切に初期化されること保証しなければなりません。例えば、 super().__init__([args...]) 。

__new__() と __init__() は連携してオブジェクトを構成する (__new__() が作成し、 __init__() がそれをカスタマイズする) ので、 __init__() から非 None 値を返してはいけません; そうしてしまうと、実行時に TypeError が送出されてしまいます。

object.__del__(self)

インスタンスが破棄されるときに呼び出されます。 これはファイナライザや (適切ではありませんが) デストラクタとも呼ばれます。 基底クラスが __del__() メソッドを持っている場合は、派生クラスの __del__() メソッドは何であれ、基底クラスの __del__() メソッドを明示的に呼び出して、インスタンスの基底クラス部分をきちんと確実に削除しなければなりません。

__del__() メソッドが破棄しようとしているインスタンスへの新しい参照を作り、破棄を送らせることは (推奨されないものの) 可能です。 これはオブジェクトの 復活 と呼ばれます。 復活したオブジェクトが再度破棄される直前に __del__() が呼び出されるかどうかは実装依存です; 現在の CPython の実装では最初の一回しか呼び出されません。

インタープリタの終了時にまだ存在するオブジェクトについては、__del__() メソッドが呼び出される保証はありません。 weakref.finalize を使うと、オブジェクトがガベージコレクションで回収されたときに呼び出す後処理の関数を簡単に登録できます。

注釈

del x は直接 x.__del__() を呼び出しません --- 前者は x の参照カウントを 1 つ減らし、後者は x の参照カウントが 0 まで落ちたときのみ呼び出されます。

循環参照によって、オブジェクトの参照カウントが 0 にならない場合があります。 その場合、循環参照は後で 循環ガベージコレクタ によって検出され、削除されます。 よくある原因の 1 つは、捕捉した例外をローカル変数に保持することです。 フレームのローカル変数が例外を参照し、例外が自身のトレースバックを参照し、トレースバックがそこに含まれる全フレームのローカル変数を参照するためです。

参考

gc モジュールのドキュメント。

警告

メソッド __del__() は不安定な状況で呼び出されるため、実行中に発生した例外は無視され、代わりに sys.stderr に警告が表示されます。特に:

  • __del__() は、任意のコードが実行されているときに、任意のスレッドから呼び出せます。 __del__() で、ロックを取ったり、ブロックするリソースを呼び出したりする必要がある場合、 __del__() の実行により中断されたコードにより、そのリソースが既に取得されていて、デッドロックが起きるかもしれません。

  • __del__() は、インタプリタのシャットダウン中に実行できます。 従って、(他のモジュールも含めた) アクセスする必要があるグローバル変数はすでに削除されているか、 None に設定されているかもしれません。 Python は、単一のアンダースコアで始まる名前のグローバルオブジェクトは、他のグローバル変数が削除される前にモジュールから削除されることを保証します; そのようなグローバル変数への他からの参照が存在しない場合、__del__() メソッドが呼ばれた時点で、インポートされたモジュールがまだ利用可能であることを保証するのに役立つかもしれません。

object.__repr__(self)

repr() 組み込み関数によって呼び出され、オブジェクトを表す「公式の (official)」文字列を計算します。可能なら、これは (適切な環境が与えられれば) 同じ値のオブジェクトを再生成するのに使える、有効な Python 式のようなものであるべきです。できないなら、 <...some useful description...> 形式の文字列が返されるべきです。戻り値は文字列オブジェクトでなければなりません。クラスが __repr__() を定義していて __str__() は定義していなければ、そのクラスのインスタンスの「非公式の (informal)」文字列表現が要求されたときにも __repr__() が使われます。

通常はデバッグに使うため、情報が豊富で曖昧さのない表現にすることが重要です。 object クラス自身がデフォルトの実装を提供します。

object.__str__(self)

str(object)、デフォルトの __format__() 実装、および組み込み関数 print() から呼び出され、オブジェクトの「非公式な」、または表示に適した文字列表現を生成します。 戻り値は str オブジェクトでなければなりません。

__str__() が有効な Python 表現を返すことが期待されないという点で、このメソッドは object.__repr__() とは異なります: より便利な、または簡潔な表現を使用することができます。

組み込み型 object によって定義されたデフォルト実装は、 object.__repr__() を呼び出します。

object.__bytes__(self)

bytes から呼び出され、オブジェクトのバイト列による表現を生成します。 bytes オブジェクトを返す必要があります。 object クラス自身はこのメソッドを提供しません。

object.__format__(self, format_spec)

format() 組み込み関数、さらには フォーマット済み文字列リテラル の評価、 str.format() メソッドによって呼び出され、オブジェクトの "フォーマット化された (formatted)" 文字列表現を作ります。 format_spec 引数は、 必要なフォーマット化オプションの記述を含む文字列です。 format_spec 引数の解釈は、 __format__() を実装する型によりますが、 ほとんどのクラスは組み込み型のいずれかにフォーマット化を委譲したり、 同じようなフォーマット化オプション構文を使います。

標準のフォーマット構文の解説は、 書式指定ミニ言語 を参照してください。

戻り値は文字列オブジェクトでなければなりません。

object クラスのデフォルト実装には、空文字列の format_spec を渡す必要があります。 この実装は __str__() に処理を委譲します。

バージョン 3.4 で変更: 空でない文字列が渡された場合 object 自身の __format__ メソッドは TypeError を送出します。

バージョン 3.7 で変更: object.__format__(x, '') は format(str(x), '') ではなく str(x) と等価になりました。

object.__lt__(self, other)
object.__le__(self, other)
object.__eq__(self, other)
object.__ne__(self, other)
object.__gt__(self, other)
object.__ge__(self, other)

これらはいわゆる "拡張比較 (rich comparison)" メソッドです。演算子シンボルとメソッド名の対応は以下の通りです: x<y は x.__lt__(y) を呼び出します; x<=y は x.__le__(y) を呼び出します; x==y は x.__eq__(y) を呼び出します; x!=y は x.__ne__(y) を呼び出します; x>y は x.__gt__(y) を呼び出します; x>=y は x.__ge__(y) を呼び出します。

拡張比較メソッドは、与えられた引数のペアに対する演算を実装していない場合、シングルトン NotImplemented を返せます。 慣例として、比較できた場合は False または True を返します。 ただし、これらのメソッドは任意の値を返せます。 そのため、比較演算子を if 文の条件などブール値を求める文脈で使うと、Python は返された値に bool() を適用して真偽を判定します。

デフォルトでは、object は is を使って __eq__() を実装し、比較が偽になる場合は NotImplemented を返します。 つまり True if x is y else NotImplemented です。 __ne__() はデフォルトで __eq__() に処理を委譲し、結果が NotImplemented でなければ反転します。 比較演算子やそのデフォルト実装の間に、これ以外の暗黙の関係はありません。 例えば、(x<y or x==y) が真でも x<=y が真とは限りません。 1 つの基本的な演算から順序比較の演算を自動生成するには、@functools.total_ordering を参照してください。

object クラスはデフォルトで 値の比較 に沿う実装を提供します。 等値比較ではオブジェクトの同一性を比較し、順序比較では TypeError が送出されます。 各デフォルトメソッドはこれらの結果を直接返す場合も、NotImplemented を返す場合もあります。

カスタムの比較演算をサポートしていて、辞書のキーに使うことができる ハッシュ可能 オブジェクトを作るときの重要な注意点について、 __hash__() のドキュメント内に書かれているので参照してください。

これらのメソッドには、左右の引数を入れ替えた版 (左の引数が演算をサポートせず、右の引数がサポートする場合に使うもの) はありません。 代わりに、__lt__() と __gt__()、__le__() と __ge__() はそれぞれ互いの反射演算であり、__eq__() と __ne__() はそれぞれ自身の反射演算です。 被演算子の型が異なり、右の被演算子の型が左の被演算子の型の直接または間接のサブクラスである場合、右の被演算子の反射メソッドが優先されます。 それ以外の場合は左の被演算子のメソッドが優先されます。 仮想サブクラスの関係は考慮されません。

適切なメソッドがどれも NotImplemented 以外の値を返さない場合、== と != 演算子はそれぞれ is と is not による比較を行います。

object.__hash__(self)

組み込み関数 hash() や、set、frozenset、dict、frozendict などのハッシュを使うコレクションの要素に対する操作から呼び出されます。 __hash__() メソッドは整数を返す必要があります。 唯一の必須条件は、等しいと比較されるオブジェクトが同じハッシュ値を持つことです。 オブジェクトの比較に使われる構成要素をタプルにまとめ、そのタプルのハッシュを求めることで、構成要素のハッシュ値を組み合わせることを推奨します。 例を示します。

def __hash__(self):
    return hash((self.name, self.nick, self.color))

注釈

hash() はオブジェクト独自の __hash__() メソッドが返す値を Py_ssize_t のサイズに切り詰めます。 これは 64-bit でビルドされていると 8 バイトで、 32-bit でビルドされていると 4 バイトです。 オブジェクトの __hash__() が異なる bit サイズのビルドでも可搬性が必要である場合は、必ず全てのサポートするビルドの bit 幅をチェックしてください。 そうする簡単な方法は python -c "import sys; print(sys.hash_info.width)" を実行することです。

クラスが __eq__() メソッドを定義していないなら、 __hash__() メソッドも定義してはなりません; クラスが __eq__() を定義していても __hash__() を定義していないなら、そのインスタンスはハッシュ可能コレクションの要素として使えません。クラスがミュータブルなオブジェクトを定義しており、 __eq__() メソッドを実装しているなら、 __hash__() を定義してはなりません。これは、ハッシュ可能 コレクションの実装においてキーのハッシュ値がイミュータブルであることが要求されているからです (オブジェクトのハッシュ値が変化すると、誤ったハッシュバケツ: hash bucket に入ってしまいます)。

ユーザー定義クラスはデフォルトで、object クラスから継承した __eq__() メソッドと __hash__() メソッドを持ちます。 これらを使うと、どのオブジェクトも自身以外とは等しくないと比較されます。 また、x.__hash__() は、x == y なら x is y と hash(x) == hash(y) の両方が成り立つような適切な値を返します。

__eq__() をオーバーライドしていて __hash__() を定義していないクラスでは、 __hash__() は暗黙的に None に設定されます。 クラスの __hash__() メソッドが None の場合、そのクラスのインスタンスのハッシュ値を取得しようとすると適切な TypeError が送出され、 isinstance(obj, collections.abc.Hashable) でチェックするとハッシュ不能なものとして正しく認識されます。

__eq__() をオーバーライドしたクラスが親クラスからの __hash__() の 実装を保持したいなら、明示的に __hash__ = <ParentClass>.__hash__ を設定することで、それをインタプリタに伝えなければなりません。

__eq__() をオーバーライドしていないクラスがハッシュサポートを抑制したい場合、クラス定義に __hash__ = None を含めてください。クラス自身で明示的に TypeError を送出する __hash__() を定義すると、 isinstance(obj, collections.abc.Hashable) 呼び出しで誤ってハッシュ可能と識別されるでしょう。

注釈

デフォルトでは、文字列とバイト列の __hash__() 値は予測不可能なランダム値で "ソルト" されます。 ハッシュ値は単独の Python プロセス内では定数であり続けますが、Python を繰り返し起動する毎に、予測できなくなります。

これは、辞書への挿入の最悪時の計算量 O(n2) を悪用するよう選ばれた入力による、サービス拒否攻撃を防ぐためのものです。 詳細は https://ocert.org/advisories/ocert-2011-003.html を参照してください。

ハッシュ値の変更は、集合のイテレーション順序に影響します。Python はこの順序付けを保証していません (そして通常 32-bit と 64-bit の間でも異なります)。

PYTHONHASHSEED も参照してください。

バージョン 3.3 で変更: ハッシュのランダム化がデフォルトで有効になりました。

object.__bool__(self)

真偽値の判定と組み込み操作 bool() を実装するために呼び出されます。 False または True を返す必要があります。 このメソッドが定義されていなければ、__len__() が定義されている場合はそれを呼び出し、結果が 0 でなければオブジェクトを真とみなします。 object クラス自身のように、クラスが __len__() も __bool__() も定義していない場合、そのすべてのインスタンスを真とみなします。

3.3.2. 属性値アクセスをカスタマイズする

以下のメソッドを定義して、クラスインスタンスへの属性アクセス ( x.name の使用、 x.name への代入、 x.name の削除) の意味をカスタマイズすることができます。

object.__getattr__(self, name)

デフォルトの属性アクセスが AttributeError で失敗したときに呼び出されます。 これは、name が self のインスタンス属性でもクラス階層内の属性でもないために __getattribute__() が AttributeError を送出した場合や、name プロパティの __get__() が AttributeError を送出した場合です。 このメソッドは計算した属性値を返すか、AttributeError 例外を送出する必要があります。 object クラス自身はこのメソッドを提供しません。

通常の仕組みで属性が見つかった場合、__getattr__() は呼び出されません。 (__getattr__() と __setattr__() のこの非対称性は意図的なものです。) これは効率のためであると同時に、そうしなければ __getattr__() からインスタンスのほかの属性にアクセスする手段がなくなるためです。 少なくともインスタンス変数については、インスタンスの属性辞書に値を入れず、代わりに別のオブジェクトに入れることで、完全に制御できます。 属性アクセスを実際に完全に制御する方法は、次の __getattribute__() メソッドを参照してください。

object.__getattribute__(self, name)

クラスのインスタンスに対する属性アクセスを実装するために、無条件に呼び出されます。 クラスが __getattr__() も定義している場合、それは __getattribute__() が明示的に呼び出すか、AttributeError を送出しない限り呼び出されません。 このメソッドは計算した属性値を返すか、AttributeError 例外を送出する必要があります。 無限再帰を避けるため、必要な属性へのアクセスには、常に基底クラスの同名のメソッドを呼び出してください。 例えば object.__getattribute__(self, name) とします。

注釈

ただし、言語の構文や 組み込み関数 による暗黙的な呼び出しで特殊メソッドを検索する場合、このメソッドを経由しないことがあります。 特殊メソッド検索 を参照してください。

セキュリティ上注意が必要な一部の属性アクセスでは、引数 obj と name を伴う 監査イベント object.__getattr__ が発生します。

object.__setattr__(self, name, value)

属性の代入が試みられた際に呼び出されます。これは通常の代入の過程 (すなわち、インスタンス辞書への値の代入) の代わりに呼び出されます。name は属性名で、value はその属性に代入する値です。

__setattr__() の中でインスタンス属性への代入が必要なら、基底クラスのこれと同じ名前のメソッドを呼び出さなければなりません。例えば、 object.__setattr__(self, name, value) とします。

セキュリティ上注意が必要な一部の属性への代入では、引数 obj、name、value を伴う 監査イベント object.__setattr__ が発生します。

object.__delattr__(self, name)

__setattr__() に似ていますが、代入ではなく値の削除を行います。このメソッドを実装するのは、オブジェクトにとって del obj.name が意味がある場合だけにしなければなりません。

セキュリティ上注意が必要な一部の属性の削除では、引数 obj と name を伴う 監査イベント object.__delattr__ が発生します。

object.__dir__(self)

オブジェクトに対して dir() が呼び出されたときに呼び出されます。 イテラブルを返さなければなりません。 dir() は返されたイテラブルをリストに変換してソートします。

3.3.2.1. モジュールの属性値アクセスをカスタマイズする

module.__getattr__()
module.__dir__()

特殊な名前の __getattr__ と __dir__ も、モジュール属性へのアクセスをカスタマイズするのに使えます。 モジュールレベルの __getattr__ 関数は属性名である 1 引数を受け取り、計算した値を返すか AttributeError を送出します。 属性がモジュールオブジェクトから、通常の検索、つまり object.__getattribute__() で見付からなかった場合は、 AttributeError を送出する前に、モジュールの __dict__ から __getattr__ が検索されます。 見付かった場合は、その属性名で呼び出され、結果が返されます。

__dir__ 関数は引数を受け取らず、モジュールからアクセス可能な名前を表す文字列のイテラブルを返す必要があります。 この関数がある場合、モジュールに対する dir() の標準の検索を置き換えます。

module.__class__

より細かい粒度でのモジュールの動作 (属性やプロパティの設定など) のカスタマイズのために、モジュールオブジェクトの __class__ 属性に types.ModuleType のサブクラスが設定できます。 例えば次のようになります:

import sys
from types import ModuleType

class VerboseModule(ModuleType):
    def __repr__(self):
        return f'Verbose {self.__name__}'

    def __setattr__(self, attr, value):
        print(f'Setting {attr}...')
        super().__setattr__(attr, value)

sys.modules[__name__].__class__ = VerboseModule

注釈

モジュールの __getattr__ の定義や __class__ の設定が影響するのは、属性アクセス構文による検索だけです。 モジュール内のコードからのアクセスでも、モジュールのグローバル辞書への参照を通じたアクセスでも、グローバル変数への直接アクセスには影響しません。

バージョン 3.5 で変更: モジュールの属性 __class__ が書き込み可能になりました。

Added in version 3.7: __getattr__ モジュール属性と __dir__ モジュール属性。

参考

PEP 562 - モジュールの __getattr__ と __dir__

モジュールの __getattr__ 関数および __dir__ 関数の説明。

3.3.2.2. デスクリプタ (descriptor) の実装

以下のメソッドが適用されるのは、そのメソッドを含むクラス (いわゆる デスクリプタ クラス) のインスタンスが、オーナー クラス内にある場合だけです。 デスクリプタは、オーナークラスまたはその親クラスのクラス辞書に入っている必要があります。 以下の例で「属性」とは、オーナークラスの __dict__ 内でそのプロパティに対応するキーを名前とする属性を指します。 object クラス自身は、これらのプロトコルを実装しません。

object.__get__(self, instance, owner=None)

オーナークラスの属性 (クラス属性アクセス) またはそのクラスのインスタンスの属性 (インスタンス属性アクセス) を取得するために呼び出されます。 オプション引数 owner はオーナークラスです。 instance は、インスタンスを通じて属性にアクセスした場合はそのインスタンス、 owner を通じてアクセスした場合は None です。

このメソッドは、算出された属性値を返すか、 AttributeError 例外を送出します。

PEP 252 は __get__() は1つや2つの引数を持つ呼び出し可能オブジェクトであると定義しています。Pythonの組み込みのデスクリプタはこの仕様をサポートしていますが、サードパーティ製のツールの中には両方の引数を必要とするものもあります。Pythonの __getattribute__() 実装は必要かどうかに関わらず、両方の引数を常に渡します。

object.__set__(self, instance, value)

オーナークラスのインスタンス instance 上の属性を新たな値 value に設定する際に呼び出されます。

__set__() あるいは __delete__() を追加すると、デスクリプタは「データデスクリプタ」に変わります。詳細は デスクリプタの呼び出し を参照してください。

object.__delete__(self, instance)

オーナークラスのインスタンス instance 上の属性を削除する際に呼び出されます。

デスクリプタのインスタンスには __objclass__ 属性がある場合もあります。

object.__objclass__

inspect モジュールは __objclass__ 属性を、このオブジェクトが定義されたクラスを指定するものとして解釈します。 適切に設定すると、動的なクラス属性の実行時イントロスペクションに役立ちます。 呼び出し可能オブジェクトでは、最初の位置引数に、その型またはサブクラスのインスタンスが期待される、あるいは必要であることを示す場合があります。 例えば CPython は、C で実装された非束縛メソッドにこの属性を設定します。

3.3.2.3. デスクリプタの呼び出し

一般にデスクリプタとは、特殊な "束縛に関する動作 (binding behaviour)" をもつオブジェクト属性のことです。デスクリプタは、デスクリプタプロトコル (descriptor protocol) のメソッド: __get__(), __set__(), および __delete__() を使って、属性アクセスをオーバーライドしているものです。これらのメソッドのいずれかがオブジェクトに対して定義されている場合、オブジェクトはデスクリプタであるといいます。

属性アクセスのデフォルトの動作は、オブジェクトの辞書から値を取り出したり、値を設定したり、削除したりするというものです。例えば、 a.x による属性の検索では、まず a.__dict__['x'] 、次に type(a).__dict__['x'] 、そして type(a) の基底クラスでメタクラスでないものに続く、といった具合に連鎖が起こります。

しかし、検索対象の値が、デスクリプタメソッドのいずれかを定義しているオブジェクトであれば、Python はデフォルトの動作をオーバーライドして、代わりにデスクリプタメソッドを呼び出します。先述の連鎖の中のどこでデスクリプタメソッドが呼び出されるかは、どのデスクリプタメソッドが定義されていて、どのように呼び出されたかに依存します。

デスクリプタ呼び出しの基点となるのは、属性名への束縛 (binding) 、すなわち a.x です。引数がどのようにデスクリプタに結合されるかは a に依存します:

直接呼び出し (Direct Call)

最も単純で、かつめったに使われない呼び出し操作は、コード中で直接デスクリプタメソッドの呼び出し: x.__get__(a) を行うというものです。

インスタンス束縛 (Instance Binding)

オブジェクトインスタンスへ束縛すると、a.x は呼び出し type(a).__dict__['x'].__get__(a, type(a)) に変換されます。

クラス束縛 (Class Binding)

クラスへ束縛すると、A.x は呼び出し A.__dict__['x'].__get__(None, A) に変換されます。

super 束縛 (Super Binding)

super(A, a).x のようにドット記法で属性を検索すると、a.__class__.__mro__ の中で A の後にある基底クラス B を探し、 B.__dict__['x'].__get__(a, A) を返します。 x がデスクリプタでなければ、そのまま返します。

インスタンスへの束縛では、デスクリプタ呼び出しの優先順位は定義されたデスクリプタメソッドによって決まります。 デスクリプタは __get__()、__set__()、__delete__() を任意に組み合わせて定義できます。 __get__() が定義されていなければ、オブジェクトのインスタンス辞書に値がある場合を除き、属性へのアクセスはデスクリプタオブジェクト自身を返します。 __set__() または __delete__() が定義されていればデータデスクリプタ、どちらも定義されていなければ非データデスクリプタです。 通常、データデスクリプタは __get__() と __set__() の両方を定義し、非データデスクリプタは __get__() メソッドだけを持ちます。 __get__() と、__set__() または __delete__() を定義したデータデスクリプタは、インスタンス辞書での再定義よりも常に優先されます。 一方、非データデスクリプタはインスタンスでオーバーライドできます。

Python のメソッド (@staticmethod や @classmethod でデコレートされたものも含みます) は、非データデスクリプタとして実装されています。 そのため、インスタンスでメソッドを再定義してオーバーライドできます。 これにより、同じクラスのほかのインスタンスとは異なる動作を個々のインスタンスに持たせられます。

@property デコレーターはデータデスクリプタとして実装されています。 そのため、インスタンスではプロパティの動作をオーバーライドできません。

3.3.2.4. __slots__

__slots__ を使うと、(プロパティのように) データメンバを明示的に宣言し、 (明示的に __slots__ で宣言しているか親クラスに存在しているかでない限り) __dict__ や __weakref__ を作成しないようにできます。

__dict__ を使うのに比べて、節約できるメモリ空間はかなり大きいです。 属性探索のスピードもかなり向上できます。

object.__slots__

このクラス変数には、インスタンスが用いる変数名を表す、文字列、イテラブル、または文字列のシーケンスを代入できます。__slots__ は、各インスタンスに対して宣言された変数に必要な記憶領域を確保し、__dict__ と __weakref__ が自動的に生成されないようにします。

__slots__ を使う際の注意点。

  • __slots__ を持たないクラスから継承するとき、インスタンスの __dict__ 属性と __weakref__ 属性は常に利用可能です。

  • __dict__ 変数がない場合、 __slots__ に列挙されていない新たな変数をインスタンスに代入することはできません。列挙されていない変数名を使って代入しようとした場合、 AttributeError が送出されます。新たな変数を動的に代入したいのなら、 __slots__ を宣言する際に '__dict__' を変数名のシーケンスに追加してください。

  • __slots__ を定義しているクラスの各インスタンスに __weakref__ 変数がない場合、インスタンスに対する弱参照 (weak references) はサポートされません。弱参照のサポートが必要なら、 __slots__ を宣言する際に '__weakref__' を変数名のシーケンスに追加してください。

  • __slots__ は、クラスのレベルで各変数に対する デスクリプタ を使って実装されます。その結果、 __slots__ に定義されているインスタンス変数のデフォルト値はクラス属性を使って設定できなくなっています; そうしないと、デスクリプタによる代入をクラス属性が上書きしてしまうからです。

  • __slots__ 宣言の効果は、定義されたクラスだけに限りません。 親クラスで宣言した __slots__ は子クラスでも使えます。 ただし、サブクラスも __slots__ を定義しない限り、そのインスタンスには __dict__ と __weakref__ が作られます。 サブクラスの __slots__ には、追加する スロットの名前だけを含めてください。

  • あるクラスで、基底クラスですでに定義されているスロットを定義した場合、基底クラスのスロットで定義されているインスタンス変数は (デスクリプタを基底クラスから直接取得しない限り) アクセスできなくなります。これにより、プログラムの趣意が不定になってしまいます。将来は、この問題を避けるために何らかのチェックが追加されるかもしれません。

  • tuple を除く、int、bytes、type などの 可変長の組み込み型 から派生したクラスに、__dict__ と __weakref__ 以外の __slots__ を定義すると TypeError が送出されます。

  • __slots__ には、文字列以外の任意の イテラブル を代入できます。

  • __slots__ に 辞書 を代入すると、そのキーがスロット名として使われます。 辞書の値で属性ごとのドキュメンテーション文字列を指定できます。 これらは inspect.getdoc() に認識され、help() の出力に表示されます。

  • __class__ への代入は、両方のクラスが同じ __slots__ を持つ場合にのみ機能します。

  • スロットを持つ複数の親クラスから 多重継承 できますが、スロットによって作られる属性を持てる親クラスは 1 つだけです。 ほかの基底クラスのスロットレイアウトは空でなければなりません。 この条件に違反すると TypeError が送出されます。

  • もし __slots__ に対して イテレータ を使用すると、イテレータの値ごとに デスクリプタ が作られます。しかし、 __slots__ 属性は空のイテレータとなります。

バージョン 3.15 で変更: どのクラスでも __dict__ と __weakref__ の __slots__ を定義できるようになりました。 tuple から派生したクラスでは任意の __slots__ を定義できるようになりました。

3.3.3. クラス生成をカスタマイズする

クラスが他のクラスを継承するときに必ず、親クラスの __init_subclass__() が呼び出されます。これを利用すると、サブクラスの挙動を変更するクラスを書くことができます。これは、クラスデコレータととても良く似ていますが、クラスデコレータが、それが適用された特定のクラスにのみに影響するのに対して、 __init_subclass__ は、もっぱら、このメソッドを定義したクラスの将来のサブクラスに適用されます。

classmethod object.__init_subclass__(cls)

このメソッドは、それが定義されたクラスが継承された際に必ず呼び出されます。cls は新しいサブクラスです。もし、このメソッドがインスタンスメソッドとして定義されると、暗黙的にクラスメソッドに変換されます。

新しいクラスに指定したキーワード引数は、親クラスの __init_subclass__ に渡されます。 __init_subclass__ を使うほかのクラスと互換性を保つには、必要なキーワード引数だけを取り出し、残りを基底クラスに渡してください。 例えば次のようにします。

class Philosopher:
    def __init_subclass__(cls, /, default_name, **kwargs):
        super().__init_subclass__(**kwargs)
        cls.default_name = default_name

class AustralianPhilosopher(Philosopher, default_name="Bruce"):
    pass

object.__init_subclass__ のデフォルト実装は何も行いませんが、何らかの引数とともに呼び出された場合は、エラーを送出します。

注釈

メタクラスのヒント metaclass は残りの型機構によって消費され、 __init_subclass__ 実装に渡されることはありません。 実際のメタクラス (明示的なヒントではなく) は、 type(cls) としてアクセスできます。

Added in version 3.6.

クラスの作成時、type.__new__() はクラス変数を調べ、__set_name__() フックを持つものについてそのフックを呼び出します。

object.__set_name__(self, owner, name)

オーナークラス owner が作成される際に自動的に呼び出されます。 オブジェクトは、そのクラス内で name に代入されています。

class A:
    x = C()  # 自動的に x.__set_name__(A, 'x') が呼び出される

クラスを作成した後でクラス変数を代入した場合、__set_name__() は自動的には呼び出されません。 必要であれば __set_name__() を直接呼び出せます。

class A:
   pass

c = C()
A.x = c                  # フックは呼び出されない
c.__set_name__(A, 'x')   # フックを手動で呼び出す

詳細は クラスオブジェクトの作成 を参照してください。

Added in version 3.6.

3.3.3.1. メタクラス

デフォルトでは、クラスは type() を使って構築されます。 クラス本体は新しい名前空間で実行され、クラス名が type(name, bases, namespace) の結果にローカルに束縛されます。

クラス生成プロセスはカスタマイズできます。 そのためにはクラス定義行で metaclass キーワード引数を渡すか、そのような引数を定義行に含む既存のクラスを継承します。 次の例で MyClass と MySubclass は両方とも Meta のインスタンスです:

class Meta(type):
    pass

class MyClass(metaclass=Meta):
    pass

class MySubclass(MyClass):
    pass

クラス定義の中で指定された他のキーワード引数は、後述するすべてのメタクラス操作に渡されます。

クラス定義が実行される際に、以下のステップが生じます:

  • MRO エントリの解決が行われる;

  • 適切なメタクラスが決定される;

  • クラスの名前空間が準備される;

  • クラスの本体が実行される;

  • クラスオブジェクトが作られる。

3.3.3.2. MRO エントリの解決

object.__mro_entries__(self, bases)

クラス定義に現れる基底が type のインスタンスではない場合、その基底の __mro_entries__() メソッドが検索されます。 __mro_entries__() メソッドが見つかれば、クラス作成時に、その基底は __mro_entries__() を呼び出した結果に置き換えられます。 このメソッドの bases 引数には元の基底のタプルが渡され、その基底の代わりに使うクラスのタプルを返す必要があります。 空のタプルを返しても構いません。 その場合、元の基底は無視されます。

参考

types.resolve_bases()

type のインスタンスではない基底を動的に解決します。

types.get_original_bases()

__mro_entries__() による変更前の、クラスの「元の基底」を取得します。

PEP 560

typing モジュールとジェネリック型のための中核的なサポート。

3.3.3.3. 適切なメタクラスの決定

クラス定義に対して適切なメタクラスは、以下のように決定されます:

  • 基底も明示的なメタクラスも与えられていない場合は、 type() が使われます;

  • 明示的なメタクラスが与えられていて、それが type() のインスタンス ではない 場合、それをメタクラスとして直接使います;

  • 明示的なメタクラスとして type() のインスタンスが与えられたか、基底が定義されていた場合は、最も派生した (継承関係で最も下の) メタクラスが使われます。

最も派生的なメタクラスは、(もしあれば) 明示的に指定されたメタクラスと、指定されたすべてのベースクラスのメタクラスから選ばれます。最も派生的なメタクラスは、これらのメタクラス候補のすべてのサブタイプであるようなものです。メタクラス候補のどれもその基準を満たさなければ、クラス定義は TypeError で失敗します。

3.3.3.4. クラスの名前空間の準備

適切なメタクラスが決まると、クラスの名前空間が準備されます。 メタクラスに __prepare__ 属性があれば、namespace = metaclass.__prepare__(name, bases, **kwds) として呼び出されます。 追加のキーワード引数は、クラス定義で指定されたものです。 __prepare__ メソッドは クラスメソッド として実装する必要があります。 返された名前空間は __new__ に渡されますが、最終的なクラスオブジェクトが作成される際には、その名前空間が新しい dict にコピーされます。

メタクラスに __prepare__ 属性がない場合、クラスの名前空間は空の 順序付きマッピングとして初期化されます。

参考

PEP 3115 - Metaclasses in Python 3000

__prepare__ 名前空間フックの導入

3.3.3.5. クラス本体の実行

クラス本体が (大まかには) exec(body, globals(), namespace) として実行されます。通常の呼び出しと exec() の重要な違いは、クラス定義が関数内部で行われる場合、レキシカルスコープによってクラス本体 (任意のメソッドを含む) が現在のスコープと外側のスコープから名前を参照できるという点です。

しかし、クラス定義が関数内部で行われる時でさえ、クラス内部で定義されたメソッドはクラススコープで定義された名前を見ることはできません。クラス変数はインスタンスメソッドかクラスメソッドの最初のパラメータからアクセスするか、次の節で説明する、暗黙的に静的スコープが切られている __class__ 参照からアクセスしなければなりません。

3.3.3.6. クラスオブジェクトの作成

クラス本体の実行によってクラスの名前空間が初期化されたら、metaclass(name, bases, namespace, **kwds) を呼び出すことでクラスオブジェクトが作成されます (ここで渡される追加のキーワードは __prepare__ に渡されるものと同じです)。

このクラスオブジェクトは、 super() の無引数形式によって参照されるものです。 __class__ は、クラス本体中のメソッドが __class__ または super のいずれかを参照している場合に、コンパイラによって作成される暗黙のクロージャー参照です。これは、メソッドに渡された最初の引数に基づいて現在の呼び出しを行うために使用されるクラスまたはインスタンスが識別される一方、 super() の無引数形式がレキシカルスコープに基づいて定義されているクラスを正確に識別することを可能にします。

CPython 3.6 以降では、__class__ セルはクラスの名前空間の __classcell__ エントリーとしてメタクラスに渡されます。 このエントリーがある場合、クラスを正しく初期化するには type.__new__ の呼び出しまで引き継がなければなりません。 引き継がないと、Python 3.8 では RuntimeError が発生します。

デフォルトのメタクラス type や最終的には type.__new__ を呼び出すメタクラスを使っているときは、クラスオブジェクトを作成した後に次のカスタム化の手順が起動されます:

  1. type.__new__ メソッドが、クラスの名前空間にある属性のうち __set_name__() メソッドを定義しているものをすべて集めます。

  2. それらの __set_name__ メソッドが、作成中のクラスと、それぞれの属性に割り当てられた名前を引数として呼び出されます。

  3. 新しいクラスのメソッド解決順序ですぐ上に位置する親クラスで __init_subclass__() フックが呼び出されます。

クラスオブジェクトが作成された後には、クラス定義に含まれているクラスデコレータ (もしあれば) にクラスオブジェクトが渡され、デコレータが返すオブジェクトがここで定義されたクラスとしてローカルの名前空間に束縛されます。

type.__new__ で新しいクラスを作成すると、namespace 引数に渡したオブジェクトは新しい順序付きマッピングにコピーされ、元のオブジェクトは破棄されます。 コピーは読み取り専用のプロキシでラップされ、クラスオブジェクトの __dict__ 属性になります。

参考

PEP 3135 - New super

暗黙の __class__ クロージャ参照について記述しています

3.3.3.7. メタクラスの用途

メタクラスは限りない潜在的利用価値を持っています。これまで試されてきたアイデアには、列挙型、ログ記録、インターフェースのチェック、 自動デリゲーション、自動プロパティ生成、プロキシ、フレームワーク、そして自動リソースロック／同期といったものがあります。

3.3.4. インスタンス判定とサブクラス判定のカスタマイズ

以下のメソッドは組み込み関数 isinstance() と issubclass() のデフォルトの動作を上書きするのに利用します。

特に、 abc.ABCMeta メタクラスは、抽象基底クラス (ABCs) を"仮想基底クラス (virtual base classes)" として、他の ABC を含む、任意のクラスや (組み込み型を含む) 型に追加するために、これらのメソッドを実装しています。

type.__instancecheck__(self, instance)

instance が (直接、または間接的に) class のインスタンスと考えられる場合に true を返します。定義されていれば、 isinstance(instance, class) の実装のために呼び出されます。

type.__subclasscheck__(self, subclass)

subclass が (直接、または間接的に) class のサブクラスと考えられる場合に true を返します。定義されていれば、 issubclass(subclass, class) の実装のために呼び出されます。

これらのメソッドはクラスの型、つまりメタクラスで検索されます。 対象のクラス自身にクラスメソッドとして定義することはできません。 これはインスタンスに対して呼び出される特殊メソッドの検索と同じ規則であり、この場合はインスタンス自身がクラスであるという違いだけです。

参考

PEP 3119 - 抽象基底クラスの導入

__instancecheck__() と __subclasscheck__() を通じて、isinstance() と issubclass() の動作をカスタマイズするための仕様を含みます。 また、言語に抽象基底クラスを追加するにあたり、この機能を導入する動機も説明しています (abc モジュールを参照)。

3.3.5. ジェネリック型をエミュレートする

型アノテーション を使うときは、角括弧の記法で ジェネリック型 を パラメータ化 すると便利なことがあります。 例えば list[int] というアノテーションは、すべての要素が int 型である list を表すために使えます。

参考

PEP 484 - 型ヒント

Python の型アノテーションの枠組みの導入

ジェネリックエイリアス型

パラメータ化されたジェネリッククラスを表すオブジェクトのドキュメント

ジェネリクス、ユーザー定義ジェネリック型、typing.Generic

実行時にパラメータ設定が可能であり、かつ静的な型チェッカーが理解できるジェネリッククラスを実装する方法のドキュメントです。

一般に、クラスをパラメータ化できるのは、特殊クラスメソッド __class_getitem__() を定義している場合だけです。

classmethod object.__class_getitem__(cls, key)

key にある型引数で特殊化されたジェネリッククラスを表すオブジェクトを返します。

クラスに定義された __class_getitem__() は自動的にクラスメソッドになります。 そのため、定義時に @classmethod でデコレートする必要はありません。

3.3.5.1. __class_getitem__ の目的

__class_getitem__() の目的は、標準ライブラリのジェネリッククラスを実行時にパラメータ化できるようにして、それらのクラスに 型ヒント を簡単に適用できるようにすることです。

実行時にパラメータ化でき、静的型チェッカーが理解できる独自のジェネリッククラスを実装するには、__class_getitem__() を実装済みの標準ライブラリのクラスを継承するか、独自の __class_getitem__() 実装を持つ typing.Generic を継承してください。

標準ライブラリ以外で定義されたクラスで __class_getitem__() を独自に実装すると、mypy などのサードパーティの型チェッカーが理解できない場合があります。 どのクラスでも、型ヒント以外の目的で __class_getitem__() を使うことは推奨されません。

3.3.5.2. __class_getitem__ と __getitem__ の違い

通常、角括弧を使ってオブジェクトに 添字を指定 すると、そのオブジェクトのクラスで定義されたインスタンスメソッド __getitem__() が呼び出されます。 ただし、添字を指定するオブジェクト自体がクラスの場合は、代わりにクラスメソッド __class_getitem__() が呼び出されることがあります。 __class_getitem__() を適切に定義するには、GenericAlias オブジェクトを返すようにします。

式 obj[x] を処理するとき、Python インタープリタはおおむね次の手順で __getitem__() と __class_getitem__() のどちらを呼び出すかを決めます。

from inspect import isclass

def subscribe(obj, x):
    """式 'obj[x]' の結果を返す"""

    class_of_obj = type(obj)

    # obj のクラスが __getitem__ を定義していれば、
    # class_of_obj.__getitem__(obj, x) を呼び出す
    if hasattr(class_of_obj, '__getitem__'):
        return class_of_obj.__getitem__(obj, x)

    # そうでなく、obj がクラスで __class_getitem__ を定義していれば、
    # obj.__class_getitem__(x) を呼び出す
    elif isclass(obj) and hasattr(obj, '__class_getitem__'):
        return obj.__class_getitem__(x)

    # それ以外の場合は例外を送出する
    else:
        raise TypeError(
            f"'{class_of_obj.__name__}' object is not subscriptable"
        )

Python ではすべてのクラス自体が別のクラスのインスタンスです。 クラスのクラスは メタクラス と呼ばれ、ほとんどのクラスのメタクラスは type クラスです。 type は __getitem__() を定義していないので、list[int]、dict[str, float]、tuple[str, bytes] といった式ではいずれも __class_getitem__() が呼び出されます。

>>> # 他のほとんどのクラスと同様、list のメタクラスは "type":
>>> type(list)
<class 'type'>
>>> type(dict) == type(list) == type(tuple) == type(str) == type(bytes)
True
>>> # "list[int]" は "list.__class_getitem__(int)" を呼び出す
>>> list[int]
list[int]
>>> # list.__class_getitem__ は GenericAlias オブジェクトを返す:
>>> type(list[int])
<class 'types.GenericAlias'>

ただし、クラスのメタクラスが独自に __getitem__() を定義している場合、そのクラスへの添字指定は異なる動作をすることがあります。 enum モジュールにその例があります。

>>> from enum import Enum
>>> class Menu(Enum):
...     """A breakfast menu"""
...     SPAM = 'spam'
...     BACON = 'bacon'
...
>>> # Enum classes have a custom metaclass:
>>> type(Menu)
<class 'enum.EnumMeta'>
>>> # EnumMeta defines __getitem__,
>>> # so __class_getitem__ is not called,
>>> # and the result is not a GenericAlias object:
>>> Menu['SPAM']
<Menu.SPAM: 'spam'>
>>> type(Menu['SPAM'])
<enum 'Menu'>

参考

PEP 560 - typing モジュールとジェネリック型に対する言語コアによるサポート

__class_getitem__() を導入し、添字指定 で __getitem__() の代わりに __class_getitem__() が呼び出される条件を説明しています。

3.3.6. 呼び出し可能オブジェクトをエミュレートする

object.__call__(self[, args...])

インスタンスが関数として「呼び出された」ときに呼び出されます。 このメソッドが定義されている場合、x(arg1, arg2, ...) はおおむね type(x).__call__(x, arg1, ...) に置き換えられます。 object クラス自体はこのメソッドを提供しません。

3.3.7. コンテナをエミュレートする

The following methods can be defined to implement container objects. None of them are provided by the object class itself. Containers usually are sequences (such as lists or tuples) or mappings (like dictionaries), but can represent other containers as well. The first set of methods is used either to emulate a sequence or to emulate a mapping; the difference is that for a sequence, the allowable keys should be the integers k for which 0 <= k < N where N is the length of the sequence, or slice objects, which define a range of items. It is also recommended that mappings provide the methods keys(), values(), items(), get(), clear(), setdefault(), pop(), popitem(), copy(), and update() behaving similar to those for Python's standard dictionary objects. The collections.abc module provides a MutableMapping abstract base class to help create those methods from a base set of __getitem__(), __setitem__(), __delitem__(), and keys().

変更可能なシーケンスは、Python の標準の list オブジェクトと同様に、append()、clear()、count()、extend()、index()、insert()、pop()、remove()、reverse() メソッドを提供するべきです。 さらにシーケンス型は、後述の __add__()、__radd__()、__iadd__()、__mul__()、__rmul__()、__imul__() メソッドを定義して、加算 (結合) と乗算 (繰り返し) を実装するべきです。 それ以外の数値演算子は定義するべきではありません。

マッピングとシーケンスのどちらも、in 演算子を効率よく使えるように __contains__() メソッドを実装することが推奨されます。 マッピングの in はキーを検索し、シーケンスの in は値を検索するようにします。 また、コンテナ内を効率よく反復処理できるように、どちらも __iter__() メソッドを実装することが推奨されます。 マッピングの __iter__() はキーを反復処理し、シーケンスでは値を反復処理するようにします。

object.__len__(self)

組み込み関数 len() を実装するために呼び出されます。 オブジェクトの長さを >= 0 の整数で返す必要があります。 また、__bool__() メソッドを定義しておらず、__len__() メソッドがゼロを返すオブジェクトは、真偽値を求める文脈では偽とみなされます。

CPython では長さは sys.maxsize 以下でなければなりません。 長さが sys.maxsize より大きいと、len() などの機能が OverflowError を送出する場合があります。 真偽値の判定で OverflowError が送出されるのを防ぐには、オブジェクトに __bool__() メソッドを定義する必要があります。

object.__length_hint__(self)

operator.length_hint() を実装するために呼び出されます。 オブジェクトの推定の長さを返す必要があります (実際の長さより大きくても小さくても構いません)。 長さは >= 0 の整数でなければなりません。 NotImplemented を返すこともでき、その場合は __length_hint__ メソッドが存在しない場合と同じように扱われます。 このメソッドは最適化のためだけのもので、正しく動作するために必要になることはありません。

Added in version 3.4.

object.__getitem__(self, subscript)

添字指定、つまり self[subscript] を実装するために呼び出されます。 構文の詳細は 添字表記とスライス表記 を参照してください。

__getitem__() による添字指定をサポートする組み込みオブジェクトには、次の 2 種類があります。

subscript の型が適切でない場合、__getitem__() は TypeError を送出する必要があります。 subscript の値が適切でない場合、__getitem__() は LookupError かそのサブクラス (シーケンスでは IndexError、マッピングでは KeyError) を送出する必要があります。

注釈

スライスは __getitem__()、__setitem__()、__delitem__() で処理されます。 次のような呼び出しは、

a[1:2] = b

次のように翻訳され

a[slice(1, 2, None)] = b

といった形に変換されます。 スライスで省略された項目には常に None が補われます。

注釈

シーケンスの反復プロトコル (例えば for ループで使用されます) は、シーケンスの末尾を正しく検出するため、不正なインデックスに対して IndexError が送出されることを前提としています。

注釈

クラス に 添字を指定 すると、__getitem__() の代わりに特殊クラスメソッド __class_getitem__() が呼び出されることがあります。 詳細は __class_getitem__ と __getitem__ の違い を参照してください。

object.__setitem__(self, key, value)

self[key] に対する代入を実装するために呼び出されます。 __getitem__() と同じ注意事項があてはまります。このメソッドを実装できるのは、あるキーに対する値の変更をサポートしているか、新たなキーを追加できるようなマップの場合と、ある要素を置き換えることができるシーケンスの場合だけです。不正な key に対しては、 __getitem__() メソッドと同様の例外の送出を行わなければなりません。

object.__delitem__(self, key)

self[key] の削除を実装するために呼び出されます。 __getitem__() と同じ注意事項があてはまります。このメソッドを実装できるのは、キーの削除をサポートしているマップの場合と、要素を削除できるシーケンスの場合だけです。不正な key に対しては、 __getitem__() メソッドと同様の例外の送出を行わなければなりません。

object.__missing__(self, key)

self[key] の実装において辞書内にキーが存在しなかった場合に、 dict のサブクラスのために dict.__getitem__() によって呼び出されます。

object.__iter__(self)

このメソッドは、コンテナに対して イテレータ が要求された際に呼び出されます。このメソッドは、コンテナ内の全てのオブジェクトに渡って反復処理できるような、新たなイテレータオブジェクトを返さなければなりません。マッピングでは、コンテナ内のキーに渡って反復処理しなければなりません。

object.__reversed__(self)

reversed() 組み込み関数が逆方向イテレーションを実装するために、(存在すれば)呼び出します。コンテナ内の全要素を逆順にイテレートする、新しいイテレータを返すべきです。

__reversed__() メソッドが定義されていない場合、 reversed() 組込み関数は sequence プロトコル (__len__() と __getitem__()) を使った方法にフォールバックします。 sequence プロトコルをサポートしたオブジェクトは、 reversed() よりも効率のいい実装を提供できる場合にのみ __reversed__() を定義するべきです。

帰属テスト演算子 (in および not in) は通常、コンテナの要素に対する反復処理のように実装されます。しかし、コンテナオブジェクトで以下の特殊メソッドを定義して、より効率的な実装を行ったり、オブジェクトがイテラブルでなくてもよいようにできます。

object.__contains__(self, item)

帰属テスト演算を実装するために呼び出されます。 item が self 内に存在する場合には真を、そうでない場合には偽を返さなければなりません。マップオブジェクトの場合、値やキーと値の組ではなく、キーに対する帰属テストを考えなければなりません。

__contains__() を定義しないオブジェクトに対しては、メンバシップテストはまず、 __iter__() を使った反復を試みます、次に古いシーケンス反復プロトコル __getitem__() を使います、 言語レファレンスのこの節 を参照して下さい。

3.3.8. 数値型をエミュレートする

以下のメソッドを定義して、数値型オブジェクトをエミュレートすることができます。特定の種類の数値型ではサポートされていないような演算に対応するメソッド (非整数の数値に対するビット単位演算など) は、未定義のままにしておかなければなりません。

object.__add__(self, other)
object.__sub__(self, other)
object.__mul__(self, other)
object.__matmul__(self, other)
object.__truediv__(self, other)
object.__floordiv__(self, other)
object.__mod__(self, other)
object.__divmod__(self, other)
object.__pow__(self, other[, modulo])
object.__lshift__(self, other)
object.__rshift__(self, other)
object.__and__(self, other)
object.__xor__(self, other)
object.__or__(self, other)

これらのメソッドは二項算術演算 (+、-、*、@、/、//、%、divmod()、pow()、**、<<、>>、&、^、|) を実装するために呼び出されます。 例えば x が __add__() メソッドを持つクラスのインスタンスの場合、式 x + y を評価するために type(x).__add__(x, y) が呼び出されます。 __divmod__() メソッドは __floordiv__() と __mod__() を使うのと同等の動作をするべきで、__truediv__() とは関係づけるべきではありません。 組み込みの pow() 関数の 3 引数形式をサポートするには、__pow__() が省略可能な第 3 引数を受け取るように定義する必要があります。

これらのメソッドが、渡された引数に対する演算をサポートしていない場合は、NotImplemented を返す必要があります。

object.__radd__(self, other)
object.__rsub__(self, other)
object.__rmul__(self, other)
object.__rmatmul__(self, other)
object.__rtruediv__(self, other)
object.__rfloordiv__(self, other)
object.__rmod__(self, other)
object.__rdivmod__(self, other)
object.__rpow__(self, other[, modulo])
object.__rlshift__(self, other)
object.__rrshift__(self, other)
object.__rand__(self, other)
object.__rxor__(self, other)
object.__ror__(self, other)

これらのメソッドは、被演算子を反射 (交換) した二項算術演算 (+、-、*、@、/、//、%、divmod()、pow()、**、<<、>>、&、^、|) を実装するために呼び出されます。 呼び出されるのは被演算子の型が異なり、左側の被演算子が対応する演算をサポートしていない場合 [3]、または右側の被演算子のクラスが左側の被演算子のクラスから派生している場合だけです。[4] 例えば y が __rsub__() メソッドを持つクラスのインスタンスの場合、式 x - y の評価では、type(x).__sub__(x, y) が NotImplemented を返すか、type(y) が type(x) のサブクラスであれば、type(y).__rsub__(y, x) が呼び出されます。[5]

組み込みの pow() 関数の 3 引数形式をサポートするには、__rpow__() が省略可能な第 3 引数を受け取るように定義する必要があります。

バージョン 3.14 で変更: 3 引数形式の pow() でも、必要に応じて __rpow__() の呼び出しを試みるようになりました。 以前は 2 引数形式の pow() と二項の累乗演算子でのみ呼び出されていました。

注釈

右側の被演算子の型が左側の被演算子の型のサブクラスで、そのサブクラスが演算の反射メソッドを異なる実装で定義している場合は、左側の被演算子の非反射メソッドより先に、その反射メソッドが呼び出されます。 この動作によってサブクラスは親クラスの演算をオーバーライドできます。

object.__iadd__(self, other)
object.__isub__(self, other)
object.__imul__(self, other)
object.__imatmul__(self, other)
object.__itruediv__(self, other)
object.__ifloordiv__(self, other)
object.__imod__(self, other)
object.__ipow__(self, other[, modulo])
object.__ilshift__(self, other)
object.__irshift__(self, other)
object.__iand__(self, other)
object.__ixor__(self, other)
object.__ior__(self, other)

これらのメソッドは累算算術代入 (+=、-=、*=、@=、/=、//=、%=、**=、<<=、>>=、&=、^=、|=) を実装するために呼び出されます。 これらのメソッドはインプレースで演算 (self の変更) を試み、その結果を返す必要があります (結果は self でも構いませんが、そうでなくても構いません)。 対応するメソッドが定義されていないか、そのメソッドが NotImplemented を返す場合、累算代入は通常のメソッドにフォールバックします。 例えば x が __iadd__() メソッドを持つクラスのインスタンスなら、x += y は x = x.__iadd__(y) と同等です。 __iadd__() が存在しないか、x.__iadd__(y) が NotImplemented を返す場合は、x + y の評価と同様に x.__add__(y) と y.__radd__(x) の使用が検討されます。 状況によっては累算代入で予想外のエラーが起こることもありますが (なぜ加算はされるのに a_tuple[i] += ['item'] は例外を送出するのですか? を参照)、この動作もデータモデルの一部です。

object.__neg__(self)
object.__pos__(self)
object.__abs__(self)
object.__invert__(self)

呼び出して単項算術演算 (-, +, abs() および ~) を実装します。

object.__complex__(self)
object.__int__(self)
object.__float__(self)

組み込み関数の complex(), int(), float() の実装から呼び出されます。 適切な型の値を返さなければなりません。

object.__index__(self)

呼び出して operator.index() を実装します。 Python が数値オブジェクトを整数オブジェクトに損失なく変換する必要がある場合 (たとえばスライシングや、組み込みの bin() 、 hex() 、 oct() 関数) は常に呼び出されます。 このメソッドがあるとその数値オブジェクトが整数型であることが示唆されます。 整数を返さなければなりません。

もし __int__(), __float__(), __complex__() が定義されていない場合、組み込み関数の int(), float(), complex() は __index__() にフォールバックします。

object.__round__(self[, ndigits])
object.__trunc__(self)
object.__floor__(self)
object.__ceil__(self)

組み込み関数の round() と math モジュール関数の trunc(), floor(), ceil() の実装から呼び出されます。 ndigits が __round__() に渡されない限りは、これらの全てのメソッドは Integral (たいていは int) に切り詰められたオブジェクトの値を返すべきです。

バージョン 3.14 で変更: int() は __trunc__() メソッドに処理を委譲しなくなりました。

3.3.9. with文とコンテキストマネージャ

コンテキストマネージャ(context manager) とは、 with 文の実行時にランタイムコンテキストを定義するオブジェクトです。コンテキストマネージャは、コードブロックを実行するために必要な入り口および出口の処理を扱います。コンテキストマネージャは通常、 with 文（ with 文 の章を参照）により起動されますが、これらのメソッドを直接呼び出すことで起動することもできます。

コンテキストマネージャの代表的な用途には、さまざまなグローバル状態の保存と復元、リソースのロックとアンロック、開いているファイルのクローズなどがあります。

コンテキストマネージャの詳細は コンテキストマネージャ型 を参照してください。 object クラス自体はコンテキストマネージャのメソッドを提供しません。

object.__enter__(self)

このオブジェクトに関連する実行時コンテキストに入ります。 with 文に as 節がある場合、その節で指定された代入先にこのメソッドの戻り値が束縛されます。

object.__exit__(self, exc_type, exc_value, traceback)

コンテキストマネージャの出口で実行される処理です。パラメータは、コンテキストが終了した原因となった例外について説明しています。コンテキストが例外を送出せず終了した場合は、全ての引き数に None が設定されます。

例外が渡された場合に、その例外を抑制する (伝播を防ぐ) には、真となる値を返します。 そうしなければ、このメソッドから抜ける際に例外が通常どおり処理されます。

__exit__() メソッドでは、渡された例外を再送出してはいけません。 再送出は呼び出し側が行います。

参考

PEP 343 - "with" ステートメント

Python の with 文の仕様、背景、および例が記載されています。

3.3.10. クラスパターンマッチの位置引数のカスタマイズ

パターンの中でクラス名を利用する場合、位置引数はデフォルトでは利用できません。 MyClass で特別なサポートがないと、 case MyClass(x, y) は通常無効です。このようなパターンを利用するには、 __match_args__ 属性をクラスに定義する必要があります。

object.__match_args__

このクラス変数には文字列のタプルを代入できます。 このクラスを位置引数付きのクラスパターンで使うと、各位置引数は、対応する __match_args__ の値をキーワードとするキーワード引数に変換されます。 この属性がない場合は () を設定した場合と同じです。

例えば、もし MyClass.__match_args__ に ("left", "center", "right") が定義されていた場合、 case MyClass(x, y) は case MyClass(left=x, center=y) と同義です。パターンの引数の数は、 __match_args__ の要素数と同等かそれ以下でなければならない点に注意してください。もし、多かった場合には、パターンマッチは TypeError を送出します。

Added in version 3.10.

参考

PEP 634 - 構造的パターンマッチ

match 文の詳細。

3.3.11. バッファ型をエミュレートする

バッファプロトコル は、Python オブジェクトが低レベルのメモリ配列への効率的なアクセスを提供するための仕組みです。 bytes や memoryview などの組み込み型がこのプロトコルを実装しており、サードパーティのライブラリでも独自のバッファ型を定義できます。

バッファ型は通常 C で実装されますが、Python でもこのプロトコルを実装できます。

object.__buffer__(self, flags)

self に対してバッファが要求されたとき (例えば memoryview コンストラクタから) に呼び出されます。 flags 引数は要求するバッファの種類を表す整数で、例えば返されるバッファを読み取り専用にするか、書き込み可能にするかを指定します。 フラグを解釈するには inspect.BufferFlags が便利です。 このメソッドは memoryview オブジェクトを返さなければなりません。

スレッド安全性: フリースレッド Python では、内部のエクスポート数カウンタはアトミックな操作で管理する必要があります。 このメソッドは複数のスレッドから同時に呼び出されても安全でなければならず、返されたバッファの基になるデータは、対応する __release_buffer__() の呼び出しが完了するまで有効でなければなりません。 詳細は memoryview オブジェクトのスレッドセーフ性 を参照してください。

object.__release_buffer__(self, buffer)

バッファが不要になったときに呼び出されます。 buffer 引数は、以前 __buffer__() が返した memoryview オブジェクトです。 このメソッドはバッファに関連するすべてのリソースを解放しなければなりません。 戻り値は None にする必要があります。

スレッド安全性: フリースレッド Python では、エクスポート数カウンタの減算にアトミックな操作を使う必要があります。 最後の解放処理が、他のスレッドで同時に行われる解放処理と競合する可能性があるため、リソースの後片付けはスレッドセーフでなければなりません。

後片付けが不要なバッファオブジェクトでは、このメソッドを実装する必要はありません。

Added in version 3.12.

参考

PEP 688 - バッファプロトコルを Python から利用可能にする

Python の __buffer__ メソッドと __release_buffer__ メソッドを導入しています。

collections.abc.Buffer

バッファ型の抽象基底クラス。

3.3.12. アノテーション

関数、クラス、モジュールは アノテーション を持つことができます。 アノテーションは、シンボルに情報 (通常は 型ヒント) を関連付ける仕組みです。

object.__annotations__

この属性はオブジェクトのアノテーションを保持します。 遅延評価 されるので、属性にアクセスすると任意のコードが実行され、例外が送出される可能性があります。 評価が成功すると、変数名をアノテーションに対応付ける辞書がこの属性に設定されます。

バージョン 3.14 で変更: アノテーションが遅延評価されるようになりました。

object.__annotate__(format)

アノテーション関数。 属性名や引数名をアノテーションの値に対応付ける新しい辞書オブジェクトを返します。

アノテーションの値を提供する形式を指定する format 引数を受け取ります。 この引数は annotationlib.Format 列挙型のメンバーか、そのメンバーに対応する値の整数でなければなりません。

アノテーション関数が要求された形式をサポートしていない場合は、NotImplementedError を送出しなければなりません。 アノテーション関数は常に VALUE 形式をサポートし、この形式で呼び出されたときに NotImplementedError() を送出してはいけません。

VALUE 形式で呼び出されたアノテーション関数は NameError を送出することがありますが、それ以外の形式を要求されたときには NameError を送出してはいけません。

オブジェクトにアノテーションがない場合、__annotate__ には空の辞書を返す関数よりも None を設定することが推奨されます (この属性は削除できません)。

Added in version 3.14.

参考

PEP 649 --- デスクリプタを使ったアノテーションの遅延評価

アノテーションの遅延評価と __annotate__ 関数を導入しています。

3.3.13. 特殊メソッド検索

カスタムクラスでは、特殊メソッドの暗黙の呼び出しは、オブジェクトのインスタンス辞書ではなく、オブジェクトの型で定義されているときにのみ正しく動作することが保証されます。この動作のため、以下のコードは例外を送出します:

>>> class C:
...     pass
...
>>> c = C()
>>> c.__len__ = lambda: 5
>>> len(c)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: object of type 'C' has no len()

この動作の背景となる理由は、 __hash__() と __repr__() といった type オブジェクトを含むすべてのオブジェクトで定義されている特殊メソッドにあります。これらのメソッドの暗黙の検索が通常の検索プロセスを使った場合、 type オブジェクト自体に対して実行されたときに失敗してしまいます:

>>> 1 .__hash__() == hash(1)
True
>>> int.__hash__() == hash(int)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: descriptor '__hash__' of 'int' object needs an argument

クラスの非結合メソッドをこのようにして実行しようとすることは、'metaclass confusion' と呼ばれることもあり、特殊メソッドを検索するときはインスタンスをバイパスすることで回避されます:

>>> type(1).__hash__(1) == hash(1)
True
>>> type(int).__hash__(int) == hash(int)
True

正確性のためにインスタンス属性をスキップするのに加えて、特殊メソッド検索はオブジェクトのメタクラスを含めて、 __getattribute__() メソッドもバイパスします:

>>> class Meta(type):
...     def __getattribute__(*args):
...         print("Metaclass getattribute invoked")
...         return type.__getattribute__(*args)
...
>>> class C(object, metaclass=Meta):
...     def __len__(self):
...         return 10
...     def __getattribute__(*args):
...         print("Class getattribute invoked")
...         return object.__getattribute__(*args)
...
>>> c = C()
>>> c.__len__()                 # インスタンスを介した明示的な検索
Class getattribute invoked
10
>>> type(c).__len__(c)          # 型を介した明示的な検索
Metaclass getattribute invoked
10
>>> len(c)                      # 暗黙の検索
10

このように __getattribute__() 機構をバイパスすることで、特殊メソッドの扱いに関するある程度の自由度と引き換えに (特殊メソッドはインタプリタから一貫して実行されるためにクラスオブジェクトに設定 しなければならない)、インタープリタを高速化するための大きな余地が手に入ります。

3.4. コルーチン

3.4.1. 待機可能オブジェクト (Awaitable Object)

awaitable オブジェクトは一般的には __await__() メソッドが実装されています。 async def 関数が返す Coroutineオブジェクト は待機可能です。

注釈

types.coroutine() デコレータでデコレータが付けられたジェネレータから返される generator iterator オブジェクトも待機可能ですが、 __await__() は実装されていません。

object.__await__(self)

イテレータ を返さなければなりません。 待機可能 オブジェクトを実装するために使います。 例えば asyncio.Future は、await 式に対応するためにこのメソッドを実装しています。 object クラス自体は待機可能ではなく、このメソッドを提供しません。

注釈

__await__ が返すイテレータが yield するオブジェクトの型や値について、言語としての制約はありません。 これらは 待機可能 オブジェクトを管理する非同期実行フレームワーク (例えば asyncio) の実装に依存するためです。

Added in version 3.5.

参考

待機可能オブジェクトについてより詳しくは PEP 492 を参照してください。

3.4.2. コルーチンオブジェクト

Coroutineオブジェクト は awaitable オブジェクトです。__await__() を呼び出し、その返り値に対し反復処理をすることでコルーチンの実行を制御できます。コルーチンの実行が完了し制御を戻したとき、イテレータは StopIteration を送出し、その例外の value 属性に返り値を持たせます。コルーチンが例外を送出した場合は、イテレータにより伝搬されます。コルーチンから StopIteration 例外を外に送出すべきではありません。

コルーチンには以下に挙げるメソッドもあり、これらはジェネレータのメソッドからの類似です (ジェネレータイテレータ を参照してください)。 ただし、ジェネレータと違って、コルーチンは反復処理を直接はサポートしていません。

コルーチンは、yield する値、send で送る値、戻り値のそれぞれの型をパラメータとする ジェネリック です。

バージョン 3.5.2 で変更: コルーチンで2回以上待機 (await) すると RuntimeError となります。

coroutine.send(value)

コルーチンの実行を開始または再開します。 value が None の場合は、__await__() が返すイテレータを進めるのと同じです。 value が None でない場合は、コルーチンを一時停止させたイテレータの send() メソッドに処理を委譲します。 結果 (戻り値、StopIteration、またはその他の例外) は、上で説明した __await__() の戻り値に対して反復処理をした場合と同じです。

coroutine.throw(value)
coroutine.throw(type[, value[, traceback]])

コルーチン内で指定された例外を送出します。 コルーチンを一時停止させたイテレータに throw() メソッドがある場合は、そのメソッドに処理を委譲します。 そうでなければ、一時停止した地点で例外を送出します。 結果 (戻り値、StopIteration、またはその他の例外) は、上で説明した __await__() の戻り値に対して反復処理をした場合と同じです。 例外がコルーチン内で捕捉されなければ、呼び出し元に伝播します。

バージョン 3.12 で変更: 2番目のシグネチャ (type[, value[, traceback]]) は非推奨となり、将来のバージョンの Python で削除される可能性があります。

coroutine.close()

コルーチンが自分自身の後片付けをし終了します。 コルーチンが一時停止している場合は、コルーチンを一時停止させたイテレータに close() メソッドがあれば、まずはそれに処理を委任します。 そして一時停止した地点から GeneratorExit が送出され、ただちにコルーチンが自分自身の後片付けを行います。 最後に、実行が開始されていなかった場合でも、コルーチンに実行が完了した印を付けます。

コルーチンオブジェクトが破棄されるときには、上記の手順を経て自動的に閉じられます。

3.4.3. 非同期イテレータ (Asynchronous Iterator)

非同期イテレータ の __anext__ メソッドからは非同期のコードが呼べます。

非同期イテレータは async for 文の中で使えます。

object クラス自体はこれらのメソッドを提供しません。

object.__aiter__(self)

非同期イテレータ オブジェクトを返さなくてはなりません。

object.__anext__(self)

イテレータの次の値を返す 待機可能オブジェクト を返さなければなりません。 反復処理が終了したときには StopAsyncIteration エラーを送出すべきです。

非同期イテラブルオブジェクトの例:

class Reader:
    async def readline(self):
        ...

    def __aiter__(self):
        return self

    async def __anext__(self):
        val = await self.readline()
        if val == b'':
            raise StopAsyncIteration
        return val

Added in version 3.5.

バージョン 3.7 で変更: Python 3.7 より前では、 __aiter__() は 非同期イテレータ になる awaitable を返せました。

Python 3.7 からは、 __aiter__() は非同期イテレータオブジェクトを返さなければなりません。 それ以外のものを返すと TypeError になります。

3.4.4. 非同期コンテキストマネージャ (Asynchronous Context Manager)

非同期コンテキストマネージャ は、 __aenter__ メソッドと __aexit__ メソッド内部で実行を一時停止できる コンテキストマネージャ です。

非同期コンテキストマネージャは async with 文の中で使えます。

object クラス自体はこれらのメソッドを提供しません。

object.__aenter__(self)

意味は __enter__() と同じですが、待機可能オブジェクト を返さなければならない点だけが異なります。

object.__aexit__(self, exc_type, exc_value, traceback)

意味は __exit__() と同じですが、待機可能オブジェクト を返さなければならない点だけが異なります。

非同期コンテキストマネージャクラスの例:

class AsyncContextManager:
    async def __aenter__(self):
        await log('entering context')

    async def __aexit__(self, exc_type, exc, tb):
        await log('exiting context')

Added in version 3.5.

脚注