PEP 8 & Referência de Estilo

PEP 8 é o guia de estilo oficial do Python. Esta página destila as regras que mais importam em projetos modernos de Python 3.14 com aplicação do ruff.

Receita

[tool.ruff]
line-length = 88
target-version = "py314"
 
[tool.ruff.lint]
select = ["E", "W", "F", "I"]

uv run ruff format . && uv run ruff check --fix .

Quando usar isto:

Resolvendo debates de estilo em revisão de código
Configurando o ruff para um novo projeto
Integrando desenvolvedores de outras linguagens

Referência PEP 8

Tópico	Regra	Exemplo
Indentação	4 espaços, sem tabs	`def foo():` + corpo de 4 espaços
Comprimento da linha	88 caracteres (padrão Black/ruff)	Quebrar com parênteses
Importações	stdlib, third-party, local	Linha em branco entre grupos
Nomes	`snake_case`, classes `CapWords`	`minha_funcao`, `MinhaClasse`
Espaçamento	espaço ao redor de operadores	`x = 1`, `a + b`, não `x=1`
Comentários	frases completas	`# Calcula o total, não o imposto.`
Strings	estilo de aspas consistente	aspas duplas (padrão ruff)

Exemplo de Trabalho

# Good PEP 8 style
from __future__ import annotations
 
import os
from pathlib import Path
 
import httpx
from pydantic import BaseModel
 
 
class Invoice(BaseModel):
    id: int
    amount: float
    customer_email: str
 
 
def fetch_invoice(client: httpx.Client, invoice_id: int) -> Invoice:
    response = client.get(f"/invoices/{invoice_id}")
    response.raise_for_status()
    return Invoice.model_validate(response.json())
 
 
def main() -> None:
    base = os.environ.get("API_URL", "http://localhost:8000")
    with httpx.Client(base_url=base) as client:
        invoice = fetch_invoice(client, 42)
        print(invoice.customer_email)
 
 
if __name__ == "__main__":
    main()

O que isto demonstra:

Duas linhas em branco antes de funções e classes de nível superior
Importações agrupadas e ordenadas
Dicas de tipo em funções públicas
Guarda if __name__ para execução de script

Mergulho Profundo

Convenções de Nomenclatura

Tipo	Convenção	Exemplo
Módulo	minúsculas	`meu_modulo.py`
Classe	CapWords	`ServicoFatura`
Função	snake_case	`calcular_total`
Constante	UPPER_SNAKE	`MAX_TENTATIVAS`
Privado	`_` inicial	`_ajudante_interno`
Métodos Mágicos	dunder	`__init__`, `__str__`

Quebra de Linha

# Preferred: hanging indent with parentheses
result = some_function(
    long_argument_one,
    long_argument_two,
    long_argument_three,
)
 
# Dict/list trailing comma ok
settings = {
    "host": "localhost",
    "port": 8000,
}

Armadilhas

Tabs vs espaços - erro de sintaxe na mistura. Correção: editor insere espaços; ruff aplica.
Espaço em branco no final - diffs barulhentos. Correção: hook trailing-whitespace do pre-commit.
Importações wildcard - from modulo import * polui o namespace. Correção: importações explícitas.
Argumentos padrão mutáveis - def f(items=[]): estado compartilhado. Correção: padrão None, criar dentro.
Comparando com None - use is None, não == None.

Alternativas

Alternativa	Usar Quando	Não Usar Quando
Estilo Python do Google	Interoperabilidade com código do Google	Projeto PEP 8 padrão
Estilo de docstring do numpy	Computação científica	Aplicações web gerais
Formatação manual	Nunca	Sempre usar ruff format

FAQs

Linhas de 79 ou 88 caracteres?

88 é o padrão moderno (Black/ruff). Consistência importa mais que o número exato.

Aspas simples ou duplas?

Escolha uma via formatador. ruff format usa aspas duplas por padrão.

Quando ignorar PEP 8?

Código gerado, migrações e casos raros onde quebrar prejudica a legibilidade. Documentar # noqa.

O ruff substitui a revisão PEP 8?

Sim, para regras mecânicas. A revisão humana ainda é necessária para qualidade de nomenclatura e estrutura.

O que é E501?

Linha muito longa. Geralmente ignorado ao usar ruff format.

Dicas de tipo e PEP 8?

As dicas de tipo PEP 484 complementam o PEP 8. Veja PEP 484 para estilo de tipagem.

Linhas em branco em métodos?

Uma linha em branco entre métodos em uma classe. Duas linhas em branco entre definições de nível superior.

Linha Shebang?

#!/usr/bin/env python3 apenas para scripts executáveis.

Declaração de codificação?

Não é necessária em Python 3. UTF-8 é o padrão.

Onde está o PEP 8 completo?

peps.python.org/pep-0008/ - esta página é a destilação prática.

Relacionados

50 Regras Python - regras mais amplas
Configuração do Ruff - ferramentas de aplicação
Black / Ruff Format - formatação
Melhores Práticas de Linting - política de equipe

Versões da Pilha: Esta página foi escrita para Python 3.14.0, FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, e uv 0.6+.

PEP 8 & Referência de Estilo

