Manipulação de Arquivos em Python — Lendo e Escrevendo da Forma Certa

O tratamento de arquivos embutido do Python é um dos pontos fortes genuínos da linguagem — sem importações necessárias para operações básicas de leitura/escrita, e a API é limpa o suficiente para aprender em uma tarde. Mas há uma lacuna real entre a versão tutorial e o que você realmente implantaria. A versão tutorial abre um arquivo, lê e fecha. A versão de produção lida com incompatibilidades de codificação que corrompem dados silenciosamente, caminhos que funcionam no macOS mas explodem no Windows, e arquivos de log que consumem silenciosamente toda a sua memória se você chamar read() em um arquivo de 2 GB. Este artigo cobre os padrões que resistem — não apenas o caminho feliz.

A Instrução with — Use Sempre

Todo exemplo de tratamento de arquivo em Python deve usar um gerenciador de contexto — o bloco with que garante que o arquivo seja fechado mesmo se uma exceção for levantada no meio da leitura. Um gerenciador de contexto é um objeto que define o que acontece na entrada e saída de um bloco with; para arquivos, saída significa que close() é chamado automaticamente. Aqui está por que isso importa na prática:

# ❌ Manual close — works until it doesn't
f = open('app.log')
data = f.read()   # if this raises an exception...
f.close()         # ...this line never runs. File handle leaks.

# ✅ Context manager — close() is guaranteed
with open('app.log') as f:
    data = f.read()
# file is closed here, no matter what happened inside the block

Em servidores de longa duração isso não é acadêmico — vazamentos de handles de arquivo eventualmente causam OSError: [Errno 24] Too many open files. A instrução with não custa nada e previne completamente essa classe de bug. Use-a em todos os lugares.

Lendo Arquivos — Quatro Maneiras, Uma Ferramenta Certa para Cada Vez

Python fornece vários métodos em um objeto de arquivo, e escolher o correto importa mais do que a maioria dos tutoriais admite:

• f.read() — lê o arquivo inteiro em uma única string. Adequado para arquivos de configuração pequenos, perigoso para grandes.
• f.readline() — lê uma linha por vez, avançando o ponteiro interno. Útil quando você precisa de controle manual sobre a iteração.
• f.readlines() — lê todas as linhas em uma lista. Conveniente, mas ainda carrega o arquivo inteiro na memória.
• for line in f: — o protocolo iterador. Lê uma linha por vez sem carregar o arquivo completo. Este é o padrão a usar por padrão.

Aqui está um exemplo realista: ler um arquivo de configuração estilo .env e transformá-lo em um dicionário. É o tipo de coisa que você realmente escreve, não uma demonstração artificial de "ler hello.txt":

from pathlib import Path

def load_config(path: str) -> dict:
    """Read a key=value config file, ignoring comments and blank lines."""
    config = {}
    with open(path, encoding='utf-8') as f:
        for line in f:
            line = line.strip()
            if not line or line.startswith('#'):
                continue
            if '=' not in line:
                continue
            key, _, value = line.partition('=')
            config[key.strip()] = value.strip()
    return config

# Usage
settings = load_config('config/app.conf')
db_host = settings.get('DB_HOST', 'localhost')

Escrevendo e Anexando — Saiba Qual Modo Destrói Dados

O segundo argumento para open() é o modo. Dois modos que pegam as pessoas repetidamente:

• 'w' — modo de escrita. Abre o arquivo para escrita. Se o arquivo já existir, ele é truncado para zero bytes imediatamente — antes de você escrever um único caractere. Isso é destruição silenciosa de dados se você abrir o caminho errado.
• 'a' — modo de anexação. Abre o arquivo e move o ponteiro de escrita para o final. O conteúdo existente nunca é tocado. Novas escritas vão após o que já estava lá.

Um bom caso de uso para o modo de anexação é escrever um arquivo de log estruturado com timestamps. Aqui está um padrão que é útil em scripts e pequenos serviços:

import datetime

LOG_FILE = 'logs/pipeline.log'

def log_event(level: str, message: str) -> None:
    timestamp = datetime.datetime.utcnow().isoformat() + 'Z'
    line = f"[{timestamp}] {level.upper()}: {message}\n"
    with open(LOG_FILE, 'a', encoding='utf-8') as f:
        f.write(line)

log_event('info', 'Pipeline started')
log_event('warning', 'Retrying connection to database')
log_event('error', 'Failed to parse row 4821 — skipping')

Codificação — O Bug Que Morde Todo Mundo Eventualmente

