Python PEP 8

Os dois programas abaixo fazem exatamente a mesma coisa e mostram o mesmo resultado. Um deles você entende em segundos; o outro, você precisa decifrar. A diferença não está no que o código faz, está no jeito de escrever. A comunidade Python combinou um jeito, escrito num documento chamado PEP 8, e quase todo código Python que você vai encontrar segue esse combinado. Nesta aula você aprende as regras principais e as ferramentas que conferem (e até arrumam) o código por você.

A ideia: letra legível e ortografia combinada

Um bilhete escrito às pressas, sem pontuação, com abreviações que só você entende, até passa a mensagem. Mas quem lê sofre. Por isso existem a ortografia e as regras de pontuação: todo mundo escreve do mesmo jeito, e todo mundo lê sem esforço.

Com código é igual. O Python aceita muita coisa, mas um programa é lido muito mais vezes do que é escrito: por você mesma daqui a um mês, por quem vai continuar o seu trabalho, por quem vai ajudar a achar um erro. A PEP 8 é a "ortografia" do Python.

Antes e depois

import sys, os
def CalculaTotal( Itens,Desc ):
  T=0
  for i in Itens :
      T=T+i[ 0 ]*i[1]
  if Desc==True : T = T*0.9
  return T
class carrinho:
    def __init__(self,dono): self.dono=dono;self.itens=[]
print(CalculaTotal([(27.90,2),(8.49,3)],True))

DESCONTO_CLIENTE_FIEL = 0.10


def calcular_total(itens, cliente_fiel):
    total = 0
    for preco, quantidade in itens:
        total += preco * quantidade
    if cliente_fiel:
        total *= 1 - DESCONTO_CLIENTE_FIEL
    return total


class Carrinho:
    def __init__(self, dono):
        self.dono = dono
        self.itens = []


print(calcular_total([(27.90, 2), (8.49, 3)], True))

$ python3 baguncado.py
73.143
$ python3 arrumado.py
73.143

Mesmo resultado. Mas no segundo dá para ler como um texto: "para cada preço e quantidade nos itens, some ao total; se for cliente fiel, aplique o desconto". As seções a seguir mostram, uma por uma, as regras que transformaram o primeiro no segundo.

1. Indentação: 4 espaços

No Python, a indentação (o recuo no começo da linha) não é enfeite: é ela que diz o que está dentro do for, do if, da função (veja Sintaxe e Indentação). O Python aceita qualquer quantidade de espaços, desde que você seja coerente dentro do bloco. O baguncado.py usa 2 espaços num lugar, 6 em outro e 4 na classe, e funciona. A PEP 8 combina: 4 espaços por nível, sempre.

def calcular_total(itens):
    total = 0  # 1 nível: 4 espaços
    for preco, quantidade in itens:
        total += preco * quantidade  # 2 níveis: 8 espaços
    return total

E a tecla Tab? A PEP 8 prefere espaços. Os editores de código (VS Code, o editor deste guia e outros) já trocam o Tab por 4 espaços sozinhos. O que não pode é misturar os dois no mesmo bloco: o Python recusa (veja Quando dá errado).

2. Nomes

Cada tipo de coisa tem o seu jeito de escrever o nome. Assim, só de olhar, você sabe se Carrinho é uma classe e se calcular_total é uma função.

Mais quatro conselhos sobre nomes:

• Diga o que é. for preco, quantidade in itens: se lê sozinho; for i in Itens: com i[0] e i[1] obriga quem lê a adivinhar. Letras soltas (i, x) só para contadores e contas curtas.
• Nunca use l (L minúsculo), O (o maiúsculo) ou I (i maiúsculo) sozinhos como nome. Em muitas fontes eles se confundem com 1 e 0: l = 1, O = 0.
• Não use nomes que o Python já usa, como list, str, sum, id, input: você esconde a função embutida (o erro está em Quando dá errado). Se o nome bom é uma palavra reservada, a PEP 8 sugere um sublinhado no fim: class_, id_.
• Sem acento, por costume. O Python 3 aceita preço = 10, mas quase ninguém escreve assim (é difícil de digitar em teclados de outros países). Este guia usa preco.

def CalcularMedia(Notas):
    return sum(Notas) / len(Notas)


NotasDaTurma = [8, 7, 9, 6]
print("Média:", CalcularMedia(NotasDaTurma))

def calcular_media(notas):
    return sum(notas) / len(notas)


notas_da_turma = [8, 7, 9, 6]
print("Média:", calcular_media(notas_da_turma))

3. Espaços

A regra geral: espaço onde ajuda a separar as ideias, nenhum espaço onde só atrapalha.

