Estructura de un proyecto Python y Pylint

Este curso no es una lista de reglas: es un proyecto que se construye en vivo. Vamos a programar una pequeña API de cifrado (cifrado César, encriptación simétrica y hash) y, mientras tanto, aplicar lo que un equipo profesional espera de tu código: estándares, funciones, pruebas, integración continua y documentación.

Para quién es. Para quien ya programa en Python y quiere que su código se vea profesional. No vamos a explicar qué es un for: vamos a explicar por qué un equipo te rechazaría un código que funciona.

Una estructura de carpetas que cualquiera entiende ▸1:13

No es obligatorio copiarla tal cual, pero tener siempre la misma estructura hace que cualquier persona del equipo sepa dónde buscar:

api_cifrado/
├── app/            ← el código de la aplicación (en otros proyectos: src/)
│   ├── __init__.py ← convierte la carpeta en un paquete
│   └── main.py     ← el punto de entrada
├── img/            ← solo imágenes
│   └── .gitkeep
├── notebooks/      ← prototipos y pruebas rápidas, nunca código de producción
├── tests/          ← las pruebas automáticas
├── venv/           ← el entorno virtual (no se sube a git)
├── .gitignore
├── README.md
└── requirements.txt

• app o src: src (de source) es una costumbre heredada de Java. En Python puedes llamarla como quieras; app es muy común.
• .gitkeep: git no guarda carpetas vacías. Este archivo vacío existe solo para que la carpeta img/ llegue al repositorio.
• __init__.py: le dice a Python que app es un paquete y que se puede importar desde otros archivos.

PEP 8: las normas APA del código ▸4:58

En la universidad te pedían escribir con normas APA o ICONTEC: márgenes, tipo de letra, citas. El código también es texto, y Python tiene su propio estándar de escritura: PEP 8.

Para no revisarlo a mano existen los linters. En el curso usamos Pylint; otros populares son Ruff y Flake8.

pip install pylint
pylint main.py

Pylint te dice exactamente qué línea incumple qué regla, con un código:

• C0304 — falta una línea vacía al final del archivo.
• C0114 — falta el docstring del módulo: un texto entre triples comillas, arriba del archivo, que explica qué hace.

"""Este es el archivo principal"""
print("Hola mundo")

Con esas dos correcciones, el puntaje pasa de 0 a 10/10.

El puntaje como regla de equipo ▸9:18

El número que da Pylint sirve para algo más que presumir: muchos equipos lo usan como puerta de entrada a producción. Por ejemplo, «no se acepta código con menos de 8/10». No se suele exigir 10/10 porque algunas reglas son tediosas de cumplir al pie de la letra, pero un piso mínimo evita que el código se degrade con el tiempo.

El reto de esta clase

Toma un script tuyo de cualquier proyecto (uno que funcione) y pásale Pylint. Anota el puntaje inicial y corrígelo hasta pasar de 8/10 sin cambiar lo que hace. ¿Qué regla te saltó más veces?

pip install pylint
pylint mi_script.py
# Lo habitual en la primera pasada:
#   C0114  falta el docstring del módulo
#   C0116  falta el docstring de una función
#   C0103  nombre que no sigue el estilo (constantes en MAYÚSCULAS, variables en snake_case)
#   C0304  falta la línea vacía al final