Como Preencher um Modelo de Documento no Word (.docx) Automatizado com Python

Como Preencher um Modelo de Documento no Word (.docx) Automatizado com Python

A automação do preenchimento de modelos no Word permite gerar contratos, relatórios e certificados em lote sem a necessidade de formatação manual. Utilizando a biblioteca python-docx, é possível localizar marcas de substituição (tags como {{nome}} ou {{data}}) dentro dos parágrafos do arquivo .docx e alterá-las dinamicamente via código.

Python

from docx import Document

def preencher_modelo_word(caminho_modelo, caminho_saida, dados):
    # Carrega o documento modelo (.docx)
    doc = Document(caminho_modelo)

    # Iterar sobre todos os parágrafos do documento
    for paragrafo in doc.paragraphs:
        for tag, valor in dados.items():
            if tag in paragrafo.text:
                # Substitui a tag pelo valor correspondente mantendo a estrutura
                paragrafo.text = paragrafo.text.replace(tag, str(valor))

    # Salva o arquivo final preenchido
    doc.save(caminho_saida)
    print(f"Documento gerado com sucesso em: {caminho_saida}")

# Exemplo prático de uso
if __name__ == "__main__":
    # Dicionário de dados para substituição
    variaveis = {
        "{{NOME_CLIENTE}}": "Carlos Eduardo Silva",
        "{{VALOR}}": "R$ 2.500,00",
        "{{DATA}}": "23 de Outubro de 2026"
    }

    # Chamada da função (certifique-se de que o arquivo 'modelo.docx' exista)
    preencher_modelo_word("modelo.docx", "contrato_final.docx", variaveis)

• Leitura com Document(): A classe Document do python-docx lê a estrutura completa do arquivo .docx, permitindo varrer seus parágrafos, tabelas e cabeçalhos.
  
  
• Preservação de Tags (replace): O uso da substituição direta de texto substitui os delimitadores (como {{TAG}}) pelo valor final, mantendo o fluxo contínuo do texto.
  
  
• Atenção à Formatação interna (Runs): No Word, um único parágrafo pode ser dividido internamente em múltiplos runs de estilização. Se a tag {{NOME}} tiver partes com estilos diferentes (ex: {{ em negrito e NOME}} normal), a busca direta em paragrafo.text funcionará, mas a substituição pode resetar a formatação específica do trecho.
  
  
• Manipulação de Tabelas: Caso o modelo possua variáveis dentro de tabelas, é necessário adicionar uma iteração secundária sobre doc.tables além de doc.paragraphs.