Leitura e Escrita de Arquivos

Programas raramente existem de forma isolada — eles leem configurações, processam dados de entrada, geram relatórios e persistem informações. Arquivos são o mecanismo mais fundamental de persistência em qualquer sistema. Python oferece uma API limpa e expressiva para trabalhar com arquivos de texto, binários e formatos estruturados como CSV e JSON.

Abrindo e Fechando Arquivos

A função open() abre um arquivo e retorna um objeto de arquivo:

# Forma manual — exige fechar explicitamente
arquivo = open("dados.txt", "r", encoding="utf-8")
conteudo = arquivo.read()
arquivo.close()

# Forma recomendada — with fecha automaticamente
with open("dados.txt", "r", encoding="utf-8") as arquivo:
    conteudo = arquivo.read()

Sempre especifique encoding="utf-8" — evita problemas com acentuação em diferentes sistemas operacionais.

O conselho merece a explicação, porque o motivo não é óbvio. Sem esse argumento, o Python usa a codificação preferida do sistema, e não uma codificação fixa: em Linux e macOS isso costuma ser UTF-8, e no Windows, historicamente, é uma página de código regional — cp1252 no Brasil. O mesmo programa, lendo o mesmo arquivo, funciona numa máquina e levanta UnicodeDecodeError na outra. Pior: às vezes não levanta erro nenhum e apenas troca os acentos por caracteres errados, o que passa despercebido até alguém ler o relatório.

Como é fácil esquecer, o Python oferece uma forma de caçar as ocorrências: executando com -X warn_default_encoding, todo open() sem encoding passa a emitir um aviso apontando a linha.

python -X warn_default_encoding -W error::EncodingWarning programa.py
# EncodingWarning: 'encoding' argument not specified

Vale rodar a suíte de testes assim de vez em quando. A regra só não se aplica ao modo binário, com "rb" e "wb", em que não há decodificação e passar encoding é erro.

Modos de Abertura

# Leitura (padrão) — erro se arquivo não existir
with open("arquivo.txt", "r") as f: ...

# Escrita — cria o arquivo ou sobrescreve se existir
with open("arquivo.txt", "w") as f: ...

# Adição — cria ou adiciona ao final
with open("arquivo.txt", "a") as f: ...

# Leitura e escrita
with open("arquivo.txt", "r+") as f: ...

# Modo binário — para imagens, PDFs, etc.
with open("imagem.png", "rb") as f: ...
with open("saida.png",  "wb") as f: ...

# Criação exclusiva — erro se arquivo já existir
with open("novo.txt", "x") as f: ...

Lendo Arquivos

# read() — lê o arquivo inteiro como string
with open("texto.txt", "r", encoding="utf-8") as f:
    conteudo = f.read()
    print(conteudo)

# readline() — lê uma linha por vez
with open("texto.txt", "r", encoding="utf-8") as f:
    primeira = f.readline()
    segunda  = f.readline()

# readlines() — retorna lista de linhas
with open("texto.txt", "r", encoding="utf-8") as f:
    linhas = f.readlines()
    print(linhas)  # ['linha1\n', 'linha2\n', 'linha3\n']

# Iteração direta — mais eficiente para arquivos grandes
with open("texto.txt", "r", encoding="utf-8") as f:
    for linha in f:
        print(linha.strip())  # strip() remove o \n do final

Para arquivos grandes, a iteração direta é preferível — não carrega tudo na memória de uma vez.

Escrevendo Arquivos

# Escrita simples
with open("saida.txt", "w", encoding="utf-8") as f:
    f.write("Primeira linha\n")
    f.write("Segunda linha\n")

# writelines() — escreve lista de strings
linhas = ["Ana\n", "Bruno\n", "Carla\n"]
with open("nomes.txt", "w", encoding="utf-8") as f:
    f.writelines(linhas)

# print() com file= — prático para formatação
with open("relatorio.txt", "w", encoding="utf-8") as f:
    print("=== Relatório ===", file=f)
    print(f"Total: {42}", file=f)

# Adicionando ao final
with open("log.txt", "a", encoding="utf-8") as f:
    from datetime import datetime
    f.write(f"{datetime.now()} — Evento registrado\n")

Trabalhando com Caminhos: pathlib

O módulo pathlib oferece uma forma orientada a objetos e multiplataforma de trabalhar com caminhos — substitui o antigo os.path:

from pathlib import Path

# Criando caminhos
base    = Path("/home/usuario/projetos")
arquivo = base / "dados" / "resultado.txt"

print(arquivo)          # /home/usuario/projetos/dados/resultado.txt
print(arquivo.name)     # resultado.txt
print(arquivo.stem)     # resultado
print(arquivo.suffix)   # .txt
print(arquivo.parent)   # /home/usuario/projetos/dados

