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

openpyxl, pandas e markitdown vêm 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.

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 toda parte, a menos que o usuário diga o contrário.
• Zero erros de fórmula. Nunca envie 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 essa célula. Um erro que você introduziu se parece exatamente com um que você herdou.
• Use fórmulas, nunca resultados codificados. Escreva sheet['B10'] = '=SUM(B2:B9)', não o total computado 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 eles descreveram. Um redesenho que calcula algo diferente falha, por mais elegante que seja.
• Documente cada suposição e número codificado onde o leitor poderá vê-lo — um comentário de célula, ou uma célula adjacente no final de uma tabela. Cite uma fonte real quando existir (Source: Company 10-K, FY2024, Page 45, Revenue Note, [SEC EDGAR URL]); 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 de valores realistas mostrando o formato esperado. Nunca adicione tal linha a um arquivo que você foi solicitado a editar.
• Editando um arquivo existente: combine suas convenções exatamente. Elas substituem todas as diretrizes aqui. Encontre suas células de entrada designadas primeiro — uma cor de fonte distinta, preenchimento ou sombreamento as marca — escreva apenas lá, e deixe todas as fórmulas existentes intocadas.

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

O openpyxl escreve fórmulas como strings com nenhum valor em cache. Até que você recalcule, cada célula de fórmula volta a ser None para qualquer coisa que leia valores em cache — pandas, load_workbook(data_only=True) e a maioria dos visualizadores.

python scripts/recalc.py output.xlsx [timeout_seconds]   # default 30

O LibreOffice computa todas as fórmulas, 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 quantos ele retirou — confie em total_errors, não no comprimento da lista). Corrija o que ele nomeia e execute-o novamente. JSON com uma chave error em vez de status significa que nada foi recalculado, e apenas esse caso sai com um código diferente de zero — errors_found sai com 0, então nunca trate uma saída limpa como uma planilha limpa.

Um recálculo verde prova que suas fórmulas avaliam, não que estão corretas. Um intervalo com um número a mais ou a menos ou uma referência à linha errada resulta em um arquivo limpo e 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 se vincula a outro arquivo perde esses vínculos se você a salvar novamente 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 contém seus dados. O openpyxl remove esse valor ao salvar; o LibreOffice então tem que resolver a referência de verdade, falha, escreve #NAME? e exclui todos os vínculos. recalc.py se recusa a executar nesse estado — copie os valores dessas células do original antes de salvá-las por cima (--force substitui e aceita a perda).

Escolhendo fórmulas que sobrevivem à verificação

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

• Prefira funções da era Excel-2007 — SUMIFS, INDEX, MATCH, IFERROR, SUMPRODUCT — que não precisam de prefixo.

…