Logs, relatórios, configuração, exportações: mais cedo ou mais tarde, todo script toca o sistema de arquivos. O manuseio de arquivos Python é simples para começar, mas alguns detalhes decidem se seu código é confiável ou destrói dados silenciosamente.

Este guia aborda arquivos de texto, CSV, JSON, dados binários e caminhos, com foco em hábitos seguros. Executamos esses exemplos no Python 3.13 em uma pasta temporária e a saída mostrada vem dessa execução.

Abra arquivos com open() e com

A função interna open() retorna um objeto de arquivo. Use-o dentro de um bloco with:

with open("notes.txt", "w", encoding="utf-8") as file:
    file.write("first line\n")
    file.write("second line\n")

print(file.closed)

# True

Quando o bloco termina, o Python fecha o arquivo, mesmo que tenha ocorrido um erro dentro dele. Sem with, você mesmo precisa chamar close(), e uma exceção pode pular essa linha. Usar um arquivo depois de fechado gera um erro:

file.read()

# ValueError: I/O operation on closed file.

Modos de arquivo

O segundo argumento para open() diz o que você planeja fazer:

Adicione b para dados binários, como em "rb" ou "wb". Texto é o padrão e também pode ser escrito explicitamente como t.

Escreva e anexe

write() não adiciona uma quebra de linha, então inclua \n você mesmo. Anexar mantém o que já está lá:

with open("notes.txt", "a", encoding="utf-8") as file:
    file.write("third line\n")

Compare isso com o modo "w", que substituiu nossas três linhas por uma, sem nenhum aviso:

with open("notes.txt", "w", encoding="utf-8") as file:
    file.write("replaced\n")

# notes.txt now contains only: replaced

Quando você não deve sobrescrever algo, use "x". Levantou FileExistsError em nosso teste, pois notes.txt já existia.

Ler um arquivo

Existem várias maneiras de ler, e a escolha certa depende do tamanho do arquivo:

with open("notes.txt", encoding="utf-8") as file:
    print(repr(file.read()))

# 'first line\nsecond line\n'

with open("notes.txt", encoding="utf-8") as file:
    for line in file:
        print(line.strip())

# first line
# second line
# third line

Observe os caracteres \n mantidos na string bruta. strip() os remove. Um objeto de arquivo também lembra sua posição, então a leitura continua de onde parou:

with open("notes.txt", encoding="utf-8") as file:
    print(file.readline().strip())
    print(file.readlines())

# first line
# ['second line\n', 'third line\n']

Fazer um loop no arquivo é a técnica chave para grandes logs e exportações. Ele lê uma linha por vez, portanto, um arquivo de vários gigabytes não precisa caber na memória.

Lidar com erros de arquivo

Os arquivos podem estar ausentes, bloqueados ou ilegíveis, então planeje isso:

try:
    with open("missing.txt", encoding="utf-8") as file:
        data = file.read()
except FileNotFoundError as error:
    print(error)

# [Errno 2] No such file or directory: 'missing.txt'

Tente abrir o arquivo e detectar o erro, em vez de verificar primeiro com exists(), pois o arquivo pode desaparecer entre a verificação e a abertura. Nosso guia para tratamento de exceções em Python aborda essa abordagem.

Arquivos CSV

Não divida as linhas CSV por vírgula, pois os valores entre aspas podem conter vírgulas. O módulo padrão csv lida com essas regras. DictWriter e DictReader são as opções mais legíveis:

import csv

with open("orders.csv", "w", newline="", encoding="utf-8") as file:
    writer = csv.DictWriter(file, fieldnames=["id", "customer", "total"])
    writer.writeheader()
    writer.writerow({"id": 1, "customer": "Asha", "total": 1200})
    writer.writerow({"id": 2, "customer": "Ben", "total": 300})

with open("orders.csv", newline="", encoding="utf-8") as file:
    rows = list(csv.DictReader(file))

print(rows[0])
print(sum(int(r["total"]) for r in rows))

# {'id': '1', 'customer': 'Asha', 'total': '1200'}
# 1500

Dois detalhes importam. Passe newline="" ao abrir arquivos CSV, conforme recomendado pela documentação, para evitar linhas em branco no Windows. E cada valor retorna como uma string, números pares, e é por isso que precisávamos de int() na soma. Para trabalho pesado com dados, uma biblioteca como o pandas pode ser uma opção melhor.

