3.3.1. 基本定制?

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

調用以創(chuàng )建一個(gè) cls 類(lèi)的新實(shí)例。__new__() 是一個(gè)靜態(tài)方法 (因為是特例所以你不需要顯式地聲明)，它會(huì )將所請求實(shí)例所屬的類(lèi)作為第一個(gè)參數。其余的參數會(huì )被傳遞給對象構造器表達式 (對類(lèi)的調用)。__new__() 的返回值應為新對象實(shí)例 (通常是 cls 的實(shí)例)。

典型的實(shí)現會(huì )附帶適宜的參數使用 super().__new__(cls[, ...])，通過(guò)超類(lèi)的 __new__() 方法來(lái)創(chuàng )建一個(gè)類(lèi)的新實(shí)例，然后根據需要修改新創(chuàng )建的實(shí)例再將其返回。

If __new__() is invoked during object construction and it returns an instance of cls, then the new instance’s __init__() method will be invoked like __init__(self[, ...]), where self is the new instance and the remaining arguments are the same as were passed to the object constructor.

如果 __new__() 未返回一個(gè) cls 的實(shí)例，則新實(shí)例的 __init__() 方法就不會(huì )被執行。

__new__() 的目的主要是允許不可變類(lèi)型的子類(lèi) (例如 int, str 或 tuple) 定制實(shí)例創(chuàng )建過(guò)程。它也常會(huì )在自定義元類(lèi)中被重載以便定制類(lèi)創(chuàng )建過(guò)程。

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

在實(shí)例 (通過(guò) __new__()) 被創(chuàng )建之后，返回調用者之前調用。其參數與傳遞給類(lèi)構造器表達式的參數相同。一個(gè)基類(lèi)如果有 __init__() 方法，則其所派生的類(lèi)如果也有 __init__() 方法，就必須顯式地調用它以確保實(shí)例基類(lèi)部分的正確初始化；例如: super().__init__([args...]).

因為對象是由 __new__() 和 __init__() 協(xié)作構造完成的 (由 __new__() 創(chuàng )建，并由 __init__() 定制)，所以 __init__() 返回的值只能是 None，否則會(huì )在運行時(shí)引發(fā) TypeError。

object.__del__(self)?

在實(shí)例將被銷(xiāo)毀時(shí)調用。 這還被稱(chēng)為終結器或析構器（不適當）。 如果一個(gè)基類(lèi)具有 __del__() 方法，則其所派生的類(lèi)如果也有 __del__() 方法，就必須顯式地調用它以確保實(shí)例基類(lèi)部分的正確清除。

__del__() 方法可以 (但不推薦!) 通過(guò)創(chuàng )建一個(gè)該實(shí)例的新引用來(lái)推遲其銷(xiāo)毀。這被稱(chēng)為對象 重生。__del__() 是否會(huì )在重生的對象將被銷(xiāo)毀時(shí)再次被調用是由具體實(shí)現決定的 ；當前的 CPython 實(shí)現只會(huì )調用一次。

當解釋器退出時(shí)不會(huì )確保為仍然存在的對象調用 __del__() 方法。

備注

del x 并不直接調用 x.__del__() --- 前者會(huì )將 x 的引用計數減一，而后者僅會(huì )在 x 的引用計數變?yōu)榱銜r(shí)被調用。

CPython implementation detail: 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.

參見(jiàn)

gc 模塊的文檔。

警告

由于調用 __del__() 方法時(shí)周邊狀況已不確定，在其執行期間發(fā)生的異常將被忽略，改為打印一個(gè)警告到 sys.stderr。特別地：

• __del__() 可在任意代碼被執行時(shí)啟用，包括來(lái)自任意線(xiàn)程的代碼。如果 __del__() 需要接受鎖或啟用其他阻塞資源，可能會(huì )發(fā)生死鎖，例如該資源已被為執行 __del__() 而中斷的代碼所獲取。

• __del__() 可以在解釋器關(guān)閉階段被執行。因此，它需要訪(fǎng)問(wèn)的全局變量（包含其他模塊）可能已被刪除或設為 None。Python 會(huì )保證先刪除模塊中名稱(chēng)以單個(gè)下劃線(xiàn)打頭的全局變量再刪除其他全局變量；如果已不存在其他對此類(lèi)全局變量的引用，這有助于確保導入的模塊在 __del__() 方法被調用時(shí)仍然可用。

object.__repr__(self)?