Em contas misturadas, a PEP 8 permite tirar os espaços do operador que é feito primeiro, para mostrar a precedência: x = a*2 + b fica mais claro que x = a * 2 + b. As duas formas são aceitas.

4. Linhas: tamanho e linhas em branco

No máximo 79 caracteres

A PEP 8 pede linhas de até 79 caracteres (72 nos comentários e docstrings), para caber em janelas estreitas e em dois arquivos lado a lado. Muitas equipes combinam um limite um pouco maior (o black e o ruff usam 88; a própria PEP 8 aceita até 99 quando a equipe concorda). Para quebrar uma linha comprida, use os parênteses: dentro de ( ), [ ] ou { }, o Python deixa você continuar na linha de baixo.

# comprida demais (111 caracteres)
mensagem = f"Olá, {nome_do_cliente}! O seu pedido de número {numero_do_pedido} saiu para entrega e chega hoje."

# quebrada com parênteses: dois textos seguidos viram um só
mensagem = (
    f"Olá, {nome_do_cliente}! O seu pedido de número {numero_do_pedido} "
    "saiu para entrega e chega hoje."
)

# uma chamada com muitos argumentos: um por linha
total = calcular_total(
    itens=carrinho,
    cliente_fiel=True,
    cupom="PADARIA10",
)

A vírgula depois do último argumento (cupom="PADARIA10",) é permitida e costumeira quando cada item está na sua linha: acrescentar um item depois mexe numa linha só. Existe também a barra invertida \ no fim da linha para continuar na próxima, mas a PEP 8 prefere os parênteses.

Linhas em branco

• Duas linhas em branco antes e depois de cada função e classe "de fora" (as que não estão dentro de outra coisa).
• Uma linha em branco entre os métodos dentro de uma classe.
• Dentro de uma função, uma linha em branco de vez em quando para separar as "etapas", como parágrafos de um texto. Sem exagero.

Volte ao arrumado.py e repare: duas linhas antes de def calcular_total, duas antes de class Carrinho, duas antes do print final.

5. imports

import csv
import json
from pathlib import Path

import requests

from loja import calcular_total

1. No começo do arquivo (depois só da docstring do módulo, se houver).
2. Um módulo por linha: import csv e import json, e não import csv, json. (Já from pathlib import Path, PurePath, vários nomes do mesmo módulo, pode.)
3. Em três grupos, separados por uma linha em branco: primeiro a biblioteca padrão (o que vem com o Python: csv, json, pathlib); depois os pacotes instalados com o pip (como o requests); por último os seus módulos (loja). Dentro de cada grupo, em ordem alfabética, por costume.
4. Evite from modulo import * ("importe tudo"): ninguém sabe de onde veio cada nome, e um nome importado pode esconder outro, como o open do exemplo em Quando dá errado.
5. Não importe o que não usa. O baguncado.py importava sys e os sem usar nenhum dos dois.

6. Comparações no estilo do Python

7. O Zen do Python

Por trás da PEP 8 há uma "filosofia", escondida dentro do próprio Python. Digite import this:

$ python3 -c "import this"
The Zen of Python, by Tim Peters

Beautiful is better than ugly.
Explicit is better than implicit.
Simple is better than complex.
Complex is better than complicated.
Flat is better than nested.
Sparse is better than dense.
Readability counts.
Special cases aren't special enough to break the rules.
Although practicality beats purity.
Errors should never pass silently.
Unless explicitly silenced.
In the face of ambiguity, refuse the temptation to guess.
There should be one-- and preferably only one --obvious way to do it.
Although that way may not be obvious at first unless you're Dutch.
Now is better than never.
Although never is often better than *right* now.
If the implementation is hard to explain, it's a bad idea.
If the implementation is easy to explain, it may be a good idea.
Namespaces are one honking great idea -- let's do more of those!

"O Zen do Python", 19 frases de Tim Peters. Algumas, traduzidas: "Bonito é melhor que feio." "Explícito é melhor que implícito." "Simples é melhor que complexo." "A legibilidade conta." "Erros nunca devem passar em silêncio." "Deve haver um (e de preferência só um) jeito óbvio de fazer." "Se a implementação é difícil de explicar, é uma má ideia." (A brincadeira do "a não ser que você seja holandês" é com o Guido van Rossum, que é holandês.)

import this

8. As ferramentas: ruff e black

Ninguém confere a PEP 8 de olho. Há programas que fazem isso: os linters (de lint, os fiapos de tecido que grudam na roupa) apontam os problemas, e os formatadores reescrevem o código no estilo certo. Os dois mais usados hoje são o ruff (linter e formatador) e o black (formatador). Eles não vêm com o Python: a Ana instalou os dois num ambiente virtual.

