← Blog · 15 de abril de 2026 · Equipo de ConvertCaseHQ · 7 min de lectura

Nombres en Python según PEP 8: snake_case para variables y funciones

PEP 8 dice que los nombres de funciones y variables deben ir en minúsculas, con las palabras separadas por guiones bajos cuando eso ayude a la legibilidad. Eso es snake_case: total_price, send_invoice(). Las clases usan CapWords (InvoiceSender), las constantes usan mayúsculas con guiones bajos (MAX_RETRIES) y los módulos reciben nombres cortos, todos en minúsculas. Eso cubre la mayor parte del Python que escribirás.

El resto de la sección de nombres de PEP 8 es donde está el detalle útil: qué significan los guiones bajos al principio y al final, cómo tratar las siglas, qué letras sueltas evitar y cuándo saltarse las reglas es lo correcto. Todo lo que sigue está comprobado con el propio PEP 8, y lo que aparece entre comillas son palabras textuales de PEP 8, en inglés y con nuestra traducción entre paréntesis.

Convenciones de nombres de PEP 8 de un vistazo

Qué estás nombrando	Estilo de PEP 8	Ejemplo
Módulo	Corto, todo en minúsculas; guiones bajos si ayudan	`billing.py`, `tax_rules.py`
Paquete	Corto, todo en minúsculas; se desaconsejan los guiones bajos	`payments`
Clase	CapWords	`InvoiceSender`
Excepción	CapWords, terminado en `Error` si es un error	`PaymentDeclinedError`
Función, método	snake_case	`send_invoice()`
Variable, variable de instancia	snake_case	`total_price`
Primer argumento de un método	`self`, o `cls` en los métodos de clase	`def from_settings(cls, settings)`
Constante	Mayúsculas con guiones bajos, normalmente a nivel de módulo	`MAX_RETRIES`
Variable de tipo	CapWords cortos	`T`, `AnyStr`
Nombre no público	Un guion bajo al principio	`_rate_cache`

Aquí tienes casi toda la tabla en un módulo pequeño:

# billing.py
MAX_RETRIES = 3
_rate_cache = {}


class PaymentDeclinedError(Exception):
    pass


class InvoiceSender:
    def __init__(self, smtp_host):
        self.smtp_host = smtp_host
        self._attempts = 0

    def send_invoice(self, invoice_id):
        self._attempts += 1
        ...

    @classmethod
    def from_settings(cls, settings):
        return cls(settings["smtp_host"])

Merece la pena conocer dos casos menos frecuentes. Las variables de tipo pueden llevar el sufijo _co o _contra para indicar covarianza o contravarianza, como en VT_co = TypeVar('VT_co', covariant=True). Y las variables globales siguen las reglas de las funciones; si un módulo está pensado para usarse con from module import *, PEP 8 recomienda enumerar sus nombres públicos en __all__.

¿Por qué snake_case?

PEP 8 data de julio de 2001, y los autores que figuran en él son Guido van Rossum, Barry Warsaw y Alyssa Coghlan. Parte de una observación de Guido: el código se lee mucho más a menudo de lo que se escribe. Las reglas de nombres sirven a ese objetivo. Los guiones bajos mantienen visibles los límites entre palabras incluso en nombres largos (days_since_last_login), y la diferencia entre valores en snake_case y clases en CapWords te dice qué tipo de cosa es un nombre antes de que lo busques. PEP 8 fija además un principio que prevalece en las API públicas: los nombres deben reflejar cómo se usa algo, no cómo está implementado.

Qué significan los guiones bajos

Python no tiene una palabra clave private, así que los guiones bajos hacen ese trabajo por convención. PEP 8 reconoce cuatro formas:

_single_leading: una señal débil de «internal use» (uso interno). from module import * se salta estos nombres, pero nada impide que alguien los use.
single_trailing_: evita un choque con una palabra clave. class_ es mejor que clss, aunque PEP 8 señala que un sinónimo puede ser todavía mejor.
__double_leading: dentro de una clase, activa el name mangling (la alteración del nombre). PEP 8 lo sugiere solo para evitar choques con atributos de las subclases, y admite que a algunas personas no les gusta.
__double_leading_and_trailing__: nombres «magic» (mágicos) como __init__ y __file__. PEP 8 dice que nunca los inventes; usa solo los documentados.

El name mangling sorprende a quien lo toma por privacidad. Es un cambio de nombre, no un candado:

class Account:
    def __init__(self):
        self.__pin = "1234"

acct = Account()
acct.__pin            # AttributeError
acct._Account__pin    # "1234": the mangled name still works

Las constantes son una convención, no una regla

Escribir un nombre en mayúsculas no impide que alguien lo reasigne; Python ejecutará MAX_RETRIES = 4 sin quejarse. Si quieres que una herramienta lo haga cumplir, anota el nombre con typing.Final:

from typing import Final

MAX_RETRIES: Final = 3
MAX_RETRIES = 4  # still runs, but mypy reports:
                 # Cannot assign to final name "MAX_RETRIES"

