weakref --- 弱參照¶

原始碼：Lib/weakref.py

weakref 模組允許 Python 程式設計師建立對物件的弱參照。

在以下文章中，術語參照目標 (referent) 表示被弱參照所參考的物件。

對物件的弱參照不足以使物件保持存在：當對參照目標的唯一剩下的參照是弱參照時，garbage collection 可以自由地銷毀參照目標並將其記憶體重新用於其他用途。然而，在物件被確實銷毀之前，即使沒有對該物件的強參照 (strong reference)，弱參照也可能會回傳該物件。

弱參照的主要用途是實作保存大型物件的快取或對映，其不希望大型物件僅僅因為它出現在快取或對映中而保持存在。

例如，如果你有許多大型的二進位影像物件，你可能會想要為每個物件關聯 (associate) 一個名稱。如果你使用 Python 字典將名稱對映到影像，或將影像對映到名稱，則影像物件將保持存活，僅因為它們在字典中作為值 (value) 或鍵 (key) 出現。weakref 模組提供的WeakKeyDictionary 和WeakValueDictionary 類別是另一種選擇，它們使用弱參照來建構對映，這些對映不會僅因為物件出現在對映物件中而使物件保持存活。例如，如果一個影像物件是WeakValueDictionary 中的一個值，那麼當對該影像物件最後的參照是弱對映 (weak mapping) 所持有的弱參照時，垃圾回收 (garbage collection) 可以回收該物件，且其對應的條目在弱對映中會被完全地刪除。

WeakKeyDictionary 和WeakValueDictionary 在其實作中使用弱參照，在弱參照上設定回呼函式，此弱參照在垃圾回收取回鍵或值時通知弱字典。WeakSet 實作了set 介面，但保留對其元素的弱參照，就像WeakKeyDictionary 一樣。

finalize 提供了一種直接的方法來註冊在物件被垃圾回收時呼叫的清理函式。這比在原始弱參照上設定回呼函式更容易使用，因為模組在物件被回收前會自動確保最終化器 (finalizer) 保持存活。

大多數程式應該發現使用這些弱容器種類之一或finalize 就足夠了—通常不需要直接建立自己的弱參照。低層級的機制由weakref 模組公開，以利於進階用途。

並非所有物件都可以被弱參照。支援弱參照的物件包括類別實例、用 Python （但不是C）編寫的函式、實例方法、集合、凍結集合 (frozenset)、一些檔案物件、產生器、類型物件、socket、陣列、雙向佇列、正規表示式模式物件和程式碼物件。

一些內建型別，例如list 和dict 不直接支援弱參照，但可以透過子類別化來支援：

classDict(dict):passobj=Dict(red=1,green=2,blue=3)# 這個物件是可被弱參照的

擴充型別 (extension type) 可以輕易地支援弱參照；請參閱Weak Reference Support。

當為給定的型別定義__slots__ 時，弱參照支援將被停用，除非'__weakref__' 字串也存在於__slots__ 宣告的字串序列中。詳情請參閱__slots__ 文件。

classweakref.ref(object[,callback])¶

回傳對object 的弱參照。如果參照目標仍存活，則可以透過呼叫參照物件來取回原始物件；如果參照目標已不存活，呼叫參照物件將導致None 被回傳。如果callback 被提供而非None，且回傳的弱參照物件仍存活，那麼當物件即將被最終化 (finalize) 時，回呼將被呼叫；弱參照物件將作為唯一的參數傳遞給回呼；參照物件將不再可用。

為同一個物件建構多個弱參照是可行的。為每個弱參照註冊的回呼將按照最新到最舊註冊的回呼順序來被呼叫。

回呼引發的例外將在標準錯誤輸出中被註明，但無法被傳播；它們的處理方式與物件的__del__() 方法引發的例外完全相同。

如果object 是可雜湊的，那麼弱參照就是可雜湊的。即使在object 被刪除後，它們仍將保留其雜湊值。如果僅在object 刪除後才第一次呼叫hash()，則該呼叫將引發TypeError。

弱參照支援相等性的測試，但不支援排序。如果參照目標仍存活，則兩個參照與其參照目標具有相同的相等關係（無論callback 如何）。如果任一參照目標已被刪除，則僅當參照物件是同一物件時，參照才相等。

這是一個可子類別化的型別，而不是一個工廠函式。

__callback__¶

此唯讀屬性回傳目前與弱參照關聯的回呼。如果沒有回呼或弱參照的參照目標已不存活，那麼該屬性的值為None。

在 3.4 版的變更:新增__callback__ 屬性。