由 repr() 內置函數調用以輸出一個(gè)對象的“官方”字符串表示。如果可能，這應類(lèi)似一個(gè)有效的 Python 表達式，能被用來(lái)重建具有相同取值的對象（只要有適當的環(huán)境）。如果這不可能，則應返回形式如 <...some useful description...> 的字符串。返回值必須是一個(gè)字符串對象。如果一個(gè)類(lèi)定義了 __repr__() 但未定義 __str__()，則在需要該類(lèi)的實(shí)例的“非正式”字符串表示時(shí)也會(huì )使用 __repr__()。

此方法通常被用于調試，因此確保其表示的內容包含豐富信息且無(wú)歧義是很重要的。

object.__str__(self)?

通過(guò) str(object) 以及內置函數 format() 和 print() 調用以生成一個(gè)對象的“非正式”或格式良好的字符串表示。返回值必須為一個(gè) 字符串 對象。

此方法與 object.__repr__() 的不同點(diǎn)在于 __str__() 并不預期返回一個(gè)有效的 Python 表達式：可以使用更方便或更準確的描述信息。

內置類(lèi)型 object 所定義的默認實(shí)現會(huì )調用 object.__repr__()。

object.__bytes__(self)?

通過(guò) bytes 調用以生成一個(gè)對象的字節串表示。這應該返回一個(gè) bytes 對象。

object.__format__(self, format_spec)?

通過(guò) format() 內置函數、擴展、格式化字符串字面值 的求值以及 str.format() 方法調用以生成一個(gè)對象的“格式化”字符串表示。 format_spec 參數為包含所需格式選項描述的字符串。 format_spec 參數的解讀是由實(shí)現 __format__() 的類(lèi)型決定的，不過(guò)大多數類(lèi)或是將格式化委托給某個(gè)內置類(lèi)型，或是使用相似的格式化選項語(yǔ)法。

請參看 格式規格迷你語(yǔ)言 了解標準格式化語(yǔ)法的描述。

返回值必須為一個(gè)字符串對象。

在 3.4 版更改: object 本身的 __format__ 方法如果被傳入任何非空字符，將會(huì )引發(fā)一個(gè) TypeError。

在 3.7 版更改: object.__format__(x, '') 現在等同于 str(x) 而不再是 format(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)?

以上這些被稱(chēng)為“富比較”方法。運算符號與方法名稱(chēng)的對應關(guān)系如下：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)。

如果指定的參數對沒(méi)有相應的實(shí)現，富比較方法可能會(huì )返回單例對象 NotImplemented。按照慣例，成功的比較會(huì )返回 False 或 True。不過(guò)實(shí)際上這些方法可以返回任意值，因此如果比較運算符是要用于布爾值判斷（例如作為 if 語(yǔ)句的條件），Python 會(huì )對返回值調用 bool() 以確定結果為真還是假。

在默認情況下，object 通過(guò)使用 is 來(lái)實(shí)現 __eq__()，并在比較結果為假值時(shí)返回 NotImplemented: True if x is y else NotImplemented。 對于 __ne__()，默認會(huì )委托給 __eq__() 并對結果取反，除非結果為 NotImplemented。 比較運算符之間沒(méi)有其他隱含關(guān)系或默認實(shí)現；例如，(x<y or x==y) 為真并不意味著(zhù) x<=y。 要根據單根運算自動(dòng)生成排序操作，請參看 functools.total_ordering()。

請查看 __hash__() 的相關(guān)段落，了解創(chuàng )建可支持自定義比較運算并可用作字典鍵的 hashable 對象時(shí)要注意的一些事項。

這些方法并沒(méi)有對調參數版本（在左邊參數不支持該操作但右邊參數支持時(shí)使用）；而是 __lt__() 和 __gt__() 互為對方的反射， __le__() 和 __ge__() 互為對方的反射，而 __eq__() 和 __ne__() 則是它們自己的反射。如果兩個(gè)操作數的類(lèi)型不同，且右操作數類(lèi)型是左操作數類(lèi)型的直接或間接子類(lèi)，則優(yōu)先選擇右操作數的反射方法，否則優(yōu)先選擇左操作數的方法。虛擬子類(lèi)不會(huì )被考慮。

object.__hash__(self)?

Called by built-in function hash() and for operations on members of hashed collections including set, frozenset, and dict. The __hash__() method should return an integer. The only required property is that objects which compare equal have the same hash value; it is advised to mix together the hash values of the components of the object that also play a part in comparison of objects by packing them into a tuple and hashing the tuple. Example:

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

