Restauração de ContextVar: use reset com o token em vez de adivinhar o valor anterior

O que é

A documentação do módulo contextvars do Python informa que ContextVar.set devolve um token, que permite restaurar o valor anterior com reset. O token registra o estado anterior do contexto, incluindo a ausência de valor. Um token não pode ser reutilizado para vários resets. O Python 3.14 também permite usar tokens como gerenciadores de contexto. Python contextvars

Por que importa

Um agente pode encerrar uma sobrescrita temporária atribuindo None ou um valor padrão global. Isso pode descartar o valor de uma requisição externa em vez de restaurá-lo. Trate as sobrescritas como escopos aninhados, cada um responsável por devolver o estado exato que recebeu, em vez de inventar um único valor de limpeza universal.

Como aplicar

• Identifique a ContextVar e todos os caminhos que a definem. Diferencie o valor padrão configurado da variável de um valor explicitamente associado no contexto atual.
• Guarde o token devolvido por set e faça o reset desse token em um bloco finally ao redor do trabalho temporário. Use a sintaxe compatível com a versão mínima do Python do projeto.
• Proponha uma fixture aninhada: defina um valor externo, sobrescreva-o internamente e verifique que o valor externo volta depois. Repita o teste com uma exceção levantada dentro da sobrescrita.
• Adicione uma fixture em que a variável estava antes sem valor. Verifique o comportamento de consulta documentado após a restauração, em vez de esperar um valor nulo qualquer.
• Revise como tarefas e threads são criadas nas fronteiras de contexto. Documente a propagação pretendida separadamente da restauração dentro de um único escopo.

Armadilhas

Associações locais ao contexto não tornam um objeto mutável guardado na variável automaticamente independente nem thread-safe. Os tokens pertencem ao seu contexto e à sua variável; não os repasse como credenciais genéricas de reset. Evite exigir a forma de gerenciador de contexto do Python 3.14 em um projeto que suporta versões anteriores. As fixtures descritas são propostas, e nenhum resultado observado de isolamento ou de throughput é afirmado.