🌗 ← Índice

🐍 Python P23 — Projeto: Leitor de Planilhas (openpyxl + pandas)

Data: 14/08/2026

Nível: Projeto (Mês 3 — Projetos Reais)

🎯 Objetivos

• Ler planilhas Excel com `openpyxl` e `pandas`
• Escrever e modificar planilhas
• Analisar dados de planilha (totais, médias, agrupamentos)
• **Projeto**: CLI que lê uma planilha e gera um relatório

📖 Teoria

Instalar

pip install openpyxl pandas

Ler com openpyxl (sem pandas)

from openpyxl import load_workbook

workbook = load_workbook("vendas.xlsx")
planilha = workbook.active          # primeira aba

for linha in planilha.iter_rows(values_only=True):
    print(linha)

Ler com pandas (muito mais fácil)

import pandas as pd

df = pd.read_excel("vendas.xlsx")
print(df.head())
print(df.columns.tolist())
print(df["valor"].sum())

Criar planilha do zero

from openpyxl import Workbook

workbook = Workbook()
planilha = workbook.active
planilha.title = "Vendas"

planilha.append(["produto", "quantidade", "valor"])
planilha.append(["Caneta", 10, 15.0])
planilha.append(["Caderno", 5, 30.0])

workbook.save("vendas.xlsx")

Modificar planilha existente

from openpyxl import load_workbook

workbook = load_workbook("vendas.xlsx")
planilha = workbook.active
planilha.append(["Borracha", 3, 6.0])       # adiciona linha
planilha["A1"] = "Produto"                   # altera célula
workbook.save("vendas.xlsx")

Análise rápida com pandas

import pandas as pd

df = pd.read_excel("vendas.xlsx")

print(df.groupby("produto")["valor"].sum())     # total por produto
print(df["valor"].mean())                        # média
print(df.sort_values("valor", ascending=False))  # ranking

🏗️ O Projeto: `leitor_planilhas.py`

CLI que lê uma planilha e imprime um relatório:

python leitor_planilhas.py vendas.xlsx
# 📊 Relatório de vendas.xlsx
# Total de linhas: 4
# Colunas: produto, quantidade, valor
# Total vendido: R$ 51.00
# Média por linha: R$ 17.00
# Produto mais caro: Caderno (R$ 30.00)

import argparse
import pandas as pd


def gerar_relatorio(caminho: str) -> str:
    df = pd.read_excel(caminho)

    linhas = [
        f"📊 Relatório de {caminho}",
        f"Total de linhas: {len(df)}",
        f"Colunas: {', '.join(df.columns)}",
    ]

    # se existir coluna numérica chamada valor, calcula totais
    if "valor" in df.columns:
        linhas.append(f"Total: R$ {df['valor'].sum():.2f}")
        linhas.append(f"Média: R$ {df['valor'].mean():.2f}")
        if "produto" in df.columns:
            mais_caro = df.loc[df["valor"].idxmax()]
            linhas.append(f"Mais caro: {mais_caro['produto']} (R$ {mais_caro['valor']:.2f})")

    return "\n".join(linhas)


def main():
    parser = argparse.ArgumentParser(description="Leitor de planilhas Excel")
    parser.add_argument("arquivo", help="Caminho da planilha .xlsx")
    parser.add_argument("--aba", default=None, help="Nome da aba (padrão: primeira)")
    parser.add_argument("--gravar", default=None, help="Salva relatório em arquivo")
    args = parser.parse_args()

    try:
        df = pd.read_excel(args.arquivo, sheet_name=args.aba)
    except FileNotFoundError:
        print(f"❌ Arquivo não encontrado: {args.arquivo}")
        return
    except Exception as erro:
        print(f"❌ Erro ao ler planilha: {erro}")
        return

    relatorio = gerar_relatorio(args.arquivo)
    print(relatorio)

    if args.gravar:
        with open(args.gravar, "w", encoding="utf-8") as f:
            f.write(relatorio)
        print(f"\nRelatório salvo em {args.gravar}")


if __name__ == "__main__":
    main()

✍️ Exercícios

1. 1. Crie uma planilha `gastos.xlsx` com 3 colunas (categoria, descricao, valor) e 5 linhas usando openpyxl.
2. 2. Use pandas para calcular o total por categoria e imprimir.
3. 3. Adicione ao CLI a opção `--top N` que mostra as N linhas de maior valor.

🧪 Desafio

Estenda o CLI com exportação para CSV e JSON:

python leitor_planilhas.py vendas.xlsx --csv saida.csv
python leitor_planilhas.py vendas.xlsx --json saida.json

Requisitos:

• `--csv`: grava o DataFrame original em CSV
• `--json`: grava o DataFrame em JSON (`df.to_json(orient="records", force_ascii=False)`)

✅ Correção (desafio)

# no main(), adicione:
parser.add_argument("--csv", default=None, help="Exporta dados para CSV")
parser.add_argument("--json", default=None, help="Exporta dados para JSON")

# após o relatório:
if args.csv:
    df.to_csv(args.csv, index=False)
    print(f"Dados exportados para {args.csv}")

if args.json:
    df.to_json(args.json, orient="records", force_ascii=False, indent=2)
    print(f"Dados exportados para {args.json}")

💡 Dica real: orient="records" gera uma lista de dicionários — o formato ideal para consumir em APIs ou no seu RAG.

HB Estudos · ← Voltar ao índice de Python