Escritor de Relatórios CSV (CSV Report Writer)
Use esta skill quando um trabalho produzir uma lista de linhas de resultados e você quiser um CSV limpo para planilhas, além de uma tabela Markdown para um comentário em PR ou resumo no Telegram — a partir de uma única definição de colunas, para que as duas saídas nunca fiquem dessincronizadas. Você declara as colunas (chave, cabeçalho, formatador opcional) uma vez; o helper emite ambas, em uma ordem de colunas estável, com citações CSV adequadas e escape de pipes para Markdown. Nada de pandas.
Quando invocar
- O usuário diz: "escreva os resultados em um CSV", "exporte um relatório", "crie uma tabela Markdown disso", "salve a saída da execução como uma planilha".
- O código na conversa tem uma
list[dict](ou lista de objetos) que atualmente imprime de forma ad hoc.
Quando NÃO invocar
- Os dados precisam de trabalho real com dataframes — junções, agrupamentos, pivôs; recorra a pandas/polars.
- Um único resultado escalar, onde um CSV/tabela é exagero.
Exemplo concreto
Entrada do usuário:
Tenho uma lista de tokens escaneados com uma pontuação e um preço. Salve um CSV e também me dê uma tabela markdown para o resumo do Telegram.
Saída:
# Copie assets/report.py para o seu projeto, depois:
from report import Column, write_csv, to_markdown
columns = [
Column("symbol", "Símbolo"),
Column("score", "Pontuação", fmt=lambda v: f"{v:.1f}"),
Column("price_usd", "Preço", fmt=lambda v: f"${v:,.4f}"),
]
rows = [
{"symbol": "ABC", "score": 8.4, "price_usd": 0.0123},
{"symbol": "XYZ", "score": 6.1, "price_usd": 1.5},
]
write_csv("scan.csv", columns, rows) # CSV com esquema, ordem estável de colunas
print(to_markdown(columns, rows)) # mesmas colunas, tabela Markdown
Ambas as saídas usam exatamente as mesmas colunas na mesma ordem, então o CSV e a tabela do resumo sempre concordam.
Padrão a aplicar
- Declare cada
Column(key, header, fmt=...)uma vez; ambos os escritores consomem a mesma lista, então cabeçalhos e ordem permanecem sincronizados. - Mantenha a ordem das colunas estável e explícita — não dependa da ordem de inserção do dicionário de linhas arbitrárias.
- Deixe o
fmtcallable cuidar da apresentação (moeda, arredondamento); armazene valores brutos nos dicionários de linha. - Use
csv.writerpara citação correta; escape|e novas linhas na tabela Markdown para que ela nunca quebre o layout. - Trate uma chave ausente como célula vazia em vez de causar erro, para que linhas parciais ainda sejam reportadas.
Referência: assets/report.py.
Fonte
Destilado do uso em produção nos projetos de automação do autor. v1.0.0. Veja também: [[pr-body-formatter]], [[sqlite-state]], [[telegram-alerter]].
→ Construa o bot executável completo com o Trawlkit.