TareaFácil funciona: la v0.16 tiene clases con validación, una agenda que protege sus datos y persistencia en JSON. Pero todo eso vive en un único fichero que ya acumula tres clases, una docena de funciones de entrada y salida, las constantes, el menú y la persistencia. Cada vez que hay que tocar algo toca recorrerlo entero buscando dónde, y si mañana Marta quiere una versión web, no hay forma de reutilizar la lógica sin arrastrar también el menú de la consola. Esta lección resuelve ese problema con la última pieza de organización que le falta al curso: repartir el código en varios ficheros que se importan entre sí. Verás qué es un módulo y qué ocurre exactamente cuando Python importa uno —lo que explica por fin el if __name__ == "__main__": que arrastramos desde 04-04—, cómo se agrupan varios módulos en un paquete, qué tesoros trae la biblioteca estándar y cómo se instalan librerías de terceros con pip. Al final, TareaFácil dejará de ser un fichero para convertirse en el paquete tareafacil/.

1. Qué es un módulo y por qué separar
2. Las formas de importar
3. Cómo encuentra Python los módulos
4. Qué ocurre al importar: __name__ y if __name__ == "__main__"
5. Paquetes: carpetas con __init__.py
6. La biblioteca estándar
7. Paquetes de terceros: PyPI y pip
8. Importaciones circulares
9. TareaFácil v0.17: el paquete tareafacil/
10. Errores comunes y consejos
11. Ejercicios
12. Conclusión

Un módulo es, simplemente, un fichero .py. No hay que declarar nada ni marcarlo de ninguna manera: en cuanto guardas validaciones.py, ya tienes un módulo llamado validaciones que cualquier otro fichero puede importar. Lo llevas usando desde el principio del curso sin saberlo: import json, import csv, from pathlib import Path cargan módulos escritos por otros.

¿Por qué repartir el código en varios ficheros? Por cuatro razones muy concretas:

• Encontrar las cosas. En un proyecto con modelo.py, agenda.py, almacen.py e interfaz.py, saber dónde tocar es inmediato. En un fichero de mil líneas, no.
• Reutilizar. Si la lógica de tareas vive en modelo.py sin una sola llamada a print ni a input, ese fichero sirve igual para la aplicación de consola, para una web o para un script de informes.
• Trabajar en equipo. Dos personas en dos ficheros distintos no se pisan; en el mismo fichero, sí.
• Limitar el daño. Un módulo con una responsabilidad clara se puede leer, entender y cambiar sin tener toda la aplicación en la cabeza.

El criterio para decidir qué va en cada fichero es el mismo que ya usaste con las funciones en 04-04 y con las clases en este módulo: una responsabilidad por módulo. Los datos por un lado, la persistencia por otro, la conversación con el usuario por otro.

Supongamos un fichero formato.py con una constante y una función:

Desde otro fichero, en la misma carpeta, se puede acceder de cuatro formas:

La última fila de la tabla merece explicación. from modulo import * trae todos los nombres públicos del módulo al fichero actual, y está desaconsejado por dos motivos serios: quien lea tu código no puede saber de dónde sale titulo —¿lo has definido tú, viene de formato o de otro import *?—, y si dos módulos exportan el mismo nombre, el segundo pisa al primero sin decir nada. Un from os import * seguido de from numpy import * puede dejarte con una función distinta de la que crees estar llamando. Es un ahorro de tecleo que se paga con horas de depuración. La regla práctica que siguen casi todos los proyectos: import modulo por defecto, from modulo import nombre cuando se usa mucho un nombre concreto, y nunca *.

Cuando escribes import formato, Python busca ese fichero en una lista de carpetas, en orden:

1. La carpeta del script que has ejecutado (o el directorio actual, en la consola interactiva).
2. Las carpetas indicadas en la variable de entorno PYTHONPATH, si existe.
3. Las carpetas de la instalación de Python, donde está la biblioteca estándar.
4. La carpeta site-packages, donde pip instala los paquetes de terceros.

Esa lista es visible y se puede consultar:

Si Python no encuentra el módulo, el error es inconfundible: ModuleNotFoundError: No module named 'formato'. Las causas habituales son tres: el fichero no está en la carpeta que crees, el nombre está mal escrito (mayúsculas incluidas: en Linux Formato y formato son distintos), o has ejecutado el script desde otra carpeta.

Y hay una trampa que hay que conocer sí o sí: nunca llames a tus ficheros como un módulo de la biblioteca estándar. Si creas un random.py para practicar y dentro escribes import random, Python encontrará tu fichero antes que el oficial —la carpeta del script va primero— y fallará con un error incomprensible del tipo AttributeError: module 'random' has no attribute 'randint'. Lo mismo con json.py, csv.py, math.py, time.py o email.py. Si te ocurre, renombra tu fichero y borra la carpeta __pycache__ que Python haya dejado al lado.

