Arquivos e exceções em Python

Um arquivo de texto mantém informações depois que um programa para. O Python usa um objeto de arquivo, retornado por open(), para trabalhar com essas informações. A abertura conecta o programa ao arquivo; uma operação de leitura recupera seu texto.

Escolha o que ler

O modo padrão é "r", para leitura. Um nome sem caminho é procurado no diretório de trabalho atual. Se ele estiver ausente nesse diretório, open() lança FileNotFoundError.

with open("fruit.txt", encoding="utf-8") as f:
    text = f.read()

Suponha que o arquivo tenha três linhas, “apple”, “banana” e “cherry”, todas com terminadores de linha. text é 'apple\nbanana\ncherry\n'. A sequência de escape \n representa um caractere de nova linha. Uma última linha também pode terminar sem esse caractere.

readline() retorna '' no fim do arquivo. Uma linha em branco que tem um terminador de linha retorna '\n', então uma linha em branco e o fim do arquivo são diferentes.

Acompanhe a posição

A leitura avança a posição no arquivo. Depois que f.read() consome o arquivo, outra chamada retorna ''; um laço sobre o mesmo objeto não tem mais nada a percorrer. Abra o arquivo novamente para recomeçar ou mantenha o texto ou as linhas necessárias em uma variável. read() e readlines() carregam o restante do arquivo na memória. Percorrer diretamente o arquivo permite processar um arquivo grande uma linha por vez.

As linhas mantêm seus caracteres de nova linha. print(line) acrescenta seu próprio caractere de nova linha, o que pode deixar linhas em branco extras na tela. Use print(line, end="") para manter o espaçamento original ou remova o terminador de linha antes de imprimir. line.rstrip("\n") remove caracteres de nova linha do fim; line.strip() também remove espaços das duas extremidades.

Transforme texto em números

Mesmo os dígitos chegam como strings. Este arquivo contém as notas “72”, “85” e “90”:

scores = []
with open("scores.txt", encoding="utf-8") as f:
    for line in f:
        scores.append(int(line))
total = sum(scores)
print(total, round(total / len(scores), 2))

A lista é [72, 85, 90], então o programa imprime 247 82.33. int() aceita espaços e caracteres de nova linha ao redor dos dígitos. Uma string vazia ou uma palavra como "forty" lança ValueError.

Leia caracteres com a codificação correta

Uma codificação associa caracteres a bytes armazenados. UTF-8 pode representar caracteres como “é” e emojis. Use encoding="utf-8" explicitamente para arquivos UTF-8. O Python 3.15 ativa o modo UTF-8 por padrão; instalações anteriores podem usar uma codificação local. Uma codificação incorreta pode produzir texto corrompido ou UnicodeDecodeError. Informar a codificação explicitamente não converte em UTF-8 um arquivo salvo em outra codificação.

O bloco with fecha o arquivo quando termina. Um arquivo fechado não pode ser lido: outra chamada a f.read() lança ValueError.

Um arquivo aberto usa recursos do sistema operacional. O texto que está sendo gravado também pode esperar em um buffer de memória antes de chegar ao arquivo. Fechar o arquivo libera os recursos e descarrega a saída do buffer. Uma instrução with organiza essa liberação em um ponto claro do código.

Leia dentro do bloco e use o resultado depois

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

Os dois-pontos iniciam o bloco. A linha indentada é executada enquanto f está aberto. Quando a execução chega ao print() sem indentação, o arquivo já foi fechado, mas text continua sendo uma string comum. O nome f ainda se refere ao objeto de arquivo; f.closed agora é True.

O mesmo padrão funciona para uma lista:

with open("fruit.txt", encoding="utf-8") as f:
    lines = f.readlines()
for line in lines:
    print(line.strip().upper())

O laço usa dados já lidos em lines. Mover f.readlines() para fora do bloco tentaria ler um arquivo fechado e lançaria ValueError.

Liberação de recursos quando a execução muda de direção

Considere uma função que retorna a primeira linha:

def first_line(path):
    with open(path, encoding="utf-8") as f:
        return f.readline().rstrip("\n")

O valor de retorno é preparado dentro do bloco. O Python então sai do bloco e fecha o arquivo antes que o código chamador receba esse valor. O arquivo também fecha quando uma exceção sai do bloco. Uma chamada manual a f.close() colocada depois de uma instrução que falha nunca seria alcançada.

Objetos de arquivo oferecem esse comportamento porque são gerenciadores de contexto: objetos que organizam a preparação e a liberação de recursos em torno de um bloco with. Você pode usar esse comportamento sem escrever um gerenciador de contexto por conta própria.

Abra uma entrada e uma saída juntas

with open("in.txt", encoding="utf-8") as src, open("out.txt", "w", encoding="utf-8") as dst:
    for line in src:
        dst.write(line.upper())

Cada linha de entrada é convertida em maiúsculas e gravada na saída. Ambos os arquivos fecham quando o bloco termina. Se a segunda abertura falhar, o primeiro arquivo, já aberto por with, será fechado quando o Python sair da instrução.

Liberação de recursos e recuperação têm funções diferentes

with não captura erros de arquivo. Se open() não conseguir encontrar notes.txt, ele lançará FileNotFoundError antes da execução do corpo. Se a conversão de uma linha com int() falhar dentro do corpo, o arquivo fechará e a exceção continuará se propagando. É necessária uma cláusula except correspondente para recuperar-se do erro ou mostrar uma mensagem.

