Python é conhecido por sua legibilidade e sintaxe limpa. Grande parte dessa reputação vem do PEP 8 — o guia de estilo oficial da linguagem. Criado por Guido van Rossum, Barry Warsaw e Nick Coghlan, o PEP 8 estabelece convenções que tornam o código Python uniforme e fácil de entender, independentemente de quem o escreveu.

Neste guia completo, você vai aprender todas as regras essenciais do PEP 8, desde convenções de nomenclatura até organização de imports, indentação, espaçamento e muito mais. Se você quer escrever código Python profissional e seguir as melhores práticas da comunidade, este artigo é para você.

O que é PEP 8?

PEP significa Python Enhancement Proposal. Trata-se de um documento que propõe melhorias, novos recursos ou padrões para a linguagem Python. O PEP 8 é a proposta de número 8 e define o guia de estilo oficial para código Python.

Seguir o PEP 8 não é obrigatório para que seu código funcione — o interpretador Python não valida estilo. No entanto, é considerado uma boa prática fundamental para qualquer desenvolvedor profissional. Projetos open source, empresas e a própria biblioteca padrão do Python seguem o PEP 8 rigorosamente.

Você pode consultar a lista completa de PEPs no índice oficial de PEPs do Python.

Por que Seguir o PEP 8?

Adotar o PEP 8 traz benefícios concretos para você e sua equipe:

  • Legibilidade: código consistente é mais fácil de ler e entender
  • Manutenibilidade: outros desenvolvedores conseguem dar manutenção sem estranheza
  • Colaboração: reduz o atrito em code reviews e contribuições
  • Profissionalismo: demonstra domínio das práticas da comunidade
  • Ferramentas: linters e formatadores automatizam a verificação do estilo

Empresas como Google, Instagram e Spotify exigem que seus times sigam o PEP 8. Se você deseja trabalhar com Python profissionalmente, dominar essas convenções é essencial.

Indentação

A indentação é uma das regras mais conhecidas do PEP 8. Python usa indentação para definir blocos de código, diferentemente de linguagens como C ou Java que usam chaves.

4 Espaços por Nível

Use 4 espaços para cada nível de indentação. Nunca misture tabs e espaços. Configure seu editor para inserir espaços automaticamente quando você pressionar Tab.

# Correto — 4 espaços
def funcao():
    if condicao:
        print("Indentado com 4 espaços")

Errado — misturado


def funcao():
if condicao:
print("Indentação inconsistente")

Alinhamento Vertical

Para continuar uma linha longa, você pode alinhar os elementos verticalmente com a abertura do delimitador:

# Alinhamento vertical
resultado = calcula_valor(primeiro_parametro,
                          segundo_parametro,
                          terceiro_parametro)

Linhas Continuadas

Use 4 espaços extras para linhas continuadas:

# Linha continuada com indentação extra
resultado = calcula_valor(
    primeiro_parametro,
    segundo_parametro,
    terceiro_parametro
)

Comprimento Máximo de Linhas

O PEP 8 recomenda um limite de 79 caracteres por linha para código e 72 caracteres para comentários e docstrings. Esse limite permite visualizar múltiplos arquivos lado a lado sem rolagem horizontal.

# Linha dentro do limite de 79 caracteres
def minha_funcao(parametro_um, parametro_dois, parametro_tres):
    pass

Quebra usando barra invertida


resultado = valor1 + valor2 + valor3 \


    

  • valor4 + valor5

Na prática, muitos times adotam 88 ou 100 caracteres. O formatador Black, por exemplo, usa 88 caracteres por padrão.

Linhas em Branco

O uso de linhas em branco melhora a legibilidade:

  • Duas linhas em branco entre definições de funções e classes no nível superior do módulo
  • Uma linha em branco entre métodos dentro de uma classe
  • Uma linha em branco para separar seções lógicas dentro de uma função
import os
import sys

def funcao_um():
"""Primeira função do módulo."""
pass


def funcao_dois():
"""Segunda função do módulo."""
pass