備注

hash() 會(huì )從一個(gè)對象自定義的 __hash__() 方法返回值中截斷為 Py_ssize_t 的大小。通常對 64 位構建為 8 字節，對 32 位構建為 4 字節。如果一個(gè)對象的 __hash__() 必須在不同位大小的構建上進(jìn)行互操作，請確保檢查全部所支持構建的寬度。做到這一點(diǎn)的簡(jiǎn)單方法是使用 python -c "import sys; print(sys.hash_info.width)"。

如果一個(gè)類(lèi)沒(méi)有定義 __eq__() 方法，那么也不應該定義 __hash__() 操作；如果它定義了 __eq__() 但沒(méi)有定義 __hash__()，則其實(shí)例將不可被用作可哈希集的項。如果一個(gè)類(lèi)定義了可變對象并實(shí)現了 __eq__() 方法，則不應該實(shí)現 __hash__()，因為可哈希集的實(shí)現要求鍵的哈希集是不可變的（如果對象的哈希值發(fā)生改變，它將處于錯誤的哈希桶中）。

用戶(hù)定義的類(lèi)默認帶有 __eq__() 和 __hash__() 方法；使用它們與任何對象（自己除外）比較必定不相等，并且 x.__hash__() 會(huì )返回一個(gè)恰當的值以確保 x == y 同時(shí)意味著(zhù) x is y 且 hash(x) == hash(y)。

一個(gè)類(lèi)如果重載了 __eq__() 且沒(méi)有定義 __hash__() 則會(huì )將其 __hash__() 隱式地設為 None。當一個(gè)類(lèi)的 __hash__() 方法為 None 時(shí)，該類(lèi)的實(shí)例將在一個(gè)程序嘗試獲取其哈希值時(shí)正確地引發(fā) TypeError，并會(huì )在檢測 isinstance(obj, collections.abc.Hashable) 時(shí)被正確地識別為不可哈希對象。

如果一個(gè)重載了 __eq__() 的類(lèi)需要保留來(lái)自父類(lèi)的 __hash__() 實(shí)現，則必須通過(guò)設置 __hash__ = <ParentClass>.__hash__ 來(lái)顯式地告知解釋器。

如果一個(gè)沒(méi)有重載 __eq__() 的類(lèi)需要去掉哈希支持，則應該在類(lèi)定義中包含 __hash__ = None。一個(gè)自定義了 __hash__() 以顯式地引發(fā) TypeError 的類(lèi)會(huì )被 isinstance(obj, collections.abc.Hashable) 調用錯誤地識別為可哈希對象。

備注

在默認情況下，str 和 bytes 對象的 __hash__() 值會(huì )使用一個(gè)不可預知的隨機值“加鹽”。 雖然它們在一個(gè)單獨 Python 進(jìn)程中會(huì )保持不變，但它們的值在重復運行的 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(n²) complexity. See http://www.ocert.org/advisories/ocert-2011-003.html for details.

改變哈希值會(huì )影響集合的迭代次序。Python 也從不保證這個(gè)次序不會(huì )被改變（通常它在 32 位和 64 位構建上是不一致的）。

另見(jiàn) PYTHONHASHSEED.

在 3.3 版更改: 默認啟用哈希隨機化。

object.__bool__(self)?

調用此方法以實(shí)現真值檢測以及內置的 bool() 操作；應該返回 False 或 True。如果未定義此方法，則會(huì )查找并調用 __len__() 并在其返回非零值時(shí)視對象的邏輯值為真。如果一個(gè)類(lèi)既未定義 __len__() 也未定義 __bool__() 則視其所有實(shí)例的邏輯值為真。

3.3.2. 自定義屬性訪(fǎng)問(wèn)?

可以定義下列方法來(lái)自定義對類(lèi)實(shí)例屬性訪(fǎng)問(wèn)（x.name 的使用、賦值或刪除）的具體含義.

object.__getattr__(self, name)?

當默認屬性訪(fǎng)問(wèn)因引發(fā) AttributeError 而失敗時(shí)被調用 (可能是調用 __getattribute__() 時(shí)由于 name 不是一個(gè)實(shí)例屬性或 self 的類(lèi)關(guān)系樹(shù)中的屬性而引發(fā)了 AttributeError；或者是對 name 特性屬性調用 __get__() 時(shí)引發(fā)了 AttributeError)。此方法應當返回（找到的）屬性值或是引發(fā)一個(gè) AttributeError 異常。