A ausência de dois-pontos no fim da linha de with causa SyntaxError.

A gravação começa com uma escolha sobre os dados existentes. O modo controla se o Python lê, substitui, amplia ou cria um arquivo. Faça essa escolha antes de chamar open(), pois a substituição acontece imediatamente.

Escolha o modo

Abrir a única cópia de dados importantes com "w" destrói seu conteúdo anterior mesmo que nenhum write() venha depois. Use um arquivo de saída separado enquanto aprende a transformar dados. "x" é útil quando a substituição de um arquivo existente deve ser recusada.

Acrescentar "b", como em "rb", seleciona o modo binário para bytes brutos. Modos de texto trabalham com strings e uma codificação; modos binários não recebem um argumento encoding.

Decida onde as linhas terminam

with open("todo.txt", "w", encoding="utf-8") as f:
    f.write("buy milk\n")
    f.write("call Sam\n")

O arquivo tem as duas linhas “buy milk” e “call Sam”. write() acrescenta exatamente a string fornecida, sem separador automático. Sem os caracteres de nova linha, o arquivo conteria "buy milkcall Sam" em uma linha.

write() retorna o número de caracteres gravados. Por exemplo, f.write("Ana,92\n") retorna 7. Essa é uma contagem de caracteres, não necessariamente o número de bytes codificados no disco. Ele aceita uma string; f.write(42) lança TypeError. Converta um número primeiro, por exemplo, com f.write(f"{score}\n").

Compare os recursos de saída

print() pode gravar em um arquivo:

with open("total.txt", "w", encoding="utf-8") as f:
    print("Total:", 247, file=f)

O texto de saída é "Total: 247\n". print() converte seus argumentos, separa-os com espaços e acrescenta um caractere de nova linha ao fim por padrão.

writelines() recebe uma sequência de strings, mas não insere terminadores de linha. f.writelines(["a", "b"]) grava "ab". Para obter um item por linha, inclua um caractere de nova linha em cada string ou junte as strings com "\n" e acrescente um caractere de nova linha ao fim.

Mantenha as execuções anteriores

with open("log.txt", "a", encoding="utf-8") as f:
    f.write("Program started\n")

Começando sem um arquivo, duas execuções produzem duas linhas. Com "w", cada execução substituiria o registro anterior. O modo de acréscimo não fornece um caractere de nova linha ausente: se o texto existente terminar no meio de uma linha, o novo texto começa imediatamente depois dele.

Para um relatório, percorra pares como [("Ana", 92), ("Ben", 78)] e grave f"{name}: {score}\n". A formatação acontece antes da gravação, então f"{82.333:.1f}" produz o texto "82.3". Em seguida, with fecha a saída e descarrega o texto do buffer no fim do bloco.

Muitas tarefas com arquivos consistem em um laço com uma decisão dentro dele. Leia uma linha, remova o espaçamento indesejado, decida se ela interessa e atualize um resultado. Manter essas etapas separadas facilita a verificação do programa.

Examine um arquivo de registro

Suponha que server.log contenha estes registros, com uma linha em branco antes do último:

2026-03-01 08:14 INFO Server started
2026-03-01 08:20 ERROR Disk almost full
2026-03-01 09:02 INFO User login: maya
2026-03-01 09:15 WARNING Slow response
2026-03-01 10:40 ERROR Database timeout

2026-03-01 11:05 INFO Backup finished

Cada registro que não está em branco tem data, horário, nível e mensagem. Divida apenas três vezes para manter a mensagem junta:

errors = 0
with open("server.log", encoding="utf-8") as f:
    for line in f:
        line = line.strip()
        if not line:
            continue
        parts = line.split(maxsplit=3)
        if parts[2] == "ERROR":
            errors += 1
            print(parts[3])
print(errors, "errors")

Para o segundo registro, parts[2] é "ERROR" e parts[3] é "Disk almost full". Essa mensagem é impressa e o contador sobe para 1. O erro posterior faz o contador subir para 2. O programa imprime as duas mensagens e depois “2 errors”.

Verifique a parte desejada

Buscar em qualquer posição também encontraria “INFO No ERRORS today”. Verificar o campo de nível responde à pergunta sobre o registro com mais precisão.

Após strip(), uma linha em branco é ""; dividi-la produz []. A indexação de parts[2] lançaria então IndexError. O continue pula essa linha antes de qualquer indexação. Um registro que não está em branco, mas está incompleto, também precisa de uma verificação de comprimento quando esses registros são possíveis.

Conte categorias ou grave um arquivo filtrado

Um dicionário mantém uma contagem por nível. Para cada registro, defina level = parts[2] e depois counts[level] = counts.get(level, 0) + 1. Para o registro acima, as contagens são {'INFO': 3, 'ERROR': 2, 'WARNING': 1}. O valor padrão 0 inicia uma categoria na primeira vez que ela aparece.

Para salvar registros correspondentes, abra um destino separado na mesma instrução with e grave uma linha quando seu nível corresponder ao desejado. Mantenha a line original se o espaçamento for importante; se gravar o texto limpo, coloque seu caractere de nova linha de volta. Nunca abra a própria origem com "w": seu conteúdo seria esvaziado antes do início da leitura.

Veja caracteres invisíveis

