weakref em Python: referências fracas e cache

Uma referência comum mantém o objeto vivo. weakref permite observá-lo sem impedir a coleta de memória quando não restam referências fortes. Isso ajuda em caches, registries e associações auxiliares.

from weakref import WeakValueDictionary

class Image:
    def __init__(self, path: str) -> None:
        self.path = path

cache: WeakValueDictionary[str, Image] = WeakValueDictionary()
image = Image("cover.png")
cache[image.path] = image
assert cache["cover.png"] is image

Como usar com segurança

Nem todo tipo aceita referência fraca. O desaparecimento de uma entrada pode ocorrer entre duas operações, portanto obtenha o valor uma vez e teste o resultado. Não use weakref como substituto de uma política explícita de cache com limite e expiração.

Para aprofundar a base, consulte guia de collections em Python e guia de type hints.

A documentação oficial do Python, consultada em 22 de julho de 2026, descreve a API, os casos-limite e a compatibilidade entre versões.