xlsx

Criação, edição e análise de XLSX

Tarefa	Abordagem
Criar ou editar com fórmulas/formatação	openpyxl — veja as armadilhas abaixo
Dados em massa entrada/saída	pandas (read_excel, to_excel)
Olhada rápida em uma planilha	markitdown arquivo.xlsx — ## NomeDaAba por aba; também lê .xlsm. Sem coordenadas de célula, então não planeje edições a partir disso
Ler um modelo (fórmulas e valores)	duas passagens load_workbook — veja as armadilhas

openpyxl, pandas e markitdown estão pré-instalados — não execute pip install primeiro; escreva o script e importe diretamente. Somente se uma importação falhar (ou o comando markitdown estiver faltando): pip install o pacote ausente.

Caminhos de script abaixo são relativos ao diretório desta skill.

Requisitos para toda saída

• Fonte profissional (Arial, Times New Roman) em todo o documento, a menos que o usuário diga o contrário.
• Zero erros de fórmula. Nunca entregue enquanto recalc.py reportar errors_found. Se você acha que um erro é anterior a você, prove: carregue o original com data_only=True e veja aquela célula. Um erro que você introduziu parece exatamente igual a um que você herdou.
• Use fórmulas, nunca resultados fixos. Escreva sheet['B10'] = '=SOMA(B2:B9)', não o total calculado em Python. A planilha deve recalcular quando suas entradas mudarem.
• Siga a especificação do usuário literalmente. Nomes de abas exatos, cabeçalhos de coluna exatos e a fórmula que ele escreveu. Um redesign que calcule outra coisa falha, por mais elegante que seja.
• Documente toda suposição e número fixo onde o leitor possa ver — um comentário de célula ou uma célula adjacente no final de uma tabela. Cite uma fonte real quando existir (Fonte: 10-K da Empresa, AF2024, Página 45, Nota de Receita, [URL SEC EDGAR]); quando o número veio do usuário, diga isso claramente.
• Uma pasta de trabalho criada por você para alguém preencher precisa de uma legenda curta nomeando quais células editar e uma linha de exemplo com valores realistas mostrando o formato esperado. Nunca adicione tal linha a um arquivo que você foi instruído a editar.
• Editando um arquivo existente: siga suas convenções exatamente. Elas substituem toda diretriz aqui. Encontre primeiro suas células de entrada designadas — uma cor de fonte, preenchimento ou sombreamento distinto as marca — escreva somente lá e deixe toda fórmula existente intocada.

Recalcular (obrigatório sempre que o arquivo contiver fórmulas)

openpyxl escreve fórmulas como strings sem valores em cache. Até você recalcular, toda célula de fórmula retorna None para qualquer coisa que leia valores em cache — pandas, load_workbook(data_only=True) e a maioria dos visualizadores.

python scripts/recalc.py saida.xlsx [tempo_limite_segundos]   # padrão 30

LibreOffice calcula toda fórmula, o arquivo é reescrito no local e você recebe JSON: status (success | errors_found), total_formulas, total_errors e um error_summary nomeando até 100 células por tipo de erro (locations_truncated diz quantas foram omitidas — confie em total_errors, não no comprimento da lista). Corrija o que ele nomear e execute novamente. JSON com uma chave error em vez de status significa que nada foi recalculado, e apenas esse caso sai com código diferente de zero — errors_found sai com 0, então nunca trate uma saída limpa como uma pasta de trabalho limpa.

Um recálculo verde prova que suas fórmulas avaliam, não que estão corretas. Um intervalo com diferença de um ou uma referência à linha errada produz um arquivo limpo, sem erros, com números errados. Escreva 2–3 fórmulas primeiro e verifique se elas puxam os valores esperados, antes de construir uma grade.

Uma pasta de trabalho que vincula a outro arquivo perde esses vínculos se você a salvar novamente com openpyxl e depois recalcular. Tal fórmula lê ='[1]Análise de Retornos'!$B$2 — o [1] é um índice na lista de referências externas da pasta de trabalho, nomeando um arquivo separado no disco, não uma aba. Esse arquivo raramente está presente aqui, então o valor em cache da célula é a única coisa que mantém seus dados. openpyxl remove esse valor ao salvar; LibreOffice então precisa resolver a referência de verdade, falha, escreve #NOME? e deleta todo vínculo. recalc.py se recusa a executar nesse estado — copie os valores dessas células do original antes de salvar sobre ele (--force substitui e aceita a perda).