print(repr(line)) torna visíveis os espaços e caracteres de nova linha no fim, por exemplo, 'Disk full \n'. strip() remove ambos, enquanto rstrip("\n") mantém os espaços. A leitura normal em modo texto traduz os terminadores de linha reconhecidos do Windows, Unix e Mac antigo para "\n". Uma última linha sem terminador permanece sem ele. Um nome de arquivo obtido por input("File name: ").strip() permite que o mesmo laço funcione com diferentes arquivos de entrada.

Um caminho descreve uma localização em uma árvore de pastas. Ele pode começar na raiz dessa árvore ou no diretório de trabalho atual do programa. Um arquivo pode existir no computador e ainda assim estar ausente na localização solicitada pelo programa.

Leia um caminho a partir de seu ponto de partida

Suponha que uma pasta chamada project contenha uma pasta scripts e uma pasta data. Você executa python scripts/report.py enquanto trabalha em project. Abrir "data/notes.txt" procura dentro de project/data, embora o script esteja em project/scripts.

Se, em vez disso, você iniciar o mesmo script enquanto trabalha em project/scripts, esse caminho relativo apontará para dentro de project/scripts/data. O script não mudou de lugar; o ponto de partida mudou.

from pathlib import Path
print(Path.cwd())

Isso imprime o diretório de trabalho atual. os.getcwd() após import os fornece a mesma informação como uma string. Editores e ferramentas de execução podem escolher um diretório de trabalho, então verifique-o quando a localização não estiver clara.

Percorra pastas

Em um caminho relativo, . significa a pasta atual e .. significa sua pasta pai. A partir de project/scripts, ../data/notes.txt sobe até project e depois entra em data. Acrescentar .. sem verificar a pasta de partida pode levar um programa à localização errada.

Um caminho absoluto é útil para identificar uma localização exata, mas um caminho como C:/Users/Maya/Desktop/data.csv vincula o código compartilhado às pastas de uma pessoa. Use um caminho relativo com um ponto de partida claro ou construa o caminho a partir da própria pasta do script quando for lá que os dados estão.

Mantenha intactas as barras invertidas do Windows

O Windows geralmente exibe barras invertidas entre pastas. Em uma string comum do Python, uma barra invertida inicia uma sequência de escape: \n torna-se um caractere de nova linha e \t, uma tabulação. Portanto, o literal "C:\new\table.txt" não contém o caminho pretendido.

Estas formas preservam o caminho pretendido:

raw = r"C:\new\table.txt"
escaped = "C:\\new\\table.txt"
forward = "C:/new/table.txt"

O Python no Windows aceita barras comuns. Uma string bruta impede que barras invertidas se tornem sequências de escape, mas não pode terminar com uma única barra invertida. Por exemplo, r"C:\data\" é uma sintaxe inválida.

Verifique o nome e a pasta

Procure diferenças na escrita e extensões ocultas: um arquivo exibido como “notes.txt” pode, na verdade, se chamar “notes.txt.txt”. Letras maiúsculas e minúsculas também importam. O Linux geralmente distingue Data.csv de data.csv; as configurações usuais do Windows e do macOS não fazem essa distinção. Usar exatamente as mesmas maiúsculas e minúsculas mantém um projeto utilizável em diferentes sistemas.

O módulo padrão pathlib dá a um caminho seu próprio objeto. Um Path permite juntar nomes de pastas, inspecionar um nome de arquivo e realizar tarefas comuns com arquivos sem construir manualmente strings de separadores.

Junte e inspecione

from pathlib import Path
p = Path("reports") / "2026" / "sales.csv"
print(p.name)
print(p.stem)
print(p.suffix)
print(p.parent)

Os três primeiros resultados são “sales.csv”, “sales” e “.csv”. A pasta pai é o caminho reports/2026, exibido com o separador do sistema. Aqui / junta partes de um caminho; ele não divide números. O antigo os.path.join() também junta partes de caminhos em strings.

Um Path descreve uma localização mesmo antes de existir algo nela. p.exists() verifica se há algo nessa localização. p.is_file() e p.is_dir() distinguem um arquivo de um diretório. Uma verificação de existência não pode garantir uma abertura posterior: o arquivo pode desaparecer ou o acesso pode mudar entre essas operações. Trate erros de abertura quando o programa precisar se recuperar.

Leia ou grave um arquivo pequeno

open() aceita um Path diretamente. Para um arquivo pequeno, estes recursos também cuidam da abertura e do fechamento:

p = Path("greeting.txt")
p.write_text("Hello\n", encoding="utf-8")
text = p.read_text(encoding="utf-8")

text torna-se "Hello\n". write_text() substitui o conteúdo existente, assim como abrir com "w"; ele não é um recurso de acréscimo. read_text() carrega o arquivo inteiro, então use um laço sobre o arquivo quando precisar tratar um arquivo grande linha por linha.

Comece pela pasta do script

Um arquivo de dados fornecido ao lado de um script deve ser localizado a partir desse script, independentemente do diretório de trabalho:

base = Path(__file__).resolve().parent
scores_path = base / "data" / "scores.txt"
with open(scores_path, encoding="utf-8") as f:
    scores = f.readlines()

__file__ identifica o arquivo do script. resolve() torna seu caminho absoluto, e parent seleciona a pasta que o contém. Em um interpretador interativo, __file__ não está definido, então esse padrão pertence a um script.