Aquí llega la explicación que prometimos en 04-04. Cuando Python importa un módulo, ejecuta su código de arriba abajo, entero, una sola vez. Las líneas def y class definen funciones y clases sin ejecutarlas, pero cualquier otra línea sí se ejecuta: asignaciones, print, llamadas.

Y en esa ejecución, Python define en el módulo una variable especial llamada __name__, con un valor que depende de cómo se haya llegado a él:

Vamos a comprobarlo con dos ficheros:

Al ejecutar python saludo.py salen dos líneas: Ejecutando saludo.py, __name__ vale: __main__ y Hola, Marta.. Pero al ejecutar python principal.py la salida es esta:

Léela con calma, porque contiene tres lecciones:

• El print de saludo.py se ejecutó aunque solo lo hayamos importado: importar es ejecutar. Por eso un módulo no debe hacer trabajo pesado ni pedir datos al usuario en su nivel superior.
• __name__ valió "saludo", no "__main__", así que la línea print(saludar("Marta")) no se ejecutó. Ese es exactamente el propósito del if: el código que solo tiene sentido al ejecutar el fichero directamente.
• __name__ vale "__main__" en el fichero que arrancó todo, sea cual sea su nombre.

De ahí sale la conclusión que llevábamos arrastrando: if __name__ == "__main__": main() significa «arranca la aplicación solo si me están ejecutando a mí; si alguien me importa para reutilizar mis funciones, no hagas nada». Sin esa guarda, importar tareafacil para usar su clase Tarea lanzaría el menú interactivo por sorpresa.

Un último detalle: al importar por primera vez, Python guarda una versión compilada en __pycache__ para acelerar las siguientes ejecuciones, y no vuelve a ejecutar el módulo si ya está importado, aunque aparezcan diez import iguales.

Cuando los módulos se multiplican, se agrupan en carpetas. Una carpeta que Python trata como un conjunto de módulos es un paquete, y para marcarla como tal se le añade un fichero llamado __init__.py.

Con esa estructura, los módulos se importan con la notación del punto: import tareafacil.modelo para el módulo completo, from tareafacil.modelo import Tarea para un nombre concreto o from tareafacil import agenda para un módulo del paquete. El __init__.py se ejecuta al importar cualquier cosa del paquete, y sirve para dos cosas: dejarlo vacío (lo más habitual y perfectamente correcto), o usarlo para exponer una interfaz cómoda, de modo que quien use el paquete no tenga que conocer su estructura interna:

Gracias a eso, quien use el paquete puede escribir from tareafacil import Tarea, Agenda sin saber en qué fichero está cada clase. Lo que no debe hacer nunca un __init__.py es trabajo pesado, porque se ejecuta en cada importación. Y fíjate en el punto de from .modelo import Tarea: es una importación relativa, y significa «el módulo modelo que está en mi mismo paquete».

Las dos funcionan y las verás en proyectos reales. La guía de estilo oficial recomienda las absolutas por claridad, con las relativas como opción aceptable dentro de un paquete grande. Lo que no conviene es mezclar los dos estilos sin criterio en el mismo proyecto.

Python viene «con las pilas puestas»: al instalarlo tienes cientos de módulos ya disponibles, sin instalar nada. Estos son los que más te van a servir ahora:

Un ejemplo con datetime aplicado a nuestras tareas, que es el uso que más falta le hace a TareaFácil: pasar de «días estimados» a fechas de entrega reales.

Tres piezas: date.today() da la fecha actual, timedelta(days=n) representa una duración que se suma o resta a una fecha, y strftime la formatea (%d día, %m mes, %Y año). Restar dos fechas devuelve un timedelta, cuyo .days da la diferencia. Y como las fechas se comparan con < y >, ordenar tareas por fecha de entrega con sorted(..., key=attrgetter("entrega")) funciona sin más.

Cuando la biblioteca estándar no llega, se recurre a PyPI (Python Package Index), el repositorio público donde la comunidad publica más de medio millón de paquetes: requests para hablar con webs, pandas para analizar datos, flask y django para aplicaciones web, pytest para pruebas.

Se instalan con pip, el gestor de paquetes que viene con Python:

El fichero requirements.txt es la pieza clave del trabajo en equipo: contiene las dependencias con su versión exacta, se guarda junto al código y permite que cualquiera reproduzca tu entorno con un solo comando.

Y aquí conviene recordar el entorno virtual de Entornos de desarrollo. Los paquetes deben instalarse dentro del venv del proyecto, no en el Python del sistema, por dos motivos: dos proyectos pueden necesitar versiones distintas de la misma librería, y así el requirements.txt refleja exactamente lo que ese proyecto usa y nada más.