請注意如果屬性是通過(guò)正常機制找到的，__getattr__() 就不會(huì )被調用。（這是在 __getattr__() 和 __setattr__() 之間故意設置的不對稱(chēng)性。）這既是出于效率理由也是因為不這樣設置的話(huà) __getattr__() 將無(wú)法訪(fǎng)問(wèn)實(shí)例的其他屬性。要注意至少對于實(shí)例變量來(lái)說(shuō)，你不必在實(shí)例屬性字典中插入任何值（而是通過(guò)插入到其他對象）就可以模擬對它的完全控制。請參閱下面的 __getattribute__() 方法了解真正獲取對屬性訪(fǎng)問(wèn)的完全控制權的辦法。

object.__getattribute__(self, name)?

此方法會(huì )無(wú)條件地被調用以實(shí)現對類(lèi)實(shí)例屬性的訪(fǎng)問(wèn)。如果類(lèi)還定義了 __getattr__()，則后者不會(huì )被調用，除非 __getattribute__() 顯式地調用它或是引發(fā)了 AttributeError。此方法應當返回（找到的）屬性值或是引發(fā)一個(gè) AttributeError 異常。為了避免此方法中的無(wú)限遞歸，其實(shí)現應該總是調用具有相同名稱(chēng)的基類(lèi)方法來(lái)訪(fǎng)問(wèn)它所需要的任何屬性，例如 object.__getattribute__(self, name)。

備注

此方法在作為通過(guò)特定語(yǔ)法或內置函數隱式地調用的結果的情況下查找特殊方法時(shí)仍可能會(huì )被跳過(guò)。參見(jiàn) 特殊方法查找。

引發(fā)一個(gè) 審計事件 object.__getattr__，附帶參數 obj, name。

object.__setattr__(self, name, value)?

此方法在一個(gè)屬性被嘗試賦值時(shí)被調用。這個(gè)調用會(huì )取代正常機制（即將值保存到實(shí)例字典）。 name 為屬性名稱(chēng)， value 為要賦給屬性的值。

如果 __setattr__() 想要賦值給一個(gè)實(shí)例屬性，它應該調用同名的基類(lèi)方法，例如 object.__setattr__(self, name, value)。

引發(fā)一個(gè) 審計事件 object.__setattr__，附帶參數 obj, name, value。

object.__delattr__(self, name)?

類(lèi)似于 __setattr__() 但其作用為刪除而非賦值。此方法應該僅在 del obj.name 對于該對象有意義時(shí)才被實(shí)現。

引發(fā)一個(gè) 審計事件 object.__delattr__，附帶參數 obj, name。

object.__dir__(self)?

此方法會(huì )在對相應對象調用 dir() 時(shí)被調用。返回值必須為一個(gè)序列。 dir() 會(huì )把返回的序列轉換為列表并對其排序。

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

3.3.3. 自定義類(lèi)創(chuàng )建?

Whenever a class inherits from another class, __init_subclass__() is called on the parent class. This way, it is possible to write classes which change the behavior of subclasses. This is closely related to class decorators, but where class decorators only affect the specific class they're applied to, __init_subclass__ solely applies to future subclasses of the class defining the method.

classmethod object.__init_subclass__(cls)?

當所在類(lèi)派生子類(lèi)時(shí)此方法就會(huì )被調用。cls 將指向新的子類(lèi)。如果定義為一個(gè)普通實(shí)例方法，此方法將被隱式地轉換為類(lèi)方法。

傳入一個(gè)新類(lèi)的關(guān)鍵字參數會(huì )被傳給父類(lèi)的 __init_subclass__。為了與其他使用 __init_subclass__ 的類(lèi)兼容，應當根據需要去掉部分關(guān)鍵字參數再將其余的傳給基類(lèi)，例如:

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__ 的默認實(shí)現什么都不做，只在帶任意參數調用時(shí)引發(fā)一個(gè)錯誤。

備注

元類(lèi)提示 metaclass 將被其它類(lèi)型機制消耗掉，并不會(huì )被傳給 __init_subclass__ 的實(shí)現。實(shí)際的元類(lèi)（而非顯式的提示）可通過(guò) type(cls) 訪(fǎng)問(wèn)。

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)?

