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 para dentro ou fora | pandas (read_excel, to_excel) |
| Vista rápida de uma planilha | markitdown arquivo.xlsx — ## NomeDaPlanilha por planilha; 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 passadas load_workbook — veja as armadilhas |
openpyxl,pandasemarkitdownestão pré-instalados — não executepip installprimeiro; escreva o script e importe diretamente. Só se uma importação falhar (ou o comandomarkitdownestiver faltando):pip installo pacote ausente.
Os caminhos de script abaixo são relativos ao diretório desta habilidade.
Requisitos para cada 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-o: 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 soletrou. Um redesign que calcula outra coisa falha, por mais elegante que seja.
- Documente cada 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: 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 que você cria 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 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 cada 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é que você recalcule, 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 [timeout_em_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
ele reteve — confie em total_errors, não no comprimento da lista). Corrija o que ele nomeou 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 não 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 que você espera, antes de construir uma grade.
Uma pasta de trabalho que vincula a outro arquivo perde esses vínculos se você a re-salvar com openpyxl e
depois recalcular. Tal fórmula lê ='[1]Returns Analysis'!$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 retém seus
dados. openpyxl remove esse valor ao salvar; LibreOffice então tem que resolver a referência para
real, falha, escreve #NAME? e deleta todos os vínculos. recalc.py se recusa a executar nesse estado
— copie os valores dessas células do original antes de salvá-los por cima (--force substitui,
e aceita a perda).
Escolhendo fórmulas que sobrevivem à verificação
LibreOffice implementa menos funções do que 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 openpyxl escreve sua fórmula no XML literalmente e o Excel armazena nomes pós-2007 prefixados (sua UI oculta o prefixo):_xlfn.TEXTJOIN,_xlfn.CONCAT,_xlfn.IFS,_xlfn.SWITCH,_xlfn.MAXIFS,_xlfn.MINIFS. Escritas nuas, cada uma produz#NAME?. - Nunca use
XLOOKUP,XMATCH,SORT,FILTER,UNIQUEouSEQUENCE. O runtime do LibreOffice 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 transbordo, 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 deduza 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 indicador 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 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=Trueem um arquivo que o openpyxl acabou de escrever retornaNoneem toda parte — executerecalc.pyprimeiro. (Uma fórmula cujo resultado é""também retornaNone.)- Células mescladas: escreva apenas a âncora superior esquerda. Todas as outras células no intervalo são um
MergedCellcujo.valueé somente leitura. .xlsmperde suas macros a menos que você passekeep_vba=Trueparaload_workbook.- Um nome de planilha contendo um espaço deve ser citado em uma referência entre planilhas:
='Assumptions Inputs'!$B$5. Sem aspas, avalia para#VALUE!.
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 vínculos a outra planilha · vermelho (255,0,0) para vínculos a outro arquivo ·
preenchimento amarelo (255,255,0) para suposições chave 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 avaliação 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 cada período de projeção, pois uma
célula editada isolada no meio da 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, pré-configurado para ambientes isolados via scripts/office/soffice.py)