# Verificações
print(arquivo.exists())
print(arquivo.is_file())
print(arquivo.is_dir())

# Leitura e escrita diretas
arquivo.parent.mkdir(parents=True, exist_ok=True)
arquivo.write_text("Conteúdo do arquivo", encoding="utf-8")
conteudo = arquivo.read_text(encoding="utf-8")

# Listando arquivos
pasta = Path(".")
for item in pasta.iterdir():
    print(item)

# Filtrando por extensão
for py_file in pasta.glob("**/*.py"):
    print(py_file)

# Caminho do usuário
home = Path.home()
config = home / ".config" / "meu_app" / "config.json"

Arquivos CSV

CSV (Comma-Separated Values) é o formato mais comum para dados tabulares:

import csv
from pathlib import Path

# Escrevendo CSV
alunos = [
    {"nome": "Ana",    "nota": 9.5, "turma": "A"},
    {"nome": "Bruno",  "nota": 7.0, "turma": "B"},
    {"nome": "Carla",  "nota": 8.5, "turma": "A"},
]

with open("alunos.csv", "w", newline="", encoding="utf-8") as f:
    campos = ["nome", "nota", "turma"]
    writer = csv.DictWriter(f, fieldnames=campos)
    writer.writeheader()
    writer.writerows(alunos)

# Lendo CSV
with open("alunos.csv", "r", encoding="utf-8") as f:
    reader = csv.DictReader(f)
    for linha in reader:
        print(f"{linha['nome']:10} — nota: {linha['nota']}")
        # atenção: linha['nota'] é a STRING "9.5", não o número

# CSV com delimitador diferente
with open("dados.csv", "r", encoding="utf-8") as f:
    reader = csv.reader(f, delimiter=";")
    for linha in reader:
        print(linha)

Duas ressalvas sobre CSV, e a primeira é a que mais produz relatório errado sem dar erro: o módulo csv devolve tudo como texto. Escrevemos 9.5 como número e lemos de volta a string "9.5". A f-string do exemplo acima esconde isso perfeitamente, porque imprimir string ou número dá o mesmo resultado na tela — o problema aparece na primeira conta.

notas = [l["nota"] for l in csv.DictReader(f)]

sum(notas)
# TypeError: unsupported operand type(s) for +: 'int' and 'str'

sorted(["9.5", "10.0", "7.0"])
# ['10.0', '7.0', '9.5']   — ordem alfabética: "10" vem antes de "7"

A soma ao menos falha barulhentamente. A ordenação é o caso perigoso: devolve uma lista plausível, com a nota 10 em primeiro lugar por começar com o algarismo 1, e ninguém percebe. A conversão é responsabilidade de quem lê, e deve acontecer na entrada — float(linha["nota"]) —, tratando o valor ausente ou malformado ali mesmo. Quando a tabela é grande e tem muitas colunas com tipos diferentes, vale considerar o pandas, que infere os tipos ao ler.

A segunda ressalva é o newline="". O exemplo o usa ao escrever, e a documentação do módulo pede que ele seja usado também na leitura — pelo motivo concreto de que, sem ele, uma quebra de linha dentro de um campo entre aspas é convertida em silêncio:

# um campo com \r\n dentro, como o Excel grava
with open("dados.csv", newline="", encoding="utf-8") as f:
    list(csv.reader(f))   # ['1', 'linha um\r\nlinha dois']  — preservado

with open("dados.csv", encoding="utf-8") as f:
    list(csv.reader(f))   # ['1', 'linha um\nlinha dois']    — alterado

Não há erro, e o dado que sai do programa não é o que entrou. Na escrita o argumento evita o problema espelhado: no Windows, sem ele, o terminador \r\n produzido pelo módulo é traduzido outra vez e o arquivo sai com uma linha em branco entre cada registro. A regra é curta — newline="" em toda abertura de arquivo CSV, nos dois sentidos.

Arquivos JSON

JSON é o formato padrão para troca de dados em APIs e configurações:

import json
from pathlib import Path

# Serialização — Python → JSON
config = {
    "host":    "localhost",
    "porta":   5432,
    "debug":   True,
    "tags":    ["producao", "v2"],
    "timeout": None
}

# Para string
json_str = json.dumps(config, indent=2, ensure_ascii=False)
print(json_str)

# Para arquivo
with open("config.json", "w", encoding="utf-8") as f:
    json.dump(config, f, indent=2, ensure_ascii=False)

# Desserialização — JSON → Python
with open("config.json", "r", encoding="utf-8") as f:
    dados = json.load(f)

print(dados["host"])   # localhost
print(type(dados))     # <class 'dict'>

