atexit no Python: execute limpeza ao sair

Scripts e serviços de linha de comando frequentemente precisam salvar estado, fechar relatórios, remover arquivos temporários ou registrar métricas quando terminam. O módulo atexit no Python permite cadastrar funções executadas automaticamente durante o encerramento normal do interpretador, reduzindo o risco de esquecer uma etapa de limpeza no caminho principal.

Neste guia, você aprenderá a usar register(), decorators, argumentos, ordem LIFO, unregister() e tratamento de exceções. O conteúdo complementa nossos artigos sobre context managers, tempfile, tracebacks, faulthandler e weakref.

Registrar uma função

atexit.register() adiciona uma função à lista de handlers de encerramento.

import atexit


def despedir():
    print("Aplicação encerrada")

atexit.register(despedir)

Quando o módulo principal termina normalmente ou sys.exit() é chamado, o handler é executado.

Usar como decorator

Como register() devolve a própria função, ele pode ser usado como decorator.

import atexit

@atexit.register
def salvar_metricas():
    print("Salvando métricas")

Esse formato funciona diretamente quando a função não exige argumentos. Para parâmetros, passe-os na chamada de registro.

Passar argumentos

def registrar_saida(nome, status="ok"):
    print(f"{nome}: {status}")

atexit.register(
    registrar_saida,
    "processamento",
    status="finalizado",
)

Os argumentos são armazenados no registro e usados somente durante o encerramento. Evite capturar objetos gigantes ou recursos que podem já estar em estado parcialmente destruído.

Ordem LIFO

Os handlers são chamados em ordem inversa ao registro. Se A, B e C forem cadastrados nessa sequência, a execução será C, B e A.

atexit.register(lambda: print("primeiro registrado"))
atexit.register(lambda: print("segundo registrado"))
atexit.register(lambda: print("terceiro registrado"))

A documentação oficial de atexit explica que módulos de baixo nível tendem a ser carregados antes e, portanto, são limpos por último.

Encerramento normal

Os handlers são executados quando o módulo principal chega ao fim ou quando sys.exit() gera SystemExit.

import sys

atexit.register(lambda: print("limpeza"))
sys.exit(0)

O código de saída não impede o handler. Contudo, a função não deve alterar silenciosamente o significado do status final.

Casos em que não executa

Atexit não é garantia absoluta. Os handlers não são chamados quando:

• o processo recebe um sinal fatal não tratado pelo Python;
• ocorre um erro interno fatal do interpretador;
• os._exit() é usado;
• o processo é encerrado externamente de forma abrupta;
• a máquina perde energia.

Dados críticos precisam de gravação transacional durante a operação, não somente no final.

atexit e sinais

Se a aplicação precisa reagir a SIGTERM ou SIGINT, instale handlers com o módulo signal e inicie um encerramento controlado.

import signal
import sys


def encerrar(signum, frame):
    sys.exit(128 + signum)

signal.signal(signal.SIGTERM, encerrar)
signal.signal(signal.SIGINT, encerrar)

O handler deve ser simples. A conversão para sys.exit() permite que o encerramento normal acione atexit.

Não usar os._exit()

os._exit() encerra imediatamente sem flush normal, finally, handlers de atexit ou callbacks de alto nível.

Ele é usado em situações específicas após fork() ou em falhas extremas. Não o escolha para sair de uma aplicação comum.

Exceções nos handlers

Se um handler gera uma exceção diferente de SystemExit, um traceback é exibido e os demais handlers continuam sendo executados.

Depois que todos têm oportunidade de rodar, a última exceção é relançada.

def falhar():
    raise RuntimeError("falha na limpeza")

atexit.register(falhar)

Por isso, cada etapa deve capturar e registrar erros recuperáveis sem impedir outras limpezas.

Handler resiliente

import logging

logger = logging.getLogger(__name__)


def fechar_relatorio():
    try:
        gerar_relatorio_final()
    except Exception:
        logger.exception("Não foi possível gerar o relatório final")

atexit.register(fechar_relatorio)

Evite esconder toda falha quando ela torna o encerramento incorreto. Defina quais erros são apenas diagnósticos e quais devem produzir status não zero.

Registrar a mesma função várias vezes

A mesma função e os mesmos argumentos podem ser cadastrados mais de uma vez. Cada ocorrência é executada.

def mostrar(nome):
    print(nome)

atexit.register(mostrar, "A")
atexit.register(mostrar, "B")

Esse comportamento pode gerar duplicidade em módulos importados repetidamente por sistemas de plugins. Proteja a inicialização com estado explícito.

Remover com unregister()

atexit.unregister() remove todas as ocorrências de uma função.

atexit.unregister(fechar_relatorio)

Se a função não estava registrada, nada acontece. A remoção usa comparação por igualdade, não apenas identidade.

Implicações da igualdade

Objetos chamáveis podem definir __eq__(). Duas instâncias consideradas iguais podem ser removidas juntas.

class Acao:
    def __init__(self, nome):
        self.nome = nome

    def __call__(self):
        print(self.nome)

    def __eq__(self, outro):
        return isinstance(outro, Acao) and self.nome == outro.nome

Para handlers importantes, prefira funções simples ou mantenha referências claras.

Alterar registros durante a limpeza

Registrar ou remover handlers enquanto um handler está sendo executado possui efeito indefinido.

Monte a lista durante a inicialização e não a modifique no encerramento. Se a ordem precisa ser dinâmica, registre um único coordenador que chama uma lista própria.

Coordenador de limpeza

acoes = []


def adicionar_acao(funcao):
    acoes.append(funcao)


