XLSX

Requisitos para Saídas

Todos os arquivos Excel

Fonte Profissional

• Use uma fonte consistente e profissional (por exemplo, Arial, Times New Roman) para todos os entregáveis, a menos que o usuário instruya de outra forma

Zero Erros de Fórmula

• Todo modelo Excel DEVE ser entregue com ZERO erros de fórmula (#REF!, #DIV/0!, #VALUE!, #N/A, #NAME?)

Preservar Templates Existentes (ao atualizar templates)

• Estude e CORRESPONDA EXATAMENTE ao formato, estilo e convenções existentes ao modificar arquivos
• Nunca imponha formatação padronizada em arquivos com padrões estabelecidos
• As convenções de template existentes SEMPRE superam essas diretrizes

Modelos financeiros

Padrões de Codificação por Cores

A menos que o usuário declare o contrário ou template existente

Convenções de Cor Padrão da Indústria

• Texto azul (RGB: 0,0,255): Entradas codificadas e números que os usuários alterarão para cenários
• Texto preto (RGB: 0,0,0): TODAS as fórmulas e cálculos
• Texto verde (RGB: 0,128,0): Links puxando de outras planilhas dentro do mesmo workbook
• Texto vermelho (RGB: 255,0,0): Links externos para outros arquivos
• Fundo amarelo (RGB: 255,255,0): Principais premissas que precisam de atenção ou células que precisam ser atualizadas

Padrões de Formatação de Números

Regras de Formato Obrigatórias

• Anos: Formatar como strings de texto (ex: "2024" não "2.024")
• Moeda: Use formato $#,##0; SEMPRE especifique unidades em cabeçalhos ("Receita (R$ mm)")
• Zeros: Use formatação de números para fazer todos os zeros "-", incluindo percentuais (ex: "$#,##0;($#,##0);-")
• Percentuais: Padrão de formato 0,0% (uma decimal)
• Múltiplos: Formatar como 0,0x para múltiplos de avaliação (EV/EBITDA, P/E)
• Números negativos: Use parênteses (123) não menos -123

Regras de Construção de Fórmula

Posicionamento de Premissas

• Coloque TODAS as premissas (taxas de crescimento, margens, múltiplos, etc.) em células de premissas separadas
• Use referências de célula em vez de valores codificados em fórmulas
• Exemplo: Use =B5*(1+$B$6) em vez de =B5*1,05

Prevenção de Erros de Fórmula

• Verifique que todas as referências de célula estão corretas
• Verifique erros de off-by-one em intervalos
• Garanta formulas consistentes em todos os períodos de projeção
• Teste com casos extremos (valores zero, números negativos)
• Verifique que não há referências circulares não intencionais

Requisitos de Documentação para Valores Codificados

• Comente ou em células ao lado (se no final da tabela). Formato: "Fonte: [Sistema/Documento], [Data], [Referência Específica], [URL se aplicável]"
• Exemplos:
  • "Fonte: 10-K da Empresa, FY2024, Página 45, Nota de Receita, [URL SEC EDGAR]"
  • "Fonte: 10-Q da Empresa, Q2 2025, Anexo 99.1, [URL SEC EDGAR]"
  • "Fonte: Bloomberg Terminal, 15/08/2025, AAPL US Equity"
  • "Fonte: FactSet, 20/08/2025, Tela de Estimativas de Consenso"

XLSX criação, edição e análise

Visão Geral

Um usuário pode pedir que você crie, edite ou analise o conteúdo de um arquivo .xlsx. Você tem diferentes ferramentas e workflows disponíveis para diferentes tarefas.

Requisitos Importantes

LibreOffice Necessário para Recalcular Fórmulas: Você pode assumir que LibreOffice está instalado para recalcular valores de fórmula usando o script scripts/recalc.py. O script configura automaticamente o LibreOffice na primeira execução, inclusive em ambientes sandboxed onde sockets Unix são restritos (tratados por scripts/office/soffice.py)

Leitura e análise de dados

Análise de dados com pandas

Para análise de dados, visualização e operações básicas, use pandas, que oferece poderosos recursos de manipulação de dados:

import pandas as pd

# Ler Excel
df = pd.read_excel('file.xlsx')  # Padrão: primeira planilha
all_sheets = pd.read_excel('file.xlsx', sheet_name=None)  # Todas as planilhas como dict

# Analisar
df.head()      # Visualizar dados
df.info()      # Informações de coluna
df.describe()  # Estatísticas

# Escrever Excel
df.to_excel('output.xlsx', index=False)

Workflows de Arquivo Excel

CRÍTICO: Use Fórmulas, Não Valores Codificados

Sempre use fórmulas Excel em vez de calcular valores em Python e codificá-los. Isso garante que a planilha permaneça dinâmica e atualizável.

❌ ERRADO - Codificação de Valores Calculados

# Ruim: Calcular em Python e codificar resultado
total = df['Sales'].sum()
sheet['B10'] = total  # Codifica 5000

# Ruim: Computar taxa de crescimento em Python
growth = (df.iloc[-1]['Revenue'] - df.iloc[0]['Revenue']) / df.iloc[0]['Revenue']
sheet['C5'] = growth  # Codifica 0,15

# Ruim: Cálculo Python para média
avg = sum(values) / len(values)
sheet['D20'] = avg  # Codifica 42,5

✅ CORRETO - Usando Fórmulas Excel

# Bom: Deixe Excel calcular a soma
sheet['B10'] = '=SUM(B2:B9)'

# Bom: Taxa de crescimento como fórmula Excel
sheet['C5'] = '=(C4-C2)/C2'

# Bom: Média usando função Excel
sheet['D20'] = '=AVERAGE(D2:D19)'

Isso se aplica a TODOS os cálculos — totais, percentuais, razões, diferenças, etc. A planilha deve ser capaz de recalcular quando os dados de origem mudam.

Workflow Comum

1. Escolher ferramenta: pandas para dados, openpyxl para fórmulas/formatação
2. Criar/Carregar: Criar novo workbook ou carregar arquivo existente
3. Modificar: Adicionar/editar dados, fórmulas e formatação
4. Salvar: Escrever em arquivo
5. Recalcular fórmulas (OBRIGATÓRIO SE USAR FÓRMULAS): Use o script scripts/recalc.py

   python scripts/recalc.py output.xlsx
   

6. Verificar e corrigir erros:
   • O script retorna JSON com detalhes de erro
   • Se status for errors_found, verifique error_summary para tipos de erro específicos e locais
   • Corrija os erros identificados e recalcule novamente
   • Erros comuns a corrigir:
     • #REF!: Referências de célula inválidas
     • #DIV/0!: Divisão por zero
     • #VALUE!: Tipo de dados errado em fórmula
     • #NAME?: Nome de fórmula não reconhecido

Criando novos arquivos Excel

# Usando openpyxl para fórmulas e formatação
from openpyxl import Workbook
from openpyxl.styles import Font, PatternFill, Alignment

wb = Workbook()
sheet = wb.active

# Adicionar dados
sheet['A1'] = 'Hello'
sheet['B1'] = 'World'
sheet.append(['Row', 'of', 'data'])

# Adicionar fórmula
sheet['B2'] = '=SUM(A1:A10)'

# Formatação
sheet['A1'].font = Font(bold=True, color='FF0000')
sheet['A1'].fill = PatternFill('solid', start_color='FFFF00')
sheet['A1'].alignment = Alignment(horizontal='center')

# Largura da coluna
sheet.column_dimensions['A'].width = 20

wb.save('output.xlsx')

Editando arquivos Excel existentes

# Usando openpyxl para preservar fórmulas e formatação
from openpyxl import load_workbook

# Carregar arquivo existente
wb = load_workbook('existing.xlsx')
sheet = wb.active  # ou wb['SheetName'] para planilha específica

# Trabalhando com múltiplas planilhas
for sheet_name in wb.sheetnames:
    sheet = wb[sheet_name]
    print(f"Planilha: {sheet_name}")

# Modificar células
sheet['A1'] = 'Novo Valor'
sheet.insert_rows(2)  # Inserir linha na posição 2
sheet.delete_cols(3)  # Deletar coluna 3

# Adicionar nova planilha
new_sheet = wb.create_sheet('NovaPlaniha')
new_sheet['A1'] = 'Dados'

wb.save('modified.xlsx')

Recalculando fórmulas

Arquivos Excel criados ou modificados por openpyxl contêm fórmulas como strings mas não valores calculados. Use o script fornecido scripts/recalc.py para recalcular fórmulas:

python scripts/recalc.py <excel_file> [timeout_seconds]

Exemplo:

python scripts/recalc.py output.xlsx 30

O script:

• Configura automaticamente macro do LibreOffice na primeira execução
• Recalcula todas as fórmulas em todas as planilhas
• Verifica TODAS as células para erros Excel (#REF!, #DIV/0!, etc.)
• Retorna JSON com locais e contagens de erro detalhadas
• Funciona em Linux e macOS

Checklist de Verificação de Fórmula

Verificações rápidas para garantir que as fórmulas funcionem corretamente:

Verificação Essencial

• Testar 2-3 referências de amostra: Verifique se elas puxam valores corretos antes de construir modelo completo
• Mapeamento de coluna: Confirme que colunas Excel correspondem (ex: coluna 64 = BL, não BK)
• Offset de linha: Lembre-se que linhas Excel são indexadas em 1 (linha 5 do DataFrame = linha 6 do Excel)

Armadilhas Comuns

• Tratamento de NaN: Verifique valores nulos com pd.notna()
• Colunas à direita: Dados de FY frequentemente em colunas 50+
• Múltiplas correspondências: Procure todas as ocorrências, não apenas a primeira
• Divisão por zero: Verifique denominadores antes de usar / em fórmulas (#DIV/0!)
• Referências erradas: Verifique que todas as referências de célula apontam para células pretendidas (#REF!)
• Referências entre planilhas: Use formato correto (Sheet1!A1) para lincar planilhas

Estratégia de Teste de Fórmula

• Comece pequeno: Teste fórmulas em 2-3 células antes de aplicar amplamente
• Verifique dependências: Verifique que todas as células referenciadas em fórmulas existem
• Teste casos extremos: Inclua zero, negativo e valores muito grandes

Interpretando Saída de scripts/recalc.py

O script retorna JSON com detalhes de erro:

{
  "status": "success",           // ou "errors_found"
  "total_errors": 0,              // Contagem total de erros
  "total_formulas": 42,           // Número de fórmulas no arquivo
  "error_summary": {              // Só presente se erros encontrados
    "#REF!": {
      "count": 2,
      "locations": ["Sheet1!B5", "Sheet1!C10"]
    }
  }
}

Boas Práticas

Seleção de Biblioteca

• pandas: Melhor para análise de dados, operações em massa e exportação de dados simples
• openpyxl: Melhor para formatação complexa, fórmulas e recursos específicos do Excel

Trabalhando com openpyxl

• Índices de célula são baseados em 1 (row=1, column=1 refere-se à célula A1)
• Use data_only=True para ler valores calculados: load_workbook('file.xlsx', data_only=True)
• Aviso: Se aberto com data_only=True e salvo, fórmulas são substituídas por valores e perdidas permanentemente
• Para arquivos grandes: Use read_only=True para leitura ou write_only=True para escrita
• Fórmulas são preservadas mas não avaliadas — use scripts/recalc.py para atualizar valores

Trabalhando com pandas

• Especifique tipos de dados para evitar problemas de inferência: pd.read_excel('file.xlsx', dtype={'id': str})
• Para arquivos grandes, leia colunas específicas: pd.read_excel('file.xlsx', usecols=['A', 'C', 'E'])
• Trate datas adequadamente: pd.read_excel('file.xlsx', parse_dates=['date_column'])

Diretrizes de Estilo de Código

IMPORTANTE: Ao gerar código Python para operações Excel:

• Escreva código Python mínimo e conciso sem comentários desnecessários
• Evite nomes de variáveis verbosos e operações redundantes
• Evite print statements desnecessários

Para arquivos Excel em si:

• Adicione comentários a células com fórmulas complexas ou premissas importantes
• Documente fontes de dados para valores codificados
• Inclua notas para cálculos-chave e seções de modelo