# Usando pathlib diretamente
config_path = Path("config.json")
dados = json.loads(config_path.read_text(encoding="utf-8"))

Correspondência de tipos:

JSON          Python
─────────────────────
object    →   dict
array     →   list
string    →   str
number    →   int / float
true/false→   True / False
null      →   None

Arquivos Binários e pickle

Para serializar objetos Python arbitrários:

import pickle
from dataclasses import dataclass
from typing import List

@dataclass
class ModeloML:
    nome:       str
    parametros: dict
    acuracia:   float
    versao:     str

modelo = ModeloML(
    nome="ClassificadorSpam",
    parametros={"learning_rate": 0.01, "epochs": 100},
    acuracia=0.94,
    versao="1.0.0"
)

# Salvando
with open("modelo.pkl", "wb") as f:
    pickle.dump(modelo, f)

# Carregando
with open("modelo.pkl", "rb") as f:
    modelo_carregado = pickle.load(f)

print(modelo_carregado)
print(modelo_carregado.acuracia)  # 0.94

Atenção: nunca carregue arquivos .pkl de fontes não confiáveis — o pickle pode executar código arbitrário durante a desserialização.

Exemplo Completo: Sistema de Log

import json
from pathlib import Path
from datetime import datetime
from enum import Enum


class Nivel(str, Enum):
    DEBUG   = "DEBUG"
    INFO    = "INFO"
    AVISO   = "AVISO"
    ERRO    = "ERRO"
    CRITICO = "CRITICO"


class Logger:
    def __init__(self, nome: str, pasta: str = "logs"):
        self.nome  = nome
        self.pasta = Path(pasta)
        self.pasta.mkdir(parents=True, exist_ok=True)

        data_hoje         = datetime.now().strftime("%Y-%m-%d")
        self._arquivo_txt  = self.pasta / f"{nome}_{data_hoje}.log"
        self._arquivo_json = self.pasta / f"{nome}_{data_hoje}.jsonl"

    def _registrar(self, nivel: Nivel, mensagem: str, **extras):
        agora  = datetime.now()
        entrada = {
            "timestamp": agora.isoformat(),
            "nivel":     nivel.value,
            "logger":    self.nome,
            "mensagem":  mensagem,
            **extras
        }

        # Formato legível para .log
        linha_txt = (f"[{agora.strftime('%H:%M:%S')}] "
                     f"[{nivel.value:7}] "
                     f"[{self.nome}] {mensagem}")

        if extras:
            linha_txt += f" | {extras}"

        with open(self._arquivo_txt, "a", encoding="utf-8") as f:
            f.write(linha_txt + "\n")

        # Formato estruturado para .jsonl (JSON Lines)
        with open(self._arquivo_json, "a", encoding="utf-8") as f:
            f.write(json.dumps(entrada, ensure_ascii=False) + "\n")

    def debug(self, msg, **extras):
        self._registrar(Nivel.DEBUG, msg, **extras)

    def info(self, msg, **extras):
        self._registrar(Nivel.INFO, msg, **extras)

    def aviso(self, msg, **extras):
        self._registrar(Nivel.AVISO, msg, **extras)

    def erro(self, msg, **extras):
        self._registrar(Nivel.ERRO, msg, **extras)

    def ler_logs(self, nivel: Nivel = None) -> list:
        """Lê e filtra logs do arquivo JSONL."""
        if not self._arquivo_json.exists():
            return []

        logs = []
        # iteração linha a linha: arquivo de log é justamente o que cresce
        with open(self._arquivo_json, encoding="utf-8") as f:
            for linha in f:
                entrada = json.loads(linha)
                if nivel is None or entrada["nivel"] == nivel.value:
                    logs.append(entrada)
        return logs


logger = Logger("sistema")

logger.info("Aplicação iniciada", versao="2.1.0")
logger.debug("Conectando ao banco", host="localhost", porta=5432)
logger.info("Usuário autenticado", usuario_id=42)
logger.aviso("Tentativa de login falhou", tentativas=3)
logger.erro("Falha na conexão com o banco", codigo=500)

print("\n=== Logs de ERRO ===")
for log in logger.ler_logs(Nivel.ERRO):
    print(f"  {log['timestamp']} — {log['mensagem']}")

print(f"\n=== Total de logs: {len(logger.ler_logs())} ===")

Abrir, ler e gravar é a parte fácil, e o with resolve a maior parte do que costumava dar errado: o arquivo fecha mesmo quando o bloco levanta exceção. O que sobra são decisões que o Python não toma por você. A codificação é a primeira delas — sem encoding="utf-8", quem decide é o sistema, e o mesmo arquivo lido no Windows vira Relatório em vez de dar erro. A segunda é o tamanho: read() e read_text() carregam tudo de uma vez, e só a iteração linha a linha mantém a memória constante, o que importa justamente nos arquivos que crescem, como os de log. O pathlib junta caminho, verificação, leitura e escrita num só objeto, com a ressalva de que mkdir(exist_ok=True) só cria a última pasta; a árvore inteira pede também parents=True.

