Aprenda a manipular arquivos CSV em Python: leitura, escrita, DictReader, DictWriter, pandas e boas praticas para processar dados tabulares.

CSV: O que É e Como Funciona | Python Brasil | Python Brasil

O que e CSV?

CSV (Comma-Separated Values) e um formato de arquivo simples para armazenar dados tabulares em texto puro. Cada linha representa um registro e os campos sao separados por um delimitador — geralmente virgula, mas pode ser ponto-e-virgula, tab ou outro caractere. CSV e amplamente usado para importacao e exportacao de dados entre sistemas, planilhas e bancos de dados.

Python possui o modulo embutido csv que facilita a leitura e escrita de arquivos CSV, tratando automaticamente casos especiais como campos com virgulas, quebras de linha e aspas.

Leitura Basica

import csv

# Leitura simples com csv.reader
with open('dados.csv', 'r', encoding='utf-8') as arquivo:
    leitor = csv.reader(arquivo)
    cabecalho = next(leitor)  # primeira linha (cabecalho)
    print(f'Colunas: {cabecalho}')

    for linha in leitor:
        print(linha)  # cada linha e uma lista de strings

# Leitura com DictReader (cada linha vira dicionario)
with open('dados.csv', 'r', encoding='utf-8') as arquivo:
    leitor = csv.DictReader(arquivo)
    for registro in leitor:
        print(f"Nome: {registro['nome']}, Idade: {registro['idade']}")

Escrita Basica

import csv

# Escrita com csv.writer
dados = [
    ['nome', 'idade', 'cidade'],
    ['Ana', '28', 'Sao Paulo'],
    ['Bruno', '35', 'Rio de Janeiro'],
    ['Carla', '22', 'Belo Horizonte'],
]

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

# Escrita com DictWriter
registros = [
    {'nome': 'Ana', 'idade': 28, 'cidade': 'Sao Paulo'},
    {'nome': 'Bruno', 'idade': 35, 'cidade': 'Rio de Janeiro'},
    {'nome': 'Carla', 'idade': 22, 'cidade': 'Belo Horizonte'},
]

with open('saida.csv', 'w', encoding='utf-8', newline='') as arquivo:
    campos = ['nome', 'idade', 'cidade']
    escritor = csv.DictWriter(arquivo, fieldnames=campos)
    escritor.writeheader()
    escritor.writerows(registros)

Delimitadores e Dialetos

import csv

# CSV com ponto-e-virgula (comum em sistemas brasileiros)
with open('dados_br.csv', 'r', encoding='utf-8') as arquivo:
    leitor = csv.reader(arquivo, delimiter=';')
    for linha in leitor:
        print(linha)

# CSV com tabulacao (TSV)
with open('dados.tsv', 'r', encoding='utf-8') as arquivo:
    leitor = csv.reader(arquivo, delimiter='\t')
    for linha in leitor:
        print(linha)

# Registrando um dialeto customizado
csv.register_dialect('brasileiro', delimiter=';', quotechar='"',
                     quoting=csv.QUOTE_MINIMAL)

with open('dados_br.csv', 'r', encoding='utf-8') as arquivo:
    leitor = csv.reader(arquivo, dialect='brasileiro')
    for linha in leitor:
        print(linha)

# Ver dialetos disponiveis
print(csv.list_dialects())  # ['excel', 'excel-tab', 'unix']

Processamento de Dados

import csv
from collections import Counter

# Calcular estatisticas
with open('vendas.csv', 'r', encoding='utf-8') as arquivo:
    leitor = csv.DictReader(arquivo)
    registros = list(leitor)

# Total de vendas
total = sum(float(r['valor']) for r in registros)
print(f'Total: R$ {total:.2f}')

# Vendas por cidade
por_cidade = Counter(r['cidade'] for r in registros)
for cidade, qtd in por_cidade.most_common():
    print(f'{cidade}: {qtd} vendas')

# Filtrar e gravar novo CSV
vendas_sp = [r for r in registros if r['cidade'] == 'Sao Paulo']

with open('vendas_sp.csv', 'w', encoding='utf-8', newline='') as arquivo:
    escritor = csv.DictWriter(arquivo, fieldnames=registros[0].keys())
    escritor.writeheader()
    escritor.writerows(vendas_sp)

CSV com Pandas

Para arquivos maiores ou analises mais complexas, o pandas oferece funcionalidade muito mais poderosa.

import pandas as pd

# Leitura
df = pd.read_csv('dados.csv', encoding='utf-8')
print(df.head())
print(df.describe())

# Leitura com opcoes
df = pd.read_csv(
    'dados_br.csv',
    sep=';',
    encoding='utf-8',
    decimal=',',              # virgula como decimal (padrao brasileiro)
    parse_dates=['data'],     # interpretar coluna como data
    dtype={'cep': str},       # forcar tipo de coluna
)

# Filtrar e processar
vendas_grandes = df[df['valor'] > 1000]
por_mes = df.groupby(df['data'].dt.month)['valor'].sum()

# Gravar
df.to_csv('saida.csv', index=False, encoding='utf-8')
vendas_grandes.to_csv('grandes.csv', index=False, sep=';')

Tratamento de Erros e Casos Especiais

import csv

# Lidar com encoding
def ler_csv_seguro(caminho: str) -> list[dict]:
    """Tenta ler CSV com diferentes encodings."""
    encodings = ['utf-8', 'latin-1', 'cp1252']
    for enc in encodings:
        try:
            with open(caminho, 'r', encoding=enc) as f:
                return list(csv.DictReader(f))
        except UnicodeDecodeError:
            continue
    raise ValueError(f'Nao foi possivel ler {caminho} com nenhum encoding')

# Lidar com campos ausentes
with open('incompleto.csv', 'r', encoding='utf-8') as arquivo:
    leitor = csv.DictReader(arquivo, restval='N/A')
    for registro in leitor:
        nome = registro.get('nome', 'Desconhecido')
        idade = registro.get('idade', '0')
        print(f'{nome}: {idade}')

# Grandes arquivos — processar linha por linha
def processar_csv_grande(caminho: str):
    """Processa CSV grande sem carregar tudo na memoria."""
    with open(caminho, 'r', encoding='utf-8') as arquivo:
        leitor = csv.DictReader(arquivo)
        total = 0
        for i, registro in enumerate(leitor):
            total += float(registro.get('valor', 0))
            if (i + 1) % 100000 == 0:
                print(f'Processadas {i + 1} linhas...')
    return total

Erros Comuns

O erro mais frequente e esquecer o parametro newline='' ao abrir o arquivo para escrita, causando linhas em branco extras no Windows. Outro erro e assumir que o separador e virgula quando no Brasil frequentemente se usa ponto-e-virgula. Tambem e comum nao especificar o encoding, causando erros com caracteres acentuados. Tentar carregar arquivos CSV muito grandes inteiramente na memoria com list() em vez de processar linha por linha e outro problema recorrente.

Boas Praticas

Sempre especifique encoding='utf-8' e newline='' ao abrir arquivos CSV. Use DictReader e DictWriter para maior legibilidade. Para arquivos grandes, processe linha por linha. Para analise de dados, use pandas. Valide os dados ao ler de fontes externas. Documente o formato esperado do CSV (delimitador, encoding, colunas).

Quando Usar

CSV e ideal para troca de dados simples e tabulares entre sistemas, importacao e exportacao de planilhas, e armazenamento de dados que nao precisam de relacionamentos complexos. Para dados hierarquicos, prefira JSON. Para grandes volumes com consultas complexas, use um banco de dados.

CSV: O que É e Como Funciona | Python Brasil