PEP 8 é o guia de estilo oficial do Python. Esta página destila as regras que mais importam em projetos modernos de Python 3.14 com aplicação do ruff.

Receita

[tool.ruff]
line-length = 88
target-version = "py314"
 
[tool.ruff.lint]
select = ["E", "W", "F", "I"]

uv run ruff format . && uv run ruff check --fix .

Quando usar isto:

Resolvendo debates de estilo em revisão de código
Configurando o ruff para um novo projeto
Integrando desenvolvedores de outras linguagens

Referência PEP 8

Tópico	Regra	Exemplo
Indentação	4 espaços, sem tabs	`def foo():` + corpo de 4 espaços
Comprimento da linha	88 caracteres (padrão Black/ruff)	Quebrar com parênteses
Importações	stdlib, third-party, local	Linha em branco entre grupos
Nomes	`snake_case`, classes `CapWords`	`minha_funcao`, `MinhaClasse`
Espaçamento	espaço ao redor de operadores	`x = 1`, `a + b`, não `x=1`
Comentários	frases completas	`# Calcula o total, não o imposto.`
Strings	estilo de aspas consistente	aspas duplas (padrão ruff)

Exemplo de Trabalho

# Good PEP 8 style
from __future__ import annotations
 
import os
from pathlib import Path
 
import httpx
from pydantic import BaseModel
 
 
class Invoice(BaseModel):
    id: int
    amount: float
    customer_email: str
 
 
def fetch_invoice(client: httpx.Client, invoice_id: int) -> Invoice:
    response = client.get(f"/invoices/{invoice_id}")
    response.raise_for_status()
    return Invoice.model_validate(response.json())
 
 
def main() -> None:
    base = os.environ.get("API_URL", "http://localhost:8000")
    with httpx.Client(base_url=base) as client:
        invoice = fetch_invoice(client, 42)
        print(invoice.customer_email)
 
 
if __name__ == "__main__":
    main()

O que isto demonstra:

Duas linhas em branco antes de funções e classes de nível superior
Importações agrupadas e ordenadas
Dicas de tipo em funções públicas
Guarda if __name__ para execução de script

Mergulho Profundo

Convenções de Nomenclatura

Tipo	Convenção	Exemplo
Módulo	minúsculas	`meu_modulo.py`
Classe	CapWords	`ServicoFatura`
Função	snake_case	`calcular_total`
Constante	UPPER_SNAKE	`MAX_TENTATIVAS`
Privado	`_` inicial	`_ajudante_interno`
Métodos Mágicos	dunder	`__init__`, `__str__`

Quebra de Linha

# Preferred: hanging indent with parentheses
result = some_function(
    long_argument_one,
    long_argument_two,
    long_argument_three,
)
 
# Dict/list trailing comma ok
settings = {
    "host": "localhost",
    "port": 8000,
}

Armadilhas

Tabs vs espaços - erro de sintaxe na mistura. Correção: editor insere espaços; ruff aplica.
Espaço em branco no final - diffs barulhentos. Correção: hook trailing-whitespace do pre-commit.
Importações wildcard - from modulo import * polui o namespace. Correção: importações explícitas.
Argumentos padrão mutáveis - def f(items=[]): estado compartilhado. Correção: padrão None, criar dentro.
Comparando com None - use is None, não == None.

Alternativas

Alternativa	Usar Quando	Não Usar Quando
Estilo Python do Google	Interoperabilidade com código do Google	Projeto PEP 8 padrão
Estilo de docstring do numpy	Computação científica	Aplicações web gerais
Formatação manual	Nunca	Sempre usar ruff format

FAQs

Linhas de 79 ou 88 caracteres?

88 é o padrão moderno (Black/ruff). Consistência importa mais que o número exato.

Aspas simples ou duplas?

Escolha uma via formatador. ruff format usa aspas duplas por padrão.

Quando ignorar PEP 8?

Código gerado, migrações e casos raros onde quebrar prejudica a legibilidade. Documentar # noqa.

O ruff substitui a revisão PEP 8?

Sim, para regras mecânicas. A revisão humana ainda é necessária para qualidade de nomenclatura e estrutura.

O que é E501?

Linha muito longa. Geralmente ignorado ao usar ruff format.

Dicas de tipo e PEP 8?

As dicas de tipo PEP 484 complementam o PEP 8. Veja PEP 484 para estilo de tipagem.

Linhas em branco em métodos?

Uma linha em branco entre métodos em uma classe. Duas linhas em branco entre definições de nível superior.

Linha Shebang?

#!/usr/bin/env python3 apenas para scripts executáveis.

Declaração de codificação?

Não é necessária em Python 3. UTF-8 é o padrão.

Onde está o PEP 8 completo?

peps.python.org/pep-0008/ - esta página é a destilação prática.

Relacionados

50 Regras Python - regras mais amplas
Configuração do Ruff - ferramentas de aplicação
Black / Ruff Format - formatação
Melhores Práticas de Linting - política de equipe

Versões da Pilha: Esta página foi escrita para Python 3.14.0, FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, e uv 0.6+.

PEP 8 & Referência de Estilo

Buscar na documentação

PEP 8 & Referência de Estilo