Encontre arquivos e prepare pastas de saída

for p in sorted(Path("logs").glob("*.txt")):
    text = p.read_text(encoding="utf-8")
    print(p.name, len(text.splitlines()))

glob("*.txt") seleciona caminhos correspondentes em logs. iterdir() produz as entradas da pasta sem esse filtro por padrão de nomes. A ordenação torna a ordem previsível. splitlines() conta as linhas de texto sem tratar o terminador da última linha como uma linha vazia extra.

A gravação cria um arquivo, mas não as pastas pai ausentes. Prepare-as primeiro:

folder = Path("output") / "daily"
folder.mkdir(parents=True, exist_ok=True)
(folder / "report.txt").write_text("Ready\n", encoding="utf-8")

parents=True cria pastas ausentes acima de daily. exist_ok=True aceita um diretório que já existe. Ele não transforma um arquivo comum existente em uma pasta.

Um arquivo CSV armazena uma tabela como texto. Seus registros são linhas, e seus campos são valores de colunas. Vírgulas geralmente separam os campos, mas campos delimitados por aspas podem conter vírgulas e até quebras de linha. Use o módulo csv para manter esses valores juntos.

Deixe o leitor tratar as aspas

name,quiz1,quiz2
Ana,8,9
Ben,7,6
"Lopez, Maria",10,8

A primeira linha é um cabeçalho, que contém nomes de colunas. A última linha de dados tem três campos, não quatro: a vírgula dentro do nome entre aspas faz parte do nome. Uma aspa dupla dentro de um campo delimitado por aspas é escrita duas vezes. Dividir cada linha com split(",") ignoraria essas regras e quebraria o nome em partes.

import csv
with open("grades.csv", newline="", encoding="utf-8") as f:
    reader = csv.reader(f)
    header = next(reader)
    for row in reader:
        average = (int(row[1]) + int(row[2])) / 2
        print(row[0], average)

O leitor retorna listas de strings. next(reader) consome o cabeçalho uma vez, deixando o laço processar os dados. O programa imprime “Ana 8.5”, “Ben 6.5” e “Lopez, Maria 9.0”. Na primeira linha de dados, converter "8" e "9" dá 17 no total; em seguida, dividir por 2 dá 8,5.

Alinhe o tratamento do arquivo e a interpretação da tabela

Abra arquivos CSV com newline="" para que o próprio módulo csv trate os terminadores de linha. Isso é importante quando um campo delimitado por aspas inclui uma quebra de linha. Um registro CSV pode ocupar várias linhas físicas do arquivo, então dividir linha por linha não substitui um leitor de CSV.

O comportamento padrão do leitor mantém os valores como strings. Sem conversão, somar row[1] + row[2] junta "8" e "9" em "89". Esquecer de pular o cabeçalho faz o programa tentar converter "quiz1" e lançar ValueError.

Se um arquivo puder estar vazio, next(reader, None) consome um cabeçalho quando ele existe e retorna None caso contrário. Uma linha CSV completamente em branco se torna []. Pule essas linhas com if not row: continue antes de indexar. Uma linha que não está em branco, mas tem poucos campos, também precisa de uma verificação de comprimento; pular apenas linhas em branco não protegerá row[2] de todos os registros curtos.

Use o formato do arquivo

reader = csv.reader(f, delimiter=";", skipinitialspace=True)

Isso seleciona pontos e vírgulas como separadores e remove espaços imediatamente após eles. Escolha o separador que o arquivo realmente usa; mudar o separador não converte vírgulas decimais em pontos decimais. float("2,50") ainda lança ValueError.

Alguns arquivos exportados de planilhas começam com uma marca de ordem de bytes UTF-8. Ler um desses arquivos com encoding="utf-8" pode deixar "\ufeff" no início do primeiro campo, transformando o cabeçalho "name" em "\ufeffname". Para esse formato, encoding="utf-8-sig" remove o marcador; ele também pode ler arquivos UTF-8 sem o marcador.

Um gravador de CSV transforma valores em campos corretamente separados e delimitados por aspas. Forneça a ele linhas como sequências de valores e deixe que ele cuide da pontuação. Isso evita uma saída que parece correta até que um nome ou uma mensagem contenha uma vírgula.

Grave um cabeçalho e dados

import csv
with open("summary.csv", "w", newline="", encoding="utf-8") as f:
    writer = csv.writer(f)
    writer.writerow(["name", "average"])
    writer.writerow(["Ana", 8.5])
    writer.writerow(["Lopez, Maria", 9.0])

O arquivo tem as linhas name,average, Ana,8.5 e "Lopez, Maria",9.0. O gravador converte números em texto. Ele coloca o nome com vírgula entre aspas e duplica qualquer aspa dupla dentro de um campo delimitado por aspas. None torna-se um campo vazio, então ler o arquivo novamente não recupera None automaticamente.

writerow() recebe uma linha. writerows() recebe uma sequência de linhas, como [["Ana", 8.5], ["Ben", 6.5]]. Passar "Ana" diretamente a writerow() fornece três caracteres, produzindo A,n,a. Use ["Ana"] para uma linha com um campo.

Dê ao CSV o controle dos terminadores de linha

Use newline="" ao abrir a saída. O gravador padrão termina registros com "\r\n". Permitir também a tradução de caracteres de nova linha do modo texto pode acrescentar um retorno de carro extra no Windows, produzindo linhas em branco indesejadas em alguns leitores. O argumento newline impede essa segunda camada de tradução.