Una advertencia de seguridad que ya nunca deberías olvidar: instalar un paquete es ejecutar código de un desconocido en tu ordenador. Antes de un pip install, comprueba que el nombre está bien escrito —existen paquetes maliciosos con nombres casi idénticos a los populares, a la caza de erratas—, mira si el proyecto tiene actividad reciente y usuarios, y desconfía de dependencias que aparecen sin que sepas quién las pidió. TareaFácil, por cierto, no necesita ninguna: todo lo que usa está en la biblioteca estándar.

Ocurre cuando dos módulos se importan mutuamente: agenda.py hace import almacen y almacen.py hace import agenda. Python empieza a cargar el primero, ve el import del segundo, empieza a cargar el segundo, que vuelve al primero... que todavía está a medio ejecutar, y por tanto le faltan nombres. El resultado es un ImportError: cannot import name 'X' from partially initialized module que desconcierta a cualquiera.

La solución no es técnica sino de diseño: las dependencias deben ir en una sola dirección. En TareaFácil, almacen sabe de modelo, e interfaz sabe de las dos, pero modelo no sabe nada de nadie. Si te encuentras con un ciclo, casi siempre significa que:

• Las responsabilidades están mal repartidas y hay algo que debería estar en un tercer módulo del que dependan los dos.
• O una de las dos direcciones sobra: normalmente el módulo «de abajo» no necesita conocer al de arriba, sino recibir lo que necesite como parámetro.

Repartimos la v0.16 en cinco módulos, cada uno con una responsabilidad:

Y estas son las cabeceras de cada uno, que muestran quién depende de quién:

Y así se ejecuta ahora el programa, desde la carpeta que contiene a tareafacil/:

La opción -m le dice a Python «ejecuta este paquete como programa», y por eso el fichero se llama __main__.py: es el que Python busca para arrancar un paquete. La alternativa clásica es dejar fuera de la carpeta un main.py de tres líneas —from tareafacil.__main__ import main, y la guarda if __name__ == "__main__": main()— y ejecutar python main.py. Fíjate en el resultado, que es lo importante de toda la lección:

Las flechas van en una sola dirección, así que no hay importaciones circulares. Y modelo.py, que no depende de nada y no tiene un solo print, se puede reutilizar tal cual en una versión web o probar de forma aislada, que es justo lo que haremos en 08-04.

• Llamar a un fichero como un módulo estándar (random.py, json.py, csv.py). Python cargará el tuyo y el error será incomprensible. Renombra y borra __pycache__.
• Usar from modulo import *. Destruye la trazabilidad de los nombres y provoca choques silenciosos.
• Ejecutar el paquete desde dentro de su carpeta. python __main__.py desde dentro de tareafacil/ rompe las importaciones relativas (attempted relative import with no known parent package). Sitúate en la carpeta de arriba y usa python -m tareafacil.
• Poner código ejecutable en el nivel superior de un módulo. Recuerda que importar es ejecutar: un input() o un print sueltos se dispararán en cuanto alguien importe el fichero. Todo lo ejecutable, dentro de funciones y bajo if __name__ == "__main__":.
• Crear ciclos entre módulos. Si a importa b y b importa a, revisa el reparto de responsabilidades: casi siempre sobra una de las dos direcciones.
• Instalar paquetes fuera del entorno virtual. Acabas con un Python del sistema lleno de librerías y un requirements.txt que no refleja el proyecto.
• Consejo: empieza por un fichero y separa cuando duela. Dividir demasiado pronto crea diez ficheros de veinte líneas y un lío de importaciones. La señal para separar es concreta: cuando cueste encontrar dónde tocar o cuando quieras reutilizar una parte sin las demás.

Crea medidas.py con una constante IVA = 0.21, una función con_iva(base) que devuelva el importe con IVA y un print("cargando medidas") en el nivel superior. Crea después factura.py que lo importe y calcule el total de un presupuesto de 1.200 € para el cliente Vidal. Predice qué imprimirá cada uno al ejecutarse directamente y compruébalo; después añade a medidas.py una prueba rápida protegida con if __name__ == "__main__": y explica qué cambia.

Un compañero ha escrito un único fichero gestor.py de 600 líneas con: la clase Cliente, la clase Factura, funciones para leer y escribir el CSV de facturas, funciones que piden datos por teclado, el menú y el main(). Propón un reparto en módulos, indica qué importa cada uno y dibuja mentalmente las flechas de dependencia para comprobar que no hay ciclos.

Escribe una función fecha_entrega(dias) que devuelva la fecha de entrega a partir de hoy formateada como dd/mm/aaaa, y otra dias_para(fecha) que reciba un date y devuelva cuántos días faltan (negativo si ya pasó). Úsalas para imprimir el plan de las tres tareas de Estudio Alba: cartel (3 días), logotipo (5) y presupuesto (2).