Esta é a fonte mais comum de corrupção silenciosa de dados no tratamento de arquivos Python. A codificação padrão do Python 3 quando você chama open() sem especificar uma é determinada por locale.getpreferredencoding() — que no Windows é tipicamente cp1252, e no Linux/macOS é geralmente UTF-8. Isso significa que código que funciona perfeitamente no seu Mac pode corromper silenciosamente ou travar em um servidor Windows quando o arquivo contém qualquer caractere fora do ASCII. A correção é um argumento extra:

# ❌ Platform-dependent — works on Linux, corrupts on Windows
with open('customers.csv') as f:
    data = f.read()

# ✅ Explicit UTF-8 — same behavior on every platform
with open('customers.csv', encoding='utf-8') as f:
    data = f.read()

# For files exported from Excel on Windows — may have a BOM (byte order mark)
# utf-8-sig strips the BOM automatically on read
with open('export.csv', encoding='utf-8-sig') as f:
    data = f.read()

O problema do BOM é particularmente comum com arquivos CSV exportados do Microsoft Excel — o arquivo começa com um caractere \ufeff oculto que aparece como  se lido com a codificação errada, ou faz o primeiro cabeçalho de coluna parecer nome em vez de nome. Usar encoding='utf-8-sig' lida com isso de forma transparente. Veja a documentação de codecs do Python para a lista completa de nomes de codificação.

Trabalhando com Caminhos — Use pathlib

A maneira antiga de construir caminhos de arquivo em Python era concatenação de strings ou os.path.join(). A maneira moderna é pathlib.Path, disponível desde o Python 3.4 e totalmente madura desde o 3.6. Ela lida com separadores de caminho corretamente no Windows e Unix sem você precisar pensar nisso, e substitui um punhado de chamadas os.path por acesso a atributos legível.

from pathlib import Path

# Build a path relative to the current script — works on Windows and Unix
base_dir = Path(__file__).parent
data_dir = base_dir / 'data'
input_file = data_dir / 'records.csv'

# Check existence before opening
if not input_file.exists():
    raise FileNotFoundError(f"Input file not found: {input_file}")

# Create a directory (including parents) without error if it already exists
output_dir = base_dir / 'output' / 'reports'
output_dir.mkdir(parents=True, exist_ok=True)

# Iterate over all JSON files in a directory
for json_file in data_dir.glob('*.json'):
    print(json_file.name)       # just the filename: 'records.json'
    print(json_file.stem)       # filename without extension: 'records'
    print(json_file.suffix)     # extension: '.json'
    print(json_file.parent)     # parent directory as a Path

# The / operator builds paths — no os.path.join needed
report_path = output_dir / f"report_{input_file.stem}.txt"

O operador / não é divisão aqui — Path o substitui para significar junção de caminhos. Isso lê naturalmente e elimina os problemas de citação e separador que vêm com a construção de caminhos baseada em strings. Mais um método útil: path.read_text(encoding='utf-8') é um atalho para o padrão open/read/close quando você quer apenas o conteúdo do arquivo como string.

Lendo Arquivos Grandes Sem Explodir a Memória

Quando um arquivo é pequeno — digamos, abaixo de alguns megabytes — f.read() ou f.readlines() está bem. Quando é um log de servidor de 500 MB ou uma exportação de dados de múltiplos gigabytes, carregar tudo na memória é um caminho rápido para um MemoryError ou um processo morto pelo SO. A correção é iteração linha por linha:

from pathlib import Path
from collections import Counter

def count_error_levels(log_path: str) -> dict:
    """
    Process a large log file line by line.
    Memory usage stays roughly constant regardless of file size.
    """
    counts = Counter()
    with open(log_path, encoding='utf-8') as f:
        for line in f:
            # Each line is fetched from disk as needed — not loaded all at once
            if ' ERROR ' in line:
                counts['error'] += 1
            elif ' WARN ' in line:
                counts['warning'] += 1
            elif ' INFO ' in line:
                counts['info'] += 1
    return dict(counts)

results = count_error_levels('/var/log/app/server.log')
print(f"Errors: {results.get('error', 0)}, Warnings: {results.get('warning', 0)}")

O padrão for line in f: funciona porque o objeto de arquivo do Python implementa o protocolo iterador — ele busca linhas do disco uma por vez usando um buffer interno, então o uso de memória é essencialmente constante independentemente do tamanho do arquivo. Para arquivos verdadeiramente massivos (dezenas de gigabytes) onde mesmo a iteração linha por linha não é rápida o suficiente, mmap permite mapear o arquivo na memória e pesquisá-lo com expressões regulares sem lê-lo — mas para a maioria dos casos de uso, o iterador de linha é tudo que você precisa.

