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 — ## NomeDaPlanilha por planilha; lê .xlsm também. Sem coordenadas de célula, então não planeje edições a partir dele
Ler um modelo (fórmulas e valores)	duas passadas 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. Apenas se uma importação falhar (ou o comando markitdown estiver ausente): pip install o pacote ausente.

Os 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 relatar errors_found. Se você acha que um erro é anterior a você, prove: carregue o original com data_only=True e 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 exatos de abas, cabeçalhos de coluna exatos e a fórmula que ele explicitou. Um redesign que calcula algo diferente falha, por mais elegante que seja.
• Documente toda suposição e número fixo onde o leitor puder ver — 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 que você cria 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.
• Ao editar 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 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 é lida como None por 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 toda 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 diz quantos foram omitidos — 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 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 certas. Um intervalo com erro 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 retornam 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 então recalcular. Tal fórmula lê como ='[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 sobre ele (--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 #NAME? literal 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 com prefixo (sua UI oculta o prefixo): _xlfn.TEXTJOIN, _xlfn.CONCAT, _xlfn.IFS, _xlfn.SWITCH, _xlfn.MAXIFS, _xlfn.MINIFS. Escritas sem, cada uma resulta em #NAME?.
• Nunca use XLOOKUP, XMATCH, SORT, FILTER, UNIQUE ou SEQUENCE. O LibreOffice do ambiente de execução não consegue avaliá-las sob nenhum prefixo. Versões mais novas as avaliam, mas são funções de matriz transbordante 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 — e recalc.py relata total_errors: 0 no resultado truncado. Use INDEX/MATCH para consultas, e ordene, filtre e deduplique 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=True fornece valores em cache com as fórmulas removidas; o padrão fornece strings de fórmula sem valores. Uma única passagem 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=True em um arquivo que o openpyxl acabou de escrever retorna None em tudo — execute recalc.py primeiro. (Uma fórmula cujo resultado é "" também é lida como None.)
• Células mescladas: escreva apenas o canto superior esquerdo. 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 planilha contendo espaço deve ser citado em uma referência entre planilhas: ='Entradas de Premissas'!$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 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 planilha · vermelho (255,0,0) para links para outro arquivo · preenchimento amarelo (255,255,0) para premissas-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 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 valuation 0.0x · anos como texto ("2024", nunca 2.024).

Estrutura: cada premissa 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, pois uma única célula editada 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 ausente) · LibreOffice (soffice, pré-configurado para ambientes isolados via scripts/office/soffice.py)