Solución 1.

Al ejecutar python factura.py la salida es cargando medidas y después Presupuesto cliente Vidal: 1452.0 EUR. El primer mensaje aparece aunque no lo hayamos pedido, porque importar es ejecutar; el 121.0 de la prueba no aparece, porque al importarse __name__ vale "medidas" y no "__main__". Esa guarda es lo que permite que un módulo tenga su propia comprobación rápida sin molestar a quien lo reutiliza. Y el print("cargando medidas") suelto es justo lo que no debe hacer un módulo de verdad: aquí está solo para verlo.

Solución 2.

Las flechas van de principal hacia los demás y de almacen/interfaz hacia modelo: ninguna vuelve hacia atrás, así que no hay ciclos. La clave del reparto es que modelo.py no importe nada del proyecto ni contenga un solo print o input; si Factura necesitara pedir algo al usuario, sería señal de que esa lógica está en el sitio equivocado. Si las cuatro piezas crecen, el paso siguiente es agruparlas en un paquete gestor/ con su __init__.py.

Solución 3.

Dos detalles que conviene fijar. date.today() + timedelta(days=dias) devuelve un objeto date nuevo: las fechas son inmutables, como las tuplas y las cadenas, así que nunca se modifican en el sitio. Y strftime se aplica solo al final, para mostrar: mientras el programa calcula, conviene trabajar siempre con objetos date y no con textos, porque los objetos se comparan, se restan y se ordenan, y "08/08/2026" no.

Un módulo es cualquier fichero .py, y separar el código en varios responde a cuatro necesidades muy concretas: encontrar las cosas, reutilizar la lógica sin arrastrar la interfaz, trabajar en equipo y limitar el daño de cada cambio. Se importan con import modulo —la forma más clara, porque el prefijo dice de dónde sale cada nombre—, import modulo as alias, from modulo import nombre y su variante con as, evitando siempre from modulo import *, que borra la trazabilidad y provoca choques silenciosos. Python busca los módulos en la carpeta del script, en PYTHONPATH, en la instalación y en site-packages, lista visible en sys.path; de ahí el ModuleNotFoundError y la trampa de llamar a un fichero propio random.py o json.py. Al importar, el módulo se ejecuta entero una sola vez, y Python le da a __name__ el valor "__main__" solo si es el fichero que has lanzado: esa es la explicación completa del if __name__ == "__main__": que veníamos usando desde 04-04, la guarda que separa «lo que hago cuando me ejecutan» de «lo que ofrezco cuando me importan». Varios módulos en una carpeta con __init__.py forman un paquete, con importaciones absolutas (from tareafacil.modelo import Tarea) o relativas (from .modelo import Tarea), y con un __init__.py que puede quedarse vacío o exponer una interfaz cómoda. La biblioteca estándar trae ya resuelto casi todo —math, random, datetime, os, pathlib, json, csv, sys, time, statistics, collections, functools—, y para lo demás está PyPI con pip install y requirements.txt, siempre dentro del venv del proyecto y siempre mirando qué se instala. Por último, las importaciones circulares no se arreglan con trucos: se evitan haciendo que las dependencias vayan en una sola dirección.

Con esto se cierra el módulo 7 y el salto más grande del curso. Empezaste con una lista de diccionarios frágil, en la que cualquier tarea podía nacer sin completada o con la prioridad escrita como "Alta", y con las funciones que operaban sobre ellas desperdigadas por un fichero. Ahora hay una clase Tarea que garantiza en su constructor que ninguna tarea inválida llega a existir y que lleva dentro su propio comportamiento; una clase Agenda que encapsula la colección, valida lo que entra, protege su lista interna y sabe guardarse y reconstruirse desde JSON; herencia y polimorfismo en su forma justa, con la advertencia de preferir composición; y un proyecto repartido en el paquete tareafacil/, con cada módulo en su sitio y las dependencias apuntando en una sola dirección. TareaFácil es la v0.17 y se ejecuta con python -m tareafacil.

Y sin embargo, míralo con ojos de programador profesional: ese código no está documentado más allá de unas docstrings sueltas, y nadie de fuera sabría por dónde entrar; no gestiona los errores, así que un fichero JSON corrupto o un dias que llega como texto todavía tumban el programa entero con un traceback; no tiene historial, de modo que un cambio desafortunado se pierde sin vuelta atrás y no hay forma de saber quién tocó qué; y no tiene pruebas, así que cada modificación obliga a repasar el menú a mano rezando por no haber roto nada. En el módulo 8 se resuelven las cuatro cosas, empezando por Documentación y comentarios: docstrings de verdad, comentarios que explican el porqué y no el qué, y un README que permita a cualquiera —incluido tú dentro de seis meses— entender el proyecto en cinco minutos.