A biblioteca python-docx permite a criação e modificação de documentos Word (.docx) utilizando Python. A abordagem é baseada em objetos, onde o documento, seus parágrafos, textos e formatações são representados como instâncias de classe.

Instalação e Importação

Para instalar o pacote, execute o seguinte comando no terimnal:

pip install python-docx

Para utilizar a biblioteca, importe os módulos necessários:

from docx import Document
from docx.shared import Pt, Inches, RGBColor
from docx.enum.text import WD_ALIGN_PARAGRAPH, WD_LINE_SPACING

Conceitos Fundamentais

• Document: Representa o arquivo Word inteiro.
• Paragraph: Representa um parágrafo dentro do documento.
• Run: Representa uma sequência de texto com formatação contínua dentro de um parágrafo.

Lendo o Conteúdo de um Documento

O código abaixo acessa um arquivo existente, itera sobre seus parágrafos e imprime o texto de cada um.

import docx

def exibir_conteudo_arquivo(caminho_arquivo):
    documento = docx.Document(caminho_arquivo)
    total_paragrafos = len(documento.paragraphs)
    print(f"Total de parágrafos encontrados: {total_paragrafos}\n")

    for indice, paragrafo in enumerate(documento.paragraphs):
        print(f"Parágrafo {indice + 1}:")
        print(paragrafo.text)
        print("-" * 30)

# Exemplo de uso
exibir_conteudo_arquivo("documento_fonte.docx")

Criando e Escrevendo em um Novo Documento

Podemos gerar um novo documento, adicionar diferentes tipos de conteúdo e salvá-lo.

from docx import Document
from docx.shared import Inches

def criar_documento_exemplo():
    doc = Document()
    
    # Título principal
    doc.add_heading("Relatório Anual", level=0)
    
    # Parágrafo com formatação variada
    bloco_texto = doc.add_paragraph()
    bloco_texto.add_run("Este documento demonstra a ").italic = False
    bloco_texto.add_run("criação ").bold = True
    bloco_texto.add_run("automatizada de conteúdo.")
    
    # Seção com lista
    doc.add_heading("Itens Pendentes", level=1)
    itens = ["Revisão final", "Aprovação do cliente", "Publicação"]
    for item in itens:
        doc.add_paragraph(item, style='ListBullet')
    
    # Inclusão de uma tabela
    tabela = doc.add_table(rows=2, cols=2)
    cabecalho = tabela.rows[0].cells
    cabecalho[0].text = "Métrica"
    cabecalho[1].text = "Valor"
    
    registro = tabela.rows[1].cells
    registro[0].text = "Vendas"
    registro[1].text = "R$ 150.000"
    
    # Inserção de imagem
    doc.add_picture("grafico.png", width=Inches(3.5))
    
    doc.save("relatorio_gerado.docx")

criar_documento_exemplo()

Extraindo Dados de Tabelas

Para percorrer todas as tabelas de um documento e ler seu conteúdo célula por célula:

import docx

def ler_tabelas_do_documento(caminho):
    documento = docx.Document(caminho)
    for idx, tabela in enumerate(documento.tables):
        print(f"--- Tabela {idx + 1} ---")
        for linha in tabela.rows:
            valores_celula = [celula.text for celula in linha.cells]
            print("\t".join(valores_celula))
        print()

ler_tabelas_do_documento("relatorio_com_tabelas.docx")

Personalizando Parágrafos e Texto

É possível controlar detalhes como alinhamento, espaçamento e fonte.

from docx import Document
from docx.shared import Pt, Cm, RGBColor
from docx.enum.text import WD_ALIGN_PARAGRAPH

doc = Document()
doc.styles['Normal'].font.name = 'Arial'

paragrafo1 = doc.add_paragraph()
paragrafo1.alignment = WD_ALIGN_PARAGRAPH.CENTER
paragrafo1.paragraph_format.space_before = Pt(12)
paragrafo1.paragraph_format.space_after = Pt(6)
paragrafo1.paragraph_format.line_spacing_rule = WD_LINE_SPACING.ONE_POINT_FIVE

run1 = paragrafo1.add_run("Título Centralizado")
run1.font.size = Pt(16)
run1.font.bold = True
run1.font.color.rgb = RGBColor(0, 0, 139) # Azul escuro

paragrafo2 = doc.add_paragraph()
paragrafo2.paragraph_format.first_line_indent = Cm(1.25)

run2 = paragrafo2.add_run("Este parágrafo tem recuo de primeira linha e espaçamento configurado. A formatação é aplicada através do objeto 'Run'.")
run2.font.size = Pt(11)
run2.font.name = 'Calibri'

doc.save("formatado.docx")

Referência de Estilos e Propriedades

A tabela abaixo relaciona tamanhos de fonte em pontos (Pt) a suas designações comuns.

Outros Recursos Úteis

• Adicionar Cabeçalho/Rodapé: Acesse document.sections e modifique header ou footer.
• Controle de Paginação: Use paragraph_format.keep_with_next ou page_break_before para controlar quebras.
• Inserir Quebra de Página: document.add_page_break().
• Estilos de Tabela: Defina via table.style após a criação (ex: 'LightShading-Accent1').

As propriedades da fonte em um objeto Run incluem: bold, italic, underline, color, size e name. O alinhamento do parágrafo é definido com constantes como WD_ALIGN_PARAGRAPH.LEFT, .CENTER, .RIGHT e .JUSTIFY.