Escrita Segura em Excel com Openpyxl em Ambientes Multithreading

15 Sep, 2026

Entendendo o Conceito

A biblioteca openpyxl é uma das ferramentas mais comuns para manipulação de arquivos Excel no formato .xlsx no ecossistema Python. No entanto, ela não fornece suporte nativo a operações simultâneas em ambientes multithreading, o que significa que seus objetos de planilha (Workbook) não são thread-safe para modificações paralelas. Se múltiplos fluxos de execução tentarem alterar células ou salvar o arquivo ao mesmo tempo, ocorrerão inconsistências graves, corrupção do documento ou falhas de runtime devido à alteração de estruturas internas durante a iteração.

Para superar essa limitação, torna-se indispensável o uso de primitivas de sincronização que controlem o acesso ao arquivo. O emprego de uma trava de exclusão mútua, conhecida como lock ou mutex, assegura que apenas uma thread realize a escrita ou execute o processo de gravação por vez. Essa abordagem protege as seções críticas do código, garantindo a integridade dos dados finais sem que ocorram colisões de concorrência.

Passo a Passo

O procedimento a seguir demonstra como estruturar uma classe que protege as operações do openpyxl por meio do módulo threading.

Primeiramente, instale a biblioteca de manipulação de planilhas por meio do gerenciador de pacotes pip:

pip install openpyxl

Em seguida, implemente a lógica de sincronização encapsulando o workbook e a trava correspondente:

import threading
import time
from openpyxl import Workbook

class ThreadSafeExcelWriter:
    def __init__(self, filename):
        self.filename = filename
        self.wb = Workbook()
        self.ws = self.wb.active
        self.lock = threading.Lock()

    def write_data(self, row, col, value):
        with self.lock:
            self.ws.cell(row=row, column=col, value=value)

    def save_workbook(self):
        with self.lock:
            self.wb.save(self.filename)

def worker_task(writer, start_row, value):
    for i in range(5):
        writer.write_data(row=start_row + i, col=1, value=value)
        time.sleep(0.01)

writer = ThreadSafeExcelWriter("dados_seguros.xlsx")

threads = []
for index in range(1, 6):
    t = threading.Thread(target=worker_task, args=(writer, index * 10, f"Thread-{index}"))
    threads.append(t)
    t.start()

for t in threads:
    t.join()

writer.save_workbook()

Explicando o código

A estrutura desenvolvida utiliza comandos específicos da linguagem para viabilizar o comportamento concorrente seguro:

• threading.Lock(): Cria uma nova trava primitiva de exclusão mútua com dois estados possíveis, travado e destravado, permitindo que apenas a thread detentora execute a região protegida.
• with self.lock:: Utiliza o protocolo de gerenciamento de contexto do Python para garantir a chamada implícita do método acquire() ao iniciar o escopo e do método release() ao final, prevenindo o travamento infinito mesmo diante de exceções no bloco.
• self.ws.cell(row=row, column=col, value=value): Altera a célula de coordenadas especificadas no objeto do openpyxl de modo seguro após a obtenção da trava.
• self.wb.save(self.filename): Realiza a gravação física dos dados sob a proteção do lock para evitar colisões caso threads ainda tentem escrever enquanto o disco é acessado.
• threading.Thread(target=..., args=...): Configura uma nova linha de execução do sistema operacional mapeada para rodar a rotina do trabalhador paralelamente com os parâmetros indicados.
• t.start(): Inicia de forma efetiva o processamento concorrente da thread correspondente.
• t.join(): Obriga o interpretador a suspender a thread principal até que a execução paralela seja integralmente concluída.

Observações

• O uso de locks impede a corrupção de dados, porém introduz um gargalo de desempenho à medida que a escrita em si passa a ser estritamente sequencial.
• Se o salvamento do arquivo for efetuado enquanto uma thread tenta escrever sem a proteção do lock, o interpretador lançará um erro fatal de dicionário modificado durante a iteração.
• O Global Interpreter Lock do Python limita a execução concorrente em tarefas puramente computacionais, mas a sincronização descrita é crítica para operações de E/S que compartilham mutabilidade como planilhas.
• Gerenciadores de contexto com o bloco with devem ser sempre priorizados em relação a chamadas diretas de acquire e release para blindar o código contra problemas de deadlock.
• Para cenários de altíssimo volume de escrita em paralelo, uma arquitetura baseada em fila centralizada (queue.Queue) com uma única thread de consumo reduz substancialmente o overhead gerado por locks concorrentes.

Referências

1. Documentação Oficial do Openpyxl: https://openpyxl.readthedocs.io/
2. Discussão sobre Thread Safety no Openpyxl: https://stackoverflow.com/questions/11234203/openpyxl-thread-safe
3. Registro de Falha de Concorrência do HeptaPod: https://foss.heptapod.net/openpyxl/openpyxl/-/issues/228
4. Documentação de Threading e Locks do Python: https://docs.python.org/3/library/threading.html

#concurrency #excel #openpyxl #python #threading #threadsafe