Transforme um arquivo em outro

with open("grades.csv", newline="", encoding="utf-8") as src, open("summary.csv", "w", newline="", encoding="utf-8") as dst:
    reader = csv.reader(src)
    writer = csv.writer(dst)
    next(reader)
    writer.writerow(["name", "average"])
    for row in reader:
        average = (int(row[1]) + int(row[2])) / 2
        writer.writerow([row[0], round(average, 2)])

Para as linhas de notas “Ana,8,9”, “Ben,7,6” e "Lopez, Maria",10,8, as médias são 8,5, 6,5 e 9,0. O leitor remove a delimitação por aspas do CSV do valor do campo de entrada; o gravador acrescenta novamente as aspas necessárias na saída. round() controla o valor numérico gravado, embora não obrigue a exibição de duas casas decimais. Use um formato como f"{average:.2f}" quando quiser exatamente duas casas.

Acrescente sem repetir o cabeçalho

Antes de abrir um arquivo para acréscimo, verifique se ele precisa de um cabeçalho:

from pathlib import Path
p = Path("sales.csv")
needs_header = not p.exists() or p.stat().st_size == 0
with open(p, "a", newline="", encoding="utf-8") as f:
    writer = csv.writer(f)
    if needs_header:
        writer.writerow(["item", "quantity"])
    writer.writerow(["coffee", 4])

Um arquivo existente e vazio também precisa de cabeçalho. Gravar o cabeçalho em toda execução coloca nomes de colunas no meio dos dados. Esse padrão pressupõe que um único programa esteja atualizando o arquivo; uma verificação de existência não impede que outros programas o alterem.

Código baseado em posição, como row[2], depende da ordem das colunas. Um leitor baseado em dicionários permite nomear o valor necessário. Um dicionário associa chaves a valores; aqui, o cabeçalho fornece as chaves e cada registro de dados fornece seus valores.

Leia campos pelo nome

import csv
with open("inventory.csv", newline="", encoding="utf-8") as f:
    reader = csv.DictReader(f)
    rows = list(reader)

Para o cabeçalho product,stock,price e a linha notebook,12,2.50, o primeiro dicionário é {'product': 'notebook', 'stock': '12', 'price': '2.50'}. reader.fieldnames fornece os nomes do cabeçalho. O cabeçalho é consumido automaticamente; chamar next(reader) pularia o primeiro registro de dados.

Use row["stock"] para selecionar o estoque, mesmo que as colunas sejam reordenadas. Converta-o com int() para comparar quantidades. Os valores continuam sendo strings; os nomes das colunas não fornecem tipos numéricos ao leitor.

Filtre e some

Suponha que a tabela contenha estoque de 12 cadernos ao preço de 2,50, estoque de 3 canetas a 1,20, estoque de 0 grampeadores a 7,95 e estoque de 25 pastas a 0,80.

low = [r for r in rows if int(r["stock"]) < 5]
value = sum(int(r["stock"]) * float(r["price"]) for r in rows)

low contém as linhas da caneta e do grampeador. O valor é R$ 53,6: os cadernos contribuem com 30, as canetas com 3,6, os grampeadores com 0 e as pastas com 20. O filtro usa o estoque, enquanto o total usa tanto o estoque quanto o preço.

Distinga chaves ausentes de valores ausentes

Os nomes do cabeçalho devem corresponder exatamente. Name e name são chaves diferentes. Um espaço após uma vírgula pode se tornar parte de um cabeçalho; skipinitialspace=True remove espaços imediatamente após os separadores.

Um cabeçalho name,quiz1,quiz2 com os dados Ben,7 produz {'name': 'Ben', 'quiz1': '7', 'quiz2': None}. A chave existe, mas seu valor está ausente. int(None) lança TypeError. Um campo presente e vazio é "", e convertê-lo lança ValueError. Uma chave ausente do cabeçalho causa KeyError na consulta.

Com os dados Cara,1,2,3, campos extras são reunidos como None: ['3']; os campos nomeados ainda contêm "Cara", "1" e "2". Verifique a estrutura de uma linha quando totais precisos dependerem de todos os campos.

Grave colunas selecionadas

with open("reorder.csv", "w", newline="", encoding="utf-8") as f:
    writer = csv.DictWriter(f, fieldnames=["product", "stock"])
    writer.writeheader()
    for r in low:
        writer.writerow({"product": r["product"], "stock": r["stock"]})

fieldnames define a ordem da saída, independentemente da ordem do dicionário. Chaves ausentes do dicionário tornam-se campos vazios. Chaves extras lançam ValueError por padrão: passar um dicionário de estoque que contém price a esse gravador de duas colunas falha. Crie o dicionário menor como mostrado ou escolha extrasaction="ignore" quando descartar campos extras for intencional.

Uma exceção é um objeto que sinaliza um problema durante a execução. Lançá-la interrompe a execução normal. Se nenhum tratador lidar com ela, o Python encerra o programa com um traceback, um relatório das chamadas que levaram ao erro.

Comece pela parte inferior

def average(values):
    return sum(values) / len(values)

def report():
    scores = []
    print(average(scores))

report()