Automatically called at the time the owning class owner is created. The object has been assigned to name in that class:

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

詳情參見(jiàn) 創(chuàng )建類(lèi)對象。

3.6 新版功能.

class Meta(type):
    pass

class MyClass(metaclass=Meta):
    pass

class MySubclass(MyClass):
    pass

3.3.4. 自定義實(shí)例及子類(lèi)檢查?

以下方法被用來(lái)重載 isinstance() 和 issubclass() 內置函數的默認行為。

特別地，元類(lèi) abc.ABCMeta 實(shí)現了這些方法以便允許將抽象基類(lèi)（ABC）作為“虛擬基類(lèi)”添加到任何類(lèi)或類(lèi)型（包括內置類(lèi)型），包括其他 ABC 之中。

class.__instancecheck__(self, instance)?

如果 instance 應被視為 class 的一個(gè)（直接或間接）實(shí)例則返回真值。如果定義了此方法，則會(huì )被調用以實(shí)現 isinstance(instance, class)。

class.__subclasscheck__(self, subclass)?

Return true 如果 subclass 應被視為 class 的一個(gè)（直接或間接）子類(lèi)則返回真值。如果定義了此方法，則會(huì )被調用以實(shí)現 issubclass(subclass, class)。

請注意這些方法的查找是基于類(lèi)的類(lèi)型（元類(lèi)）。它們不能作為類(lèi)方法在實(shí)際的類(lèi)中被定義。這與基于實(shí)例被調用的特殊方法的查找是一致的，只有在此情況下實(shí)例本身被當作是類(lèi)。

3.3.5. 模擬泛型類(lèi)型?

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.

A class can generally only be parameterized if it defines the special class method __class_getitem__().

classmethod object.__class_getitem__(cls, key)?

按照 key 參數指定的類(lèi)型返回一個(gè)表示泛型類(lèi)的專(zhuān)門(mén)化對象。

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.

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"
        )

>>> # 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'>

>>> 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'>

3.3.6. 模擬可調用對象?

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

此方法會(huì )在實(shí)例作為一個(gè)函數被“調用”時(shí)被調用；如果定義了此方法，則 x(arg1, arg2, ...) 就大致可以被改寫(xiě)為 type(x).__call__(x, arg1, ...)。

3.3.7. 模擬容器類(lèi)型?

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)?

調用此方法以實(shí)現內置函數 len()。應該返回對象的長(cháng)度，以一個(gè) >= 0 的整數表示。此外，如果一個(gè)對象未定義 __bool__() 方法而其 __len__() 方法返回值為零，則在布爾運算中會(huì )被視為假值。

CPython implementation detail: 在 CPython 中，要求長(cháng)度最大為 sys.maxsize。如果長(cháng)度大于 sys.maxsize 則某些特性 (例如 len()) 可能會(huì )引發(fā) OverflowError。要通過(guò)真值檢測來(lái)防止引發(fā) OverflowError，對象必須定義 __bool__() 方法。

object.__length_hint__(self)?

調用此方法以實(shí)現 operator.length_hint()。 應該返回對象長(cháng)度的估計值（可能大于或小于實(shí)際長(cháng)度）。 此長(cháng)度應為一個(gè) >= 0 的整數。 返回值也可以為 NotImplemented，這會(huì )被視作與 __length_hint__ 方法完全不存在時(shí)一樣處理。 此方法純粹是為了優(yōu)化性能，并不要求正確無(wú)誤。

3.4 新版功能.

a[1:2] = b

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

object.__getitem__(self, key)?

Called to implement evaluation of self[key]. For sequence types, the accepted keys should be integers and slice objects. Note that the special interpretation of negative indexes (if the class wishes to emulate a sequence type) is up to the __getitem__() method. If key is of an inappropriate type, TypeError may be raised; if of 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 循環(huán)在有不合法索引時(shí)會(huì )期待捕獲 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)?

調用此方法以實(shí)現向 self[key] 賦值。注意事項與 __getitem__() 相同。為對象實(shí)現此方法應該僅限于需要映射允許基于鍵修改值或添加鍵，或是序列允許元素被替換時(shí)。不正確的 key 值所引發(fā)的異常應與 __getitem__() 方法的情況相同。

object.__delitem__(self, key)?