def executar_acoes():
    for funcao in reversed(acoes):
        try:
            funcao()
        except Exception:
            logger.exception("Falha em ação de limpeza")

atexit.register(executar_acoes)

Esse padrão centraliza ordem, logging e métricas, mas continua sujeito às limitações de encerramento abrupto.

Não iniciar threads

A partir do Python 3.12, tentar iniciar uma nova thread dentro de um handler gera RuntimeError.

import threading


def incorreto():
    thread = threading.Thread(target=trabalho)
    thread.start()

Durante o shutdown, o runtime já pode estar liberando estados internos. Inicie e finalize workers antes de chegar à fase de atexit.

Não usar fork()

Também desde Python 3.12, chamar os.fork() em um handler gera RuntimeError.

Criação de processos durante a desmontagem pode causar race conditions e crashes. Toda tarefa assíncrona de encerramento deve ser concluída antes ou realizada por um supervisor externo.

Threads existentes

Atexit não substitui um protocolo de parada. A thread principal deve sinalizar workers, aguardar join() e só então terminar.

stop_event.set()
for thread in threads:
    thread.join(timeout=5)

O handler pode registrar que uma thread permaneceu viva, mas não deve iniciar nova infraestrutura.

Context managers são preferíveis

Recursos locais devem ser fechados com with.

with open("saida.txt", "w", encoding="utf-8") as arquivo:
    arquivo.write("resultado")

O bloco libera o recurso assim que ele deixa de ser necessário, inclusive em exceções. Atexit deve ser uma camada final para recursos de vida global.

try/finally

Quando a aplicação controla claramente o loop principal, try/finally torna a ordem explícita.

iniciar()
try:
    executar_loop()
finally:
    encerrar()

Esse padrão é mais fácil de testar. Atexit é útil quando a inicialização ocorre em módulo e não existe um ponto único de encerramento acessível.

Arquivos temporários

Objetos de tempfile normalmente oferecem context managers e limpeza automática. Use atexit apenas como fallback para recursos globais.

Não presuma que a remoção sempre acontecerá. Armazene temporários em diretórios seguros que possam ser limpos na próxima inicialização.

Salvar estado

O exemplo clássico é persistir um contador.

from pathlib import Path
import atexit

caminho = Path("contador.txt")
contador = int(caminho.read_text()) if caminho.exists() else 0


def salvar():
    temporario = caminho.with_suffix(".tmp")
    temporario.write_text(str(contador), encoding="utf-8")
    temporario.replace(caminho)

atexit.register(salvar)

A escrita temporária e substituição reduz arquivos parcialmente gravados, mas não garante execução em crash.

Logging no encerramento

A ordem dos handlers e a desmontagem de módulos podem afetar logging. Registre o handler depois de configurar o logger e garanta que os destinos permaneçam disponíveis.

Evite depender de globals que possam ter sido alterados. Capture referências diretas necessárias durante o registro.

Subinterpretadores

Desde Python 3.7, registros feitos por extensões C em subinterpretadores são locais ao interpretador em que foram criados.

Ferramentas embutidas e runtimes com múltiplos interpretadores devem registrar limpeza no contexto correto.

Testar handlers

Não encerre o processo principal do conjunto de testes. Extraia a lógica para uma função comum e teste-a diretamente.

def salvar_estado():
    ...

atexit.register(salvar_estado)


def test_salvar_estado(tmp_path):
    salvar_estado()

Para testar a integração real, execute um subprocesso e verifique arquivo, saída e status após o término.

Subprocesso de teste

import subprocess
import sys

resultado = subprocess.run(
    [sys.executable, "app_teste.py"],
    capture_output=True,
    text=True,
)

assert resultado.returncode == 0
assert "limpeza concluída" in resultado.stdout

Adicione cenários com sys.exit(), exceção não tratada e sinal convertido em saída controlada.

Aplicações web

Servidores possuem hooks próprios de startup e shutdown. Use o ciclo de vida do framework para fechar pools, filas e clientes.

Atexit pode atuar como fallback local, mas workers podem ser terminados abruptamente pelo orquestrador. A lógica principal deve estar no mecanismo oficial do servidor.

Containers e Kubernetes

Containers recebem SIGTERM e possuem um período antes de SIGKILL. O processo PID 1 deve tratar o sinal, parar de aceitar trabalho, concluir operações e sair normalmente.

Atexit será executado somente se esse caminho controlado chegar ao encerramento do Python antes do limite.

Erros frequentes

• Usar atexit como única proteção de dados críticos.
• Esperar execução após os._exit() ou SIGKILL.
• Iniciar thread ou processo no handler.
• Registrar a mesma função várias vezes sem perceber.
• Modificar registros durante a limpeza.
• Depender de logging já encerrado.
• Usar atexit no lugar de with.
• Executar tarefas longas no shutdown.

Boas práticas

• Registre handlers curtos e idempotentes.
• Use LIFO conscientemente.
• Prefira context managers e finally.
• Não inicie threads nem faça fork.
• Proteja gravações com arquivos temporários.
• Teste a lógica diretamente e em subprocesso.
• Integre sinais e ciclo de vida do framework.
• Planeje recuperação após encerramento abrupto.

Conclusão

O módulo atexit no Python registra funções executadas em ordem inversa durante o encerramento normal. Ele é útil para métricas finais, persistência leve e limpeza de recursos globais que não possuem um ponto de finalização melhor.

A garantia é limitada: sinais fatais, os._exit(), crashes e perda de energia ignoram os handlers. Com funções curtas, idempotência, context managers e um protocolo explícito de shutdown, atexit funciona como uma última camada de organização, não como substituto de durabilidade.