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 — ## NomeDaPlanilha por planilha; também lê .xlsm. Sem coordenadas de célula, portanto não planeje edições a partir dele |
| Ler um modelo (fórmulas e valores) | duas passadas de load_workbook — veja as armadilhas |
openpyxl,pandasemarkitdownestão pré-instalados — não executepip installprimeiro; escreva o script e importe diretamente. Somente se uma importação falhar (ou o comandomarkitdownestiver faltando):pip installo pacote ausente.
Os caminhos dos scripts abaixo são relativos ao diretório desta habilidade.
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.pyrelatarerrors_found. Se você acha que um erro é anterior a você, prove: carregue o original comdata_only=Truee olhe para 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'] = '=SUM(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 guias exatos, cabeçalhos de coluna exatos e a fórmula que ele detalhou. Um redesign que calcula outra coisa falha, por mais elegante que seja.
- Documente toda suposição e número fixo onde o leitor possa vê-lo — um comentário de célula, ou uma célula adjacente no final de uma tabela. Cite uma fonte real quando existir (
Fonte: Formulário 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 breve legenda nomeando quais células editar, e uma linha de exemplo com valores realistas mostrando o formato esperado. Nunca adicione essa linha a um arquivo que você foi solicitado a editar.
- Editando um arquivo existente: siga suas convenções exatamente. Elas substituem todas as diretrizes aqui. Encontre primeiro suas células de entrada designadas — uma cor de fonte, preenchimento ou sombreamento distinto as marca — escreva apenas lá, e deixe toda fórmula existente intacta.
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 é lida como 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
O LibreOffice calcula cada fórmula, o arquivo é reescrito no lugar, 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 informa quantas ele
ocultou — confie em total_errors, não no comprimento da lista). Corrija o que ele nomeia 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, portanto 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 deslocado por 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 trazem os valores esperados, antes de construir uma grade.
Uma pasta de trabalho que vincula a outro arquivo perde esses links 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 planilha.
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; o LibreOffice então precisa resolver a referência de
verdade, falha, escreve #NAME? e deleta todos os links. recalc.py se recusa a executar nesse estado
— copie os valores dessas células do original antes de salvar por cima (--force substitui,
e aceita a perda).
Escolhendo fórmulas que sobrevivem à verificação
O LibreOffice implementa menos funções que o Excel, e uma que ele não consegue avaliar se torna um
literal #NAME? gravado no arquivo que você entrega.
- Prefira funções da era Excel-2007 —
SUMIFS,INDEX,MATCH,IFERROR,SUMPRODUCT— que não precisam de prefixo. - Seis funções pós-2007 funcionam, mas apenas com um prefixo
_xlfn., porque o openpyxl escreve sua fórmula no XML literalmente e o Excel armazena nomes pós-2007 prefixados (sua IU oculta o prefixo):_xlfn.TEXTJOIN,_xlfn.CONCAT,_xlfn.IFS,_xlfn.SWITCH,_xlfn.MAXIFS,_xlfn.MINIFS. Escritas sem prefixo, cada uma gera#NAME?. - Nunca use
XLOOKUP,XMATCH,SORT,FILTER,UNIQUEouSEQUENCE. O LibreOffice do runtime não consegue avaliá-las sob nenhum prefixo. Versões mais novas as avaliam, mas são funções de matriz com dispersão e um arquivo escrito pelo openpyxl não tem metadados de dispersão, então apenas a célula superior esquerda do intervalo recebe um valor — erecalc.pyrelatatotal_errors: 0no resultado truncado. UseINDEX/MATCHpara buscas, e classifique, filtre e remova duplicatas em Python antes de escrever as células. - Uma fórmula que o LibreOffice não conseguiu analisar é escrita de volta em minúsculas — um sinal rápido ao lado de um
#NAME?.
Armadilhas do openpyxl
- Ler um modelo requer duas cargas.
data_only=Trueproduz valores em cache com as fórmulas removidas; o padrão produz strings de fórmula sem valores. Uma única passada não pode fornecer 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=Trueem um arquivo que o openpyxl acabou de escrever retornaNoneem todo lugar — executerecalc.pyprimeiro. (Uma fórmula cujo resultado é""também é lida comoNone.)- Células mescladas: escreva apenas a âncora superior esquerda. Todas as outras células no intervalo são
MergedCellcujo.valueé somente leitura. .xlsmperde suas macros a menos que você passekeep_vba=Trueparaload_workbook.- Um nome de planilha contendo espaço deve ser entre aspas em uma referência entre planilhas:
='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 outra coisa.
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 planilha · 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
renderizam como -, inclusive em porcentagens ($#,##0;($#,##0);-) · negativos entre parênteses ·
porcentagens 0.0%, armazenadas como frações (0.15 renderiza 15.0%; armazenar 15 renderiza
1500.0%) · múltiplos de avaliação 0.0x · anos como texto ("2024", nunca 2,024).
Estrutura: toda suposição em sua própria célula nomeada, 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, pois uma
célula editada isolada no meio de uma linha é o erro silencioso mais comum · proteger 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)