調用此方法以實(shí)現 self[key] 的刪除。注意事項與 __getitem__() 相同。為對象實(shí)現此方法應該權限于需要映射允許移除鍵，或是序列允許移除元素時(shí)。不正確的 key 值所引發(fā)的異常應與 __getitem__() 方法的情況相同。

object.__missing__(self, key)?

此方法由 dict.__getitem__() 在找不到字典中的鍵時(shí)調用以實(shí)現 dict 子類(lèi)的 self[key]。

object.__iter__(self)?

This method is called when an iterator is required for a container. This method should return a new iterator object that can iterate over all the objects in the container. For mappings, it should iterate over the keys of the container.

object.__reversed__(self)?

此方法（如果存在）會(huì )被 reversed() 內置函數調用以實(shí)現逆向迭代。它應當返回一個(gè)新的以逆序逐個(gè)迭代容器內所有對象的迭代器對象。

如果未提供 __reversed__() 方法，則 reversed() 內置函數將回退到使用序列協(xié)議 (__len__() 和 __getitem__())。支持序列協(xié)議的對象應當僅在能夠提供比 reversed() 所提供的實(shí)現更高效的實(shí)現時(shí)才提供 __reversed__() 方法。

成員檢測運算符 (in 和 not in) 通常以對容器進(jìn)行逐個(gè)迭代的方式來(lái)實(shí)現。 不過(guò)，容器對象可以提供以下特殊方法并采用更有效率的實(shí)現，這樣也不要求對象必須為可迭代對象。

object.__contains__(self, item)?

調用此方法以實(shí)現成員檢測運算符。如果 item 是 self 的成員則應返回真，否則返回假。對于映射類(lèi)型，此檢測應基于映射的鍵而不是值或者鍵值對。

對于未定義 __contains__() 的對象，成員檢測將首先嘗試通過(guò) __iter__() 進(jìn)行迭代，然后再使用 __getitem__() 的舊式序列迭代協(xié)議，參看 語(yǔ)言參考中的相應部分。

3.3.8. 模擬數字類(lèi)型?

定義以下方法即可模擬數字類(lèi)型。特定種類(lèi)的數字不支持的運算（例如非整數不能進(jìn)行位運算）所對應的方法應當保持未定義狀態(tài)。

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)?

These methods are called to implement the binary arithmetic operations (+, -, *, @, /, //, %, divmod(), pow(), **, <<, >>, &, ^, |). For instance, to evaluate the expression x + y, where x is an instance of a class that has an __add__() method, type(x).__add__(x, y) is called. The __divmod__() method should be the equivalent to using __floordiv__() and __mod__(); it should not be related to __truediv__(). Note that __pow__() should be defined to accept an optional third argument if the ternary version of the built-in pow() function is to be supported.

如果這些方法中的某一個(gè)不支持與所提供參數進(jìn)行運算，它應該返回 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 expression x - y, where y is an instance of a class that has an __rsub__() method, type(y).__rsub__(y, x) is called if type(x).__sub__(x, y) returns NotImplemented.

請注意三元版的 pow() 并不會(huì )嘗試調用 __rpow__() (因為強制轉換規則會(huì )太過(guò)復雜)。

備注

如果右操作數類(lèi)型為左操作數類(lèi)型的一個(gè)子類(lèi)，且該子類(lèi)提供了指定運算的反射方法，則此方法將先于左操作數的非反射方法被調用。 此行為可允許子類(lèi)重載其祖先類(lèi)的運算符。

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)?

調用這些方法來(lái)實(shí)現擴展算術(shù)賦值 (+=, -=, *=, @=, /=, //=, %=, **=, <<=, >>=, &=, ^=, |=)。這些方法應該嘗試進(jìn)行自身操作 (修改 self) 并返回結果 (結果應該但并非必須為 self)。如果某個(gè)方法未被定義，相應的擴展算術(shù)賦值將回退到普通方法。例如，如果 x 是具有 __iadd__() 方法的類(lèi)的一個(gè)實(shí)例，則 x += y 就等價(jià)于 x = x.__iadd__(y)。否則就如 x + y 的求值一樣選擇 x.__add__(y) 和 y.__radd__(x)。在某些情況下，擴展賦值可導致未預期的錯誤 (參見(jiàn) 為什么 a_tuple[i] += ['item'] 會(huì )引發(fā)異常？)，但此行為實(shí)際上是數據模型的一個(gè)組成部分。

object.__neg__(self)?

object.__pos__(self)?

object.__abs__(self)?

object.__invert__(self)?

調用此方法以實(shí)現一元算術(shù)運算 (-, +, abs() 和 ~)。

object.__complex__(self)?

object.__int__(self)?

object.__float__(self)?

調用這些方法以實(shí)現內置函數 complex(), int() 和 float()。應當返回一個(gè)相應類(lèi)型的值。

object.__index__(self)?

調用此方法以實(shí)現 operator.index() 以及 Python 需要無(wú)損地將數字對象轉換為整數對象的場(chǎng)合（例如切片或是內置的 bin(), hex() 和 oct() 函數)。 存在此方法表明數字對象屬于整數類(lèi)型。 必須返回一個(gè)整數。