weakref.proxy(object[,callback])¶

回傳一個使用弱參照的object 的代理 (proxy)。這支援在大多數情境中使用代理，而不需要對弱參照物件明確地取消參照。回傳的物件將具有ProxyType 或CallableProxyType 型別，具體取決於object 是否為可呼叫物件。無論參照目標如何，代理物件都不是hashable；這避免了與其基本可變物件本質相關的許多問題，並阻止它們作為字典的鍵被使用。callback 與ref() 函式的同名參數是相同的。

在參照目標被垃圾回收後存取代理物件的屬性會引發ReferenceError。

在 3.8 版的變更:提供對代理物件的運算子支援，以包括矩陣乘法運算子@ 和@=。

weakref.getweakrefcount(object)¶

回傳參照object 的弱參照和代理的數量。

weakref.getweakrefs(object)¶

回傳參照object 的所有弱參照和代理物件的一個串列。

classweakref.WeakKeyDictionary([dict])¶

弱參照鍵的對映類別。當不再有對鍵的強參照時，字典中的條目將被丟棄。這可用於將附加資料與應用程式其他部分擁有的物件相關聯，而無需向這些物件新增屬性。這對於覆蓋屬性存取的物件特別有用。

請注意，當將與現有鍵具有相同值的鍵（但識別性不相等）插入字典時，它會替換該值，但不會替換現有鍵。因此，當刪除對原始鍵的參照時，它也會刪除字典中的條目：

>>>classT(str):pass...>>>k1,k2=T(),T()>>>d=weakref.WeakKeyDictionary()>>>d[k1]=1# d = {k1: 1}>>>d[k2]=2# d = {k1: 2}>>>delk1# d = {}

一個變通的解法是在重新賦值 (reassignment) 之前刪除鍵：

>>>classT(str):pass...>>>k1,k2=T(),T()>>>d=weakref.WeakKeyDictionary()>>>d[k1]=1# d = {k1: 1}>>>deld[k1]>>>d[k2]=2# d = {k2: 2}>>>delk1# d = {k2: 2}

在 3.9 版的變更:新增對| 和|= 運算子的支持，如PEP 584 中所說明。

WeakKeyDictionary 物件有一個直接公開內部參照的附加方法。參照在被使用時不保證是 "存活的"，因此在使用之前需要檢查呼叫參照的結果。這可以用來防止建立會導致垃圾回收器保留鍵的時間超過其所需時間的參照。

WeakKeyDictionary.keyrefs()¶

回傳對鍵的弱參照的可疊代物件。

classweakref.WeakValueDictionary([dict])¶

弱參照值的對映類別。當不再存在對值的強參照時，字典中的條目將被丟棄。

在 3.9 版的變更:新增對| 和|= 運算子的支持，如PEP 584 中所說明。

WeakValueDictionary 物件有一個附加方法，它與WeakKeyDictionary.keyrefs() 方法有相同的問題。

WeakValueDictionary.valuerefs()¶

回傳對值的弱參照的可疊代物件。

classweakref.WeakSet([elements])¶

保留對其元素的弱參照的集合類別。當不再存在對某個元素的強參照時，該元素將被丟棄。

classweakref.WeakMethod(method[,callback])¶

一個特製的ref 子類別，其模擬對繫結方法 (bound method) （即在類別上定義並在實例上查找的方法）的弱參照。由於繫結方法是短暫存在的，因此標準弱參照無法保留它。WeakMethod 有特殊的程式碼來重新建立繫結方法，直到物件或原始函式死亡：

>>>classC:...defmethod(self):...print("method called!")...>>>c=C()>>>r=weakref.ref(c.method)>>>r()>>>r=weakref.WeakMethod(c.method)>>>r()<bound method C.method of <__main__.C object at 0x7fc859830220>>>>>r()()method called!>>>delc>>>gc.collect()0>>>r()>>>

callback 與ref() 函式的同名參數是相同的。

在 3.4 版被加入.

classweakref.finalize(obj,func,/,*args,**kwargs)¶

回傳可呼叫的最終化器物件，此物件在obj 被垃圾回收時會被呼叫。與一般的弱參照不同，最終化器將始終存在，直到參照物件被回收為止，從而大大簡化了生命週期管理。

最終化器在被呼叫（明確呼叫或在垃圾回收時）之前被視為存活，之後它就會死亡。呼叫存活的最終化器會回傳func(*arg,**kwargs) 的計算結果，而呼叫死亡的最終化器會回傳None。