O traceback termina com ZeroDivisionError: division by zero. Comece por ali: o tipo indica a espécie de problema e a mensagem fornece detalhes. A entrada imediatamente acima aponta para a divisão em average(). Entradas anteriores mostram a chamada de report() e a chamada original a report(). A lista está vazia, então seu comprimento é 0. A linha indicada como falha é onde o problema aparece; a atribuição anterior da lista vazia explica como ele surgiu.

Escolha o tipo correspondente

int("abc") recebe um tipo de entrada permitido, uma string, mas não consegue interpretar esse valor como um inteiro. Já "5" + 3 mistura tipos incompatíveis para adição. Uma string que contém dígitos continua sendo uma string.

Operações com arquivos têm tipos mais específicos: FileNotFoundError para um caminho ausente, PermissionError para acesso negado e FileExistsError para a criação de um arquivo existente com "x". Abrir um diretório como um arquivo comum pode lançar IsADirectoryError. Decodificar bytes com uma codificação incompatível pode lançar UnicodeDecodeError.

Entenda a árvore de família

As classes de exceção formam uma hierarquia. Um tratador para uma classe pai pode capturar suas classes filhas:

• OSError é a classe pai de erros comuns do sistema de arquivos, incluindo FileNotFoundError e PermissionError.
• LookupError é a classe pai de IndexError e KeyError.
• ArithmeticError é a classe pai de ZeroDivisionError.
• UnicodeDecodeError está abaixo de ValueError.

Esses ramos descendem de Exception, que descende de BaseException. Já KeyboardInterrupt e SystemExit descendem diretamente de BaseException. Essa distinção permite que except Exception deixe passar a interrupção pelo usuário e a saída do programa.

Separe problemas de sintaxe, execução e lógica

A ausência de dois-pontos ou de um parêntese de fechamento pode impedir o Python de analisar um script. O SyntaxError resultante ocorre antes da execução do script, então um try nesse mesmo script não pode capturá-lo. Uma exceção em tempo de execução ocorre enquanto código válido é executado. Um erro de lógica produz uma resposta errada sem necessariamente lançar uma exceção, como dividir um total pela contagem errada.

Uma instrução try executa código que pode falhar e oferece um caminho de recuperação para exceções selecionadas. O tratador deve corresponder ao problema que o programa espera e ao qual sabe responder.

Acompanhe o fluxo

while True:
    try:
        age = int(input("Age: "))
        break
    except ValueError:
        print("Please enter a whole number, like 34.")
print("Next year you will be", age + 1)

Digitar “twenty” faz int() lançar ValueError. O Python ignora o restante do try, incluindo break, e executa o tratador correspondente. O laço então pergunta novamente. Digitar “34” permite que o try prossiga até break, então o programa sai do laço e imprime “Next year you will be 35”.

Um tratador não retoma a execução na instrução que falhou. A execução prossegue depois da instrução try, a menos que o próprio tratador altere esse fluxo. Se nenhum tratador corresponder, a exceção se propaga.

Trate falhas diferentes de maneiras diferentes

try:
    result = int(a) / int(b)
except ValueError:
    print("Both values must be whole numbers.")
except ZeroDivisionError:
    print("The second value cannot be 0.")

Uma conversão inválida e um divisor zero precisam de mensagens diferentes. Se a resposta tiver de ser idêntica, agrupe os tipos em uma tupla: except (ValueError, ZeroDivisionError):. Os parênteses funcionam em todo o Python 3. O Python 3.14 também permite uma lista sem parênteses quando não há uma parte as; a forma de tupla continua clara em todas as versões.

O Python verifica as cláusulas de cima para baixo e executa a primeira correspondente. Coloque FileNotFoundError antes de seu tipo pai OSError se um arquivo ausente precisar de uma resposta especial. Inverter a ordem torna o tratador especial inalcançável.

Use a mensagem sem ocultar outros defeitos

try:
    quantity = int(text)
except ValueError as err:
    print("Cannot read quantity:", err)

err é o objeto de exceção; imprimi-lo mostra sua mensagem. type(err).__name__ fornece o nome de sua classe. O Python apaga a associação de err no tratador quando ele termina, então copie sua mensagem para outra variável dentro do bloco se precisar dela depois.

Mantenha o try pequeno. Coloque cálculos posteriores fora do tratador de conversão quando suas falhas precisarem de tratamento diferente. except Exception: pode ocultar defeitos, como uma variável não definida. Um except: sem tipo é ainda mais abrangente: ele também captura KeyboardInterrupt e SystemExit.

Tente a operação, não uma imitação aproximada

Testar text.isdigit() não testa tudo o que int() aceita. "-5" e " 34" falham nesse teste, mas são convertidos com sucesso; "²" passa no teste, mas não é convertido com int(). Tentar a conversão e capturar ValueError usa as próprias regras da conversão.

Faça algo visível ou registrado ao tratar dados inválidos. Um except ValueError: pass vazio pode deixar o programa continuar com resultados ausentes e sem registro do que deu errado.

Uma instrução try pode separar a operação que pode falhar, a recuperação, as ações em caso de sucesso e a liberação de recursos. Uma exceção também pode sair de uma função e ser tratada pelo código que a chamou.

Dê às ações em caso de sucesso um bloco próprio

try:
    x = 10 / int(text)
except ValueError:
    print("not a number")
except ZeroDivisionError:
    print("zero")
else:
    print("result", x)
finally:
    print("done")

