Requisitos para Saídas
Todos os Arquivos Excel
Zero Erros de Fórmula
- Cada modelo Excel DEVE ser entregue com ZERO erros de fórmula (#REF!, #DIV/0!, #VALUE!, #N/A, #NAME?)
Preservar Templates Existentes (ao atualizar templates)
- Estudar e COMBINAR EXATAMENTE o formato, estilo e convenções existentes ao modificar arquivos
- Nunca impor formatação padronizada em arquivos com padrões estabelecidos
- As convenções do template existente SEMPRE substituem estas diretrizes
Modelos Financeiros
Padrões de Codificação de Cores
A menos que seja especificado de outra forma pelo usuário ou template existente
Convenções de Cores Padrão da Indústria
- Texto azul (RGB: 0,0,255): Entradas fixas 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 que puxam de outras planilhas dentro do mesmo workbook
- Texto vermelho (RGB: 255,0,0): Links externos para outros arquivos
- Fundo amarelo (RGB: 255,255,0): Premissas-chave 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: Usar formato $#.##0; SEMPRE especificar unidades nos cabeçalhos ("Receita ($mm)")
- Zeros: Usar formatação de número para tornar todos os zeros "-", incluindo porcentagens (ex.: "$#.##0;($#.##0);-")
- Porcentagens: Padrão para formato 0,0% (uma casa decimal)
- Múltiplos: Formatar como 0,0x para múltiplos de valuation (EV/EBITDA, P/L)
- Números negativos: Usar parênteses (123) não sinal de menos -123
Regras de Construção de Fórmulas
Posicionamento de Premissas
- Colocar TODAS as premissas (taxas de crescimento, margens, múltiplos, etc.) em células de premissas separadas
- Usar referências de célula em vez de valores fixos nas fórmulas
- Exemplo: Usar =B5*(1+$B$6) em vez de =B5*1,05
Prevenção de Erros de Fórmula
- Verificar se todas as referências de célula estão corretas
- Verificar erros de deslocamento em intervalos
- Garantir fórmulas consistentes em todos os períodos de projeção
- Testar com casos extremos (valores zero, números negativos)
- Verificar se não há referências circulares não intencionais
Requisitos de Documentação para Valores Fixos
- Comentar ou em células ao lado (se for final da tabela). Formato: "Fonte: [Sistema/Documento], [Data], [Referência Específica], [URL se aplicável]"
- Exemplos:
- "Fonte: 10-K da Empresa, AF2024, Página 45, Nota de Receita, [URL SEC EDGAR]"
- "Fonte: 10-Q da Empresa, T2 2025, Anexo 99.1, [URL SEC EDGAR]"
- "Fonte: Terminal Bloomberg, 15/08/2025, AAPL US Equity"
- "Fonte: FactSet, 20/08/2025, Tela de Estimativas de Consenso"
Criação, edição e análise de XLSX
Visão Geral
Um usuário pode solicitar que você crie, edite ou analise o conteúdo de um arquivo .xlsx. Você tem diferentes ferramentas e fluxos de trabalho disponíveis para diferentes tarefas.
Requisitos Importantes
LibreOffice Necessário para Recalcular Fórmulas: Você pode assumir que o LibreOffice está instalado para recalcular valores de fórmula usando o script recalc.py. O script configura automaticamente o LibreOffice na primeira execução
Lendo e analisando dados
Análise de dados com pandas
Para análise de dados, visualização e operações básicas, use pandas que fornece capacidades poderosas de manipulação de dados:
import pandas as pd
# Ler Excel
df = pd.read_excel('arquivo.xlsx') # Padrão: primeira planilha
todas_as_planilhas = pd.read_excel('arquivo.xlsx', sheet_name=None) # Todas as planilhas como dicionário
# Analisar
df.head() # Visualizar dados
df.info() # Informações das colunas
df.describe() # Estatísticas
# Escrever Excel
df.to_excel('saida.xlsx', index=False)
Fluxos de Trabalho de Arquivos Excel
CRÍTICO: Use Fórmulas, Não Valores Fixos
Sempre use fórmulas do Excel em vez de calcular valores em Python e fixá-los. Isso garante que a planilha permaneça dinâmica e atualizável.
❌ ERRADO - Valores Calculados Fixos
# Ruim: Calculando em Python e fixando o resultado
total = df['Vendas'].sum()
planilha['B10'] = total # Fixa 5000
# Ruim: Calculando taxa de crescimento em Python
crescimento = (df.iloc[-1]['Receita'] - df.iloc[0]['Receita']) / df.iloc[0]['Receita']
planilha['C5'] = crescimento # Fixa 0,15
# Ruim: Cálculo de média em Python
media = soma(valores) / len(valores)
planilha['D20'] = media # Fixa 42,5
✅ CORRETO - Usando Fórmulas do Excel
# Bom: Deixe o Excel calcular a soma
planilha['B10'] = '=SUM(B2:B9)'
# Bom: Taxa de crescimento como fórmula do Excel
planilha['C5'] = '=(C4-C2)/C2'
# Bom: Média usando função do Excel
planilha['D20'] = '=AVERAGE(D2:D19)'
Isso se aplica a TODOS os cálculos - totais, porcentagens, índices, diferenças, etc. A planilha deve ser capaz de recalcular quando os dados de origem mudam.
Fluxo de Trabalho Comum
- Escolher ferramenta: pandas para dados, openpyxl para fórmulas/formatação
- Criar/Carregar: Criar novo workbook ou carregar arquivo existente
- Modificar: Adicionar/editar dados, fórmulas e formatação
- Salvar: Escrever no arquivo
- Recalcular fórmulas (OBRIGATÓRIO SE USAR FÓRMULAS): Usar o script recalc.py
python recalc.py saida.xlsx - Verificar e corrigir quaisquer erros:
- O script retorna JSON com detalhes do erro
- Se
statusforerrors_found, verifiqueerror_summarypara tipos e locais específicos de erro - Corrigir os erros identificados e recalcular novamente
- Erros comuns a corrigir:
#REF!: Referências de célula inválidas#DIV/0!: Divisão por zero#VALUE!: Tipo de dado errado na 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()
planilha = wb.active
# Adicionar dados
planilha['A1'] = 'Olá'
planilha['B1'] = 'Mundo'
planilha.append(['Linha', 'de', 'dados'])
# Adicionar fórmula
planilha['B2'] = '=SUM(A1:A10)'
# Formatação
planilha['A1'].font = Font(bold=True, color='FF0000')
planilha['A1'].fill = PatternFill('solid', start_color='FFFF00')
planilha['A1'].alignment = Alignment(horizontal='center')
# Largura da coluna
planilha.column_dimensions['A'].width = 20
wb.save('saida.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('existente.xlsx')
planilha = wb.active # ou wb['NomePlanilha'] para planilha específica
# Trabalhando com múltiplas planilhas
for nome_planilha in wb.sheetnames:
planilha = wb[nome_planilha]
print(f"Planilha: {nome_planilha}")
# Modificar células
planilha['A1'] = 'Novo Valor'
planilha.insert_rows(2) # Inserir linha na posição 2
planilha.delete_cols(3) # Excluir coluna 3
# Adicionar nova planilha
nova_planilha = wb.create_sheet('NovaPlanilha')
nova_planilha['A1'] = 'Dados'
wb.save('modificado.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 recalc.py fornecido para recalcular fórmulas:
python recalc.py <arquivo_excel> [segundos_timeout]
Exemplo:
python recalc.py saida.xlsx 30
O script:
- Configura automaticamente a macro do LibreOffice na primeira execução
- Recalcula todas as fórmulas em todas as planilhas
- Escaneia TODAS as células em busca de erros do Excel (#REF!, #DIV/0!, etc.)
- Retorna JSON com locais de erro detalhados e contagens
- Funciona tanto em Linux quanto em macOS
Checklist de Verificação de Fórmulas
Verificações rápidas para garantir que as fórmulas funcionem corretamente:
Verificação Essencial
- Testar 2-3 referências de amostra: Verificar se elas puxam valores corretos antes de construir o modelo completo
- Mapeamento de colunas: Confirmar se as colunas do Excel correspondem (ex.: coluna 64 = BL, não BK)
- Deslocamento de linha: Lembrar que as linhas do Excel são indexadas a partir de 1 (linha 5 do DataFrame = linha 6 do Excel)
Armadilhas Comuns
- Tratamento de NaN: Verificar valores nulos com
pd.notna() - Colunas à direita: Dados de AF geralmente estão nas colunas 50+
- Múltiplas correspondências: Pesquisar todas as ocorrências, não apenas a primeira
- Divisão por zero: Verificar denominadores antes de usar
/em fórmulas (#DIV/0!) - Referências erradas: Verificar se todas as referências de célula apontam para as células pretendidas (#REF!)
- Referências entre planilhas: Usar formato correto (Planilha1!A1) para vincular planilhas
Estratégia de Teste de Fórmulas
- Começar pequeno: Testar fórmulas em 2-3 células antes de aplicar amplamente
- Verificar dependências: Verificar se todas as células referenciadas nas fórmulas existem
- Testar casos extremos: Incluir valores zero, negativos e muito grandes
Interpretando a Saída do recalc.py
O script retorna JSON com detalhes do 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": { // Presente apenas se erros encontrados
"#REF!": {
"count": 2,
"locations": ["Planilha1!B5", "Planilha1!C10"]
}
}
}
Melhores Práticas
Seleção de Biblioteca
- pandas: Melhor para análise de dados, operações em lote e exportação simples de dados
- 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 (linha=1, coluna=1 refere-se à célula A1)
- Usar
data_only=Truepara ler valores calculados:load_workbook('arquivo.xlsx', data_only=True) - Aviso: Se aberto com
data_only=Truee salvo, as fórmulas são substituídas por valores e permanentemente perdidas - Para arquivos grandes: Usar
read_only=Truepara leitura ouwrite_only=Truepara escrita - As fórmulas são preservadas, mas não avaliadas - use recalc.py para atualizar os valores
Trabalhando com pandas
- Especificar tipos de dados para evitar problemas de inferência:
pd.read_excel('arquivo.xlsx', dtype={'id': str}) - Para arquivos grandes, ler colunas específicas:
pd.read_excel('arquivo.xlsx', usecols=['A', 'C', 'E']) - Lidar com datas corretamente:
pd.read_excel('arquivo.xlsx', parse_dates=['coluna_data'])
Diretrizes de Estilo de Código
IMPORTANTE: Ao gerar código Python para operações com Excel:
- Escrever código Python mínimo e conciso, sem comentários desnecessários
- Evitar nomes de variáveis verbosos e operações redundantes
- Evitar declarações print desnecessárias
Para os próprios arquivos Excel:
- Adicionar comentários em células com fórmulas complexas ou premissas importantes
- Documentar fontes de dados para valores fixos
- Incluir notas para cálculos-chave e seções do modelo