Arquivos JSON

JSON é o formato usual para dados de configuração e API. Ele mapeia perfeitamente em dicionários Python e listas:

import json

config = {"debug": True, "retries": 3, "hosts": ["a", "b"]}

with open("config.json", "w", encoding="utf-8") as file:
    json.dump(config, file, indent=2)

with open("config.json", encoding="utf-8") as file:
    print(json.load(file)["retries"])

# 3

Lembre-se da nomenclatura: dump e load funcionam com arquivos, enquanto dumps e loads funcionam com strings. Tipos como datas não podem ser armazenados diretamente, então você precisará primeiro convertê-los em strings.

Trabalhe com caminhos usando pathlib

A colagem de caminhos com strings quebra os sistemas operacionais. O módulo padrão pathlib lida com separadores para você e oferece atalhos úteis:

from pathlib import Path

path = Path("data") / "reports" / "summary.txt"
path.parent.mkdir(parents=True, exist_ok=True)
path.write_text("all good\n", encoding="utf-8")

print(path.read_text(encoding="utf-8").strip())   # all good
print(path.suffix, path.stem, path.exists())      # .txt summary True
print(sorted(p.name for p in Path(".").glob("*.csv")))
# ['orders.csv']

Esse último resolve uma dor de cabeça comum. Os caminhos relativos são resolvidos a partir de onde você executou o script, e não de onde o script reside, portanto, construir caminhos a partir de Path(__file__).parent evita muitas surpresas de “arquivo não encontrado”.

Arquivos binários

Imagens, PDFs e arquivos ZIP não são texto. Abra-os com b e você lê e escreve bytes, sem nenhuma codificação envolvida:

with open("pixel.bin", "wb") as file:
    file.write(bytes([255, 0, 128]))

with open("pixel.bin", "rb") as file:
    print(file.read())

# b'\xff\x00\x80'

Gravações mais seguras

Se um programa travar no meio da gravação de um arquivo importante, você poderá ficar com um resultado corrompido. Uma solução comum é gravar primeiro em um arquivo temporário e depois trocá-lo:

temp = Path("settings.tmp")
temp.write_text("new", encoding="utf-8")
temp.replace("settings.txt")

print(Path("settings.txt").read_text(), temp.exists())

# new False

replace() substitui o destino. No mesmo sistema de arquivos, a renomeação é geralmente atômica, de modo que os leitores veem o arquivo antigo ou o novo, em vez de uma mistura escrita pela metade.

Um exemplo prático: resumir um log

Este pequeno roteiro reúne várias ideias. Ele lê um log uma linha por vez, portanto seu tamanho não importa, conta cada nível usando Counter e grava um resumo em um novo arquivo:

from collections import Counter

counts = Counter()
with open("app.log", encoding="utf-8") as file:
    for line in file:
        counts[line.split()[0]] += 1

with open("summary.txt", "w", encoding="utf-8") as out:
    for level, total in counts.most_common():
        out.write(f"{level}: {total}\n")

# summary.txt
# ERROR: 2
# INFO: 2
# WARN: 1

Nosso log de amostra tinha cinco linhas. Uma linha em branco quebraria line.split()[0], então os scripts reais devem pular as linhas vazias primeiro.

Erros comuns

• Usando "w" quando você quis dizer "a". Seus dados existentes desaparecem imediatamente ao serem abertos, mesmo que você nunca escreva nada.
• Omitindo a codificação. O padrão varia de acordo com o sistema, portanto, um script que funciona no Linux pode falhar no Windows com texto acentuado ou emoji.
• Chamar read() em arquivos grandes. Isso pode esgotar a memória, então faça um loop nas linhas.
• Esquecer int() dos valores CSV. "10" + "20" dá "1020".
• Deixando de fora newline="" o CSV. Você pode obter linhas em branco inesperadas no Windows.
• Não está testando o código do arquivo. Use o acessório tmp_path do pytest para que os testes nunca toquem em arquivos reais. Veja nosso tutorial de pytest.

Considerações finais

Alguns hábitos cobrem quase tudo aqui: use with, defina a codificação, pense duas vezes sobre "w" e deixe csv, json e pathlib fazerem as partes difíceis. Para praticar, escreva um pequeno script que leia um CSV, totalize uma coluna e salve um resumo JSON em uma nova pasta.

Perguntas frequentes

Continue aprendendo