Escolhendo fórmulas que sobrevivem à verificação

LibreOffice implementa menos funções que Excel, e uma que ele não consegue avaliar se torna um literal #NOME? gravado no arquivo que você entrega.

• Prefira funções da era Excel-2007 — SOMASES, ÍNDICE, CORRESP, SEERRO, SOMARPRODUTO — que não precisam de prefixo.
• Seis funções pós-2007 funcionam, mas apenas com um prefixo _xlfn., porque openpyxl escreve sua fórmula no XML literalmente e Excel armazena nomes pós-2007 prefixados (sua UI esconde o prefixo): _xlfn.TEXTJOIN, _xlfn.CONCAT, _xlfn.IFS, _xlfn.SWITCH, _xlfn.MAXIFS, _xlfn.MINIFS. Escritas sem prefixo, cada uma resulta em #NOME?.
• Nunca use XLOOKUP, XMATCH, SORT, FILTER, UNIQUE ou SEQUENCE. O LibreOffice do ambiente de execução não consegue avaliá-los sob nenhum prefixo. Versões mais novas os avaliam, mas são funções de matriz dinâmica e um arquivo escrito por openpyxl não tem metadados de expansão, então apenas a célula superior esquerda do intervalo recebe um valor — e recalc.py reporta total_errors: 0 no resultado truncado. Use ÍNDICE/CORRESP para buscas, e ordene, filtre e remova duplicatas em Python antes de escrever as células.
• Uma fórmula que LibreOffice não conseguiu analisar é escrita de volta em minúsculas — um sinal rápido ao lado de um #NOME?.

Armadilhas do openpyxl

• Ler um modelo requer duas cargas. data_only=True fornece valores em cache com as fórmulas removidas; o padrão fornece strings de fórmula sem valores. Uma passagem não pode dar ambos.
• data_only=True é destrutivo se você salvar. Essa pasta de trabalho não tem mais fórmulas, então salvar substitui cada uma por um literal — permanentemente.
• data_only=True em um arquivo que openpyxl acabou de escrever retorna None em toda parte — execute recalc.py primeiro. (Uma fórmula cujo resultado é "" também retorna None.)
• Células mescladas: escreva apenas a âncora superior esquerda. Todas as outras células no intervalo são MergedCell cujo .value é somente leitura.
• .xlsm perde suas macros a menos que você passe keep_vba=True para load_workbook.
• Um nome de aba contendo espaço deve ser entre aspas em uma referência entre abas: ='Entradas de Suposições'!$B$5. Sem aspas, avalia para #VALOR!.

Modelos financeiros

A menos que o usuário diga o contrário, ou o arquivo existente já faça algo diferente.

Cor: texto azul (0,0,255) para entradas fixas e alavancas de cenário · preto para fórmulas · verde (0,128,0) para links para outra aba · vermelho (255,0,0) para links para outro arquivo · preenchimento amarelo (255,255,0) para suposições principais e células que o usuário deve preencher.

Números: moeda $#,##0, com a unidade nomeada no cabeçalho (Receita ($mm)) · zeros renderizados como -, inclusive em percentuais ($#,##0;($#,##0);-) · negativos entre parênteses · percentuais 0,0%, armazenados como frações (0,15 renderiza 15,0%; armazenar 15 renderiza 1500,0%) · múltiplos de valuation 0,0x · anos como texto ("2024", nunca 2.024).

Estrutura: toda suposição em sua própria célula rotulada, referenciada pelas fórmulas que a usam (=B5*(1+$B$6), nunca =B5*1,05) · fórmulas consistentes em todo período de projeção, já que uma célula editada isolada no meio de uma linha é o erro silencioso mais comum · proteja denominadores que podem ser zero.

Dependências

openpyxl, pandas, markitdown (pip, pré-instalados — instale apenas se uma importação falhar ou o comando estiver faltando) · LibreOffice (soffice, configurado automaticamente para ambientes isolados via scripts/office/soffice.py)