如果未定義 __int__(), __float__() 和 __complex__() 則相應的內置函數 int(), float() 和 complex() 將回退為 __index__()。

object.__round__(self[, ndigits])?

object.__trunc__(self)?

object.__floor__(self)?

object.__ceil__(self)?

調用這些方法以實(shí)現內置函數 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 版更改: The delegation of int() to __trunc__() is deprecated.

3.3.9. with 語(yǔ)句上下文管理器?

上下文管理器 是一個(gè)對象，它定義了在執行 with 語(yǔ)句時(shí)要建立的運行時(shí)上下文。 上下文管理器處理進(jìn)入和退出所需運行時(shí)上下文以執行代碼塊。 通常使用 with 語(yǔ)句（在 with 語(yǔ)句 中描述），但是也可以通過(guò)直接調用它們的方法來(lái)使用。

上下文管理器的典型用法包括保存和恢復各種全局狀態(tài)，鎖定和解鎖資源，關(guān)閉打開(kāi)的文件等等。

要了解上下文管理器的更多信息，請參閱 上下文管理器類(lèi)型。

object.__enter__(self)?

進(jìn)入與此對象相關(guān)的運行時(shí)上下文。 with 語(yǔ)句將會(huì )綁定這個(gè)方法的返回值到 as 子句中指定的目標，如果有的話(huà)。

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

退出關(guān)聯(lián)到此對象的運行時(shí)上下文。 各個(gè)參數描述了導致上下文退出的異常。 如果上下文是無(wú)異常地退出的，三個(gè)參數都將為 None。

如果提供了異常，并且希望方法屏蔽此異常（即避免其被傳播），則應當返回真值。 否則的話(huà)，異常將在退出此方法時(shí)按正常流程處理。

請注意 __exit__() 方法不應該重新引發(fā)被傳入的異常，這是調用者的責任。

3.3.10. 定制類(lèi)模式匹配中的位置參數?

當在模式中使用類(lèi)名稱(chēng)時(shí)，默認不允許模式中出現位置參數，例如 case MyClass(x, y) 通常是無(wú)效的，除非 MyClass 提供了特別支持。 要能使用這樣的模式，類(lèi)必須定義一個(gè) __match_args__ 屬性。

object.__match_args__?

該類(lèi)變量可以被賦值為一個(gè)字符串元組。 當該類(lèi)被用于帶位置參數的類(lèi)模式時(shí)，每個(gè)位置參數都將被轉換為關(guān)鍵字參數，并使用 __match_args__ 中的對應值作為關(guān)鍵字。 缺失此屬性就等價(jià)于將其設為 ()。

舉例來(lái)說(shuō)，如果 MyClass.__match_args__ 為 ("left", "center", "right") 則意味著(zhù) case MyClass(x, y) 就等價(jià)于 case MyClass(left=x, center=y)。 請注意模式中參數的數量必須小于等于 __match_args__ 中元素的數量；如果前者大于后者，則嘗試模式匹配時(shí)將引發(fā) TypeError。

3.3.11. 特殊方法查找?

對于自定義類(lèi)來(lái)說(shuō)，特殊方法的隱式發(fā)起調用僅保證在其定義于對象類(lèi)型中時(shí)能正確地發(fā)揮作用，而不能定義在對象實(shí)例字典中。 該行為就是以下代碼會(huì )引發(fā)異常的原因。:

>>> 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()

The rationale behind this behaviour lies with a number of special methods such as __hash__() and __repr__() that are implemented by all objects, including type objects. If the implicit lookup of these methods used the conventional lookup process, they would fail when invoked on the type object itself:

>>> 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

以這種方式不正確地嘗試發(fā)起調用一個(gè)類(lèi)的未綁定方法有時(shí)被稱(chēng)為‘元類(lèi)混淆’，可以通過(guò)在查找特殊方法時(shí)繞過(guò)實(shí)例的方式來(lái)避免:

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

