Python es conocido por su legibilidad y sintaxis limpia. Gran parte de esta reputación se debe al PEP 8 — la guía de estilo oficial del lenguaje. Creado por Guido van Rossum, Barry Warsaw y Nick Coghlan, el PEP 8 establece convenciones que hacen que el código Python sea uniforme y fácil de entender, sin importar quién lo haya escrito.

En esta guía completa, aprenderás todas las reglas esenciales del PEP 8, desde convenciones de nomenclatura hasta organización de imports, indentación, espaciado y más. Si quieres escribir código Python profesional y seguir las mejores prácticas de la comunidad, este artículo es para ti.

¿Qué es PEP 8?

PEP significa Python Enhancement Proposal. Son documentos que proponen mejoras, nuevas características o estándares para el lenguaje Python. El PEP 8 es la propuesta número 8 y define la guía de estilo oficial para el código Python.

Seguir el PEP 8 no es obligatorio para que tu código funcione — el intérprete de Python no valida el estilo. Sin embargo, se considera una buena práctica fundamental para cualquier desarrollador profesional. Los proyectos open source, las empresas y la propia biblioteca estándar de Python siguen el PEP 8 rigurosamente.

Puedes consultar la lista completa de PEPs en el índice oficial de PEPs de Python.

¿Por Qué Seguir el PEP 8?

Adoptar el PEP 8 trae beneficios concretos para ti y tu equipo:

  • Legibilidad: el código consistente es más fácil de leer y entender
  • Mantenibilidad: otros desarrolladores pueden mantener tu código sin dificultad
  • Colaboración: reduce la fricción en code reviews y contribuciones
  • Profesionalismo: demuestra dominio de las prácticas de la comunidad
  • Herramientas: linters y formateadores automatizan la verificación del estilo

Empresas como Google, Instagram y Spotify exigen que sus equipos sigan el PEP 8. Si deseas trabajar con Python profesionalmente, dominar estas convenciones es esencial.

Indentación

La indentación es una de las reglas más conocidas del PEP 8. Python usa indentación para definir bloques de código, a diferencia de lenguajes como C o Java que usan llaves.

4 Espacios por Nivel

Usa 4 espacios para cada nivel de indentación. Nunca mezcles tabs y espacios. Configura tu editor para insertar espacios automáticamente al presionar Tab.

# Correcto — 4 espacios
def funcion():
    if condicion:
        print("Indentado con 4 espacios")

Incorrecto — mezclado


def funcion():
if condicion:
print("Indentación inconsistente")

Alineación Vertical

Para líneas largas, puedes alinear los elementos verticalmente con la apertura del delimitador:

# Alineación vertical
resultado = calcular_valor(primer_parametro,
                           segundo_parametro,
                           tercer_parametro)

Líneas Continuadas

Usa 4 espacios adicionales para líneas continuadas:

# Línea continuada con indentación extra
resultado = calcular_valor(
    primer_parametro,
    segundo_parametro,
    tercer_parametro
)

Longitud Máxima de Líneas

El PEP 8 recomienda un límite de 79 caracteres por línea para código y 72 caracteres para comentarios y docstrings. Este límite permite ver múltiples archivos lado a lado sin desplazamiento horizontal.

# Línea dentro del límite de 79 caracteres
def mi_funcion(parametro_uno, parametro_dos, parametro_tres):
    pass

Salto usando barra invertida


resultado = valor1 + valor2 + valor3 \


    

  • valor4 + valor5

En la práctica, muchos equipos adoptan 88 o 100 caracteres. El formateador Black, por ejemplo, usa 88 caracteres por defecto.

Líneas en Blanco

El uso de líneas en blanco mejora la legibilidad:

  • Dos líneas en blanco entre definiciones de funciones y clases al nivel superior del módulo
  • Una línea en blanco entre métodos dentro de una clase
  • Una línea en blanco para separar secciones lógicas dentro de una función
import os
import sys

def funcion_uno():
"""Primera función del módulo."""
pass