Com text = "4", o programa imprime “result 2.5” e “done”. Com "abc", imprime “not a number” e “done”; com "0", imprime “zero” e “done”.

else é executado quando o try termina normalmente, sem uma exceção. Ele não é executado depois que um tratador se recupera de um erro. Também é ignorado quando return, break ou continue faz a execução sair do try antes do fim. Erros lançados dentro de else não são capturados pelas cláusulas except anteriores dessa instrução, então as ações em caso de sucesso não compartilham acidentalmente os tratadores da operação que pode falhar.

Libere recursos em todos os caminhos de saída

finally é executado quando o controle sai da instrução: após o sucesso, após uma exceção tratada e antes que uma exceção não tratada continue se propagando. Ele também é executado antes que um retorno pendente seja concluído.

def label():
    try:
        return "from try"
    finally:
        print("finally ran")

value = label()
print(value)

Isso imprime “finally ran” e depois “from try”. O retorno aguardou enquanto os recursos eram liberados. Para arquivos, with já fornece o comportamento de fechamento, então geralmente elimina a necessidade de um fechamento manual em finally.

Não coloque uma saída como return, break ou continue em finally. Sair do bloco de liberação dessa maneira pode descartar uma exceção pendente ou substituir um retorno. O Python 3.14 e versões posteriores emitem um SyntaxWarning para esse padrão. Use esse bloco apenas para liberar recursos.

Acompanhe uma exceção até o código chamador

def read_scores(path):
    with open(path, encoding="utf-8") as f:
        return [int(line) for line in f]

try:
    scores = read_scores("scores.txt")
except FileNotFoundError:
    print("The score file is missing.")

Se a abertura falhar, read_scores() não tem tratador, então FileNotFoundError se propaga até a chamada dentro do try externo. O código chamador o trata e imprime a mensagem. Se uma linha não for um inteiro, um ValueError segue o mesmo caminho, mas o tratador de arquivo ausente não corresponde a ele.

Escolha o nível que pode dar uma resposta útil

Uma função de leitura pode saber como obter dados, mas não se um arquivo ausente deve provocar uma nova tentativa, uma tarefa ignorada ou uma interrupção controlada. Deixar a exceção chegar ao código chamador que interage com o usuário mantém essa escolha ali. Capturá-la cedo demais e retornar uma lista vazia pode ocultar a diferença entre um arquivo vazio e uma leitura que falhou.

Um programa trata uma falha de forma controlada quando responde a um problema de maneira controlada e útil. Ele pode perguntar novamente, informar uma linha ignorada ou parar com uma mensagem clara. Escolha essa resposta de acordo com o uso do resultado.

Tente novamente quando um arquivo estiver ausente

while True:
    name = input("File name: ").strip()
    try:
        with open(name, encoding="utf-8") as f:
            text = f.read()
    except FileNotFoundError:
        print(f"No file named '{name}'. Please try again.")
    else:
        break
print(len(text.splitlines()), "lines")

Uma abertura que falha ignora a atribuição e chega ao tratador. O laço pergunta novamente. Uma leitura bem-sucedida chega a else, interrompe o laço e deixa text disponível para a contagem final. O arquivo é fechado por with em qualquer saída de um bloco em que se tenha entrado.

Para problemas diferentes de arquivo, use FileNotFoundError, depois PermissionError e depois um tratador geral de OSError se outros erros do sistema de arquivos precisarem de uma resposta. As cláusulas específicas devem vir primeiro. Decodificar bytes inválidos é um problema diferente; uma mensagem sobre um caminho ausente não o descreveria.

Trate cada linha de dados separadamente

Para um resumo rápido de vendas, suponha que as linhas CSV após o cabeçalho sejam coffee,4, tea,two, muffin,3, cookie, e juice,5.

import csv
total = 0
skipped = 0
with open("sales.csv", newline="", encoding="utf-8") as f:
    reader = csv.reader(f)
    next(reader, None)
    for row in reader:
        try:
            if len(row) != 2:
                raise ValueError("expected two fields")
            quantity = int(row[1])
        except ValueError as err:
            skipped += 1
            print(f"sales.csv, ending line {reader.line_num}: {err}")
        else:
            total += quantity
print("Total:", total, "Skipped:", skipped)

As quantidades válidas totalizam 12. A palavra “two” e a quantidade vazia são rejeitadas, então a contagem de linhas ignoradas é 2. A verificação da linha também transforma uma quantidade inesperada de campos em um erro de dados informado antes da indexação. Colocar try dentro do laço permite que o próximo registro seja processado após a falha de um registro; colocar o laço dentro de um único try faria a execução sair do laço na primeira falha.

Informe as localizações com precisão

Para os cinco registros de uma linha cada, os valores inválidos terminam nas linhas 3 e 5 do arquivo. enumerate(reader, start=2) corresponderia a esses números de linha aqui, mas uma quebra de linha dentro de aspas faz um registro CSV ocupar mais de uma linha. reader.line_num informa quantas linhas físicas o leitor consumiu. Chamá-la de linha final mantém as mensagens precisas para registros de várias linhas.

Decida se um resultado parcial é aceitável

Uma contagem exploratória rápida pode permitir que linhas sejam ignoradas e informadas. Um total financeiro ou de notas pode precisar de todos os registros: pare e peça dados corrigidos em vez de apresentar um total parcial como completo. Informe o arquivo, a localização e o problema para que ele possa ser corrigido.