Imports

Os imports devem ser organizados em seções, na seguinte ordem:

  1. Bibliotecas padrão do Python
  2. Bibliotecas de terceiros
  3. Módulos locais do seu projeto

Cada grupo deve ser separado por uma linha em branco. Dentro de cada grupo, os imports devem ser ordenados alfabeticamente.

# Correto
import os
import sys
from collections import defaultdict
from pathlib import Path

import requests
from flask import Flask


from meu_projeto.models import Usuario
from meu_projeto.utils import formatar_data


Errado — fora de ordem


from flask import Flask
import os
from meu_projeto.models import Usuario
import requests

Evite imports curinga (from modulo import *), pois poluem o namespace e dificultam identificar a origem dos nomes.

Convenções de Nomenclatura

O PEP 8 define padrões claros de nomenclatura para diferentes elementos do código:

Variáveis e Funções

Use snake_case com letras minúsculas e underscores para palavras compostas:

# Correto
nome_completo = "João Silva"
def calcular_total(itens):
    pass

Errado


nomeCompleto = "João Silva"
def CalcularTotal(itens):
pass

Constantes

Use letras maiúsculas com underscores:

# Correto
MAX_TENTATIVAS = 3
TAXA_JUROS = 0.15

Errado


max_tentativas = 3
taxa_juros = 0.15

Classes

Use PascalCase (também conhecido como CapitalizedWords):

# Correto
class ClienteVip:
    pass

class ConexaoBancoDados:
pass


Errado


class clienteVip:
pass


class conexao_banco_dados:
pass

Métodos e Atributos Privados

Prefixe com um underscore para indicar uso interno:

class Cliente:
    def __init__(self):
        self._saldo = 0  # atributo privado por convenção

def _calcular_desconto(self):  # método interno
    pass

Name Mangling (Duplo Underscore)

Use __nome para criar atributos com name mangling, útil para evitar conflitos em herança:

class Conta:
    def __init__(self):
        self.__saldo = 0  # vira _Conta__saldo internamente

Nomes que não devem ser usados

Evite usar l (letra L), O (letra O) e I (letra I) como nomes de variáveis, pois podem ser confundidos com 1, 0 e 1 respectivamente.

# Errado — difícil de ler
l = 1
O = 0
I = 1

Correto


linha = 1
zero = 0
indice = 1

Espaçamento em Operadores

O PEP 8 tem regras específicas para espaçamento ao redor de operadores:

Sempre use espaços:

  • Após vírgulas: lista = [1, 2, 3]
  • Ao redor de operadores de atribuição: x = 5
  • Ao redor de operadores de comparação: if x == 5:
  • Ao redor de operadores booleanos: if x and y:
  • Em parâmetros de função com valor padrão: def func(x=5):

Não use espaços:

  • Dentro de parênteses, colchetes ou chaves: spam(ham[1], {chave: valor})
  • Entre o nome da função e o parêntese de abertura: funcao()
  • Antes de vírgulas ou dois-pontos: if x == 5: e range(1, 10)
  • Em slicing: lista[0:5]
# Correto
resultado = a + b * c
dicionario = {"chave": "valor"}
funcao(parametro1, parametro2)
if valor > 10:
    print("Maior que 10")

Errado


resultado = a+b*c
dicionario = {"chave":"valor"}
funcao( parametro1, parametro2 )
if valor>10:
print("Maior que 10")

Comentários e Docstrings

Comentários explicam o porquê do código, não o que ele faz — isso deve ser claro pela própria sintaxe.

Comentários em Linha

Use # seguido de um espaço. Comentários muito longos devem ser evitados; prefira refatorar o código para torná-lo autoexplicativo.

# Calcula o total com desconto progressivo
total = sum(itens) * (1 - desconto)

Docstrings

Docstrings são usadas para documentar módulos, classes, funções e métodos. Siga as convenções do PEP 257 para docstrings:

def calcular_media(numeros):
    """Calcula a média aritmética de uma lista de números.

Args:
    numeros: Lista de números inteiros ou floats.

Returns:
    A média aritmética dos números fornecidos.
"""
return sum(numeros) / len(numeros)

Convenções de Programação

O PEP 8 também inclui recomendações sobre como programar:

  • Comparações com None: use if x is None e não if x == None
  • Comparações booleanas: use if not x em vez de if x == False
  • Verificação de sequências vazias: use if not sequencia: em vez de if len(sequencia) == 0:
  • Retornos explícitos: prefira return None a return ou omitir o retorno
# Correto
if resultado is None:
    print("Sem resultado")

if not lista:
print("Lista vazia")


if erro_ocorreu:
return


Errado


if resultado == None:
print("Sem resultado")


if len(lista) == 0:
print("Lista vazia")

Ferramentas para Automatizar o PEP 8

Você não precisa memorizar todas as regras do PEP 8. Ferramentas automatizadas verificam e corrigem o estilo do seu código automaticamente:

Black

O Black é o formatador de código oficial do Python. Ele reformata seu código automaticamente para seguir o PEP 8, sem perguntar. É conhecido como "o formatador implacável".

pip install black
black meu_arquivo.py

Flake8

O Flake8 é um linter que verifica seu código contra o PEP 8 e reporta violações. Ele combina três ferramentas: PyFlakes, pycodestyle e McCabe.

pip install flake8
flake8 meu_arquivo.py

Pylint

O Pylint é um linter mais completo que verifica não apenas estilo, mas também erros lógicos, convenções e qualidade do código.

pip install pylint
pylint meu_arquivo.py

Integração com Editores

Os principais editores de código oferecem suporte nativo ou por extensão:

  • VS Code: instale a extensão Python e ative "Format on Save" para usar o Black
  • PyCharm: o PyCharm já vem com verificação de PEP 8 integrada e pode reformatar automaticamente seu código com Ctrl+Alt+L
  • pre-commit hooks: use pre-commit para executar Black e Flake8 automaticamente antes de cada commit

Como Configurar um Projeto PEP 8

Aqui está um guia rápido para configurar seu projeto Python com as ferramentas de estilo:

# Instale as ferramentas
pip install black flake8 pylint

Crie o arquivo pyproject.toml para configurar o Black


[tool.black]


line-length = 88


target-version = ['py312']


Crie o arquivo .flake8 para configurar o Flake8


[flake8]


max-line-length = 88


extend-ignore = E203, W503

Após configurar, execute o Black regularmente e mantenha o Flake8 no seu pipeline de CI/CD para garantir que todo o código siga o PEP 8 antes de ser mesclado.

PEP 8 vs Type Hints

O PEP 8 foi complementado pelo PEP 484, que introduziu type hints no Python. Type hints melhoram a legibilidade e permitem que ferramentas como mypy verifiquem tipos estaticamente. Confira nosso guia completo sobre Type Hints em Python para dominar essa técnica.

from typing import List, Optional

def processar_dados(nome: str, itens: List[int]) -> Optional[float]:
"""Processa dados com type hints seguindo PEP 8."""
if not itens:
return None
return sum(itens) / len(itens)

Conclusão

O PEP 8 é muito mais que um conjunto de regras arbitrárias — é a expressão da filosofia do Python: código legível é código de qualidade. Seguir o guia de estilo oficial torna seu código mais consistente, profissional e fácil de manter.

Lembre-se: ninguém memoriza todas as regras do PEP 8. O importante é entender os princípios e usar ferramentas como Black, Flake8 e Pylint para automatizar a verificação. Comece aplicando as convenções de nomenclatura e organização de imports, e o restante virá naturalmente com a prática.

Para se aprofundar ainda mais em boas práticas, veja também nosso artigo sobre Clean Code em Python, que aborda princípios complementares para escrever código profissional de alta qualidade.

Gostou deste guia? Compartilhe com outros desenvolvedores e ajude a comunidade Python a escrever código cada vez melhor!