Módulos e imports
Hasta ahora todo el código vivía en un único archivo o en la consola interactiva. En cuanto un programa crece, conviene partirlo en piezas: cada pieza en su propio archivo, y el archivo principal se aprovecha de las funciones y datos que viven en los demás. A esa unidad (un archivo .py que puede ser importado desde otro) Python la llama módulo.
Pero hay una motivación más inmediata que justificar el organizar tu propio código: Python trae centenares de módulos ya escritos, agrupados en lo que se llama la biblioteca estándar (o stdlib). Para usarlos no tienes que instalar nada, solo importarlos.
El import básico
La forma más sencilla es import módulo. A partir de ahí, todo lo que el módulo expone se accede con la sintaxis módulo.cosa:
>>> import math
>>> print(math.pi)
3.141592653589793
>>> print(math.sqrt(16))
4.0
>>> print(math.floor(3.7))
3
El módulo math es parte de la stdlib. math.pi es una constante; math.sqrt() y math.floor() son funciones. La estructura módulo.cosa deja claro al leer el código de dónde sale cada función, lo que ayuda mucho cuando estás revisando un archivo que no escribiste tú.
La variante from ... import ...
Si solo necesitas una o dos cosas concretas de un módulo y vas a usarlas mucho, puedes importarlas directamente en el espacio de nombres actual:
>>> from math import pi, sqrt
>>> print(pi)
3.141592653589793
>>> print(sqrt(16))
4.0
Ya no hace falta el prefijo math.. Es más corto, pero pierdes la pista visual de dónde sale cada nombre. En módulos grandes (o si vas a importar varios paquetes), el primer estilo suele leerse mejor.
Nota: existe también la forma from math import *, que importa todo lo que el módulo expone. Es muy cómodo y muy peligroso: contamina tu espacio de nombres con cualquier cosa que el módulo defina, incluidas funciones con nombres que choquen con las tuyas. La regla práctica: nunca lo uses fuera de la consola interactiva.
Alias con as
Si el nombre del módulo es largo o quieres acortarlo, puedes asignarle un alias con as:
>>> import datetime as dt
>>> print(dt.date.today())
2026-05-30
>>> from numpy import ndarray as Array # también vale en la forma from-import
Ciertos alias son convenciones casi universales en la comunidad Python: los verás idénticos en cualquier código que toques: import numpy as np, import pandas as pd, import matplotlib.pyplot as plt. No los inventes tú, úsalos exactamente así.
Tu propio módulo
Cualquier archivo .py es ya un módulo importable. Si tienes una carpeta con estos dos archivos:
proyecto/
├── utilidades.py
└── main.py
y utilidades.py contiene:
# utilidades.py
def saludar(nombre):
return f"hola, {nombre}"
PI = 3.14159
desde main.py puedes usar todo lo de utilidades con un import:
# main.py
import utilidades
print(utilidades.saludar("cristina"))
print(utilidades.PI)
El nombre del módulo es el nombre del archivo sin la extensión .py. Python busca el archivo en el mismo directorio que el script que lo está importando (y en algunos otros sitios del sistema), por orden.
El truco if __name__ == "__main__"
Cuando ejecutas un archivo Python directamente (python mi_script.py), Python le asigna a la variable interna __name__ el valor "__main__". Cuando ese mismo archivo es importado desde otro, __name__ toma el nombre del módulo. Esto permite escribir código que solo se ejecuta cuando el archivo se llama directamente, y no cuando se importa:
# utilidades.py
def saludar(nombre):
return f"hola, {nombre}"
if __name__ == "__main__":
# solo se ejecuta si haces "python utilidades.py"
# no se ejecuta cuando alguien hace "import utilidades"
print(saludar("prueba"))
Lo verás constantemente en código Python real. Sirve para tres cosas: poner pruebas rápidas al final de un módulo, separar "script ejecutable" de "biblioteca importable", y evitar que el código de demostración se ejecute por accidente al hacer el import.
Paquetes: una carpeta con varios módulos
Cuando un proyecto tiene muchos módulos, conviene agruparlos en carpetas. Una carpeta con un archivo (opcional pero recomendado) llamado __init__.py es un paquete: un módulo formado por varios submódulos.
proyecto/
├── main.py
└── mi_app/
├── __init__.py
├── usuarios.py
└── pagos.py
Desde main.py los importas con notación de punto:
from mi_app import usuarios
from mi_app.pagos import procesar_pago
El archivo __init__.py puede estar vacío (basta su presencia para marcar la carpeta como paquete), o puede contener código que se ejecuta al hacer el primer import. En proyectos modernos suele estar vacío y servir solo como marcador.
Un vistazo a la biblioteca estándar
La stdlib de Python es enorme. Sin instalar nada, ya tienes:
| Módulo | Para qué sirve |
|---|---|
math | Funciones matemáticas: raíz, logaritmo, trigonometría, constantes (pi, e). |
random | Generar números aleatorios, elegir elementos al azar, barajar listas. |
datetime | Fechas, horas, diferencias entre fechas, formateo. |
pathlib | Manipular rutas de archivos y carpetas de forma moderna y multiplataforma. |
os | Interactuar con el sistema operativo: variables de entorno, listar archivos, ejecutar comandos. |
sys | Acceso al intérprete: argumentos del programa, salir con un código, entrada/salida estándar. |
json | Leer y escribir JSON. Cubierto en detalle en el manual "Otros". |
csv | Leer y escribir archivos CSV sin tener que parsearlos a mano. |
re | Expresiones regulares. |
collections | Estructuras de datos especializadas: Counter, defaultdict, deque. |
itertools | Herramientas para construir iteradores complejos: combinaciones, permutaciones, ciclos. |
urllib | Hacer peticiones HTTP básicas sin instalar nada. Para uso serio, usa requests. |
Algunos ejemplos rápidos:
>>> import random
>>> random.randint(1, 6) # tirada de dado
4
>>> random.choice(["sí", "no", "quizá"])
'no'
>>> from datetime import date, timedelta
>>> hoy = date.today()
>>> print(hoy)
2026-05-30
>>> print(hoy + timedelta(days=30)) # dentro de 30 días
2026-06-29
>>> from pathlib import Path
>>> Path(".").glob("*.py") # lista los .py del directorio actual
No hace falta memorizar nada. Cuando necesites algo, búscalo: "python módulo para X" casi siempre tiene respuesta en la stdlib o en un paquete famoso de PyPI.
Nota: la documentación oficial de la stdlib está en docs.python.org. Es referencia, no tutorial, pero cuando ya sabes el nombre del módulo es el sitio para entender qué expone.
Orden de los imports (PEP 8)
El estilo de la comunidad coloca todos los imports juntos al principio del archivo, separados en tres grupos por una línea en blanco:
- Módulos de la biblioteca estándar.
- Paquetes externos (instalados con
pip). - Módulos propios del proyecto.
# 1. stdlib
import json
from datetime import date
# 2. paquetes externos
import requests
# 3. tuyos
from mi_app import usuarios
from mi_app.pagos import procesar_pago
No es una norma del lenguaje (Python ejecuta el código aunque mezcles los imports), pero todo proyecto Python con un mínimo de cuidado los organiza así. Cubrimos esto también en el anexo de PEP 8.
En la próxima lección: manejo de archivos: abrir, leer y escribir desde Python con open() y pathlib.