Convenções de nomes em Python (PEP 8): A referência definitiva

PEP 8 é o guia de estilo oficial do Python, e suas convenções de nomes são seguidas por virtualmente todo projeto Python. Este guia cobre todas as regras que você precisa conhecer.

Por que PEP 8 importa

Python enfatiza legibilidade. PEP 8 garante que código escrito por diferentes desenvolvedores pareça e funcione da mesma forma. Linters como flake8, pylint e ruff aplicam essas convenções automaticamente.

Nomes de variáveis e funções: snake_case

Todas as variáveis e funções usam minúsculas com underscores:

user_name = "Alice"
total_price = 99.95

def get_user_by_id(user_id):
    pass

def calculate_total_price(items):
    pass

Nunca use camelCase para funções Python. Escrever getUserById é imediatamente reconhecível como não-Pythonic.

Nomes de classes: PascalCase

Classes usam CapWords (PascalCase):

class UserAccount:
    pass

class HttpRequestHandler:
    pass

Constantes: SCREAMING_SNAKE_CASE

Constantes no nível do módulo usam maiúsculas com underscores:

MAX_RETRY_COUNT = 3
API_BASE_URL = "https://api.example.com"
DEFAULT_TIMEOUT = 30

Nomes de módulos e pacotes

Módulos (arquivos): curtos, tudo em minúsculas, com underscores se necessário: utils.py, data_loader.py. Pacotes (diretórios): curtos, tudo em minúsculas, sem underscores: mypackage.

Nomes de métodos e variáveis de instância

Igual a funções — snake_case. Um underscore inicial para métodos internos (não públicos):

class User:
    def __init__(self, name):
        self.user_name = name
        self._internal_id = generate_id()

    def get_display_name(self):
        return self.user_name

    def _validate(self):
        pass

Casos especiais

Padrão	Convenção	Exemplo
Atributo privado	_underscore_inicial	_internal_cache
Name mangling	__underscore_duplo_inicial	__private_method
Magic / dunder	__duplo_ambos_lados__	__init__, __str__
Variável descartável	Underscore simples	for _ in range(10)
Variável de tipo	PascalCase, curto	T, KT, VT

Erros comuns

• Usar camelCase para funções (getUserName em vez de get_user_name)
• Usar minúsculas para nomes de classes (user_account em vez de UserAccount)
• Usar ALL_CAPS para variáveis normais
• Nomes de variáveis de uma única letra fora de loops

Converta seu código rapidamente

Migrando de JavaScript ou Java? Use nosso conversor snake_case para transformar identificadores camelCase rapidamente. Para nomes de classes, experimente o conversor PascalCase. O hub de conversão permite comparar todos os formatos de uma vez.

Resumo

A nomenclatura PEP 8 é simples: snake_case para quase tudo, PascalCase para classes, SCREAMING_SNAKE para constantes. Siga essas regras e seu código Python se sentirá natural para todo desenvolvedor Python.