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)
Visualização rápida de 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 dela
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 uv pip install primeiro; escreva o script e importe diretamente. Apenas se uma importação falhar (ou o comando markitdown estiver ausente): uv pip install do pacote faltante.

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

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.py relatar errors_found. Se você acha que um erro é anterior a você, prove-o: carregue o original com data_only=True e olhe para aquela célula. Um erro que você introduziu parece exatamente com 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 especificou. 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ê-los — um comentário de célula, ou uma célula adjacente no final de uma tabela. Cite uma fonte real quando ela 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 breve legenda 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. Primeiro encontre suas células de entrada designadas — uma cor de fonte, preenchimento ou sombreamento distinto as marca — escreva apenas lá, e deixe todas as fórmulas existentes intocadas.

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

openpyxl escreve fórmulas como strings sem valores em cache. Até você recalcular, cada 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 cada fórmula, o arquivo é reescrito no local, e você obtém 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 nomeia e execute novamente. JSON com uma chave error em vez de status significa que nada foi recalculado, e apenas nesse caso a saída é 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 com erro de deslocamento 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 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 salvá-lo (--force substitui e aceita a perda).

Escolhendo fórmulas que sobrevivem à verificação

LibreOffice implementa menos funções que o Excel, e uma que ele não consegue avaliar se torna um literal #NAME? embutido 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 esconde o prefixo): _xlfn.TEXTJOIN, _xlfn.CONCAT, _xlfn.IFS, _xlfn.SWITCH, _xlfn.MAXIFS, _xlfn.MINIFS. Escritas sem prefixo, cada uma resulta em #NAME?.
• Nunca use XLOOKUP, XMATCH, SORT, FILTER, UNIQUE ou SEQUENCE. O LibreOffice do tempo de execução não consegue avaliá-las sob nenhum prefixo. Versões mais novas até as avaliam, mas são funções de matriz de derramamento e um arquivo escrito por openpyxl não tem metadados de derramamento, então apenas a célula superior esquerda do intervalo obtém um valor — e recalc.py relata total_errors: 0 no resultado truncado. Use INDEX/MATCH para buscas, e ordene, filtre e deduplicque 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 produz valores em cache com as fórmulas sumidas; o padrão produz strings de fórmula sem valores. Uma 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=True em um arquivo que openpyxl acabou de escrever retorna None em todos os lugares — execute recalc.py primeiro. (Uma fórmula cujo resultado é "" também retorna None.)
• Células mescladas: escreva apenas o âncora superior esquerdo. Cada outra célula no intervalo é um 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 Suposições'!$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 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: cada 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 todos os períodos de projeção, pois 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 ausente) · LibreOffice (soffice, configurado automaticamente para ambientes em sandbox via scripts/office/soffice.py)

---

Esta skill é criada e mantida por Anthropic. Incluída aqui inalterada, exceto pelos metadados do frontmatter; consulte LICENSE.txt para os termos.