Cómo dividir tu código en módulos de Python

Aprender a usar módulos en Python es el paso que separa un archivo gigante e inmanejable de un proyecto ordenado y fácil de escalar. Si tienes todo tu código en un solo main.py, este contenido te muestra cómo dividirlo en piezas con una sola responsabilidad, cómo nombrarlas bien y por qué eso te ahorra dolores de cabeza.

¿Qué son los módulos en Python y por qué importan?

Un módulo es simplemente un archivo de Python que contiene funciones, clases o cualquier cosa que quieras agrupar. La idea central es la especificidad: cada archivo debe incluir solo funcionalidades relacionadas entre sí.

Así, cuando quieras entender cómo funciona la autenticación o cómo está configurada tu aplicación, consultas un único archivo en lugar de rastrear cientos de líneas. Eso es lo que hace que trabajar con el proyecto sea más llevadero.

¿Qué es un módulo en Python? Es un archivo .py que agrupa funciones, clases u otros elementos relacionados. Sirve para dividir tu código en partes manejables en lugar de tenerlo todo en un solo archivo.

Hasta ahora todo el proyecto vivía en main.py, con ejemplos y código mezclados. El trabajo consiste en empezar a separar ese contenido en archivos correctos y, sobre todo, nombrarlos siguiendo reglas claras [00:26].

¿Cómo se deben nombrar los módulos correctamente?

El nombre no es un detalle menor. Hay dos reglas que no puedes saltarte al crear tus archivos [01:12].

• Usa snake case para nombrar los módulos, es decir, palabras en minúscula separadas por guiones bajos. Un nombre que no respete esto no es válido.
• Un módulo nunca debe llamarse igual que uno que ya existe en Python.

Y aquí viene lo interesante con la segunda regla. Cuando escribes algo como from datetime, Python busca internamente en su conjunto de módulos si ya existe uno con ese nombre [01:33].

Si lo encuentra, lo importa. Pero si tú tienes un archivo con ese mismo nombre en tu carpeta, Python nunca lo encontrará, porque siempre dará prioridad al que viene instalado o configurado por el lenguaje.

¿Cómo importar y explorar un módulo en Python?

Para usar un módulo tienes que importarlo, y lo haces con el nombre del archivo. Por ejemplo, al importar docstrings, el editor autocompleta y hasta muestra la documentación de esa clase o archivo [01:57].

La sintaxis from docstring import te permite traer cualquier nombre definido dentro de ese archivo. Un detalle práctico: coloca los imports al inicio del archivo para que el editor deje de advertirte que algo no se está usando o que debería ir arriba [02:29].

¿Cómo veo todo lo que tiene un módulo? Usa la función dir. Abre la terminal, entra a Python, importa el módulo como datetime y escribe dir(datetime). Verás todas las funcionalidades que ese módulo incluye.

La función dir es una herramienta que la propia documentación de Python destaca, porque te deja inspeccionar de un vistazo qué ofrece cualquier módulo [03:04].

¿Por qué cada módulo debe tener una sola responsabilidad?

La recomendación clave es que cada módulo tenga una única responsabilidad. Si construyes una librería, la librería puede ser un módulo. Si manejas configuración, crea un módulo config y concentra ahí todas las variables de configuración [02:50].

Esa disciplina evita que un archivo termine haciendo demasiadas cosas y se vuelva imposible de leer.

¿Cómo modularizar una aplicación paso a paso?

La base ya está lista para desmenuzar toda la aplicación. Todo el código vive colapsado en main.py, incluyendo los ejemplos creados para explicar conceptos del curso [03:33].

El proceso de modularización se ve así en la práctica:

1. Separa los ejemplos en su propio archivo, como Example.py, para que puedas consultarlos sin estorbar el código principal [03:53].
2. Crea módulos específicos con una sola acción, por ejemplo newsAPIClient, dedicado únicamente a la conexión con la API [04:20].
3. Copia en ese archivo solo lo relacionado con el cliente y agrega los imports que necesite.

Al crear un nuevo módulo tendrás que añadir sus imports. Elementos como la URL en vivo, el módulo JSON o el error de API key deben importarse en el archivo correspondiente [04:34].

Una forma cómoda de hacerlo es usar el quick fix del editor, que te ofrece opciones como "Import Live URL" de forma automática. Eso sí, asegúrate siempre de importar la librería o módulo correcto para poder usarlo [04:47].

¿Qué beneficios reales trae modularizar tu código?

Modularizar no es un capricho estético, tiene ventajas concretas que notas cuando el proyecto crece [05:33].

• Mantenimiento más simple: modificas solo el archivo que necesitas en vez de leer uno enorme lleno de líneas que ni entiendes.
• Mejor uso de un LLM para generar código, porque solo importa el fragmento que quieres modificar.
• Mayor claridad: encuentras rápido dónde está la autenticación, la configuración o el cliente de la API.

Con esta estructura, comparar tu proyecto contra un repositorio de referencia se vuelve directo, porque cada pieza vive donde debe. ¿Ya empezaste a separar tu main.py en módulos? Cuéntame en los comentarios cómo organizaste el tuyo.