Após import sys, sys.exit("Could not open sales.csv") grava a mensagem na saída de erros e encerra com código de saída 1. Ele lança SystemExit, que except Exception não captura. Mantenha os tratadores específicos para que um erro de programação não relacionado não seja identificado incorretamente como um problema de arquivo.

Uma função deve sinalizar quando não consegue produzir um resultado válido. raise inicia uma exceção nesse ponto, impedindo que o caminho inválido continue como se a operação tivesse dado certo.

Verifique antes de calcular

def withdraw(balance, amount):
    if amount <= 0:
        raise ValueError(f"amount must be positive, got {amount}")
    if amount > balance:
        raise ValueError(f"amount {amount} is more than the balance {balance}")
    return balance - amount

withdraw(100, 30) retorna 70. withdraw(100, 150) lança um erro sobre o saldo; withdraw(100, -5) lança um erro sobre um valor que não é positivo. Nenhuma das chamadas que falham chega à subtração.

Uma exceção lançada segue as mesmas regras de tratamento de um erro embutido. Se um tratador correspondente dentro da função a capturar, a execução poderá continuar ali. Caso contrário, a exceção sai da função e chega ao código chamador. Se nenhum tratador for encontrado, o Python apresenta um traceback.

Deixe o código chamador escolher a resposta

balance = 100
amount = 150
try:
    balance = withdraw(balance, amount)
except ValueError as err:
    print(f"Cannot withdraw: {err}")

A função informa por que não consegue realizar o saque. O código chamador decide exibir uma mensagem. Como a chamada de função falha antes de retornar, a atribuição não substitui o saldo anterior por um resultado. Outro código chamador poderia pedir um valor menor ou cancelar uma transação sem alterar a função.

Imprimir um aviso dentro da função e retornar None pode fazer o código chamador levar um valor inválido para um cálculo posterior. Lançar uma exceção mantém a falha ligada à sua causa e oferece ao código chamador um caminho de erro distinto.

Escolha um tipo significativo

Um valor numérico negativo é inaceitável. Uma lista fornecida onde um número é necessário tem um tipo inadequado. O tipo de exceção faz parte do comportamento da função: o código chamador o usa para selecionar tratadores. Não escolha um tipo apenas por ser familiar.

Escreva uma mensagem útil

Uma mensagem deve indicar o que era esperado e o que chegou. f"age must be between 0 and 130, got {age}" indica uma correção. Uma mensagem como “erro” não fornece detalhes úteis. Mantenha a mensagem relacionada à operação que falhou; o código que interage com o usuário pode acrescentar o contexto mais amplo.

raise ValueError("amount must be positive") cria uma exceção com uma mensagem. raise ValueError também é válido e cria uma exceção sem mensagem. Uma string simples não é uma exceção: raise "error" lança TypeError porque objetos lançados devem derivar de BaseException.

Às vezes, uma função percebe um erro, mas não consegue concluir seu tratamento. Ela pode precisar repassar o mesmo erro, transformá-lo em um erro mais útil ou dar a um problema específico do programa seu próprio tipo de exceção.

Relance o erro atual

def read_text(path):
    try:
        with open(path, encoding="utf-8") as f:
            return f.read()
    except FileNotFoundError:
        print(f"Missing: {path}")
        raise

O raise sem argumento dentro do tratador relança a exceção atual. Apenas imprimir uma mensagem terminaria o tratador e faria a função retornar None; relançar torna a falha de leitura visível ao código chamador. Um raise sem argumento precisa de uma exceção ativa para relançar.

Transforme o erro preservando a causa

def read_price(row):
    try:
        text = row["price"]
    except KeyError as err:
        raise ValueError("row has no 'price' column") from err
    return float(text)

Uma chave ausente torna-se um ValueError com uma mensagem sobre a linha. from err registra o KeyError original como sua causa direta. O traceback mostra o erro original, a ligação entre eles e o novo erro. O código chamador pode tratar o tipo transformado, enquanto a causa de nível inferior continua disponível para depuração.

Esse tratador limita-se à consulta. Um valor presente como "free" falha depois em float(text) com seu próprio ValueError; ele não é informado incorretamente como uma coluna ausente.

Defina um tipo distinto

class InsufficientFundsError(ValueError):
    pass

Esse padrão cria uma classe de exceção personalizada. O nome termina em Error por convenção. O nome entre parênteses é sua classe pai, então essa classe é um tipo de ValueError.

def withdraw(balance, amount):
    if amount > balance:
        raise InsufficientFundsError(
            f"balance {balance}, requested {amount}"
        )
    return balance - amount

try:
    withdraw(100, 150)
except InsufficientFundsError as err:
    print("Not enough money:", err)

O programa imprime “Not enough money: balance 100, requested 150”. O código chamador pode distinguir saldo insuficiente de outro valor inválido. Se um tratador de ValueError aparecesse antes desse tratador específico, o tipo pai o capturaria primeiro.

Escolha a classe pai para o tratamento desejado

Derivar de ValueError permite que tanto um tratador específico quanto um tratador mais amplo de erro de valor capturem o tipo personalizado. Derivar diretamente de Exception cria um ramo separado de erros comuns, então except ValueError não o capturaria. Um tipo personalizado é útil quando o código chamador precisa de uma resposta distinta; um tipo embutido claro e uma mensagem são suficientes quando isso não é necessário.