Nos formatos estruturados, o cuidado muda de lugar. O csv devolve tudo como texto, e converter na entrada é o que impede uma ordenação alfabética de passar por ranking de notas; o newline="" vale nos dois sentidos, ou uma quebra de linha dentro de um campo muda sem aviso. O json é o formato de troca, mas não faz ida e volta perfeita: chaves inteiras voltam como texto e tuplas voltam como listas. O pickle preserva qualquer objeto Python, e por isso mesmo só deve abrir arquivo de origem confiável, porque desserializar pode executar código. Por fim, o JSON Lines do exemplo de log mostra por que um objeto por linha funciona tão bem para registro: cada entrada nova é um append e a leitura pode parar em qualquer ponto.

Fontes e leituras recomendadas

• Leitura e escrita de arquivos — tutorial oficial — https://docs.python.org/3/tutorial/inputoutput.html
• pathlib — caminhos orientados a objetos — https://docs.python.org/3/library/pathlib.html
• Módulo csv — https://docs.python.org/3/library/csv.html
• Módulo json — https://docs.python.org/3/library/json.html
• Módulo pickle — https://docs.python.org/3/library/pickle.html
• BEAZLEY, David; JONES, Brian K. Python Cookbook. 3. ed. O'Reilly Media, 2013. Cap. 5 — receitas avançadas para arquivos e I/O.
• SWEIGART, Al. Automate the Boring Stuff with Python. 2. ed. No Starch Press, 2019. Cap. 8 e 9 — leitura, escrita e organização de arquivos com foco prático.
• MATTHES, Eric. Python Crash Course. 3. ed. No Starch Press, 2023. Cap. 10 — arquivos e exceções combinados.

Exercícios

Exercício 1

Um script lê notas.csv com csv.DictReader e publica no mural da escola o primeiro colocado, usando sorted(linhas, key=lambda l: l["nota"], reverse=True)[0]. O arquivo tem Ana com 9.5, Bruno com 10.0 e Carla com 7.0. O mural anuncia Ana. Não houve erro, e o script funcionou certo durante todo o semestre anterior. Explique o que aconteceu e por que só agora.

Exercício 2

Um programa que roda há anos num servidor Linux é instalado no notebook Windows de um cliente. Ele lê um arquivo de texto gerado pelo próprio sistema, com open("relatorio.txt"), sem outros argumentos. No Linux o relatório aparece correto; no Windows, a linha "Relatório de manutenção" sai como Relatório de manutenção, e ninguém vê mensagem de erro. Explique o que acontece e como impedir que o problema volte em outro ponto do código.

Exercício 3

Um programa guarda preferências do usuário em config.json. Ao salvar, faz with open("config.json", "w", encoding="utf-8") as f: json.dump(config, f). Numa versão nova, alguém guardou um set dentro de config. O salvamento levanta TypeError: Object of type set is not JSON serializable, o erro é capturado e registrado em log — e na próxima execução o programa não abre mais, porque não consegue ler a configuração. O que havia no arquivo, e como salvar de forma que uma falha nunca destrua a versão anterior?

import json, os
from pathlib import Path

def salvar_json(caminho: Path, dados) -> None:
    tmp = caminho.with_suffix(caminho.suffix + ".tmp")
    try:
        with open(tmp, "w", encoding="utf-8") as f:
            json.dump(dados, f, ensure_ascii=False, indent=2)
            f.flush()
            os.fsync(f.fileno())
    except BaseException:
        tmp.unlink(missing_ok=True)
        raise
    os.replace(tmp, caminho)

Exercício 4

Uma API em Python guarda um cache de cotações em JSON: {1: 5.12, 2: 5.40}, onde a chave é o id da moeda. Depois de recarregar o cache do disco, cache[1] passa a levantar KeyError, embora o arquivo tenha as duas cotações. Na mesma revisão, alguém nota que as coordenadas salvas como tupla (lat, lon) voltam de outro jeito, e que um valor float("nan") vindo de um cálculo produziu um arquivo que o frontend em JavaScript se recusa a ler. Explique os três casos.

Exercício 5

O Logger do exemplo deste artigo está em produção e o arquivo .jsonl do dia chega a 20 MB. Numa revisão de código, alguém propõe simplificar ler_logs assim: linhas = self._arquivo_json.read_text(encoding="utf-8").splitlines(), seguido do mesmo filtro. Avalie a proposta e aponte outros dois pontos do Logger que merecem atenção antes de ele crescer mais.