$ python3 -m venv .venv
$ .venv/bin/pip install -q ruff black
$ .venv/bin/ruff --version
ruff 0.17.1
$ .venv/bin/black --version
black, 26.10.1 (compiled: yes)
Python (CPython) 3.14.4

(As versões mudam com o tempo; as saídas abaixo são destas versões.)

O linter: ruff check

Por padrão, o ruff check confere só um grupo pequeno de regras (nesta versão, entre outras, os imports desnecessários e a ordem dos imports):

$ .venv/bin/ruff check --output-format concise baguncado.py
baguncado.py:1:1: I001 [*] Import block is un-sorted or un-formatted
baguncado.py:1:8: F401 [*] `sys` imported but unused
baguncado.py:1:13: F401 [*] `os` imported but unused
Found 3 errors.
[*] 3 fixable with `--fix`.

Pedindo mais regras com --select (E e W: os erros e avisos de estilo da PEP 8; F: os erros prováveis; N: os nomes), aparece quase tudo o que você viu nesta aula:

$ .venv/bin/ruff check --select E,W,F,N --output-format concise baguncado.py
baguncado.py:1:1: E401 [*] Multiple imports on one line
baguncado.py:1:8: F401 [*] `sys` imported but unused
baguncado.py:1:13: F401 [*] `os` imported but unused
baguncado.py:2:5: N802 Function name `CalculaTotal` should be lowercase
baguncado.py:2:19: N803 Argument name `Itens` should be lowercase
baguncado.py:2:25: N803 Argument name `Desc` should be lowercase
baguncado.py:3:3: N806 Variable `T` in function should be lowercase
baguncado.py:5:7: N806 Variable `T` in function should be lowercase
baguncado.py:6:6: E712 Avoid equality comparisons to `True`; use `Desc:` for truth checks
baguncado.py:6:17: E701 Multiple statements on one line (colon)
baguncado.py:6:19: N806 Variable `T` in function should be lowercase
baguncado.py:8:7: N801 Class name `carrinho` should use CapWords convention
baguncado.py:9:44: E702 Multiple statements on one line (semicolon)
Found 13 errors.
[*] 3 fixable with `--fix` (1 unsafe fix available with `--fix --unsafe-fixes`).

baguncado.py:2:5:

Arquivo, linha 2, coluna 5: onde está o problema.

N802

O código da regra. Cada letra é uma família (E, W, F, N, I de imports…). Com o código, você acha a explicação completa na documentação do ruff.

Function name `CalculaTotal` should be lowercase

"O nome da função CalculaTotal deveria ser em minúsculas."

[*]

O ruff sabe consertar este sozinho, com --fix.

Algumas traduções: E401 "vários imports numa linha"; F401 "sys importado mas não usado"; E712 "evite comparar com True; use Desc:"; E701/E702 "várias instruções numa linha (dois-pontos / ponto e vírgula)"; N801 "o nome da classe carrinho deveria usar CapWords". E o tamanho da linha tem a regra E501:

$ .venv/bin/ruff check --select E501 --output-format concise linha_longa.py
linha_longa.py:1:89: E501 Line too long (111 > 88)
Found 1 error.

"Linha comprida demais (111 > 88)". O ruff usa 88 como limite, a não ser que você configure outro. Um código sem nenhum problema recebe: All checks passed! ("tudo conferido"), como o arrumado.py:

$ .venv/bin/ruff check --output-format concise arrumado.py
All checks passed!

O formatador: ruff format (ou black)

Com --diff, o formatador mostra o que mudaria, sem mexer no arquivo. As linhas com - saem, as com + entram:

$ .venv/bin/ruff format --diff baguncado.py
--- baguncado.py
+++ baguncado.py
@@ -1,10 +1,19 @@
 import sys, os
-def CalculaTotal( Itens,Desc ):
-  T=0
-  for i in Itens :
-      T=T+i[ 0 ]*i[1]
-  if Desc==True : T = T*0.9
-  return T
+
+
+def CalculaTotal(Itens, Desc):
+    T = 0
+    for i in Itens:
+        T = T + i[0] * i[1]
+    if Desc == True:
+        T = T * 0.9
+    return T
+
+
 class carrinho:
-    def __init__(self,dono): self.dono=dono;self.itens=[]
-print(CalculaTotal([(27.90,2),(8.49,3)],True))
+    def __init__(self, dono):
+        self.dono = dono
+        self.itens = []
+
+
+print(CalculaTotal([(27.90, 2), (8.49, 3)], True))

1 file would be reformatted

Indentação de 4, espaços nos lugares certos, uma instrução por linha, duas linhas em branco entre as definições. O black --diff baguncado.py propõe exatamente as mesmas mudanças (o ruff format foi feito para imitar o black). Sem o --diff, o arquivo é reescrito. A Ana fez isso numa cópia, e depois pediu ao ruff check --fix que consertasse o que soubesse:

$ cp baguncado.py copia.py
$ .venv/bin/ruff format copia.py
1 file reformatted
$ .venv/bin/ruff check --fix --output-format concise copia.py
Found 2 errors (2 fixed, 0 remaining).
$ .venv/bin/ruff format copia.py
1 file reformatted
$ cat copia.py
def CalculaTotal(Itens, Desc):
    T = 0
    for i in Itens:
        T = T + i[0] * i[1]
    if Desc == True:
        T = T * 0.9
    return T


class carrinho:
    def __init__(self, dono):
        self.dono = dono
        self.itens = []


print(CalculaTotal([(27.90, 2), (8.49, 3)], True))
$ python3 copia.py
73.143

O --fix apagou os dois imports inúteis, e o segundo format limpou as linhas em branco que sobraram no começo. O programa continua dando 73.143. Mas repare no que ficou: CalculaTotal, T, carrinho, i[0], == True. As ferramentas cuidam da "pontuação"; dar bons nomes e escrever com clareza continua sendo trabalho seu.

Formas diferentes de seguir o estilo

Quando dá errado

Estilo ruim, na maior parte das vezes, não quebra nada: só dificulta a leitura. Mas algumas escolhas de estilo provocam erros de verdade.

def saudacao(nome):
    mensagem = "Olá, " + nome
	return mensagem

print(saudacao("Ana"))

$ python3 tab.py
  File "/home/ana/tab.py", line 3
    	return mensagem
    ^
TabError: inconsistent use of tabs and spaces in indentation

list = ["arroz", "feijão", "café"]
print(list)
letras = list("Ana")

$ python3 sombra.py
['arroz', 'feijão', 'café']
Traceback (most recent call last):
  File "/home/ana/sombra.py", line 3, in <module>
    letras = list("Ana")
TypeError: 'list' object is not callable

from os import *

with open("compras.txt", "w") as arquivo:
    arquivo.write("arroz\n")

$ python3 estrela.py
Traceback (most recent call last):
  File "/home/ana/estrela.py", line 3, in <module>
    with open("compras.txt", "w") as arquivo:
         ~~~~^^^^^^^^^^^^^^^^^^^^
TypeError: 'str' object cannot be interpreted as an integer

class = "3º ano B"
print(class)

$ python3 palavra_chave.py
  File "/home/ana/palavra_chave.py", line 1
    class = "3º ano B"
          ^
SyntaxError: invalid syntax

list = ["arroz", "feijão", "café"]
print(list)
letras = list("Ana")
print(letras)

compras = ["arroz", "feijão", "café"]
print(compras)
letras = list("Ana")
print(letras)

Referência rápida

Exercícios

Missão final: arrumando o baguncado.py

import sys, os
def CalculaTotal( Itens,Desc ):
  T=0
  for i in Itens :
      T=T+i[ 0 ]*i[1]
  if Desc==True : T = T*0.9
  return T
class carrinho:
    def __init__(self,dono): self.dono=dono;self.itens=[]
print(CalculaTotal([(27.90,2),(8.49,3)],True))

def calcular_total(itens, cliente_fiel):
    total = 0
    for preco, quantidade in itens:
        total = total + preco * quantidade
    if cliente_fiel:
        total = total * 0.9
    return total


class Carrinho:
    def __init__(self, dono):
        self.dono = dono
        self.itens = []


print(calcular_total([(27.90, 2), (8.49, 3)], True))

Compare a sua versão com o arrumado.py do começo da aula. Lá, o 0.9 virou uma constante com nome (DESCONTO_CLIENTE_FIEL = 0.10), o que conta para quem lê de onde veio aquele número.

Resumo

• A PEP 8 é o guia de estilo do Python: o jeito combinado de escrever, porque o código é lido muito mais vezes do que é escrito.
• 4 espaços de indentação (nunca misturados com Tab); linhas de até 79 caracteres, quebradas com parênteses; 2 linhas em branco entre funções e classes, 1 entre métodos.
• Nomes: minusculas_com_sublinhado para variáveis e funções, PalavrasComMaiuscula para classes, MAIUSCULAS para constantes. Nada de l/O/I sozinhos, nem de nomes embutidos como list.
• Espaços em volta de = e operadores e depois da vírgula; nenhum dentro dos parênteses, nem no = de argumento nomeado. Uma instrução por linha.
• Imports no topo, um por linha, em grupos; sem import *. Compare com is None; teste a verdade com if x:.
• ruff check aponta os problemas; ruff format e black arrumam o estilo. Bons nomes continuam sendo com você.