Python weakref.finalize 怎样为对象注册清理回调

如果一个 Python 对象持有临时目录、文件句柄或外部连接，最容易踩到的坑不是“不会清理”，而是清理动作和对象生命周期没有对齐。weakref.finalize 可以为支持弱引用的对象注册一次性清理回调：对象被回收时执行，业务代码也可以提前调用同一个 finalizer。这样既保留了兜底路径，也能把主动释放写进显式方法。

官方文档：https://docs.python.org/3/library/weakref.html

weakref.finalize(obj, func, *args, **kwargs) 返回一个可调用的 finalizer。回调函数和参数不能反向持有 obj，否则对象一直无法回收；需要主动释放时直接调用 finalizer，重复调用不会再次执行。

finalize 解决的是哪一段生命周期

普通的 weakref.ref 也可以登记回调，但调用方需要自己保证弱引用对象仍然存活。weakref.finalize 把这层管理收起来：它返回的 finalizer 会一直存活到目标对象被回收，回调最多执行一次。对临时资源来说，代码关注点就从“如何保留回调引用”变成了“回调需要哪些独立参数”。

它仍然不是确定时刻的资源管理器。只要对象还有强引用，回调就不会因为创建了 finalizer 而立刻执行；需要严格的进入和退出边界时，with 或 try/finally 仍然优先。

先用独立函数注册清理回调

注册时把真正需要清理的资源句柄作为参数传给回调，而不是把整个对象塞进去。下面的例子用临时目录名模拟外部资源：finalize 保存的是清理函数和目录字符串，清理函数不会读取 self。

import shutil
import tempfile
import weakref


def remove_directory(path):
    # 回调只接收清理所需的独立值，不通过闭包捕获 Resource 实例。
    shutil.rmtree(path, ignore_errors=True)


class Resource:
    def __init__(self):
        # 资源对象保存目录名，finalizer 只保存同一个字符串值。
        self.path = tempfile.mkdtemp(prefix="demo-resource-")
        self._finalizer = weakref.finalize(self, remove_directory, self.path)

    def close(self):
        # 主动关闭和垃圾回收共用同一个一次性清理入口。
        self._finalizer()

    @property
    def closed(self):
        # finalizer 执行后 alive 会变为 False。
        return not self._finalizer.alive

这里的关键不是临时目录，而是引用方向：Resource 指向 finalizer，finalizer 指向独立函数和字符串；清理函数没有再指回 Resource。官方文档特别提醒，func、args 和 kwargs 不能直接或间接拥有目标对象的引用。

主动调用 finalizer，保证 close 可以重复使用

finalizer 本身是可调用对象。它活着时会标记自己为 dead 并执行回调；再次调用时返回 None，不会把清理逻辑执行第二遍。因此可以把它放到 close() 中，让调用方有明确的主动释放入口。

resource = Resource()

# 业务完成后主动释放，避免一直等待垃圾回收。
resource.close()
resource.close()  # 第二次调用不会重复删除同一目录。

# 这个状态只表达 finalizer 是否已执行，不代表所有业务字段都被重置。
print(resource.closed)

如果清理动作还需要更新对象的其他状态，就在 close() 中先调用 finalizer，再维护自己的状态字段；不要把状态更新藏在回调里，让回调同时承担资源释放和业务对象变更两种职责。

避免闭包和绑定方法把对象重新留住

下面这种写法看起来方便，却会形成反向引用：

import weakref


class BadResource:
    def __init__(self):
        # 绑定方法隐含持有 self，finalizer 又被 self 持有，形成保活链。
        self._finalizer = weakref.finalize(self, self._cleanup)

    def _cleanup(self):
        # 这个方法不应作为自己的 finalizer 回调。
        pass

同样需要警惕在 lambda 或嵌套函数中直接引用 self。安全做法是把清理所需的句柄、路径或不可变配置提前取出，交给模块级函数或不持有目标对象的可调用对象。能用 with 明确包住资源时，也不要为了“自动兜底”把所有清理都改成 finalizer。

detach、atexit 和异常行为要分开看

如果资源已经由其他路径接管，可以用 detach() 让 finalizer 失效。它会返回创建 finalizer 时保存的 (obj, func, args, kwargs)，调用方可以据此完成迁移；如果 finalizer 已经执行，detach() 返回 None。

resource = Resource()

# detach 会杀死仍然存活的 finalizer，避免后续再触发自动清理。
detached = resource._finalizer.detach()
if detached is not None:
    obj, func, args, kwargs = detached
    # 接管后由新的资源管理器决定是否调用这组清理参数。
    del obj, func, args, kwargs

# 默认情况下，解释器退出时仍存活的 finalizer 会被调用。
resource = Resource()
resource._finalizer.atexit = False  # 由进程级管理器负责退出清理。

退出阶段的回调有两个边界：默认 atexit 为真，仍存活的 finalizer 会在解释器退出时调用；把它设为 False 后则跳过这条退出路径。另外，回调在垃圾回收或退出时抛出的异常不能传播给原调用方，会按类似 __del__() 的方式写到标准错误，所以回调里应尽量保持短小、幂等，并自行处理可预期错误。

finalize、with 和 __del__ 怎么选

我的经验是先问“资源能不能被一个明确的代码块包住”。能包住就用上下文管理器；不能修改对象类型或需要额外兜底时，再使用 finalize。无论采用哪条路径，都要先检查回调是否反向持有对象，再决定是否保留退出时自动调用。

所有 Python 对象都能传给 weakref.finalize 吗？

不能。目标对象必须支持弱引用；一些内置类型不直接支持，定义 __slots__ 时还要显式加入 __weakref__。遇到不支持弱引用的类型，应改用显式的 with、包装对象或由资源提供方管理生命周期。

finalize 会在对象离开当前函数后马上执行吗？

不应把它当作确定时刻通知。只要还有强引用，目标对象就不会被回收；即使引用变少，最终回收时机也由实现和运行状态决定。需要立即释放时直接调用保存的 finalizer 或使用 close()。

为什么 finalizer 回调里不能直接用 self？

因为绑定方法、闭包或参数对象可能间接保存 self，形成对象到 finalizer、finalizer 再回到对象的保活链。把清理函数放在类外，并只传入路径、句柄等独立数据，才能让回收路径真正断开。

weakref.finalize 的价值是补上对象回收时的兜底清理，不是替代所有显式资源管理。让回调保持独立，把主动释放放进 close()，再按需设置 detach() 和 atexit，这套边界足以覆盖大多数需要“回收时清理”的 Python 小型资源对象。