Manipulação de Arquivos em Python: Um Guia Completo

A manipulação de arquivos permite que seus programas armazenem dados permanentemente e os recuperem posteriormente. Este capítulo explica todas as operações comuns de arquivos em Python — abrir arquivos em diferentes modos, ler e escrever dados, navegar dentro de um arquivo, especificar a codificação de caracteres e tratar os erros que surgem em código real.

A Função open()

Toda operação de arquivo em Python começa com open(). Ela retorna um objeto de arquivo que expõe métodos para leitura, escrita e posicionamento dentro do arquivo.

file_object = open(file, mode="r", encoding=None)

• file — o caminho para o arquivo (uma string ou um objeto pathlib.Path).
• mode — como abrir o arquivo (veja a tabela abaixo).
• encoding — a codificação de texto, por exemplo "utf-8". Especifique sempre para arquivos de texto para que seu código funcione da mesma forma em qualquer sistema operacional.

Modos de Arquivo

Sempre Use with para Abrir Arquivos

A instrução with (um gerenciador de contexto) garante que o arquivo seja fechado quando o bloco termina — mesmo que uma exceção seja lançada. Isso evita vazamentos de recursos e garante que escritas em buffer sejam descarregadas no disco.

Abra um arquivo com segurança usando with

with open("notes.txt", "r", encoding="utf-8") as f:
    contents = f.read()
# File is automatically closed here

Chamar open() sem with e esquecer file.close() é uma fonte comum de corrupção de dados e erros de "muitos arquivos abertos" em programas de longa execução.

Leitura de Arquivos

Python oferece diversas maneiras de ler o conteúdo de um arquivo.

Leia o Arquivo Inteiro com read()

read() retorna o conteúdo completo do arquivo como uma única string.

Leia um arquivo inteiro

with open("notes.txt", "r", encoding="utf-8") as f:
    content = f.read()
    print(content)

Para arquivos grandes, isso carrega tudo na memória de uma vez, o que é adequado para arquivos pequenos, mas ineficiente para logs de vários gigabytes.

Leia um Número Fixo de Caracteres

Passe um inteiro para read(n) para ler no máximo n caracteres.

Leia os primeiros 20 caracteres

with open("notes.txt", "r", encoding="utf-8") as f:
    chunk = f.read(20)
    print(repr(chunk))

Leia Uma Linha por Vez com readline()

readline() retorna a próxima linha incluindo o \n final, ou uma string vazia no fim do arquivo.

Leia um arquivo linha por linha com readline()

with open("notes.txt", "r", encoding="utf-8") as f:
    line = f.readline()
    while line:
        print(line, end="")   # line already contains '\n'
        line = f.readline()

Itere Sobre as Linhas (Mais Pythônico)

Iterar diretamente sobre um objeto de arquivo é a abordagem mais eficiente em memória para leitura linha por linha.

Itere sobre as linhas

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

Leia Todas as Linhas em uma Lista com readlines()

readlines() retorna uma lista onde cada elemento é uma linha (incluindo o caractere de nova linha).

Leia todas as linhas em uma lista

with open("notes.txt", "r", encoding="utf-8") as f:
    lines = f.readlines()

print(lines[0])   # first line
print(len(lines)) # total number of lines

Use readlines() quando precisar de acesso aleatório a linhas específicas por índice. Para processamento sequencial, prefira o padrão for line in f.

Escrita em Arquivos

Modo de Escrita ("w")

O modo de escrita cria o arquivo se ele não existir e o trunca (esvazia) se existir.

Escreva texto em um arquivo

with open("output.txt", "w", encoding="utf-8") as f:
    f.write("Line one\n")
    f.write("Line two\n")

Escreva Múltiplas Linhas com writelines()

writelines() aceita um iterável de strings. Ele não adiciona caracteres de nova linha automaticamente.

Escreva uma lista de linhas

lines = ["apple\n", "banana\n", "cherry\n"]

with open("fruits.txt", "w", encoding="utf-8") as f:
    f.writelines(lines)

Modo de Anexação ("a")

O modo de anexação move a posição de escrita para o fim do arquivo antes de cada escrita, de modo que o conteúdo existente nunca é sobrescrito.

Adicione uma entrada de log

import datetime

entry = f"{datetime.date.today()} — task complete\n"

with open("log.txt", "a", encoding="utf-8") as f:
    f.write(entry)

Cada vez que esse script é executado, ele adiciona uma nova linha ao log.txt sem alterar as entradas anteriores.

Modo de Criação Exclusiva ("x")