垃圾回收期間最終化器回呼引發的例外會在標準錯誤輸出中顯示，但無法傳播。它們的處理方式與從物件的__del__() 方法或弱參照的回呼引發的例外相同。

當程式結束時，除非該最終化器的atexit 屬性已被設定為 false，否則每個存活的最終化器會被呼叫。它們以與建立相反的順序被呼叫。

當模組的 globals 可能被None 取代時，最終化器永遠不會在interpreter shutdown 的後期叫用（invoke）其回呼。

__call__()¶

如果self 仍存活，則將其標記為死亡並回傳呼叫func(*args,**kwargs) 的結果。如果self 已死亡，則回傳None。

detach()¶

如果self 仍存活，則將其標記為死亡並回傳元組(obj,func,args,kwargs)。如果self 已死亡，則回傳None。

peek()¶

如果self 仍存活，則回傳元組(obj,func,args,kwargs)。如果self 已死亡，則回傳None。

alive¶

如果最終化器仍存活，則屬性為 true，否則為 false。

atexit¶

一個可寫的布林屬性，預設為 true。當程式結束時，它會呼叫atexit 為 true 的所有剩餘且仍存活的最終化器。它們以與建立相反的順序被呼叫。

備註

確保func、args 和kwargs 不直接或間接擁有對obj 的任何參照非常重要，否則obj 將永遠不會被垃圾回收。尤其func 不應該是obj 的繫結方法。

在 3.4 版被加入.

weakref.ReferenceType¶

弱參照物件的型別物件。

weakref.ProxyType¶

非可呼叫物件的代理的型別物件。

weakref.CallableProxyType¶

可呼叫物件的代理的型別物件。

weakref.ProxyTypes¶

包含代理的所有型別物件的序列。這可以讓測試物件是否為代理變得更簡單，而無需依賴命名兩種代理型別。

>>>importweakref>>>classObject:...pass...>>>o=Object()>>>r=weakref.ref(o)>>>o2=r()>>>oiso2True

>>>delo,o2>>>print(r())None

# r is a weak reference objecto=r()ifoisNone:# referent has been garbage collectedprint("Object has been deallocated; can't frobnicate.")else:print("Object is still live!")o.do_something_useful()

importweakrefclassExtendedRef(weakref.ref):def__init__(self,ob,callback=None,/,**annotations):super().__init__(ob,callback)self.__counter=0fork,vinannotations.items():setattr(self,k,v)def__call__(self):"""Return a pair containing the referent and the number of        times the reference has been called.        """ob=super().__call__()ifobisnotNone:self.__counter+=1ob=(ob,self.__counter)returnob

importweakref_id2obj_dict=weakref.WeakValueDictionary()defremember(obj):oid=id(obj)_id2obj_dict[oid]=objreturnoiddefid2obj(oid):return_id2obj_dict[oid]

>>>importweakref>>>classObject:...pass...>>>kenny=Object()>>>weakref.finalize(kenny,print,"You killed Kenny!")<finalize object at ...; for 'Object' at ...>>>>delkennyYou killed Kenny!

>>>defcallback(x,y,z):...print("CALLBACK")...returnx+y+z...>>>obj=Object()>>>f=weakref.finalize(obj,callback,1,2,z=3)>>>assertf.alive>>>assertf()==6CALLBACK>>>assertnotf.alive>>>f()# callback not called because finalizer dead>>>delobj# callback not called because finalizer dead

>>>obj=Object()>>>f=weakref.finalize(obj,callback,1,2,z=3)>>>f.detach()(<...Object object ...>, <function callback ...>, (1, 2), {'z': 3})>>>newobj,func,args,kwargs=_>>>assertnotf.alive>>>assertnewobjisobj>>>assertfunc(*args,**kwargs)==6CALLBACK

>>>obj=Object()>>>weakref.finalize(obj,print,"obj dead or exiting")<finalize object at ...; for 'Object' at ...>>>>exit()obj dead or exiting

classTempDir:def__init__(self):self.name=tempfile.mkdtemp()defremove(self):ifself.nameisnotNone:shutil.rmtree(self.name)self.name=None@propertydefremoved(self):returnself.nameisNonedef__del__(self):self.remove()

classTempDir:def__init__(self):self.name=tempfile.mkdtemp()self._finalizer=weakref.finalize(self,shutil.rmtree,self.name)defremove(self):self._finalizer()@propertydefremoved(self):returnnotself._finalizer.alive

importweakref,sysdefunloading_module():# implicit reference to the module globals from the function bodyweakref.finalize(sys.modules[__name__],unloading_module)