3. データモデル¶
3.1. オブジェクト、値、および型¶
Python における オブジェクト (object) とは、データを抽象的に表したものです。Python プログラムにおけるデータは全て、オブジェクトまたはオブジェクト間の関係として表されます。(ある意味では、プログラムコードもまたオブジェクトとして表されます。これはフォン・ノイマン: Von Neumann の "プログラム記憶方式コンピュータ: stored program computer" のモデルに適合します。)
すべてのオブジェクトは、同一性 (identity)、型、値をもっています。 同一性 は生成されたあとは変更されません。これはオブジェクトのアドレスのようなものだと考えられるかもしれません。 is
演算子は2つのオブジェクトの同一性を比較します。 id()
関数は同一性を表す整数を返します。
CPython 実装の詳細: CPython では、id(x)
は x
が格納されているメモリ上のアドレスを返します。
オブジェクトの型はオブジェクトがサポートする操作 (例: len()
をサポートするか) と、オブジェクトが取りうる値を決定します。 type()
関数はオブジェクトの型 (型自体もオブジェクトです) を返します。同一性と同じく、オブジェクトの型(type) も変更不可能です。 [1]
オブジェクトによっては 値 を変更することが可能です。値を変更できるオブジェクトのことを mutable と呼びます。生成後に値を変更できないオブジェクトのことを immutable と呼びます。(mutable なオブジェクトへの参照を格納している immutableなコンテナオブジェクトの値は、その格納しているオブジェクトの値が変化した時に変化しますが、コンテナがどのオブジェクトを格納しているのかが変化しないのであれば immutable だと考えることができます。したがって、immutable かどうかは値が変更可能かどうかと完全に一致するわけではありません) オブジェクトが mutable かどうかはその型によって決まります。例えば、数値型、文字列型とタプル型のインスタンスは immutable で、dict や list は mutable です。
オブジェクトを明示的に破壊することはできません; しかし、オブジェクトに到達不能 (unreachable) になると、ガベージコレクション (garbage-collection) によって処理されるかもしれません。ガベージコレクションを遅らせたり、全く行わない実装も許されています --- 到達可能なオブジェクトを処理してしまわないかぎり、ガベージコレクションをどう実装するかは実装品質の問題です。
CPython 実装の詳細: 現在の CPython 実装では参照カウント (reference-counting) 方式を使っており、(オプションとして) 循環参照を行っているガベージオブジェクトを遅延検出します。この実装ではほとんどのオブジェクトを到達不能になると同時に処理することができますが、循環参照を含むガベージオブジェクトの収集が確実に行われるよう保証しているわけではありません。循環参照を持つガベージオブジェクト収集の制御については、 gc
モジュールを参照してください。 CPython以外の実装は別の方式を使っており、CPythonも将来は別の方式を使うかもしれません。オブジェクトが到達不能になったときに即座に終了処理されることに頼らないでください (ですからファイルは必ず明示的に閉じてください)。
Note that the use of the implementation's tracing or debugging facilities may
keep objects alive that would normally be collectable. Also note that catching
an exception with a try
...except
statement may keep
objects alive.
Some objects contain references to "external" resources such as open files or
windows. It is understood that these resources are freed when the object is
garbage-collected, but since garbage collection is not guaranteed to happen,
such objects also provide an explicit way to release the external resource,
usually a close()
method. Programs are strongly recommended to explicitly
close such objects. The try
...finally
statement
and the with
statement provide convenient ways to do this.
他のオブジェクトに対する参照をもつオブジェクトもあります; これらは コンテナ (container) と呼ばれます。コンテナオブジェクトの例として、タプル、リスト、および辞書が挙げられます。オブジェクトへの参照自体がコンテナの値の一部です。ほとんどの場合、コンテナの値というと、コンテナに入っているオブジェクトの値のことを指し、それらオブジェクトのアイデンティティではありません; しかしながら、コンテナの変更可能性について述べる場合、今まさにコンテナに入っているオブジェクトのアイデンティティのことを指します。したがって、 (タプルのように) 変更不能なオブジェクトが変更可能なオブジェクトへの参照を含む場合、その値が変化するのは変更可能なオブジェクトが変更された時、ということになります。
Types affect almost all aspects of object behavior. Even the importance of
object identity is affected in some sense: for immutable types, operations that
compute new values may actually return a reference to any existing object with
the same type and value, while for mutable objects this is not allowed. E.g.,
after a = 1; b = 1
, a
and b
may or may not refer to the same object
with the value one, depending on the implementation, but after c = []; d =
[]
, c
and d
are guaranteed to refer to two different, unique, newly
created empty lists. (Note that c = d = []
assigns the same object to both
c
and d
.)
3.2. 標準型の階層¶
以下は Python に組み込まれている型のリストです。(実装によって、C、Java、またはその他の言語で書かれた) 拡張モジュールで、その他の型が定義されていることがあります。新たな型 (有理数や、整数を効率的に記憶する配列、など) の追加は、たいてい標準ライブラリを通して提供されますが、将来のバージョンの Python では、型の階層構造にこのような追加がなされるかもしれません。
以下に説明する型のいくつかには、 '特殊属性 (special attribute)' を列挙した段落があります。これらの属性は実装へのアクセス手段を提供するもので、一般的な用途に利用するためのものではありません。特殊属性の定義は将来変更される可能性があります。
3.2.1. None¶
この型には単一の値しかありません。この値を持つオブジェクトはただ一つしか存在しません。このオブジェクトは組み込み名 None
でアクセスされます。このオブジェクトは、様々な状況で値が存在しないことをしめします。例えば、明示的に値を返さない関数は None
を返します。 None
の真値 (truth value) は偽 (false) です。
3.2.2. NotImplemented¶
This type has a single value. There is a single object with this value. This
object is accessed through the built-in name NotImplemented
. Numeric methods
and rich comparison methods should return this value if they do not implement the
operation for the operands provided. (The interpreter will then try the
reflected operation, or some other fallback, depending on the operator.) It
should not be evaluated in a boolean context.
詳細は 算術演算の実装 を参照してください。
バージョン 3.9 で変更: Evaluating NotImplemented
in a boolean context is deprecated. While
it currently evaluates as true, it will emit a DeprecationWarning
.
It will raise a TypeError
in a future version of Python.
3.2.3. Ellipsis¶
この型には単一の値しかありません。この値を持つオブジェクトはただ一つしか存在しません。このオブジェクトはリテラル ...
またはPythonで決められている名前 Ellipsis
でアクセスされます。真理値は真 (true)です。
3.2.4. numbers.Number
¶
数値リテラルによって作成されたり、算術演算や組み込みの算術関数によって返されるオブジェクトです。数値オブジェクトは変更不能です; 一度値が生成されると、二度と変更されることはありません。Python の数値オブジェクトはいうまでもなく数学で言うところの数値と強く関係していますが、コンピュータ内で数値を表現する際に伴う制限を受けています。
__repr__()
と __str__()
から計算された数値クラスの文字列表現には次のような特性があります:
その文字列は、クラスコンストラクタに渡したときに、元の数値の値を持つオブジェクトを生成する有効な数値リテラルです。
できるなら、10を底として表現されます。
小数点の前にある 1 つのゼロを除いて、上に連なるゼロは表示されません。
小数点の後にある 1 つのゼロを除いて、下に連なるゼロは表示されません。
符号は数値が負数のときのみ表示されます。
Python distinguishes between integers, floating point numbers, and complex numbers:
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
) (実数)¶
These represent machine-level double precision floating point numbers. You are at the mercy of the underlying machine architecture (and C or Java implementation) for the accepted range and handling of overflow. Python does not support single-precision floating point numbers; the savings in processor and memory usage that are usually the reason for using these are dwarfed by the overhead of using objects in Python, so there is no reason to complicate the language with two kinds of floating point numbers.
3.2.4.3. numbers.Complex
(complex
)¶
These represent complex numbers as a pair of machine-level double precision
floating point numbers. The same caveats apply as for floating point numbers.
The real and imaginary parts of a complex number z
can be retrieved through
the read-only attributes z.real
and z.imag
.
3.2.5. シーケンス型 (sequence)¶
These represent finite ordered sets indexed by non-negative numbers. The
built-in function len()
returns the number of items of a sequence. When
the length of a sequence is n, the index set contains the numbers 0, 1,
..., n-1. Item i of sequence a is selected by a[i]
. Some sequences,
including built-in sequences, interpret negative subscripts by adding the
sequence length. For example, a[-2]
equals a[n-2]
, the second to last
item of sequence a with length n
.
Sequences also support slicing: a[i:j]
selects all items with index k such
that i <=
k <
j. When used as an expression, a slice is a
sequence of the same type. The comment above about negative indexes also applies
to negative slice positions.
シーケンスによっては、第三の "ステップ (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)
文字列はUnicodeコードポイントを表現する値の配列です。文字列中のどのコードポイントも
U+0000 - U+10FFFF
の範囲で表現されることができます。Pythonは char 型を持ちません。代わりに、文字列中のどのコードポイントも長さ ''1'' の文字列オブジェクトとして表現することができます。組み込み関数ord()
は文字列形式をU+0000 - U+10FFFF
の範囲の整数に変換します。また、組み込み関数chr()
は0 - 10FFFF
の範囲の整数を対応する長さ1
の文字列に変換します。str.encode()
はテキストエンコーディングを使うことでstr
をbytes
に変換するために使うことができます。また、bytes.decode()
によりその逆が実行することができます。- タプル型 (tuple)
タプルの要素は任意の Python オブジェクトです。二つ以上の要素からなるタプルは、個々の要素を表現する式をカンマで区切って構成します。単一の要素からなるタプル (単集合 'singleton') を作るには、要素を表現する式の直後にカンマをつけます (単一の式だけではタプルを形成しません。これは、式をグループ化するのに丸括弧を使えるようにしなければならないからです)。要素の全くない丸括弧の対を作ると空のタプルになります。
- bytes
A bytes object is an immutable array. The items are 8-bit bytes, represented by integers in the range 0 <= x < 256. Bytes literals (like
b'abc'
) and the built-inbytes()
constructor can be used to create bytes objects. Also, bytes objects can be decoded to strings via thedecode()
method.
3.2.5.2. 変更可能なシーケンス型 (mutable sequence)¶
変更可能なシーケンスは、作成した後で変更することができます。変更可能なシーケンスでは、添字表記やスライス表記を使って指定された要素に代入を行うことができ、 del
(delete) 文を使って要素を削除することができます。
注釈
The collections
and array
module provide
additional examples of mutable sequence types.
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()
は、マッピング内の要素数を返します。
Python に最初から組み込まれているマッピング型は、今のところ一つだけです:
3.2.7.1. 辞書型 (dictionary)¶
ほぼ任意の値でインデクスされたオブジェクトからなる有限の集合を表します。
キー (key) として使えない値の唯一の型は、リストや辞書、そしてオブジェクトの同一性でなく値で比較されるその他の変更可能な型です。
これは、辞書型を効率的に実装する上で、キーのハッシュ値が不変である必要があるためです。
数値型をキーに使う場合、キー値は通常の数値比較における規則に従います: 二つの値が等しくなる場合 (例えば 1
と 1.0
)、互いに同じ辞書のエントリを表すインデクスとして使うことができます。
辞書は挿入の順序を保持します。つまり、キーは辞書に追加された順番に生成されていきます。既存のキーを置き換えても、キーの順序は変わりません。キーを削除したのちに再挿入すると、元の場所ではなく辞書の最後に追加されます。
Dictionaries are mutable; they can be created by the {...}
notation (see
section 辞書表示).
拡張モジュール dbm.ndbm
、 dbm.gnu
は、 collections
モジュールのように、別のマッピング型の例を提供しています。
バージョン 3.7 で変更: Pythonのバージョン3.6では、辞書は挿入順序を保持しませんでした。CPython 3.6では挿入順序は保持されましたが、それは策定された言語の仕様というより、その当時の実装の細部とみなされていました。
3.2.8. 呼び出し可能型 (callable type)¶
関数呼び出し操作 (呼び出し (call) 参照) を行うことができる型です:
3.2.8.1. ユーザ定義関数 (user-defined function)¶
ユーザ定義関数オブジェクトは、関数定義を行うことで生成されます (関数定義 参照)。関数は、仮引数 (formal parameter) リストと同じ数の要素が入った引数リストとともに呼び出されます。
3.2.8.1.1. Special read-only attributes¶
属性 |
意味 |
---|---|
|
A reference to the |
|
セルオブジェクトは属性 |
3.2.8.1.2. Special writable attributes¶
Most of these attributes check the type of the assigned value:
属性 |
意味 |
---|---|
|
The function's documentation string, or |
|
The function's name.
See also: |
|
The function's qualified name.
See also: バージョン 3.3 で追加. |
|
関数が定義されているモジュールの名前です。モジュール名がない場合は |
|
A |
|
The code object representing the compiled function body. |
|
The namespace supporting arbitrary function attributes.
See also: |
|
A |
|
A |
Function objects also support getting and setting arbitrary attributes, which can be used, for example, to attach metadata to functions. Regular attribute dot-notation is used to get and set such attributes.
CPython 実装の詳細: CPython's current implementation only supports function attributes on user-defined functions. Function attributes on built-in functions may be supported in the future.
Additional information about a function's definition can be retrieved from its
code object
(accessible via the __code__
attribute).
3.2.8.2. インスタンスメソッド¶
インスタンスメソッドオブジェクトは、クラス、クラスインスタンスと任意の呼び出し可能オブジェクト (通常はユーザ定義関数) を結びつけます。
Special read-only attributes:
|
Refers to the class instance object to which the method is bound |
|
Refers to the original function object |
|
The method's documentation
(same as |
|
The name of the method
(same as |
|
The name of the module the method was defined in, or |
Methods also support accessing (but not setting) the arbitrary function attributes on the underlying function object.
User-defined method objects may be created when getting an attribute of a
class (perhaps via an instance of that class), if that attribute is a
user-defined function object or a
classmethod
object.
When an instance method object is created by retrieving a user-defined
function object from a class via one of its
instances, its __self__
attribute is the instance, and the
method object is said to be bound. The new method's __func__
attribute is the original function object.
When an instance method object is created by retrieving a classmethod
object from a class or instance, its __self__
attribute is the
class itself, and its __func__
attribute is the function object
underlying the class method.
When an instance method object is called, the underlying function
(__func__
) is called, inserting the class instance
(__self__
) in front of the argument list. For instance, when
C
is a class which contains a definition for a function
f()
, and x
is an instance of C
, calling x.f(1)
is
equivalent to calling C.f(x, 1)
.
When an instance method object is derived from a classmethod
object, the
"class instance" stored in __self__
will actually be the class
itself, so that calling either x.f(1)
or C.f(1)
is equivalent to
calling f(C,1)
where f
is the underlying function.
Note that the transformation from function object to instance method object happens each time the attribute is retrieved from the instance. In some cases, a fruitful optimization is to assign the attribute to a local variable and call that local variable. Also notice that this transformation only happens for user-defined functions; other callable objects (and all non-callable objects) are retrieved without transformation. It is also important to note that user-defined functions which are attributes of a class instance are not converted to bound methods; this only happens when the function is an attribute of the class.
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
文を使用している関数やメソッドを asynchronous generator function と呼びます。
そのような関数は、呼び出されたとき、非同期イテレータ オブジェクトを返します。
このオブジェクトは async for
文で関数の本体を実行するのに使えます。
非同期イテレータの aiterator.__anext__
メソッドを呼び出すと、他の処理が待たされているときに、 yield
式を使い値を提供するところまで処理を進める awaitable を返します。
その関数が空の return
文を実行する、もしくは処理の終わりに到達したときは、 StopAsyncIteration
例外が送出され、非同期イテレータは出力すべき値の最後に到達したことになります。
3.2.8.6. 組み込み関数 (built-in function)¶
A built-in function object is a wrapper around a C function. Examples of
built-in functions are len()
and math.sin()
(math
is a
standard built-in module). The number and type of the arguments are
determined by the C function. Special read-only attributes:
__doc__
is the function's documentation string, orNone
if unavailable. Seefunction.__doc__
.__name__
is the function's name. Seefunction.__name__
.__self__
is set toNone
(but see the next item).__module__
is the name of the module the function was defined in orNone
if unavailable. Seefunction.__module__
.
3.2.8.7. 組み込みメソッド (built-in method)¶
This is really a different disguise of a built-in function, this time containing
an object passed to the C function as an implicit extra argument. An example of
a built-in method is alist.append()
, assuming alist is a list object. In
this case, the special read-only attribute __self__
is set to the object
denoted by alist. (The attribute has the same semantics as it does with
other instance methods
.)
3.2.8.8. クラス¶
Classes are callable. These objects normally act as factories for new
instances of themselves, but variations are possible for class types that
override __new__()
. The arguments of the call are passed to
__new__()
and, in the typical case, to __init__()
to
initialize the new instance.
3.2.8.9. クラスのインスタンス¶
任意のクラスのインスタンスは、クラスで __call__()
メソッドを定義することで呼び出し可能になります。
3.2.9. モジュール¶
Modules are a basic organizational unit of Python code, and are created by
the import system as invoked either by the
import
statement, or by calling
functions such as importlib.import_module()
and built-in
__import__()
. A module object has a namespace implemented by a
dictionary
object (this is the dictionary referenced by the
__globals__
attribute of functions defined in the module). Attribute references are
translated to lookups in this dictionary, e.g., m.x
is equivalent to
m.__dict__["x"]
. A module object does not contain the code object used
to initialize the module (since it isn't needed once the initialization is
done).
属性の代入を行うと、モジュールの名前空間辞書の内容を更新します。例えば、 m.x = 1
は m.__dict__["x"] = 1
と同じです。
Predefined (writable) attributes:
__name__
The module's name.
__doc__
The module's documentation string, or
None
if unavailable.__file__
The pathname of the file from which the module was loaded, if it was loaded from a file. The
__file__
attribute may be missing for certain types of modules, such as C modules that are statically linked into the interpreter. For extension modules loaded dynamically from a shared library, it's the pathname of the shared library file.__annotations__
モジュールの本体の実行中に収集した 変数アノテーション を格納する辞書です。
__annotations__
を利用するベストプラクティスについては、 アノテーションのHOWTO を参照してください。
Special read-only attribute: __dict__
is the module's
namespace as a dictionary object.
CPython 実装の詳細: CPython がモジュール辞書を削除する方法により、モジュール辞書が生きた参照を持っていたとしてもその辞書はモジュールがスコープから外れた時に削除されます。これを避けるには、辞書をコピーするか、辞書を直接使っている間モジュールを保持してください。
3.2.10. カスタムクラス型¶
Custom class types are typically created by class definitions (see section
クラス定義). A class has a namespace implemented by a dictionary object.
Class attribute references are translated to lookups in this dictionary, e.g.,
C.x
is translated to C.__dict__["x"]
(although there are a number of
hooks which allow for other means of locating attributes). When the attribute
name is not found there, the attribute search continues in the base classes.
This search of the base classes uses the C3 method resolution order which
behaves correctly even in the presence of 'diamond' inheritance structures
where there are multiple inheritance paths leading back to a common ancestor.
Additional details on the C3 MRO used by Python can be found in the
documentation accompanying the 2.3 release at
https://www.python.org/download/releases/2.3/mro/.
When a class attribute reference (for class C
, say) would yield a
class method object, it is transformed into an instance method object whose
__self__
attribute is C
.
When it would yield a staticmethod
object,
it is transformed into the object wrapped by the static method
object. See section デスクリプタ (descriptor) の実装 for another way in which attributes
retrieved from a class may differ from those actually contained in its
__dict__
.
クラス属性を代入すると、そのクラスの辞書だけが更新され、基底クラスの辞書は更新しません。
クラスオブジェクトを呼び出す (上記を参照) と、クラスインスタンスを生成します (下記を参照)。
Special attributes:
__name__
The class name.
__module__
クラスが定義されているモジュールの名前。
__dict__
The dictionary containing the class's namespace.
__bases__
A tuple containing the base classes, in the order of their occurrence in the base class list.
__doc__
The class's documentation string, or
None
if undefined.__annotations__
A dictionary containing variable annotations collected during class body execution. For best practices on working with
__annotations__
, please see Annotations Best Practices.
3.2.11. クラスインスタンス (class instance)¶
A class instance is created by calling a class object (see above). A class
instance has a namespace implemented as a dictionary which is the first place
in which attribute references are searched. When an attribute is not found
there, and the instance's class has an attribute by that name, the search
continues with the class attributes. If a class attribute is found that is a
user-defined function object, it is transformed into an instance method
object whose __self__
attribute is the instance. Static method and
class method objects are also transformed; see above under "Classes". See
section デスクリプタ (descriptor) の実装 for another way in which attributes of a class
retrieved via its instances may differ from the objects actually stored in
the class's __dict__
. If no class attribute is found, and the
object's class has a __getattr__()
method, that is called to satisfy
the lookup.
属性の代入や削除を行うと、インスタンスの辞書を更新しますが、クラスの辞書を更新することはありません。クラスで __setattr__()
や __delattr__()
メソッドが定義されている場合、直接インスタンスの辞書を更新する代わりにこれらのメソッドが呼び出されます。
クラスインスタンスは、ある特定の名前のメソッドを持っている場合、数値型やシーケンス型、あるいはマップ型のように振舞うことができます。 特殊メソッド名 を参照してください。
Special attributes: __dict__
is the attribute dictionary;
__class__
is the instance's class.
3.2.12. I/O オブジェクト (ファイルオブジェクトの別名)¶
file object は開かれたファイルを表します。ファイルオブジェクトを作るための様々なショートカットがあります: open()
組み込み関数、 os.popen()
、 os.fdopen()
、ソケットオブジェクトの makefile()
メソッド (あるいは拡張モジュールから提供される他の関数やメソッド) 。
オブジェクト sys.stdin
、 sys.stdout
および sys.stderr
は、インタプリタの標準入力、標準出力、および標準エラー出力ストリームに対応するファイルオブジェクトに初期化されます。これらはすべてテキストモードで開かれ、 io.TextIOBase
抽象クラスによって定義されたインターフェースに従います。
3.2.13. 内部型 (internal type)¶
インタプリタが内部的に使っているいくつかの型は、ユーザに公開されています。これらの定義は将来のインタプリタのバージョンでは変更される可能性がありますが、ここでは記述の完全性のために触れておきます。
3.2.13.1. コードオブジェクト¶
コードオブジェクトは バイトコンパイルされた (byte-compiled) 実行可能な Python コード、別名 バイトコード を表現します。コードオブジェクトと関数オブジェクトの違いは、関数オブジェクトが関数のグローバル変数 (関数を定義しているモジュールのグローバル) に対して明示的な参照を持っているのに対し、コードオブジェクトにはコンテキストがないということです; また、関数オブジェクトではデフォルト引数値を記憶できますが、コードオブジェクトではできません (実行時に計算される値を表現するため)。関数オブジェクトと違い、コードオブジェクトは変更不可能で、変更可能なオブジェクトへの参照を (直接、間接に関わらず) 含みません。
3.2.13.1.1. Special read-only attributes¶
|
The function name |
|
The fully qualified function name バージョン 3.11 で追加. |
|
The total number of positional parameters (including positional-only parameters and parameters with default values) that the function has |
|
The number of positional-only parameters (including arguments with default values) that the function has |
|
The number of keyword-only parameters (including arguments with default values) that the function has |
|
The number of local variables used by the function (including parameters) |
|
A |
|
A |
|
A |
|
A string representing the sequence of bytecode instructions in the function |
|
A |
|
A |
|
The name of the file from which the code was compiled |
|
The line number of the first line of the function |
|
A string encoding the mapping from bytecode offsets to line numbers. For details, see the source code of the interpreter. |
|
The required stack size of the code object |
|
An |
The following flag bits are defined for co_flags
:
bit 0x04
is set if
the function uses the *arguments
syntax to accept an arbitrary number of
positional arguments; bit 0x08
is set if the function uses the
**keywords
syntax to accept arbitrary keyword arguments; bit 0x20
is set
if the function is a generator. See Code Objects Bit Flags for details
on the semantics of each flags that might be present.
Future feature declarations (from __future__ import division
) also use bits
in co_flags
to indicate whether a code object was compiled with a
particular feature enabled: bit 0x2000
is set if the function was compiled
with future division enabled; bits 0x10
and 0x1000
were used in earlier
versions of Python.
Other bits in co_flags
are reserved for internal use.
If a code object represents a function, the first item in
co_consts
is
the documentation string of the function, or None
if undefined.
3.2.13.1.2. Methods on code objects¶
- codeobject.co_positions()¶
Returns an iterable over the source code positions of each bytecode instruction in the code object.
The iterator returns
tuple
s containing the(start_line, end_line, start_column, end_column)
. The i-th tuple corresponds to the position of the source code that compiled to the i-th code unit. Column information is 0-indexed utf-8 byte offsets on the given source line.This positional information can be missing. A non-exhaustive lists of cases where this may happen:
Running the interpreter with
-X
no_debug_ranges
.Loading a pyc file compiled while using
-X
no_debug_ranges
.Position tuples corresponding to artificial instructions.
Line and column numbers that can't be represented due to implementation specific limitations.
When this occurs, some or all of the tuple elements can be
None
.バージョン 3.11 で追加.
注釈
This feature requires storing column positions in code objects which may result in a small increase of disk usage of compiled Python files or interpreter memory usage. To avoid storing the extra information and/or deactivate printing the extra traceback information, the
-X
no_debug_ranges
command line flag or thePYTHONNODEBUGRANGES
environment variable can be used.
- codeobject.co_lines()¶
Returns an iterator that yields information about successive ranges of bytecodes. Each item yielded is a
(start, end, lineno)
tuple
:start
(anint
) represents the offset (inclusive) of the start of the bytecode rangeend
(anint
) represents the offset (exclusive) of the end of the bytecode rangelineno
is anint
representing the line number of the bytecode range, orNone
if the bytecodes in the given range have no line number
The items yielded will have the following properties:
The first range yielded will have a
start
of 0.The
(start, end)
ranges will be non-decreasing and consecutive. That is, for any pair oftuple
s, thestart
of the second will be equal to theend
of the first.No range will be backwards:
end >= start
for all triples.The last
tuple
yielded will haveend
equal to the size of the bytecode.
Zero-width ranges, where
start == end
, are allowed. Zero-width ranges are used for lines that are present in the source code, but have been eliminated by the bytecode compiler.バージョン 3.10 で追加.
参考
- PEP 626 - Precise line numbers for debugging and other tools.
The PEP that introduced the
co_lines()
method.
- codeobject.replace(**kwargs)¶
Return a copy of the code object with new values for the specified fields.
バージョン 3.8 で追加.
3.2.13.2. フレーム (frame) オブジェクト¶
Frame objects represent execution frames. They may occur in traceback objects, and are also passed to registered trace functions.
3.2.13.2.1. Special read-only attributes¶
|
Points to the previous stack frame (towards the caller),
or |
|
The code object being executed in this frame.
Accessing this attribute raises an auditing event
|
|
The dictionary used by the frame to look up local variables |
|
The dictionary used by the frame to look up global variables |
|
The dictionary used by the frame to look up built-in (intrinsic) names |
|
The "precise instruction" of the frame object (this is an index into the bytecode string of the code object) |
3.2.13.2.2. Special writable attributes¶
|
If not |
|
Set this attribute to |
|
Set this attribute to |
|
The current line number of the frame -- writing to this from within a trace function jumps to the given line (only for the bottom-most frame). A debugger can implement a Jump command (aka Set Next Statement) by writing to this attribute. |
3.2.13.2.3. Frame object methods¶
フレームオブジェクトはメソッドを一つサポートします:
- frame.clear()¶
This method clears all references to local variables held by the frame. Also, if the frame belonged to a generator, the generator is finalized. This helps break reference cycles involving frame objects (for example when catching an exception and storing its traceback for later use).
RuntimeError
is raised if the frame is currently executing.バージョン 3.4 で追加.
3.2.13.3. トレースバック (traceback) オブジェクト¶
Traceback objects represent the stack trace of an exception.
A traceback object
is implicitly created when an exception occurs, and may also be explicitly
created by calling types.TracebackType
.
バージョン 3.7 で変更: Traceback objects can now be explicitly instantiated from Python code.
For implicitly created tracebacks, when the search for an exception handler
unwinds the execution stack, at each unwound level a traceback object is
inserted in front of the current traceback. When an exception handler is
entered, the stack trace is made available to the program. (See section
try 文.) It is accessible as the third item of the
tuple returned by sys.exc_info()
, and as the
__traceback__
attribute
of the caught exception.
When the program contains no suitable
handler, the stack trace is written (nicely formatted) to the standard error
stream; if the interpreter is interactive, it is also made available to the user
as sys.last_traceback
.
For explicitly created tracebacks, it is up to the creator of the traceback
to determine how the tb_next
attributes should be linked to
form a full stack trace.
Special read-only attributes:
|
Points to the execution frame of the current level. Accessing this attribute raises an
auditing event |
|
Gives the line number where the exception occurred |
|
Indicates the "precise instruction". |
The line number and last instruction in the traceback may differ from the
line number of its frame object if the exception
occurred in a
try
statement with no matching except clause or with a
finally
clause.
- traceback.tb_next¶
The special writable attribute
tb_next
is the next level in the stack trace (towards the frame where the exception occurred), orNone
if there is no next level.バージョン 3.7 で変更: This attribute is now writable
3.2.13.4. スライス (slice) オブジェクト¶
スライスオブジェクトは、 __getitem__()
メソッドのためのスライスを表すのに使われます。スライスオブジェクトは組み込みの slice()
関数でも生成されます。
読み出し専用の特殊属性: 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. クラスメソッドオブジェクト¶
A class method object, like a static method object, is a wrapper around another
object that alters the way in which that object is retrieved from classes and
class instances. The behaviour of class method objects upon such retrieval is
described above, under "instance methods". Class method objects are created
by the built-in classmethod()
constructor.
3.3. 特殊メソッド名¶
クラスは、特殊な名前のメソッドを定義して、特殊な構文 (算術演算や添え字表記、スライス表記など) による特定の演算を実装できます。これは、Python の演算子オーバロード (operator overloading) へのアプローチです。これにより、クラスは言語の演算子に対する独自の振る舞いを定義できます。例えば、あるクラスが __getitem__()
という名前のメソッドを定義しており、 x
がこのクラスのインスタンスであるとすると、 x[i]
は type(x).__getitem__(x, i)
とほぼ等価です。特に注釈のない限り、適切なメソッドが定義されていないとき、このような演算を試みると例外 (たいていは AttributeError
か TypeError
) が送出されます。
特殊メソッドに None
を設定することは、それに対応する演算が利用できないことを意味します。
例えば、クラスの __iter__()
を None
に設定した場合、そのクラスはイテラブルにはならず、そのインスタンスに対し iter()
を呼び出すと (__getitem__()
に処理が戻されずに) TypeError
を送出します。 [2]
組み込み型をエミュレートするクラスを実装するときは、模範とされるオブジェクトにとって意味がある範囲に実装をとどめるのが重要です。例えば、あるシーケンスは個々の要素の取得はきちんと動くかもしれませんが、スライスの展開が意味をなさないかもしれません。 (W3C のドキュメントオブジェクトモデルにある 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 の実装では最初の一回しか呼び出されません。It is not guaranteed that
__del__()
methods are called for objects that still exist when the interpreter exits.注釈
del x
は直接x.__del__()
を呼び出しません --- 前者はx
の参照カウントを 1 つ減らし、後者はx
の参照カウントが 0 まで落ちたときのみ呼び出されます。CPython 実装の詳細: It is possible for a reference cycle to prevent the reference count of an object from going to zero. In this case, the cycle will be later detected and deleted by the cyclic garbage collector. A common cause of reference cycles is when an exception has been caught in a local variable. The frame's locals then reference the exception, which references its own traceback, which references the locals of all frames caught in the traceback.
参考
gc
モジュールのドキュメント。警告
メソッド
__del__()
は不安定な状況で呼び出されるため、実行中に発生した例外は無視され、代わりにsys.stderr
に警告が表示されます。特に:__del__()
は、任意のコードが実行されているときに、任意のスレッドから呼び出せます。__del__()
で、ロックを取ったり、ブロックするリソースを呼び出したりする必要がある場合、__del__()
の実行により中断されたコードにより、そのリソースが既に取得されていて、デッドロックが起きるかもしれません。__del__()
は、インタプリタのシャットダウン中に実行できます。 従って、(他のモジュールも含めた) アクセスする必要があるグローバル変数はすでに削除されているか、None
に設定されているかもしれません。 Python は、単一のアンダースコアで始まる名前のグローバルオブジェクトは、他のグローバル変数が削除される前にモジュールから削除されることを保証します; そのようなグローバル変数への他からの参照が存在しない場合、__del__()
メソッドが呼ばれた時点で、インポートされたモジュールがまだ利用可能であることを保証するのに役立つかもしれません。
- object.__repr__(self)¶
repr()
組み込み関数によって呼び出され、オブジェクトを表す「公式の (official)」文字列を計算します。可能なら、これは (適切な環境が与えられれば) 同じ値のオブジェクトを再生成するのに使える、有効な Python 式のようなものであるべきです。できないなら、<...some useful description...>
形式の文字列が返されるべきです。戻り値は文字列オブジェクトでなければなりません。クラスが__repr__()
を定義していて__str__()
は定義していなければ、そのクラスのインスタンスの「非公式の (informal)」文字列表現が要求されたときにも__repr__()
が使われます。This is typically used for debugging, so it is important that the representation is information-rich and unambiguous.
- object.__str__(self)¶
Called by
str(object)
and the built-in functionsformat()
andprint()
to compute the "informal" or nicely printable string representation of an object. The return value must be a string object.__str__()
が有効な Python 表現を返すことが期待されないという点で、このメソッドはobject.__repr__()
とは異なります: より便利な、または簡潔な表現を使用することができます。組み込み型
object
によって定義されたデフォルト実装は、object.__repr__()
を呼び出します。
- object.__bytes__(self)¶
Called by bytes to compute a byte-string representation of an object. This should return a
bytes
object.
- object.__format__(self, format_spec)¶
format()
組み込み関数、さらには フォーマット済み文字列リテラル の評価、str.format()
メソッドによって呼び出され、オブジェクトの "フォーマット化された (formatted)" 文字列表現を作ります。 format_spec 引数は、 必要なフォーマット化オプションの記述を含む文字列です。 format_spec 引数の解釈は、__format__()
を実装する型によりますが、 ほとんどのクラスは組み込み型のいずれかにフォーマット化を委譲したり、 同じようなフォーマット化オプション構文を使います。標準のフォーマット構文の解説は、 書式指定ミニ言語仕様 を参照してください。
戻り値は文字列オブジェクトでなければなりません。
バージョン 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)
を呼び出します。A rich comparison method may return the singleton
NotImplemented
if it does not implement the operation for a given pair of arguments. By convention,False
andTrue
are returned for a successful comparison. However, these methods can return any value, so if the comparison operator is used in a Boolean context (e.g., in the condition of anif
statement), Python will callbool()
on the value to determine if the result is true or false.By default,
object
implements__eq__()
by usingis
, returningNotImplemented
in the case of a false comparison:True if x is y else NotImplemented
. For__ne__()
, by default it delegates to__eq__()
and inverts the result unless it isNotImplemented
. There are no other implied relationships among the comparison operators or default implementations; for example, the truth of(x<y or x==y)
does not implyx<=y
. To automatically generate ordering operations from a single root operation, seefunctools.total_ordering()
.カスタムの比較演算をサポートしていて、辞書のキーに使うことができる ハッシュ可能 オブジェクトを作るときの重要な注意点について、
__hash__()
のドキュメント内に書かれているので参照してください。There are no swapped-argument versions of these methods (to be used when the left argument does not support the operation but the right argument does); rather,
__lt__()
and__gt__()
are each other's reflection,__le__()
and__ge__()
are each other's reflection, and__eq__()
and__ne__()
are their own reflection. If the operands are of different types, and the right operand's type is a direct or indirect subclass of the left operand's type, the reflected method of the right operand has priority, otherwise the left operand's method has priority. Virtual subclassing is not considered.When no appropriate method returns any value other than
NotImplemented
, the==
and!=
operators will fall back tois
andis not
, respectively.
- object.__hash__(self)¶
組み込みの
hash()
関数や、set
,frozenset
,dict
のようなハッシュを使ったコレクション型の要素に対する操作から呼び出されます。__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 に入ってしまいます)。User-defined classes have
__eq__()
and__hash__()
methods by default; with them, all objects compare unequal (except with themselves) andx.__hash__()
returns an appropriate value such thatx == y
implies both thatx is y
andhash(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 を繰り返し起動する毎に、予測できなくなります。This is intended to provide protection against a denial-of-service caused by carefully chosen inputs that exploit the worst case performance of a dict insertion, O(n2) complexity. See http://ocert.org/advisories/ocert-2011-003.html for details.
ハッシュ値の変更は、集合のイテレーション順序に影響します。Python はこの順序付けを保証していません (そして通常 32-bit と 64-bit の間でも異なります)。
PYTHONHASHSEED
も参照してください。バージョン 3.3 で変更: ハッシュのランダム化がデフォルトで有効になりました。
- object.__bool__(self)¶
Called to implement truth value testing and the built-in operation
bool()
; should returnFalse
orTrue
. When this method is not defined,__len__()
is called, if it is defined, and the object is considered true if its result is nonzero. If a class defines neither__len__()
nor__bool__()
, all its instances are considered true.
3.3.2. 属性値アクセスをカスタマイズする¶
以下のメソッドを定義して、クラスインスタンスへの属性アクセス ( x.name
の使用、 x.name
への代入、 x.name
の削除) の意味をカスタマイズすることができます。
- object.__getattr__(self, name)¶
Called when the default attribute access fails with an
AttributeError
(either__getattribute__()
raises anAttributeError
because name is not an instance attribute or an attribute in the class tree forself
; or__get__()
of a name property raisesAttributeError
). This method should either return the (computed) attribute value or raise anAttributeError
exception.Note that if the attribute is found through the normal mechanism,
__getattr__()
is not called. (This is an intentional asymmetry between__getattr__()
and__setattr__()
.) This is done both for efficiency reasons and because otherwise__getattr__()
would have no way to access other attributes of the instance. Note that at least for instance variables, you can fake total control by not inserting any values in the instance attribute dictionary (but instead inserting them in another object). See the__getattribute__()
method below for a way to actually get total control over attribute access.
- object.__getattribute__(self, name)¶
クラスのインスタンスに対する属性アクセスを実装するために、無条件に呼び出されます。クラスが
__getattr__()
も定義している場合、__getattr__()
は、__getattribute__()
で明示的に呼び出すか、AttributeError
例外を送出しない限り呼ばれません。このメソッドは (計算された) 属性値を返すか、AttributeError
例外を送出します。このメソッドが再帰的に際限なく呼び出されてしまうのを防ぐため、実装の際には常に、必要な属性全てへのアクセスで、例えばobject.__getattribute__(self, name)
のように基底クラスのメソッドを同じ属性名を使って呼び出さなければなりません。注釈
This method may still be bypassed when looking up special methods as the result of implicit invocation via language syntax or built-in functions. See 特殊メソッド検索.
セキュリティに関わるような
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.__getattr__
を使った属性の削除は 監査イベント を送出します。
- object.__dir__(self)¶
Called when
dir()
is called on the object. An iterable must be returned.dir()
converts the returned iterable to a list and sorts it.
3.3.2.1. モジュールの属性値アクセスをカスタマイズする¶
特殊な名前の __getattr__
と __dir__
も、モジュール属性へのアクセスをカスタマイズするのに使えます。
モジュールレベルの __getattr__
関数は属性名である 1 引数を受け取り、計算した値を返すか AttributeError
を送出します。
属性がモジュールオブジェクトから、通常の検索、つまり object.__getattribute__()
で見付からなかった場合は、 AttributeError
を送出する前に、モジュールの __dict__
から __getattr__
が検索されます。
見付かった場合は、その属性名で呼び出され、結果が返されます。
The __dir__
function should accept no arguments, and return an iterable of
strings that represents the names accessible on module. If present, this
function overrides the standard dir()
search on a module.
より細かい粒度でのモジュールの動作 (属性やプロパティの設定など) のカスタマイズのために、モジュールオブジェクトの __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__
を設定したりしても、影響があるのは属性アクセスの構文が使われる検索だけです -- モジュールの globals への直接アクセスは (モジュール内のコードからとモジュールの globals のどちらでも) 影響を受けません。
バージョン 3.5 で変更: モジュールの属性 __class__
が書き込み可能になりました。
バージョン 3.7 で追加: __getattr__
モジュール属性と __dir__
モジュール属性。
参考
- PEP 562 - モジュールの __getattr__ と __dir__
モジュールの
__getattr__
関数および__dir__
関数の説明。
3.3.2.2. デスクリプタ (descriptor) の実装¶
The following methods only apply when an instance of the class containing the
method (a so-called descriptor class) appears in an owner class (the
descriptor must be in either the owner's class dictionary or in the class
dictionary for one of its parents). In the examples below, "the attribute"
refers to the attribute whose name is the key of the property in the owner
class' __dict__
.
- object.__get__(self, instance, owner=None)¶
オーナークラス(クラス属性アクセスの場合)や、クラスのインスタンス(インスタンス属性アクセスの場合)の属性取得時に呼び出されます。 instance を通じて属性をアクセスする時に、オプションの owner 引数はオーナークラスです。 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 上の属性を削除する際に呼び出されます。
Instances of descriptors may also have the __objclass__
attribute
present:
- object.__objclass__¶
The attribute
__objclass__
is interpreted by theinspect
module as specifying the class where this object was defined (setting this appropriately can assist in runtime introspection of dynamic class attributes). For callables, it may indicate that an instance of the given type (or a subclass) is expected or required as the first positional argument (for example, CPython sets this attribute for unbound methods that are implemented in 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
を変更せずに返します。
For instance bindings, the precedence of descriptor invocation depends on
which descriptor methods are defined. A descriptor can define any combination
of __get__()
, __set__()
and
__delete__()
. If it does not
define __get__()
, then accessing the attribute will return the descriptor
object itself unless there is a value in the object's instance dictionary. If
the descriptor defines __set__()
and/or __delete__()
, it is a data
descriptor; if it defines neither, it is a non-data descriptor. Normally, data
descriptors define both __get__()
and __set__()
, while non-data
descriptors have just the __get__()
method. Data descriptors with
__get__()
and __set__()
(and/or __delete__()
) defined
always override a redefinition in an
instance dictionary. In contrast, non-data descriptors can be overridden by
instances.
(@staticmethod
や @classmethod
を含む) Python メソッドは、非データデスクリプタとして実装されています。その結果、インスタンスではメソッドを再定義したりオーバーライドできます。このことにより、個々のインスタンスが同じクラスの他のインスタンスと互いに異なる動作を獲得することができます。
property()
関数はデータデスクリプタとして実装されています。従って、インスタンスはあるプロパティの動作をオーバーライドすることができません。
3.3.2.4. __slots__¶
__slots__ を使うと、(プロパティのように) データメンバを明示的に宣言し、 (明示的に __slots__ で宣言しているか親クラスに存在しているかでない限り) __dict__
や __weakref__ を作成しないようにできます。
__dict__
を使うのに比べて、節約できるメモリ空間はかなり大きいです。
属性探索のスピードもかなり向上できます。
- object.__slots__¶
このクラス変数には、インスタンスが用いる変数名を表す、文字列、イテラブル、または文字列のシーケンスを代入できます。__slots__ は、各インスタンスに対して宣言された変数に必要な記憶領域を確保し、
__dict__
と __weakref__ が自動的に生成されないようにします。
Notes on using __slots__:
__slots__ を持たないクラスから継承するとき、インスタンスの
__dict__
属性と __weakref__ 属性は常に利用可能です。__dict__
変数がない場合、 __slots__ に列挙されていない新たな変数をインスタンスに代入することはできません。列挙されていない変数名を使って代入しようとした場合、AttributeError
が送出されます。新たな変数を動的に代入したいのなら、 __slots__ を宣言する際に'__dict__'
を変数名のシーケンスに追加してください。__slots__ を定義しているクラスの各インスタンスに __weakref__ 変数がない場合、インスタンスに対する弱参照 (
weak references
) はサポートされません。弱参照のサポートが必要なら、 __slots__ を宣言する際に'__weakref__'
を変数名のシーケンスに追加してください。__slots__ は、クラスのレベルで各変数に対する デスクリプタ を使って実装されます。その結果、 __slots__ に定義されているインスタンス変数のデフォルト値はクラス属性を使って設定できなくなっています; そうしないと、デスクリプタによる代入をクラス属性が上書きしてしまうからです。
The action of a __slots__ declaration is not limited to the class where it is defined. __slots__ declared in parents are available in child classes. However, child subclasses will get a
__dict__
and __weakref__ unless they also define __slots__ (which should only contain names of any additional slots).あるクラスで、基底クラスですでに定義されているスロットを定義した場合、基底クラスのスロットで定義されているインスタンス変数は (デスクリプタを基底クラスから直接取得しない限り) アクセスできなくなります。これにより、プログラムの趣意が不定になってしまいます。将来は、この問題を避けるために何らかのチェックが追加されるかもしれません。
TypeError
will be raised if nonempty __slots__ are defined for a class derived from a"variable-length" built-in type
such asint
,bytes
, andtuple
.Any non-string iterable may be assigned to __slots__.
If a
dictionary
is used to assign __slots__, the dictionary keys will be used as the slot names. The values of the dictionary can be used to provide per-attribute docstrings that will be recognised byinspect.getdoc()
and displayed in the output ofhelp()
.__class__
assignment works only if both classes have the same __slots__.複数のスロットを持つ親クラスを使った 多重継承 はできますが、スロットで作成された属性を持つ親クラスは 1 つに限られます (他の基底クラスのスロットは空でなければなりません) - それに違反すると
TypeError
が送出されます。もし __slots__ に対して イテレータ を使用すると、イテレータの値ごとに デスクリプタ が作られます。しかし、 __slots__ 属性は空のイテレータとなります。
3.3.3. クラス生成をカスタマイズする¶
クラスが他のクラスを継承するときに必ず、親クラスの __init_subclass__()
が呼び出されます。これを利用すると、サブクラスの挙動を変更するクラスを書くことができます。これは、クラスデコレータととても良く似ていますが、クラスデコレータが、それが適用された特定のクラスにのみに影響するのに対して、 __init_subclass__
は、もっぱら、このメソッドを定義したクラスの将来のサブクラスに適用されます。
- classmethod object.__init_subclass__(cls)¶
このメソッドは、それが定義されたクラスが継承された際に必ず呼び出されます。cls は新しいサブクラスです。もし、このメソッドがインスタンスメソッドとして定義されると、暗黙的にクラスメソッドに変換されます。
Keyword arguments which are given to a new class are passed to the parent class's
__init_subclass__
. For compatibility with other classes using__init_subclass__
, one should take out the needed keyword arguments and pass the others over to the base class, as in: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)
としてアクセスできます。バージョン 3.6 で追加.
When a class is created, type.__new__()
scans the class variables
and makes callbacks to those with a __set_name__()
hook.
- object.__set_name__(self, owner, name)¶
オーナーとなるクラス owner が作成された時点で自動的に呼び出されます。 オブジェクトはそのクラスの name に割り当てられます。
class A: x = C() # Automatically calls: x.__set_name__(A, 'x')
If the class variable is assigned after the class is created,
__set_name__()
will not be called automatically. If needed,__set_name__()
can be called directly:class A: pass c = C() A.x = c # The hook is not called c.__set_name__(A, 'x') # Manually invoke the hook
詳細は クラスオブジェクトの作成 を参照してください。
バージョン 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)¶
If a base that appears in a class definition is not an instance of
type
, then an__mro_entries__()
method is searched on the base. If an__mro_entries__()
method is found, the base is substituted with the result of a call to__mro_entries__()
when creating the class. The method is called with the original bases tuple passed to the bases parameter, and must return a tuple of classes that will be used instead of the base. The returned tuple may be empty: in these cases, the original base is ignored.
参考
types.resolve_bases()
Dynamically resolve bases that are not instances of
type
.- PEP 560
Core support for typing module and generic types.
3.3.3.3. 適切なメタクラスの決定¶
クラス定義に対して適切なメタクラスは、以下のように決定されます:
基底も明示的なメタクラスも与えられていない場合は、
type()
が使われます;明示的なメタクラスが与えられていて、それが
type()
のインスタンス ではない 場合、それをメタクラスとして直接使います;明示的なメタクラスとして
type()
のインスタンスが与えられたか、基底が定義されていた場合は、最も派生した (継承関係で最も下の) メタクラスが使われます。
最も派生的なメタクラスは、(もしあれば) 明示的に指定されたメタクラスと、指定されたすべてのベースクラスのメタクラスから選ばれます。最も派生的なメタクラスは、これらのメタクラス候補のすべてのサブタイプであるようなものです。メタクラス候補のどれもその基準を満たさなければ、クラス定義は TypeError
で失敗します。
3.3.3.4. クラスの名前空間の準備¶
適切なメタクラスが指定されると、クラスの名前空間が用意されます。もしメタクラスが __prepare__
属性を持っている場合、 namespace = metaclass.__prepare__(name, bases, **kwds)
が呼ばれます。追加のキーワード引数は、もしクラス定義にあれば設定されます。 __prepare__
メソッドは クラスメソッド
として実装する必要があります。 __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 実装の詳細: CPython 3.6 以降では、 __class__
セルは、クラス名前空間にある __classcell__
エントリーとしてメタクラスに渡されます。
__class__
セルが存在していた場合は、そのクラスが正しく初期化されるために、 type.__new__
の呼び出しに到達するまで上に伝搬されます。
失敗した場合は、Python 3.8 では RuntimeError
になります。
デフォルトのメタクラス type
や最終的には type.__new__
を呼び出すメタクラスを使っているときは、クラスオブジェクトを作成した後に次のカスタム化の手順が起動されます:
type.__new__
メソッドが__set_name__()
が定義されているクラスの名前空間にある全ての属性を収集します;それらの
__set_name__
メソッドが、そのメソッドが定義されているクラス、およびそこに属する属性に割り当てられている名前を引数として呼び出されます;新しいクラスのメソッド解決順序ですぐ上に位置する親クラスで
__init_subclass__()
フックが呼び出されます。
クラスオブジェクトが作成された後には、クラス定義に含まれているクラスデコレータ (もしあれば) にクラスオブジェクトが渡され、デコレータが返すオブジェクトがここで定義されたクラスとしてローカルの名前空間に束縛されます。
When a new class is created by type.__new__
, the object provided as the
namespace parameter is copied to a new ordered mapping and the original
object is discarded. The new copy is wrapped in a read-only proxy, which
becomes the __dict__
attribute of the class object.
参考
- PEP 3135 - New super
暗黙の
__class__
クロージャ参照について記述しています
3.3.3.7. メタクラスの用途¶
メタクラスは限りない潜在的利用価値を持っています。これまで試されてきたアイデアには、列挙型、ログ記録、インターフェースのチェック、 自動デリゲーション、自動プロパティ生成、プロキシ、フレームワーク、そして自動リソースロック/同期といったものがあります。
3.3.4. インスタンスのカスタマイズとサブクラスチェック¶
以下のメソッドは組み込み関数 isinstance()
と issubclass()
のデフォルトの動作を上書きするのに利用します。
特に、 abc.ABCMeta
メタクラスは、抽象基底クラス (ABCs) を"仮想基底クラス (virtual base classes)" として、他の ABC を含む、任意のクラスや (組み込み型を含む) 型に追加するために、これらのメソッドを実装しています。
- class.__instancecheck__(self, instance)¶
instance が (直接、または間接的に) class のインスタンスと考えられる場合に true を返します。定義されていれば、
isinstance(instance, class)
の実装のために呼び出されます。
- class.__subclasscheck__(self, subclass)¶
subclass が (直接、または間接的に) class のサブクラスと考えられる場合に true を返します。定義されていれば、
issubclass(subclass, class)
の実装のために呼び出されます。
なお、これらのメソッドは、クラスの型 (メタクラス) 上で検索されます。実際のクラスにクラスメソッドとして定義することはできません。これは、インスタンスそれ自体がクラスであるこの場合にのみ、インスタンスに呼び出される特殊メソッドの検索と一貫しています。
参考
- PEP 3119 - 抽象基底クラスの導入
Includes the specification for customizing
isinstance()
andissubclass()
behavior through__instancecheck__()
and__subclasscheck__()
, with motivation for this functionality in the context of adding Abstract Base Classes (see theabc
module) to the language.
3.3.5. ジェネリック型をエミュレートする¶
When using type annotations, it is often useful to
parameterize a generic type using Python's square-brackets notation.
For example, the annotation list[int]
might be used to signify a
list
in which all the elements are of type int
.
参考
- PEP 484 - 型ヒント
Introducing Python's framework for type annotations
- Generic Alias Types
Documentation for objects representing parameterized generic classes
- ジェネリクス, user-defined generics and
typing.Generic
実行時にパラメータ設定が可能であり、かつ静的な型チェッカーが理解できるジェネリッククラスを実装する方法のドキュメントです。
A class can generally only be parameterized if it defines the special
class method __class_getitem__()
.
- classmethod object.__class_getitem__(cls, key)¶
key にある型引数で特殊化されたジェネリッククラスを表すオブジェクトを返します。
When defined on a class,
__class_getitem__()
is automatically a class method. As such, there is no need for it to be decorated with@classmethod
when it is defined.
3.3.5.1. The purpose of __class_getitem__¶
The purpose of __class_getitem__()
is to allow runtime
parameterization of standard-library generic classes in order to more easily
apply type hints to these classes.
To implement custom generic classes that can be parameterized at runtime and
understood by static type-checkers, users should either inherit from a standard
library class that already implements __class_getitem__()
, or
inherit from typing.Generic
, which has its own implementation of
__class_getitem__()
.
Custom implementations of __class_getitem__()
on classes defined
outside of the standard library may not be understood by third-party
type-checkers such as mypy. Using __class_getitem__()
on any class for
purposes other than type hinting is discouraged.
3.3.5.2. __class_getitem__ versus __getitem__¶
Usually, the subscription of an object using square
brackets will call the __getitem__()
instance method defined on
the object's class. However, if the object being subscribed is itself a class,
the class method __class_getitem__()
may be called instead.
__class_getitem__()
should return a GenericAlias
object if it is properly defined.
Presented with the expression obj[x]
, the Python interpreter
follows something like the following process to decide whether
__getitem__()
or __class_getitem__()
should be
called:
from inspect import isclass
def subscribe(obj, x):
"""Return the result of the expression 'obj[x]'"""
class_of_obj = type(obj)
# If the class of obj defines __getitem__,
# call class_of_obj.__getitem__(obj, x)
if hasattr(class_of_obj, '__getitem__'):
return class_of_obj.__getitem__(obj, x)
# Else, if obj is a class and defines __class_getitem__,
# call obj.__class_getitem__(x)
elif isclass(obj) and hasattr(obj, '__class_getitem__'):
return obj.__class_getitem__(x)
# Else, raise an exception
else:
raise TypeError(
f"'{class_of_obj.__name__}' object is not subscriptable"
)
In Python, all classes are themselves instances of other classes. The class of
a class is known as that class's metaclass, and most classes have the
type
class as their metaclass. type
does not define
__getitem__()
, meaning that expressions such as list[int]
,
dict[str, float]
and tuple[str, bytes]
all result in
__class_getitem__()
being called:
>>> # list has class "type" as its metaclass, like most classes:
>>> type(list)
<class 'type'>
>>> type(dict) == type(list) == type(tuple) == type(str) == type(bytes)
True
>>> # "list[int]" calls "list.__class_getitem__(int)"
>>> list[int]
list[int]
>>> # list.__class_getitem__ returns a GenericAlias object:
>>> type(list[int])
<class 'types.GenericAlias'>
However, if a class has a custom metaclass that defines
__getitem__()
, subscribing the class may result in different
behaviour. An example of this can be found in the enum
module:
>>> 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 モジュールとジェネリック型に対する言語コアによるサポート
Introducing
__class_getitem__()
, and outlining when a subscription results in__class_getitem__()
being called instead of__getitem__()
3.3.6. 呼び出し可能オブジェクトをエミュレートする¶
- object.__call__(self[, args...])¶
Called when the instance is "called" as a function; if this method is defined,
x(arg1, arg2, ...)
roughly translates totype(x).__call__(x, arg1, ...)
.
3.3.7. コンテナをエミュレートする¶
The following methods can be defined to implement container objects. 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()
.
Mutable sequences should provide methods append()
, count()
,
index()
, extend()
, insert()
, pop()
, remove()
,
reverse()
and sort()
, like Python standard list
objects. Finally,
sequence types should implement addition (meaning concatenation) and
multiplication (meaning repetition) by defining the methods
__add__()
, __radd__()
, __iadd__()
,
__mul__()
, __rmul__()
and __imul__()
described below; they should not define other numerical
operators. It is recommended that both mappings and sequences implement the
__contains__()
method to allow efficient use of the in
operator; for
mappings, in
should search the mapping's keys; for sequences, it should
search through the values. It is further recommended that both mappings and
sequences implement the __iter__()
method to allow efficient iteration
through the container; for mappings, __iter__()
should iterate
through the object's keys; for sequences, it should iterate through the values.
- object.__len__(self)¶
Called to implement the built-in function
len()
. Should return the length of the object, an integer>=
0. Also, an object that doesn't define a__bool__()
method and whose__len__()
method returns zero is considered to be false in a Boolean context.CPython 実装の詳細: In CPython, the length is required to be at most
sys.maxsize
. If the length is larger thansys.maxsize
some features (such aslen()
) may raiseOverflowError
. To prevent raisingOverflowError
by truth value testing, an object must define a__bool__()
method.
- object.__length_hint__(self)¶
Called to implement
operator.length_hint()
. Should return an estimated length for the object (which may be greater or less than the actual length). The length must be an integer>=
0. The return value may also beNotImplemented
, which is treated the same as if the__length_hint__
method didn't exist at all. This method is purely an optimization and is never required for correctness.バージョン 3.4 で追加.
注釈
スライシングは、以下の 3 メソッドによって排他的に行われます。次のような呼び出しは
a[1:2] = b
次のように翻訳され
a[slice(1, 2, None)] = b
以下も同様です。存在しないスライスの要素は None
で埋められます。
- object.__getitem__(self, key)¶
Called to implement evaluation of
self[key]
. For sequence types, the accepted keys should be integers. Optionally, they may supportslice
objects as well. Negative index support is also optional. If key is of an inappropriate type,TypeError
may be raised; if key is a value outside the set of indexes for the sequence (after any special interpretation of negative values),IndexError
should be raised. For mapping types, if key is missing (not in the container),KeyError
should be raised.注釈
for
ループでは、シーケンスの終端を正しく検出できるようにするために、不正なインデクスに対してIndexError
が送出されるものと期待しています。注釈
When subscripting a class, the special class method
__class_getitem__()
may be called instead of__getitem__()
. See __class_getitem__ versus __getitem__ for more details.
- 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()
関数の三項のものがサポートされていなければならない場合、__pow__()
はオプションの第三引数を受け取るものとして定義されなければなりません。If one of those methods does not support the operation with the supplied arguments, it should return
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)¶
These methods are called to implement the binary arithmetic operations (
+
,-
,*
,@
,/
,//
,%
,divmod()
,pow()
,**
,<<
,>>
,&
,^
,|
) with reflected (swapped) operands. These functions are only called if the left operand does not support the corresponding operation [3] and the operands are of different types. [4] For instance, to evaluate the expressionx - y
, where y is an instance of a class that has an__rsub__()
method,type(y).__rsub__(y, x)
is called iftype(x).__sub__(x, y)
returnsNotImplemented
.ただし、三項演算子
pow()
が__rpow__()
を呼ぶことはないので注意してください (型強制の規則が非常に難解になるからです)。注釈
右側の被演算子の型が左側の被演算子の型のサブクラスであり、このサブクラスであるメソッドに対する反射メソッドと異なる実装が定義されている場合には、左側の被演算子の非反射メソッドが呼ばれる前に、このメソッドが呼ばれます。この振る舞いにより、サブクラスが親の演算をオーバーライドすることが可能になります。
- 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)¶
These methods are called to implement the augmented arithmetic assignments (
+=
,-=
,*=
,@=
,/=
,//=
,%=
,**=
,<<=
,>>=
,&=
,^=
,|=
). These methods should attempt to do the operation in-place (modifying self) and return the result (which could be, but does not have to be, self). If a specific method is not defined, or if that method returnsNotImplemented
, the augmented assignment falls back to the normal methods. For instance, if x is an instance of a class with an__iadd__()
method,x += y
is equivalent tox = x.__iadd__(y)
. If__iadd__()
does not exist, or ifx.__iadd__(y)
returnsNotImplemented
,x.__add__(y)
andy.__radd__(x)
are considered, as with the evaluation ofx + y
. In certain situations, augmented assignment can result in unexpected errors (see なぜ加算はされるのに a_tuple[i] += ['item'] は例外を送出するのですか?), but this behavior is in fact part of the data model.
- 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
) に切り詰められたオブジェクトの値を返すべきです。The built-in function
int()
falls back to__trunc__()
if neither__int__()
nor__index__()
is defined.バージョン 3.11 で変更:
int()
の__trunc__()
への処理の委譲は非推奨になりました。
3.3.9. with文とコンテキストマネージャ¶
コンテキストマネージャ(context manager) とは、 with
文の実行時にランタイムコンテキストを定義するオブジェクトです。コンテキストマネージャは、コードブロックを実行するために必要な入り口および出口の処理を扱います。コンテキストマネージャは通常、 with
文( with 文 の章を参照)により起動されますが、これらのメソッドを直接呼び出すことで起動することもできます。
コンテキストマネージャの代表的な使い方としては、様々なグローバル情報の保存および更新、リソースのロックとアンロック、ファイルのオープンとクローズなどが挙げられます。
For more information on context managers, see コンテキストマネージャ型.
- object.__exit__(self, exc_type, exc_value, traceback)¶
コンテキストマネージャの出口で実行される処理です。パラメータは、コンテキストが終了した原因となった例外について説明しています。コンテキストが例外を送出せず終了した場合は、全ての引き数に
None
が設定されます。もし、例外が送出され、かつメソッドが例外を抑制したい場合(すなわち、例外が伝播されるのを防ぎたい場合)、このメソッドは True を返す必要があります。そうでなければ、このメソッドの終了後、例外は通常通り伝播することになります。
Note that
__exit__()
methods should not reraise the passed-in exception; this is the caller's responsibility.
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
を送出します。
バージョン 3.10 で追加.
参考
- PEP 634 - 構造的パターンマッチ
match
文の詳細。
3.3.11. 特殊メソッド検索¶
カスタムクラスでは、特殊メソッドの暗黙の呼び出しは、オブジェクトのインスタンス辞書ではなく、オブジェクトの型で定義されているときにのみ正しく動作することが保証されます。この動作のため、以下のコードは例外を送出します:
>>> 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__() # Explicit lookup via instance
Class getattribute invoked
10
>>> type(c).__len__(c) # Explicit lookup via type
Metaclass getattribute invoked
10
>>> len(c) # Implicit lookup
10
このように __getattribute__()
機構をバイパスすることで、特殊メソッドの扱いに関するある程度の自由度と引き換えに (特殊メソッドはインタプリタから一貫して実行されるためにクラスオブジェクトに設定 しなければならない)、インタープリタを高速化するための大きな余地が手に入ります。
3.4. コルーチン¶
3.4.1. 待機可能オブジェクト (Awaitable Object)¶
awaitable オブジェクトは一般的には __await__()
メソッドが実装されています。 async def
関数が返す Coroutineオブジェクト は待機可能です。
注釈
types.coroutine()
デコレータでデコレータが付けられたジェネレータから返される generator iterator オブジェクトも待機可能ですが、 __await__()
は実装されていません。
- object.__await__(self)¶
Must return an iterator. Should be used to implement awaitable objects. For instance,
asyncio.Future
implements this method to be compatible with theawait
expression.
バージョン 3.5 で追加.
参考
待機可能オブジェクトについてより詳しくは PEP 492 を参照してください。
3.4.2. コルーチンオブジェクト¶
Coroutineオブジェクト は awaitable オブジェクトです。__await__()
を呼び出し、その返り値に対し反復処理をすることでコルーチンの実行を制御できます。コルーチンの実行が完了し制御を戻したとき、イテレータは StopIteration
を送出し、その例外の value
属性に返り値を持たせます。コルーチンが例外を送出した場合は、イテレータにより伝搬されます。コルーチンから StopIteration
例外を外に送出すべきではありません。
コルーチンには以下に挙げるメソッドもあり、これらはジェネレータのメソッドからの類似です (ジェネレータ-イテレータメソッド を参照してください)。 ただし、ジェネレータと違って、コルーチンは反復処理を直接はサポートしていません。
バージョン 3.5.2 で変更: コルーチンで2回以上待機 (await) すると RuntimeError
となります。
- coroutine.send(value)¶
Starts or resumes execution of the coroutine. If value is
None
, this is equivalent to advancing the iterator returned by__await__()
. If value is notNone
, this method delegates to thesend()
method of the iterator that caused the coroutine to suspend. The result (return value,StopIteration
, or other exception) is the same as when iterating over the__await__()
return value, described above.
- coroutine.throw(value)¶
- coroutine.throw(type[, value[, traceback]])
コルーチンで指定された例外を送出します。 このメソッドは、イテレータにコルーチンを一時停止する
throw()
メソッドがある場合に処理を委任します。 そうでない場合には、中断した地点から例外が送出されます。 結果 (返り値かStopIteration
かその他の例外) は、上で解説したような__await__()
の返り値に対して反復処理を行ったときと同じです。 例外がコルーチンの中で捕捉されなかった場合、呼び出し元へ伝搬されます。
- coroutine.close()¶
コルーチンが自分自身の後片付けをし終了します。 コルーチンが一時停止している場合は、コルーチンを一時停止させたイテレータに
close()
メソッドがあれば、まずはそれに処理を委任します。 そして一時停止した地点からGeneratorExit
が送出され、ただちにコルーチンが自分自身の後片付けを行います。 最後に、実行が開始されていなかった場合でも、コルーチンに実行が完了した印を付けます。コルーチンオブジェクトが破棄されるときには、上記の手順を経て自動的に閉じられます。
3.4.3. 非同期イテレータ (Asynchronous Iterator)¶
非同期イテレータ の __anext__
メソッドからは非同期のコードが呼べます。
非同期イテレータは async for
文の中で使えます。
- 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
バージョン 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.__aenter__(self)¶
Semantically similar to
__enter__()
, the only difference being that it must return an awaitable.
- object.__aexit__(self, exc_type, exc_value, traceback)¶
Semantically similar to
__exit__()
, the only difference being that it must return an awaitable.
非同期コンテキストマネージャクラスの例:
class AsyncContextManager:
async def __aenter__(self):
await log('entering context')
async def __aexit__(self, exc_type, exc, tb):
await log('exiting context')
バージョン 3.5 で追加.
脚注