Use "x" quando quiser criar um novo arquivo e garantir que não está sobrescrevendo um existente. Python lança FileExistsError se o arquivo já existir.

Crie um arquivo somente se ele não existir

try:
    with open("config.txt", "x", encoding="utf-8") as f:
        f.write("[settings]\n")
except FileExistsError:
    print("config.txt already exists — not overwriting.")

Posições de Arquivo: seek() e tell()

Objetos de arquivo mantêm um ponteiro de posição interno que avança conforme você lê ou escreve. Você pode inspecionar e alterar esse ponteiro.

• tell() — retorna a posição atual em bytes.
• seek(offset, whence=0) — move o ponteiro. whence=0 (padrão) é a partir do início, 1 a partir da posição atual, 2 a partir do fim.

Volte ao início com seek(0)

with open("notes.txt", "r", encoding="utf-8") as f:
    first_pass = f.read()
    f.seek(0)              # go back to the start
    second_pass = f.read()

print(first_pass == second_pass)  # True

seek() é especialmente útil no modo "r+" (leitura e escrita), onde você pode ler uma seção e depois sobrescrevê-la na mesma chamada de abertura.

Trabalhando com Arquivos Binários

Abra um arquivo em modo binário adicionando "b" à string de modo ("rb", "wb", "ab"). O modo binário fornece bytes brutos em vez de strings, o que é essencial para imagens, áudio, arquivos comprimidos e outros dados não textuais.

Copie um arquivo em modo binário

with open("photo.jpg", "rb") as src:
    data = src.read()

with open("photo_backup.jpg", "wb") as dst:
    dst.write(data)

Não especifique encoding ao usar o modo binário — Python lançará um ValueError se você tentar.

Tratamento de Erros

As operações de arquivo podem falhar de formas previsíveis. Envolvê-las em blocos try/except torna seus scripts mais robustos.

Trate erros comuns de arquivo

try:
    with open("data.txt", "r", encoding="utf-8") as f:
        content = f.read()
except FileNotFoundError:
    print("Error: the file does not exist.")
except PermissionError:
    print("Error: you do not have permission to read this file.")
except OSError as e:
    print(f"OS error: {e}")

Exceções comuns que você encontrará:

A Alternativa Moderna com pathlib

O Python 3.4 introduziu pathlib.Path, uma abordagem orientada a objetos para caminhos do sistema de arquivos. Objetos Path funcionam perfeitamente com open() e também expõem seus próprios métodos de conveniência read_text() / write_text().

Leia um arquivo com pathlib

from pathlib import Path

content = Path("notes.txt").read_text(encoding="utf-8")
print(content)

Escreva em um arquivo com pathlib

from pathlib import Path

Path("output.txt").write_text("Hello, world!\n", encoding="utf-8")

read_text() e write_text() abrem e fecham o arquivo para você, tornando leituras e escritas únicas muito concisas. Use open() com um bloco with quando precisar de controle mais fino — por exemplo, ler um arquivo em partes ou usar seek().

Renomear e Mover Arquivos

Para renomear ou mover um arquivo, use os.rename() para renomear no mesmo sistema de arquivos, ou shutil.move() quando precisar mover entre sistemas de arquivos diferentes.

Renomeie um arquivo com os.rename()

import os

os.rename("old_name.txt", "new_name.txt")

Mova um arquivo com shutil.move()

import shutil

shutil.move("report.txt", "archive/report.txt")

shutil.move() funciona mesmo quando a origem e o destino estão em unidades diferentes; os.rename() lança OSError nesse caso.

Verificar se um Arquivo Existe

Antes de abrir um arquivo para leitura, talvez você queira confirmar que ele existe. Use os.path.exists() ou o equivalente do pathlib.

Verifique a existência com os.path

import os

if os.path.exists("data.txt"):
    print("File found.")
else:
    print("File not found.")

Verifique a existência com pathlib

from pathlib import Path

p = Path("data.txt")
if p.exists():
    print("File found.")

Note que os.path.exists() e Path.exists() podem retornar resultados desatualizados em programas com múltiplas threads ou processos. Nesses casos, prefira simplesmente chamar open() no arquivo e capturar FileNotFoundError.

Resumo das Funções Principais

Capítulos Relacionados

• Python Ler Arquivos — análise aprofundada de cada técnica de leitura
• Python Escrever / Criar Arquivos — escrita, criação e boas práticas
• Python Excluir Arquivos — excluir arquivos e diretórios com segurança
• Python Try Except — tratamento de exceções em Python
• Python With Statement — como funcionam os gerenciadores de contexto