def funcion_dos():
"""Segunda función del módulo."""
pass

Imports

Los imports deben organizarse en secciones, en el siguiente orden:

  1. Bibliotecas estándar de Python
  2. Bibliotecas de terceros
  3. Módulos locales de tu proyecto

Cada grupo debe separarse con una línea en blanco. Dentro de cada grupo, los imports deben ordenarse alfabéticamente.

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

import requests
from flask import Flask


from mi_proyecto.models import Usuario
from mi_proyecto.utils import formatear_fecha


Incorrecto — fuera de orden


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

Evita los imports comodín (from modulo import *), ya que contaminan el namespace y dificultan identificar el origen de los nombres.

Convenciones de Nomenclatura

El PEP 8 define patrones claros de nomenclatura para diferentes elementos del código:

Variables y Funciones

Usa snake_case con letras minúsculas y guiones bajos para palabras compuestas:

# Correcto
nombre_completo = "Juan Pérez"
def calcular_total(items):
    pass

Incorrecto


nombreCompleto = "Juan Pérez"
def CalcularTotal(items):
pass

Constantes

Usa letras mayúsculas con guiones bajos:

# Correcto
MAX_INTENTOS = 3
TASA_INTERES = 0.15

Incorrecto


max_intentos = 3
tasa_interes = 0.15

Clases

Usa PascalCase (también conocido como CapitalizedWords):

# Correcto
class ClienteVip:
    pass

class ConexionBaseDatos:
pass


Incorrecto


class clienteVip:
pass


class conexion_base_datos:
pass

Métodos y Atributos Privados

Prefija con un guión bajo para indicar uso interno:

class Cliente:
    def __init__(self):
        self._saldo = 0  # atributo privado por convención

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

Name Mangling (Doble Guión Bajo)

Usa __nombre para crear atributos con name mangling, útil para evitar conflictos en herencia:

class Cuenta:
    def __init__(self):
        self.__saldo = 0  # internamente se convierte en _Cuenta__saldo

Nombres que Debes Evitar

Nunca uses l (ele minúscula), O (o mayúscula) o I (i mayúscula) como nombres de variables, ya que pueden confundirse con 1, 0 y 1 respectivamente.

# Incorrecto — difícil de leer
l = 1
O = 0
I = 1

Correcto


linea = 1
cero = 0
indice = 1

Espaciado en Operadores

El PEP 8 tiene reglas específicas para el espaciado alrededor de operadores:

Usa siempre espacios:

  • Después de comas: lista = [1, 2, 3]
  • Alrededor de operadores de asignación: x = 5
  • Alrededor de operadores de comparación: if x == 5:
  • Alrededor de operadores booleanos: if x and y:
  • En parámetros de función con valor por defecto: def func(x=5):

Nunca uses espacios:

  • Dentro de paréntesis, corchetes o llaves: spam(ham[1], {clave: valor})
  • Entre el nombre de la función y el paréntesis de apertura: funcion()
  • Antes de comas o dos puntos: if x == 5: y range(1, 10)
  • En slicing: lista[0:5]
# Correcto
resultado = a + b * c
diccionario = {"clave": "valor"}
funcion(parametro1, parametro2)
if valor > 10:
    print("Mayor que 10")

Incorrecto


resultado = a+b*c
diccionario = {"clave":"valor"}
funcion( parametro1, parametro2 )
if valor>10:
print("Mayor que 10")

Comentarios y Docstrings

Los comentarios deben explicar el por qué del código, no lo que hace — eso debe quedar claro por la sintaxis misma.

Comentarios en Línea

Usa # seguido de un espacio. Los comentarios demasiado largos deben evitarse; prefiere refactorizar el código para hacerlo autoexplicativo.

# Calcula el total con descuento progresivo
total = sum(elementos) * (1 - descuento)

Docstrings

Los docstrings se usan para documentar módulos, clases, funciones y métodos. Sigue las convenciones del PEP 257 para docstrings:

def calcular_media(numeros):
    """Calcula la media aritmética de una lista de números.

Args:
    numeros: Lista de números enteros o floats.

Returns:
    La media aritmética de los números proporcionados.
"""
return sum(numeros) / len(numeros)

Convenciones de Programación

El PEP 8 también incluye recomendaciones sobre cómo programar:

  • Comparaciones con None: usa if x is None en lugar de if x == None
  • Comparaciones booleanas: usa if not x en vez de if x == False
  • Verificación de secuencias vacías: usa if not secuencia: en lugar de if len(secuencia) == 0:
  • Retornos explícitos: prefiere return None a return u omitir el retorno
# Correcto
if resultado is None:
    print("Sin resultado")

if not lista:
print("Lista vacía")


if error_ocurrio:
return


Incorrecto


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


if len(lista) == 0:
print("Lista vacía")

Herramientas para Automatizar el PEP 8

No necesitas memorizar todas las reglas del PEP 8. Las herramientas automatizadas verifican y corrigen el estilo de tu código automáticamente:

Black

Black es el formateador de código oficial de Python. Reformatea tu código automáticamente para cumplir con el PEP 8, sin preguntar. Se le conoce como "el formateador implacable".

pip install black
black mi_archivo.py

Flake8

Flake8 es un linter que verifica tu código contra el PEP 8 e informa violaciones. Combina PyFlakes, pycodestyle y McCabe.

pip install flake8
flake8 mi_archivo.py

Pylint

Pylint es un linter más completo que verifica no solo estilo, sino también errores lógicos, convenciones y calidad del código.

pip install pylint
pylint mi_archivo.py

Integración con Editores

Los principales editores de código ofrecen soporte nativo o mediante extensiones:

  • VS Code: instala la extensión Python y activa "Format on Save" para usar Black
  • PyCharm: PyCharm viene con verificación de PEP 8 integrada y puede reformatear automáticamente con Ctrl+Alt+L
  • pre-commit hooks: usa pre-commit para ejecutar Black y Flake8 automáticamente antes de cada commit

Cómo Configurar un Proyecto PEP 8

Aquí tienes una guía rápida para configurar tu proyecto Python con herramientas de estilo:

# Instala las herramientas
pip install black flake8 pylint

Crea el archivo pyproject.toml para configurar Black


[tool.black]


line-length = 88


target-version = ['py312']


Crea el archivo .flake8 para configurar Flake8


[flake8]


max-line-length = 88


extend-ignore = E203, W503

Una vez configurado, ejecuta Black regularmente y mantén Flake8 en tu pipeline de CI/CD para garantizar que todo el código siga el PEP 8 antes de ser fusionado.

PEP 8 y Type Hints

El PEP 8 fue complementado por el PEP 484, que introdujo los type hints en Python. Los type hints mejoran la legibilidad y permiten que herramientas como mypy verifiquen tipos estáticamente. Consulta nuestra guía completa sobre Type Hints en Python para dominar esta técnica.

from typing import List, Optional

def procesar_datos(nombre: str, items: List[int]) -> Optional[float]:
"""Procesa datos con type hints siguiendo PEP 8."""
if not items:
return None
return sum(items) / len(items)

Conclusión

El PEP 8 es mucho más que un conjunto de reglas arbitrarias — es la expresión de la filosofía de Python: el código legible es código de calidad. Seguir la guía de estilo oficial hace que tu código sea más consistente, profesional y fácil de mantener.

Recuerda: nadie memoriza todas las reglas del PEP 8. Lo importante es entender los principios y usar herramientas como Black, Flake8 y Pylint para automatizar la verificación. Empieza aplicando las convenciones de nomenclatura y organización de imports, y el resto vendrá naturalmente con la práctica.

Para profundizar aún más en buenas prácticas, consulta también nuestro artículo sobre Clean Code en Python, que cubre principios complementarios para escribir código profesional de alta calidad.

¿Te gustó esta guía? ¡Compártela con otros desarrolladores y ayuda a la comunidad Python a escribir código cada vez mejor!