Los miembros de un enum son el otro lugar donde aparecen las mayúsculas. El HOWTO de enum de la documentación de Python recomienda encarecidamente nombres de miembro en UPPER_CASE, en parte porque los enums representan constantes y en parte para evitar choques con nombres de métodos: class Color(Enum) con los miembros RED y GREEN.

Siglas, letras sueltas y otros casos límite

Siglas en nombres de clase

PEP 8 dice que en CapWords se escriban en mayúscula todas las letras de una sigla, así que HTTPServerError es mejor que HttpServerError. La biblioteca estándar lo sigue en casos como http.server.HTTPServer y json.JSONDecodeError. En snake_case, las siglas simplemente van en minúscula: parse_json, http_status.

Eso importa si renombras con una herramienta. Nuestro conversor de mayúsculas y minúsculas convierte processOrder en process_order y HTTPServerError en http_server_error, que es justo lo que corresponde en snake_case. Pero su salida en PascalCase escribe las siglas como palabras, de modo que HTTP server error sale como HttpServerError, y tendrías que corregir las mayúsculas a mano para ajustarte a PEP 8.

Letras que conviene evitar

No uses nunca l (ele minúscula), O (o mayúscula) ni I (i mayúscula) como nombres de un solo carácter. En algunas fuentes no se distinguen de 1 y 0.

mixedCase

Los nombres de función en camelCase solo se admiten donde ese ya es el estilo predominante, por compatibilidad con versiones anteriores. El propio ejemplo de PEP 8 es el módulo threading.

Por qué la biblioteca estándar rompe sus propias reglas

PEP 8 admite que los nombres de la biblioteca de Python son «a bit of a mess» (un poco desordenados). Te encontrarás con logging.getLogger() y con el assertEqual() de unittest en mixedCase, y con clases en minúscula como datetime.datetime. Los tipos integrados como list y dict van en minúscula a propósito: PEP 8 describe una convención aparte para los integrados, con CapWords solo para los nombres de excepciones y las constantes integradas.

Dos reglas de PEP 8 explican por qué estos nombres se quedan casi siempre como están. Primera: cuando una biblioteca existente tiene un estilo distinto, se prefiere la coherencia interna. Segunda, la sección titulada «A Foolish Consistency is the Hobgoblin of Little Minds» (la coherencia tonta es el duende de las mentes pequeñas): la coherencia con PEP 8 importa, la coherencia dentro de un proyecto importa más y la coherencia dentro de un módulo o una función es la que más importa. No rompas la compatibilidad con versiones anteriores solo por cumplir. Por eso una clase de pruebas de unittest sigue definiendo setUp(): el framework llama exactamente a ese nombre.

Revisa los nombres automáticamente con Ruff o pep8-naming

No hace falta revisar los nombres a ojo. El plugin de flake8 pep8-naming los comprueba, y Ruff implementa las mismas comprobaciones como sus reglas N. Dado este archivo:

maxRetries = 3


class order_processor:
    def processOrder(self, orderId):
        totalPrice = 0
        return totalPrice


class InvalidOrder(Exception):
    pass

Ruff señala todos los nombres que contiene:

$ ruff check --select N --output-format concise orders.py
orders.py:1:1: N816 Variable `maxRetries` in global scope should not be mixedCase
orders.py:4:7: N801 Class name `order_processor` should use CapWords convention
orders.py:5:9: N802 Function name `processOrder` should be lowercase
orders.py:5:28: N803 Argument name `orderId` should be lowercase
orders.py:6:9: N806 Variable `totalPrice` in function should be lowercase
orders.py:10:7: N818 Exception name `InvalidOrder` should be named with an Error suffix
Found 6 errors.

Para activar las reglas en todo un proyecto, añádelas a pyproject.toml:

[tool.ruff.lint]
extend-select = ["N"]

Cuando renombras un identificador en un archivo pegado, nuestra herramienta Buscar y reemplazar te muestra cuántas coincidencias ha cambiado, una comprobación rápida antes de volver a pegar el resultado. Para todo un código base, usa mejor la refactorización de renombrado de tu editor, para que las referencias de otros archivos se actualicen también.

Lista de comprobación de nombres de PEP 8

snake_case para funciones, métodos, variables y argumentos.
CapWords para las clases, con las siglas en mayúsculas y el sufijo Error en las excepciones.
Mayúsculas con guiones bajos para las constantes de módulo, más Final si quieres que un verificador las haga cumplir.
Nombres de módulo cortos y en minúsculas; evita los guiones bajos en los nombres de paquete.
Un guion bajo inicial para los nombres internos; guiones bajos dobles solo para evitar choques con subclases.
Cuando una biblioteca existente usa otro estilo, sigue el de la biblioteca.

¿Pasas de un lenguaje a otro? Nuestra hoja de referencia para desarrolladores compara las reglas de Python con las de JavaScript, Java, Go, Rust y otros.