Trabalhando com arquivos CSV

Conheça arquivos em formato de tabela e como manipulá-los com Python.

Você já sabe ler e escrever arquivos de texto simples. Agora vamos conhecer um formato muito usado no dia a dia de quem trabalha com dados: o CSV.

Pense em uma planilha do Excel ou do Google Sheets — com linhas e colunas. O CSV é uma forma de salvar essa mesma informação em um arquivo de texto simples, onde as colunas são separadas por vírgulas. É leve, fácil de abrir em qualquer programa e amplamente usado para exportar e importar dados.

O que é um arquivo CSV?

CSV significa Comma-Separated Values — em português, valores separados por vírgula. É exatamente isso: cada linha representa um registro, e os valores de cada coluna são separados por vírgula.

Exemplo de um arquivo alunos.csv:

nome,nota,situacao
Ana Silva,8.5,Aprovada
Bruno Costa,4.2,Reprovado
Carla Dias,7.0,Aprovada
Diego Nunes,5.5,Recuperação

A primeira linha geralmente é o cabeçalho — os nomes das colunas. As demais linhas são os dados.

Apesar do nome "vírgula", alguns arquivos CSV usam outros separadores, como ponto e vírgula (;) ou tabulação (\t). O separador mais comum no Brasil é o ;, pois a vírgula aqui é usada nos números decimais (ex.: 8,5). O módulo csv do Python suporta ambos.

O módulo csv do Python

O Python tem um módulo chamado csv feito especialmente para trabalhar com esse formato. Ele cuida de detalhes complicados para você, como campos com vírgula dentro de aspas ou quebras de linha no meio de um valor.

Para usá-lo, basta importar no início do código:

import csv

O import traz para o seu programa funcionalidades que existem no Python mas que não ficam carregadas automaticamente. O csv já vem instalado com o Python — não é preciso instalar nada.

Lendo um CSV com csv.reader

O csv.reader percorre o arquivo linha a linha, entregando cada linha como uma lista de valores:

import csv

with open("alunos.csv", "r", encoding="utf-8") as arquivo:
   leitor = csv.reader(arquivo)
   for linha in leitor:
       print(linha)

Saída:

['nome', 'nota', 'situacao']
['Ana Silva', '8.5', 'Aprovada']
['Bruno Costa', '4.2', 'Reprovado']
['Carla Dias', '7.0', 'Aprovada']
['Diego Nunes', '5.5', 'Recuperação']

Cada linha é uma lista com os valores daquele registro. Para acessar um valor específico, use o índice:

import csv

with open("alunos.csv", "r", encoding="utf-8") as arquivo:
   leitor = csv.reader(arquivo)
   next(leitor)  # Pula o cabeçalho

   for linha in leitor:
       nome = linha[0]
       nota = float(linha[1])
       situacao = linha[2]
       print(f"{nome}: {nota} — {situacao}")

Saída:

Ana Silva: 8.5 — Aprovada
Bruno Costa: 4.2 — Reprovado
Carla Dias: 7.0 — Aprovada
Diego Nunes: 5.5 — Recuperação

O next(leitor) avança o leitor uma linha sem processá-la — é uma forma prática de pular o cabeçalho. Sem ele, a primeira linha ("nome,nota,situacao") seria tratada como dados.

Caso seu arquivo use ; como separador, basta informar o parâmetro delimiter=';' ao criar o csv.reader ou csv.writer. Exemplo: csv.reader(arquivo, delimiter=';').

Lendo com csv.DictReader (mais fácil!)

O DictReader é uma alternativa ainda mais prática: em vez de listas, ele entrega cada linha como um dicionário, usando o cabeçalho como chaves automaticamente:

import csv

with open("alunos.csv", "r", encoding="utf-8") as arquivo:
   leitor = csv.DictReader(arquivo)
   for linha in leitor:
       print(linha)

Saída:

{'nome': 'Ana Silva', 'nota': '8.5', 'situacao': 'Aprovada'}
{'nome': 'Bruno Costa', 'nota': '4.2', 'situacao': 'Reprovado'}
{'nome': 'Carla Dias', 'nota': '7.0', 'situacao': 'Aprovada'}
{'nome': 'Diego Nunes', 'nota': '5.5', 'situacao': 'Recuperação'}

Agora você acessa cada valor pelo nome da coluna, sem precisar decorar índices:

import csv

with open("alunos.csv", "r", encoding="utf-8") as arquivo:
   leitor = csv.DictReader(arquivo)
   for linha in leitor:
       nome = linha["nome"]
       nota = float(linha["nota"])
       situacao = linha["situacao"]
       print(f"{nome}: {nota} — {situacao}")

O DictReader já pula o cabeçalho automaticamente e o usa como chave do dicionário. Em geral, é a forma mais legível e recomendada para ler CSVs. Isso não quer dizer que o csv.reader seja obsoleto. Ele ainda é útil quando o arquivo não tem cabeçalho ou quando se trabalha com arquivos muito grandes (pois consome menos memória).

Escrevendo um CSV com csv.writer

Para criar um arquivo CSV, usamos o csv.writer. O método writerow() escreve uma linha por vez, e o writerows() escreve várias de uma vez a partir de uma lista:

import csv

alunos = [
   ["nome", "nota", "situacao"],
   ["Ana Silva", 8.5, "Aprovada"],
   ["Bruno Costa", 4.2, "Reprovado"],
   ["Carla Dias", 7.0, "Aprovada"],
]

with open("alunos.csv", "w", encoding="utf-8", newline="") as arquivo:
   escritor = csv.writer(arquivo)
   escritor.writerows(alunos)

print("Arquivo CSV criado com sucesso!")

O parâmetro newline="" deve ser usado sempre ao escrever CSVs, para garantir que as quebras de linha sejam tratadas corretamente.

Escrevendo com csv.DictWriter

Assim como o DictReader facilita a leitura, o DictWriter facilita a escrita usando dicionários:

import csv

alunos = [
   {"nome": "Ana Silva", "nota": 8.5, "situacao": "Aprovada"},
   {"nome": "Bruno Costa", "nota": 4.2, "situacao": "Reprovado"},
   {"nome": "Carla Dias", "nota": 7.0, "situacao": "Aprovada"},
]

campos = ["nome", "nota", "situacao"]

with open("alunos.csv", "w", encoding="utf-8", newline="") as arquivo:
   escritor = csv.DictWriter(arquivo, fieldnames=campos)
   escritor.writeheader()   # Escreve a linha de cabeçalho
   escritor.writerows(alunos)

print("Arquivo CSV criado com sucesso!")

O writeheader() escreve automaticamente a primeira linha com os nomes das colunas definidos em fieldnames.

Exemplo prático: sistema de notas

Vamos criar um programa completo que registra notas de alunos em um CSV e exibe um relatório:

import csv

ARQUIVO = "notas.csv"

def salvar_aluno(nome, nota):
   situacao = "Aprovado" if nota >= 7 else ("Recuperação" if nota >= 5 else "Reprovado")
   with open(ARQUIVO, "a", encoding="utf-8", newline="") as arquivo:
       escritor = csv.writer(arquivo)
       escritor.writerow([nome, nota, situacao])
   print(f"Aluno '{nome}' registrado.")

def criar_cabecalho():
   with open(ARQUIVO, "w", encoding="utf-8", newline="") as arquivo:
       escritor = csv.writer(arquivo)
       escritor.writerow(["nome", "nota", "situacao"])

def exibir_relatorio():
   print("\n=== Relatório de Notas ===")
   with open(ARQUIVO, "r", encoding="utf-8") as arquivo:
       leitor = csv.DictReader(arquivo)
       alunos = list(leitor)

   if not alunos:
       print("Nenhum aluno registrado.")
       return

   for aluno in alunos:
       print(f"{aluno['nome']}: {aluno['nota']} — {aluno['situacao']}")

   notas = [float(a["nota"]) for a in alunos]
   media = sum(notas) / len(notas)
   print(f"\nMédia da turma: {media:.1f}")
   print(f"Total de alunos: {len(alunos)}")

# Programa principal
criar_cabecalho()

salvar_aluno("Ana Silva", 8.5)
salvar_aluno("Bruno Costa", 4.2)
salvar_aluno("Carla Dias", 7.0)
salvar_aluno("Diego Nunes", 5.5)

exibir_relatorio()

Saída:

Aluno 'Ana Silva' registrado.
Aluno 'Bruno Costa' registrado.
Aluno 'Carla Dias' registrado.
Aluno 'Diego Nunes' registrado.

=== Relatório de Notas ===
Ana Silva: 8.5 — Aprovado
Bruno Costa: 4.2 — Reprovado
Carla Dias: 7.0 — Aprovado
Diego Nunes: 5.5 — Recuperação

Média da turma: 6.3
Total de alunos: 4

Conteúdo do arquivo notas.csv gerado:

nome,nota,situacao
Ana Silva,8.5,Aprovado
Bruno Costa,4.2,Reprovado
Carla Dias,7.0,Aprovado
Diego Nunes,5.5,Recuperação

A linha notas = [float(a["nota"]) for a in alunos] é chamada de list comprehension — uma forma compacta de criar uma lista a partir de outra. Ela percorre cada aluno e extrai o valor da nota já convertido para número. Você verá esse recurso com mais detalhes em lições futuras.

O que aprendemos nesta lição

Nesta lição, você aprendeu que:

  • CSV (Comma-Separated Values) é um formato de arquivo de texto que organiza dados em linhas e colunas separadas por vírgula (ou outro delimitador).
  • O módulo csv do Python é importado com import csv e oferece ferramentas prontas para ler e escrever esse formato.
  • O csv.reader lê o arquivo linha a linha, entregando cada linha como uma lista de valores.
  • O csv.DictReader entrega cada linha como um dicionário, usando o cabeçalho como chave — forma mais legível e recomendada para leitura.
  • O csv.writer com writerow() e writerows() escreve linhas no formato CSV.
  • O csv.DictWriter escreve a partir de dicionários, com writeheader() para gerar o cabeçalho automaticamente.
  • O parâmetro newline="" deve ser usado ao escrever CSVs para evitar linhas em branco extras.
  • O next(leitor) pula uma linha do iterador — útil para ignorar o cabeçalho ao usar csv.reader.