[Python] O Guia Completo do Módulo csv! Explicando os Erros Comuns de Iniciantes ao Ler e Escrever CSV
Para executar Python no prompt de comando ou PowerShell no seu PC, é necessário baixar e instalar o Python.
Se ainda não o fez, consulte o artigo Instalação do Python e configuração do ambiente de desenvolvimento para instalar o Python.
"Quero manipular arquivos CSV na programação, mas não sei por onde começar..."
Olá! Sou o administrador deste site e, até poucos meses atrás, eu era um completo iniciante, assim como você. Com base na minha experiência de criar dois sites sozinho em um mês e meio com a ajuda de IA, posso dizer com certeza: a manipulação de arquivos CSV é uma habilidade inevitável e incrivelmente útil no desenvolvimento web!
Na verdade, esse conhecimento sobre CSV me ajudou demais quando criei funcionalidades para gerenciar dados de formulários de contato ou para carregar listas de produtos em massa.
Neste artigo, com base na minha experiência real (e em muitas falhas...), vou explicar como ler e escrever arquivos CSV livremente usando o módulo `csv` do Python da maneira mais clara possível. Evitarei ao máximo o jargão técnico. Ao final deste artigo, você será um mestre em CSV!
Aquecimento: Vamos Preparar um Arquivo CSV de Exemplo
Primeiro, vamos preparar um arquivo CSV para praticar. Copie o conteúdo abaixo e salve-o em seu PC com o nome `membros.csv`. O segredo é salvá-lo com a codificação UTF-8. (Ao salvar no Bloco de Notas, deve haver uma opção para escolher a codificação).
Este arquivo simula uma lista de membros de um site fictício.
id,nome,email
1,João da Silva,joao.silva@example.com
2,Maria Santos,maria.santos@example.com
3,José Oliveira,jose.oliveira@example.comO Básico: Lendo um Arquivo CSV (`csv.reader`)
A primeira coisa a fazer é ler o conteúdo de um arquivo CSV com Python. Vamos ler o arquivo `membros.csv` que acabamos de criar e exibir seu conteúdo no console.
Ok, vamos direto ao código! Copie, cole e execute. A maneira mais fácil é criar um arquivo Python no mesmo diretório que o `membros.csv` e executá-lo.
<!-- Código Python com escape de HTML -->
import csv
# --- Meu ponto de dificuldade nº 1: Sempre especifique a codificação de caracteres! ---
# No Windows, se você não especificar uma codificação, ele pode tentar
# abrir o arquivo com Shift_JIS e causar um erro.
# Use `encoding='utf-8'` como um amuleto da sorte.
with open('membros.csv', mode='r', encoding='utf-8') as f:
# Passar o arquivo para o csv.reader retorna um objeto leitor que analisa o CSV
reader = csv.reader(f)
# Você pode processar linha por linha em um loop
for row in reader:
print(row)
# Resultado da Execução:
# ['id', 'nome', 'email']
# ['1', 'João da Silva', 'joao.silva@example.com']
# ['2', 'Maria Santos', 'maria.santos@example.com']
# ['3', 'José Oliveira', 'jose.oliveira@example.com']
E aí, como foi? O conteúdo do CSV apareceu no seu terminal?
O ponto principal a notar é que cada linha é obtida como uma lista (o que está entre `[]`). Dados separados por vírgula, como `['1', 'João da Silva', 'joao.silva@example.com']`, tornam-se elementos da lista.
Uma breve explicação: o que é `with open(...) as f:`?
Esta é a "boa prática" ao lidar com arquivos. Ao escrever desta forma, o Python fecha automaticamente o arquivo para você ao sair do bloco `with`. Esquecer de fechar um arquivo pode levar a problemas inesperados, como vazamentos de memória, então use sempre o `with`!
[Minha História de Fracasso nº 1] O Inferno do Texto Corrompido e o `encoding`
A primeira vez que fiz isso, especialmente em um PC com Windows, meu console ficou cheio de símbolos sem sentido (texto corrompido). A causa era a codificação de caracteres. Você precisa dizer ao PC em qual regra de idioma (codificação) o arquivo está escrito, senão ele não consegue lê-lo corretamente.
A solução é adicionar `encoding='utf-8'` aos argumentos da função `open()`. `UTF-8` é o padrão mundial de codificação de caracteres, e usá-lo resolverá a maioria dos problemas. É um conhecimento essencial no mundo da web, então crie o hábito!
O Básico (Parte 2): Escrevendo em um Novo Arquivo CSV (`csv.writer`)
O próximo passo é a escrita de dados. Vamos tentar salvar dados de uma lista criada em Python em um novo arquivo CSV. Por exemplo, imagine escrever novos dados de membros em um arquivo chamado `novos_membros.csv`.
<!-- Código Python com escape de HTML -->
import csv
# Dados a serem escritos (uma lista de listas)
new_data = [
['4', 'Pedro Costa', 'pedro.costa@example.com'],
['5', 'Ana Souza', 'ana.souza@example.com']
]
# --- Meu ponto de dificuldade nº 2: Use newline='' para as linhas em branco misteriosas ---
# mode='w' para o modo de escrita. Se o arquivo não existir, ele será criado.
# Sem newline='', você terá uma linha em branco misteriosa entre cada linha no Windows!
with open('novos_membros.csv', mode='w', encoding='utf-8', newline='') as f:
writer = csv.writer(f)
# Para escrever uma única linha, use writerow
writer.writerow(['id', 'nome', 'email']) # Linha de cabeçalho
# Para escrever várias linhas de uma vez, use writerows
writer.writerows(new_data)
print('O arquivo novos_membros.csv foi criado!')
Ao executar este código, um arquivo chamado `novos_membros.csv` deve ser criado no mesmo diretório. Abra-o. Os dados estão escritos corretamente, certo?
[Minha História de Fracasso nº 2] Quem é você?! A Linha em Branco Misteriosa e o `newline=''`
Este é outro problema que me custou meio dia. Tente executar o código acima depois de remover `newline=''`. E então? Seu arquivo CSV não ficou cheio de irritantes linhas em branco a cada duas linhas?
Esta é uma armadilha comum causada por diferenças na forma como os sistemas operacionais lidam com os caracteres de nova linha. Vou pular a explicação detalhada (eu perguntei a uma IA e fiquei tipo, "Entendi, mas não entendi!"), mas a solução é simples.
Ao escrever em um CSV, sempre inclua `newline=''` na função `open()`!
Esta é uma prática superimportante que está até na documentação oficial do Python, que diz: "Se você estiver usando o módulo csv, deve sempre especificá-lo". Apenas memorize como um feitiço mágico.
Dica Avançada nº 1: Usar Dicionários Torna seu Código Legível em Nível Divino (`DictReader` e `DictWriter`)
Com o `reader` básico, você tinha que gerenciar os dados pelo número do índice, como `row[1]` ou `row[2]`. Quando o número de colunas aumenta, você acaba se perguntando: "Espere, qual era o índice do endereço de e-mail mesmo...?"
É aí que entra o `DictReader`! Ele permite que você obtenha cada linha de dados como um "dicionário". Isso significa que você pode acessar os dados pelo nome do cabeçalho, como `row['nome']` ou `row['email']`. Genial, não é?
Leitura: `DictReader`
<!-- Código Python com escape de HTML -->
import csv
with open('membros.csv', mode='r', encoding='utf-8') as f:
# Basta usar o DictReader! Fácil!
reader = csv.DictReader(f)
for row in reader:
# Você pode acessar o nome com a chave 'nome' e o email com a chave 'email'!
print(f"Nome: {row['nome']}, Email: {row['email']}")
# Resultado da Execução:
# Nome: João da Silva, Email: joao.silva@example.com
# Nome: Maria Santos, Email: maria.santos@example.com
# Nome: José Oliveira, Email: jose.oliveira@example.com
Viu? `row['nome']` é esmagadoramente mais fácil de entender do que `row[1]`, não é? Desta forma, quando você revisar seu código mais tarde, ficará imediatamente óbvio o que ele está fazendo.
Escrita: `DictWriter`
Se você pode ler com um dicionário, vai querer escrever com um também. Claro, existe o `DictWriter`. Se você preparar uma lista de dicionários, pode escrevê-la em um CSV.
<!-- Código Python com escape de HTML -->
import csv
# Prepare os dados como uma lista de dicionários
dict_data = [
{'id': '6', 'nome': 'Lucas Pereira', 'email': 'lucas.pereira@example.com'},
{'id': '7', 'nome': 'Julia Ferreira', 'email': 'julia.ferreira@example.com'}
]
# A lista de cabeçalhos (importante!)
fieldnames = ['id', 'nome', 'email']
with open('dict_membros.csv', mode='w', encoding='utf-8', newline='') as f:
# Passe o arquivo e os cabeçalhos (fieldnames) para o DictWriter
writer = csv.DictWriter(f, fieldnames=fieldnames)
# Não se esqueça de escrever o cabeçalho primeiro!
writer.writeheader()
# Escreva a lista de dicionários de uma vez
writer.writerows(dict_data)
print('O arquivo dict_membros.csv foi criado!')
Há duas coisas com as quais você deve ter cuidado ao usar o `DictWriter`:
- Ao inicializar o `csv.DictWriter()`, você precisa passar os `fieldnames` (a lista de cabeçalhos).
- Antes de escrever os dados, você precisa escrever a linha de cabeçalho com `writer.writeheader()`.
Se você esquecer isso, não será escrito corretamente, então tome cuidado! (Claro, eu cometi esse erro.)
Dica Avançada nº 2: Anexando Dados a um CSV Existente
"Quero adicionar novas informações de membros à lista toda vez que um formulário de contato for enviado." Nesse caso, você abre o arquivo no "modo de acréscimo" (append).
É super fácil. Basta alterar o `mode` em `open()` de `'w'` (write) para `'a'` (append).
<!-- Código Python com escape de HTML -->
import csv
# Novos dados de membro para anexar
new_member = ['8', 'Mariana Almeida', 'mariana.almeida@example.com']
# Basta alterar o modo para 'a' (append)!
# Como estamos anexando, não se esqueça de newline='' e encoding='utf-8'.
with open('membros.csv', mode='a', encoding='utf-8', newline='') as f:
writer = csv.writer(f)
writer.writerow(new_member)
print('Dados anexados a membros.csv!')
Depois de executar este código, abra `membros.csv` novamente. Você deve ver as informações de Mariana Almeida adicionadas no final. Ao anexar com `DictWriter`, tome cuidado para não chamar `writeheader()`. Caso contrário, um cabeçalho será adicionado toda vez que você anexar dados.
[Experimente ao Vivo] Vamos Brincar com CSV no Navegador!
Ok, já vimos muito código até agora. Mas a melhor maneira de aprender é executando e mexendo você mesmo.
Então, desta vez, preparei uma demonstração interativa usando "PyScript", uma tecnologia mágica que permite executar Python no seu navegador, para que você possa manipular dados CSV em tempo real!
Copie todo o código HTML abaixo e salve-o em seu PC com um nome como `csv_test.html`. Em seguida, abra esse arquivo em seu navegador da web. Assim, seu navegador se transformará em um editor de CSV!
<!-- Código HTML com escape de HTML -->
<!DOCTYPE html>
<html lang="pt">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Demonstração Interativa do Módulo CSV do Python</title>
<!-- Carregando o PyScript -->
<link rel="stylesheet" href="https://pyscript.net/releases/2024.1.1/core.css" />
<script type="module" src="https://pyscript.net/releases/2024.1.1/core.js"></script>
<!-- Estilos Simples -->
<style>
body { font-family: sans-serif; background-color: #202124; color: #e8eaed; padding: 2em; line-height: 1.6; }
h1, h2 { color: #8ab4f8; }
textarea, button {
border: 1px solid #5f6368;
background-color: #3c4043;
color: #e8eaed;
border-radius: 4px;
padding: 0.5em 1em;
}
textarea { width: 100%; height: 150px; margin-bottom: 1em; font-family: monospace; }
button { cursor: pointer; margin-right: 1em; }
button:hover { background-color: #5f6368; }
table { border-collapse: collapse; width: 100%; margin-top: 1em; }
th, td { border: 1px solid #5f6368; padding: 8px; text-align: left; }
th { background-color: #3c4043; }
pre { background-color: #1e1e1e; padding: 1em; border-radius: 4px; white-space: pre-wrap; }
</style>
</head>
<body>
<h1>Experimente o Módulo CSV do Python no seu Navegador!</h1>
<p>Insira ou edite os dados CSV na área de texto abaixo e pressione o botão "Carregar CSV e Exibir como Tabela".</p>
<textarea id="csv-input">Nome,Idade,Cidade
João da Silva,32,Tóquio
Maria Santos,28,Osaka
José Oliveira,45,Fukuoka</textarea>
<button py-click="read_csv">Carregar CSV e Exibir como Tabela</button>
<h2>Resultado do Carregamento</h2>
<div id="table-output"></div>
<py-script>
# O código Python abaixo é executado no seu navegador
import csv
import io # Um módulo para tratar strings como arquivos
from pyscript import document
def read_csv(*args, **kwargs):
# Obtém os dados CSV da área de texto
csv_data = document.querySelector("#csv-input").value
# Use io.StringIO para tratar a string como um arquivo.
# Isso permite que o módulo csv seja usado como se
# estivesse lendo de um arquivo real.
csv_file = io.StringIO(csv_data)
# Lê com csv.reader
reader = csv.reader(csv_file)
# Gera uma tabela HTML
html = "<table>"
try:
# Processa a primeira linha (cabeçalho)
header = next(reader)
html += "<thead><tr>"
for col in header:
html += f"<th>{col}</th>"
html += "</tr></thead>"
# Processa da segunda linha em diante (dados)
html += "<tbody>"
for row in reader:
html += "<tr>"
for cell in row:
html += f"<td>{cell}</td>"
html += "</tr>"
html += "</tbody>"
except StopIteration:
# Tratamento para quando os dados estiverem vazios
html += "<tr><td>Nenhum dado disponível</td></tr>"
html += "</table>"
# Exibe o resultado no elemento DIV
output_div = document.querySelector("#table-output")
output_div.innerHTML = html
</py-script>
</body>
</html>
Sinta-se à vontade para alterar o conteúdo da área de texto e pressionar o botão. Você verá o texto separado por vírgulas se transformar em uma tabela organizada. Este é o poder do módulo `csv`! Divirta-se experimentando.
Conclusão: Agora Você Domina o CSV!
Parabéns! Foi uma longa jornada, mas agora você dominou completamente tudo, desde o básico até os usos avançados da manipulação de CSV com Python. Vamos revisar rapidamente os pontos mais importantes que aprendemos hoje.
- Leitura: O básico é `csv.reader`; se quiser lidar com nomes de colunas, use `csv.DictReader`.
- Escrita: O básico é `csv.writer`; se quiser escrever a partir de um dicionário, use `csv.DictWriter`.
- Anexar: Defina o modo do `open()` como `'a'`.
- Os 2 Feitiços Mágicos Inesquecíveis: Use `encoding='utf-8'` para ler/escrever, e `newline=''` para escrever.
Se você se lembrar desses pontos, raramente terá problemas ao lidar com CSVs no seu trabalho. Você pode analisar dados baixados de sites ou registrar grandes quantidades de dados em um sistema em massa. As possibilidades são infinitas, dependendo das suas ideias.
O segredo para melhorar na programação é acumular esses momentos de "Funcionou!", um por um. Se este artigo o ajudou nessa jornada, eu não poderia estar mais feliz.
Próximos Passos
Outro formato de dados tão usado quanto o CSV no desenvolvimento web é o "JSON". É um conhecimento essencial para um desenvolvimento mais avançado, como a integração de APIs. Domine-o no próximo artigo para subir ainda mais de nível!
Como Lidar com Dados JSON com o Módulo json