In addition to bypassing any instance attributes in the interest of correctness, implicit special method lookup generally also bypasses the __getattribute__() method even of the object's metaclass:

>>> 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

Bypassing the __getattribute__() machinery in this fashion provides significant scope for speed optimisations within the interpreter, at the cost of some flexibility in the handling of special methods (the special method must be set on the class object itself in order to be consistently invoked by the interpreter).

3.4.1. 可等待對象?

An awaitable object generally implements an __await__() method. Coroutine objects returned from async def functions are awaitable.

object.__await__(self)?

必須返回一個(gè) iterator。 應當被用來(lái)實(shí)現 awaitable 對象。 例如，asyncio.Future 實(shí)現了此方法以與 await 表達式相兼容。

3.4.2. 協(xié)程對象?

Coroutine objects are awaitable objects. A coroutine's execution can be controlled by calling __await__() and iterating over the result. When the coroutine has finished executing and returns, the iterator raises StopIteration, and the exception's value attribute holds the return value. If the coroutine raises an exception, it is propagated by the iterator. Coroutines should not directly raise unhandled StopIteration exceptions.

協(xié)程也具有下面列出的方法，它們類(lèi)似于生成器的對應方法 (參見(jiàn) 生成器-迭代器的方法)。 但是，與生成器不同，協(xié)程并不直接支持迭代。

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 not None, this method delegates to the send() 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]])

Raises the specified exception in the coroutine. This method delegates to the throw() method of the iterator that caused the coroutine to suspend, if it has such a method. Otherwise, the exception is raised at the suspension point. The result (return value, StopIteration, or other exception) is the same as when iterating over the __await__() return value, described above. If the exception is not caught in the coroutine, it propagates back to the caller.

coroutine.close()?

此方法會(huì )使得協(xié)程清理自身并退出。 如果協(xié)程被掛起，此方法會(huì )先委托給導致協(xié)程掛起的迭代器的 close() 方法，如果存在該方法。 然后它會(huì )在掛起點(diǎn)引發(fā) GeneratorExit，使得協(xié)程立即清理自身。 最后，協(xié)程會(huì )被標記為已結束執行，即使它根本未被啟動(dòng)。

當協(xié)程對象將要被銷(xiāo)毀時(shí)，會(huì )使用以上處理過(guò)程來(lái)自動(dòng)關(guān)閉。

3.4.3. 異步迭代器?

異步迭代器 可以在其 __anext__ 方法中調用異步代碼。

異步迭代器可在 async for 語(yǔ)句中使用。

object.__aiter__(self)?

必須返回一個(gè) 異步迭代器 對象。

object.__anext__(self)?

必須返回一個(gè) 可迭代對象 輸出迭代器的下一結果值。 當迭代結束時(shí)應該引發(fā) StopAsyncIteration 錯誤。

異步可迭代對象的一個(gè)示例:

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.4.4. 異步上下文管理器?

異步上下文管理器 是 上下文管理器 的一種，它能夠在其 __aenter__ 和 __aexit__ 方法中暫停執行。

異步上下文管理器可在 async with 語(yǔ)句中使用。

object.__aenter__(self)?

在語(yǔ)義上類(lèi)似于 __enter__()，僅有的區別是它必須返回一個(gè) 可等待對象。

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

在語(yǔ)義上類(lèi)似于 __exit__()，僅有的區別是它必須返回一個(gè) 可等待對象。

異步上下文管理器類(lèi)的一個(gè)示例:

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

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

備注

1

在某些情況下 有可能 基于可控的條件改變一個(gè)對象的類(lèi)型。 但這通常不是個(gè)好主意，因為如果處理不當會(huì )導致一些非常怪異的行為。

2

The __hash__(), __iter__(), __reversed__(), and __contains__() methods have special handling for this; others will still raise a TypeError, but may do so by relying on the behavior that None is not callable.

3

這里的“不支持”是指該類(lèi)無(wú)此方法，或方法返回 NotImplemented。 如果你想強制回退到右操作數的反射方法，請不要設置方法為 None — 那會(huì )造成顯式地 阻塞 此種回退的相反效果。

4

For operands of the same type, it is assumed that if the non-reflected method -- such as __add__() -- fails then the overall operation is not supported, which is why the reflected method is not called.