weakref
weakref 模块提供对对象的弱引用：弱引用不会增加对象的引用计数，当除弱引用外不再有强引用指向该对象时，垃圾回收器可以回收该对象并复用其内存。因此，弱引用常用于缓存（避免“仅因在缓存中”而长期保留大对象）、打破循环引用（弱引用不参与引用计数，可切断环），以及对象与附加数据的关联（对象被回收时条目自动清理）。
该模块的设计源于“引用计数 + 垃圾回收”下对生命周期控制的精细需求：普通字典/集合会强引用键或值，导致对象仅因出现在容器中就无法被回收；弱引用则允许容器“看见”对象而不“持有”对象。设计上，weakref.ref 是底层原语，适合需要手动解引用和判空的场景；weakref.proxy 则提供透明代理，访问方式像原对象，但对象被回收后访问会抛出 ReferenceError；日常开发更常用的是弱引用容器：WeakValueDictionary（值弱引用，适合键→大对象缓存）、WeakKeyDictionary（键弱引用，适合对象→附加数据）、WeakSet（元素弱引用）；若只需在对象被回收时执行清理，可用 weakref.finalize 注册回调，比在 ref 上设 callback 更简单。
weakref.ref(obj[, callback])
返回 obj 的弱引用。调用返回的引用对象可得到原对象；若对象已被回收则得到 None。可选参数 callback 在对象即将被回收时被调用（以弱引用为参数）。
import weakref
class Node:
pass
obj = Node()
r = weakref.ref(obj)
print(r() is obj) # True
del obj
print(r()) # None
引用计数：CPython 用引用计数管理对象生命周期，强引用会增加计数，对象计数为 0 时被回收。弱引用不计入该计数，因此不会阻止对象被回收。
使用 callback 在回收时执行清理
带回调的用法：对象被回收时执行清理逻辑。
import weakref
def on_finalize(wr):
print("对象已被回收")
obj = object()
r = weakref.ref(obj, on_finalize)
del obj # 触发 callback，输出: 对象已被回收
weakref.proxy(obj[, callback])
返回对象的代理，可像原对象一样访问属性或调用方法，无需显式调用 ref() 解引用。对象被回收后，再访问代理会抛出 ReferenceError。若 obj 可调用，返回 CallableProxyType，否则为 ProxyType。代理不可哈希，不能作为字典键。
import weakref
class Data:
def __init__(self, x):
self.x = x
def double(self):
return self.x * 2
obj = Data(21)
p = weakref.proxy(obj)
print(p.x, p.double()) # 21 42
del obj
# 之后访问 p 会抛出 ReferenceError（此处不执行以免影响文档构建）
# print(p.x)
WeakValueDictionary
值持弱引用的字典：当值的强引用全部消失时，对应条目会被自动移除，适合「键 → 大对象」的缓存，避免缓存单独持有对象导致无法回收。
import weakref
# 值弱引用：大对象仅因在缓存中而不会被长期保留
cache = weakref.WeakValueDictionary()
cache["a"] = bytearray(10**6)
print(len(cache)) # 1
del cache["a"] # 或没有其它对 bytearray 的引用后，条目自动消失
缓存：用 WeakValueDictionary 做缓存时，条目会随值的回收而消失，缓存不会无限增长，适合“键稳定、值可被别处释放”的场景。
WeakKeyDictionary
键持弱引用的字典：当键被回收时，对应条目被移除，适合「对象 → 附加数据」的映射，且不想在对象上增加属性时使用。
import weakref
class Widget:
pass
# 对象 -> 附加数据，对象回收后条目自动删除
extra = weakref.WeakKeyDictionary()
w = Widget()
extra[w] = {"theme": "dark"}
print(extra[w]["theme"]) # dark
del w
# 键 w 被回收后，该条目会从 extra 中自动移除
print(len(extra)) # 0
对象与附加数据：当键是“别人拥有的对象”（如第三方库实例）时，用 WeakKeyDictionary 可在不修改对象的前提下关联数据，对象销毁时数据一并清理。
WeakSet
元素以弱引用保存的集合；当元素没有其它强引用时会被自动从集合中移除。
import weakref
class Event:
pass
s = weakref.WeakSet()
e = Event()
s.add(e)
print(len(s)) # 1
del e
# 下次 GC 后 len(s) 可为 0（依赖解释器回收时机）
import gc; gc.collect()
print(len(s)) # 0
weakref.finalize(obj, func, *args, **kwargs)
在对象被垃圾回收时调用 func(*args, **kwargs)，无需保存返回的 finalizer 对象即可完成注册，比在 ref 上设置 callback 更省心。finalizer 会存活到被调用（或程序退出），且最多调用一次。
import weakref
class Resource:
pass
def cleanup(name):
print(f"清理资源: {name}")
obj = Resource()
weakref.finalize(obj, cleanup, "my-resource")
del obj # 输出: 清理资源: my-resource
循环引用：若 A 引用 B、B 又引用 A，仅靠引用计数无法回收。弱引用不增加计数，将其中一环改为弱引用即可打破环，让 GC 正常回收。
小结与选用
| 需求 | 选用 |
|---|---|
| 手动解引用、判空、回收时回调 | weakref.ref(obj[, callback]) |
| 像原对象一样访问，不关心回收后报错 | weakref.proxy(obj[, callback]) |
| 键→大对象缓存，值可随别处释放而消失 | WeakValueDictionary |
| 对象→附加数据，对象回收时条目消失 | WeakKeyDictionary |
| 元素弱引用的集合 | WeakSet |
| 对象回收 时执行清理，且不想维护 ref/proxy | weakref.finalize(obj, func, *args, **kwargs) |
缓存：用 WeakValueDictionary 或 WeakKeyDictionary 做缓存时，条目会随键/值回收而消失，避免缓存无限增长。循环引用：弱引用不参与引用计数，可用来打断循环引用。proxy：weakref.proxy(obj) 返回对象的代理，可像原对象一样访问属性/方法，对象被回收后访问代理会抛出 ReferenceError；多数场景用 ref 或弱引用容器即可。