Lendo e Escrevendo JSON e CSV

Dois formatos aparecem constantemente no trabalho Python real, e ambos têm módulos stdlib dedicados que lidam com aspas, escape e estrutura corretamente — não os analise com divisões de string.

import json
import csv
from pathlib import Path

# --- JSON ---
# Reading
with open('config/settings.json', encoding='utf-8') as f:
    settings = json.load(f)            # parsed directly from the file object

# Writing (indent=2 gives readable output)
with open('output/results.json', 'w', encoding='utf-8') as f:
    json.dump(results, f, indent=2, ensure_ascii=False)

# --- CSV ---
# Reading
with open('data/customers.csv', encoding='utf-8-sig', newline='') as f:
    reader = csv.DictReader(f)         # each row is a dict keyed by header
    for row in reader:
        process_customer(row['email'], row['plan'])

# Writing
fieldnames = ['id', 'email', 'plan', 'created_at']
with open('output/export.csv', 'w', encoding='utf-8', newline='') as f:
    writer = csv.DictWriter(f, fieldnames=fieldnames)
    writer.writeheader()
    for record in records:
        writer.writerow(record)

Algumas coisas dignas de nota: passe newline='' ao abrir arquivos CSV — o módulo csv lida com suas próprias terminações de linha, e deixar o modo universal de nova linha do Python interferir causa linhas em branco duplicadas no Windows. Para JSON, ensure_ascii=False deixa caracteres não-ASCII (letras acentuadas, caracteres CJK, etc.) serem escritos como estão em vez de serem escapados para sequências \uXXXX — saída muito mais legível. Se você está trabalhando com dados JSON ou CSV e quer inspecioná-los ou transformá-los visualmente, o Formatador JSON e o Formatador CSV neste site são bons complementos à abordagem de código.

Tratamento de Erros — As Três Exceções Que Você Verá

Operações de arquivo falham de maneiras previsíveis. Tratar cada caso explicitamente dá mensagens de erro que são realmente úteis em vez de um traceback genérico:

import json
from pathlib import Path

def load_json_config(path: str) -> dict:
    """
    Load a JSON config file with explicit error handling.
    Returns the parsed config or raises with a clear message.
    """
    config_path = Path(path)

    try:
        with open(config_path, encoding='utf-8') as f:
            return json.load(f)

    except FileNotFoundError:
        raise FileNotFoundError(
            f"Config file not found: {config_path.resolve()}\n"
            f"Create it or set CONFIG_PATH to the correct location."
        )

    except PermissionError:
        raise PermissionError(
            f"No read permission on {config_path.resolve()}\n"
            f"Check file ownership and mode (chmod 644 on Linux)."
        )

    except UnicodeDecodeError as e:
        raise ValueError(
            f"Encoding error reading {config_path}: {e}\n"
            f"Try opening with encoding='utf-8-sig' if the file came from Windows."
        )

    except json.JSONDecodeError as e:
        raise ValueError(
            f"Invalid JSON in {config_path} at line {e.lineno}, col {e.colno}: {e.msg}"
        )

As quatro exceções cobrem quase todos os modos reais de falha: o arquivo não existe, você não tem permissão, a codificação está errada ou o conteúdo está malformado. Cada mensagem diz ao próximo desenvolvedor (ou a você às 2 da manhã) exatamente o que deu errado e onde procurar. Capturar uma Exception vazia e imprimir "algo deu errado" não é tratamento de erros útil — apenas move a confusão para baixo.

Conclusão

A versão curta de tudo acima: sempre use blocos with, sempre passe encoding='utf-8', use pathlib.Path para construção de caminhos e itere linhas em vez de ler arquivos inteiros quando o tamanho for desconhecido. Esses quatro hábitos eliminam a grande maioria dos bugs de tratamento de arquivo antes de chegarem à produção.

Para leitura mais profunda: a seção do tutorial Python sobre leitura e escrita de arquivos cobre o básico completamente. A documentação do pathlib vale ser favoritada — é uma das partes mais úteis da stdlib e a maioria dos desenvolvedores Python a subutiliza. Os docs do módulo csv e os docs do módulo json têm bons exemplos para os casos extremos (delimitadores personalizados, JSON em streaming, etc.) que valem a leitura se você trabalha com esses formatos regularmente.