Nem todo fluxo precisa abrir um arquivo, iniciar uma transação ou adquirir um lock. Ainda assim, muitas funções ficam mais simples quando podem executar sempre dentro de um with. O contextlib.nullcontext() resolve exatamente esse problema: ele cria um gerenciador de contexto que não executa nenhuma ação especial na entrada ou na saída e apenas devolve o valor informado.
Esse recurso é útil em APIs que aceitam tanto um objeto já aberto quanto uma origem que precisa ser aberta, em testes que alternam entre contexto real e contexto neutro, em código síncrono e assíncrono e em funções que habilitam transações, tracing ou locks apenas quando uma opção está ativa.
O que é nullcontext
nullcontext é um gerenciador de contexto neutro. Ao entrar no bloco, ele retorna o valor passado em enter_result. Ao sair, não suprime exceções e não executa limpeza adicional.
from contextlib import nullcontext
with nullcontext("pronto") as valor:
print(valor)
O exemplo imprime pronto. A principal vantagem não está em usar o recurso isoladamente, mas em combiná-lo com contextos reais para eliminar ramificações duplicadas.
Contexto opcional sem duplicar código
from contextlib import nullcontext
from pathlib import Path
def ler_fonte(origem):
contexto = open(origem, encoding="utf-8") if isinstance(origem, Path) else nullcontext(origem)
with contexto as arquivo:
return arquivo.read()
Quando origem é um caminho, o arquivo é aberto e fechado. Quando é um objeto de arquivo já aberto, nullcontext apenas o entrega ao bloco. A lógica de leitura existe uma única vez.
Ownership e responsabilidade de fechamento
O padrão anterior deixa uma regra importante explícita: quem cria o recurso deve fechá-lo. Se a função recebe um arquivo já aberto, normalmente não deve fechá-lo porque o chamador continua sendo o proprietário. nullcontext ajuda a representar essa diferença sem criar dois caminhos de processamento.
Documente esse contrato. Uma API ambígua pode fechar recursos emprestados ou deixar recursos próprios abertos. Use nomes como arquivo_ou_caminho, exemplos claros e testes para cada forma aceita.
Lock opcional
from contextlib import nullcontext
from threading import Lock
lock = Lock()
def atualizar(cache, chave, valor, seguro=True):
contexto = lock if seguro else nullcontext()
with contexto:
cache[chave] = valor
O corpo da operação é idêntico nos dois modos. Esse padrão é útil em componentes que podem rodar em ambiente single-thread ou multi-thread. Porém, não use uma opção para desativar sincronização quando a segurança dos dados depender dela.
Transações opcionais
def salvar(registros, conexao, usar_transacao=True):
contexto = conexao.begin() if usar_transacao else nullcontext()
with contexto:
for registro in registros:
conexao.execute(registro)
A interface do contexto real depende da biblioteca. Algumas conexões já implementam __enter__ e __exit__; outras fornecem um método como begin(). Confirme se o bloco realiza commit, rollback e fechamento conforme esperado.
Valor de entrada com enter_result
from contextlib import nullcontext
cliente_existente = criar_cliente()
with nullcontext(cliente_existente) as cliente:
cliente.enviar()
O parâmetro enter_result permite que o contexto neutro tenha a mesma forma do contexto real. Isso facilita funções que esperam receber o recurso pelo as.
Uso assíncrono
Versões modernas do Python permitem usar nullcontext também com async with. Isso é útil quando uma coroutine pode receber uma sessão assíncrona existente ou criar uma nova.
from contextlib import nullcontext
async def buscar(url, sessao=None):
contexto = criar_sessao() if sessao is None else nullcontext(sessao)
async with contexto as cliente:
return await cliente.get(url)
O contexto real precisa implementar o protocolo assíncrono. Verifique também se criar_sessao() devolve diretamente um async context manager ou uma coroutine que precisa ser aguardada antes.
Quando usar uma factory
Às vezes é melhor receber uma factory em vez de um objeto opcional. A factory deixa claro que a função criará e possuirá o recurso.
def processar(factory=None):
contexto = factory() if factory else nullcontext(recurso_padrao)
with contexto as recurso:
executar(recurso)
Esse desenho também melhora testes, pois uma factory falsa pode registrar entradas e saídas.
Integração com ExitStack
Quando há vários contextos opcionais, ExitStack evita uma sequência de if aninhados.
from contextlib import ExitStack, nullcontext
with ExitStack() as stack:
arquivo = stack.enter_context(open(caminho)) if caminho else stack.enter_context(nullcontext(None))
lock_ativo = stack.enter_context(lock) if usar_lock else stack.enter_context(nullcontext())
executar(arquivo)
Para uma quantidade dinâmica de recursos, ExitStack é geralmente mais legível. Consulte também o guia interno sobre contextlib e gerenciamento de recursos.
Exceções não são suprimidas
with nullcontext():
raise ValueError("falha")
A exceção continua normalmente. nullcontext não se comporta como contextlib.suppress. Essa característica é importante: o contexto neutro deve preservar a semântica do bloco, não esconder problemas.
nullcontext versus suppress
nullcontext não faz nada na saída. suppress captura tipos específicos de exceção. Eles resolvem problemas diferentes e não devem ser trocados apenas porque ambos vêm de contextlib.
nullcontext versus uma classe personalizada
Crie uma classe própria quando precisar registrar métricas, validar estado, transformar exceções, executar callbacks ou liberar recursos. Use nullcontext quando o comportamento desejado for realmente neutro.
Tipagem
Funções que recebem context managers opcionais podem usar ContextManager[T] ou protocolos equivalentes. Se a API aceitar um recurso direto e um contexto, considere normalizar ambos logo na entrada.
from contextlib import nullcontext
from typing import ContextManager, TypeVar
T = TypeVar("T")
def garantir_contexto(valor: T | ContextManager[T]) -> ContextManager[T]:
if hasattr(valor, "__enter__"):
return valor
return nullcontext(valor)
O uso de hasattr é apenas ilustrativo. Em bibliotecas públicas, prefira contratos claros ou protocolos para evitar falsos positivos.
Testes recomendados
- Verifique se o valor passado é devolvido pelo
as. - Confirme que exceções atravessam o contexto.
- Teste o caminho com recurso próprio e o caminho com recurso emprestado.
- Garanta que apenas o recurso criado internamente seja fechado.
- Em código assíncrono, teste cancelamento e falhas no contexto real.
Erros comuns
- Fechar o recurso emprestado: nullcontext não fecha nada; mantenha essa diferença intencional.
- Usar suppress por engano: isso pode ocultar falhas.
- Assumir suporte assíncrono em qualquer versão: confira a versão mínima do projeto.
- Criar contextos antes da hora: uma factory pode evitar adquirir recursos que não serão usados.
- Misturar ownership: documente quem cria, usa e fecha.
Boas práticas
Normalize o contexto no início da função, mantenha o corpo principal único, escolha nomes que revelem ownership e não use nullcontext para mascarar uma API confusa. Quando a quantidade de recursos variar, combine-o com ExitStack ou AsyncExitStack.
O conceito se encaixa bem com outros recursos avançados, como contextlib.aclosing para fechamento assíncrono determinista e gerenciadores de contexto com with.
Conclusão
contextlib.nullcontext é pequeno, mas elimina duplicação em funções que trabalham com contextos opcionais. Ele preserva exceções, pode devolver um valor e permite que o mesmo bloco seja usado com arquivos, locks, transações, sessões e recursos já existentes.
