Módulos de Python

Un módulo es un archivo que contiene código Python — funciones, clases y variables — que puedes reutilizar en múltiples programas. Los módulos son la unidad básica de organización de código en Python: en lugar de copiar lógica entre archivos, la escribes una vez, la guardas como un archivo .py y la importas donde la necesites. Este capítulo cubre todo, desde la creación de tu primer módulo hasta la navegación por la biblioteca estándar y la comprensión de cómo Python localiza los módulos en tiempo de ejecución.

¿Qué es un módulo de Python?

Cualquier archivo .py es un módulo. Cuando escribes:

# greetings.py
def hello(name):
    return f"Hello, {name}!"

def goodbye(name):
    return f"Goodbye, {name}!"

PI = 3.14159

has creado un módulo llamado greetings. El nombre del módulo es el nombre del archivo sin la extensión .py.

Los módulos pueden contener:

• Funciones — bloques de lógica reutilizables (ver Funciones de Python)
• Clases — plantillas para objetos (ver Clases de Python)
• Variables y constantes — datos compartidos
• Sentencias ejecutables — código que se ejecuta cuando el módulo se importa o se ejecuta directamente

Importar un módulo

Usa la sentencia import seguida del nombre del módulo (sin la extensión .py).

import greetings

print(greetings.hello("Alice"))    # Hello, Alice!
print(greetings.goodbye("Alice"))  # Goodbye, Alice!
print(greetings.PI)                # 3.14159

Después de import greetings, todos los nombres definidos en greetings.py son accesibles mediante el prefijo greetings.. Esta notación de punto evita colisiones de nombres — tu propia variable PI no puede entrar en conflicto con greetings.PI.

Importar nombres específicos con from ... import

Si solo necesitas uno o dos nombres, impórtalos directamente para poder usarlos sin el prefijo del módulo.

from greetings import hello, PI

print(hello("Bob"))   # Hello, Bob!
print(PI)             # 3.14159

Importar todo con *

from greetings import *

Esto trae todos los nombres públicos (los que no comienzan con _) al espacio de nombres actual. Evítalo en programas más grandes: contamina el espacio de nombres y dificulta saber de dónde proviene un nombre.

Alias de importación con as

Los nombres de módulos largos pueden ser tediosos de escribir. Usa as para crear un alias más corto.

import greetings as gr

print(gr.hello("Carol"))   # Hello, Carol!

También puedes crear alias para nombres importados individualmente:

from greetings import hello as hi

print(hi("Dave"))   # Hello, Dave!

Los alias son especialmente comunes con bibliotecas populares:

import numpy as np
import pandas as pd
import matplotlib.pyplot as plt

La función dir()

dir(module) devuelve una lista ordenada de todos los nombres definidos en un módulo — una forma rápida de explorar qué está disponible.

import math
print(dir(math))
# ['__doc__', '__loader__', ..., 'acos', 'acosh', 'asin', ..., 'sqrt', 'tan', 'tanh', 'tau']

Llama a dir() sin argumentos para ver los nombres en el ámbito actual.

La variable __name__

Cada módulo tiene una variable incorporada llamada __name__. Cuando un archivo es importado, __name__ se establece con el nombre del módulo. Cuando el archivo se ejecuta directamente, __name__ se establece con la cadena "__main__".

Este patrón es la forma estándar de escribir código que se ejecuta solo cuando el archivo se lanza como script — no cuando se importa como biblioteca:

# greetings.py

def hello(name):
    return f"Hello, {name}!"

if __name__ == "__main__":
    # This block only runs when you execute: python greetings.py
    print(hello("World"))

import greetings   # The if-block does NOT run here

Este patrón se usa en casi todos los archivos Python no triviales que encontrarás.

Ruta de búsqueda de módulos (sys.path)

Cuando escribes import greetings, Python busca el módulo en una lista de directorios almacenados en sys.path:

1. El directorio del script que se está ejecutando (o el directorio actual en modo interactivo)
2. Los directorios listados en la variable de entorno PYTHONPATH
3. Los directorios de la biblioteca estándar
4. El directorio site-packages (donde viven los paquetes de terceros instalados con pip)

import sys
print(sys.path)
# ['/path/to/script', '/usr/lib/python3.11', ..., '/usr/lib/python3/dist-packages']

Puedes agregar una ruta en tiempo de ejecución, aunque esto rara vez es necesario en proyectos bien estructurados:

import sys
sys.path.append("/path/to/my/libs")

La biblioteca estándar de Python

Python incluye una extensa biblioteca estándar — cientos de módulos que cubren desde E/S de archivos hasta protocolos de red y compresión de datos. No necesitas instalar nada; simplemente impórtalos.

math — Funciones matemáticas

import math

print(math.sqrt(16))       # 4.0
print(math.pi)             # 3.141592653589793
print(math.factorial(5))   # 120
print(math.ceil(4.2))      # 5
print(math.floor(4.8))     # 4

Consulta Python Math para una referencia completa.

random — Números aleatorios

import random

print(random.randint(1, 10))          # random integer between 1 and 10
print(random.choice(["a", "b", "c"])) # random element
print(random.random())                 # float in [0.0, 1.0)

numbers = [1, 2, 3, 4, 5]
random.shuffle(numbers)
print(numbers)   # shuffled in place

datetime — Fechas y horas

import datetime

now = datetime.datetime.now()
print(now)                       # 2024-03-15 10:30:45.123456
print(now.year)                  # 2024
print(now.strftime("%B %d, %Y")) # March 15, 2024

today = datetime.date.today()
print(today)   # 2024-03-15

Consulta Python Dates para una cobertura completa de aritmética y formato de fechas.

os y sys — Sistema operativo e intérprete

import os

print(os.getcwd())              # current working directory
print(os.listdir("."))          # files in the current directory
os.makedirs("new_dir", exist_ok=True)  # create a directory
print(os.path.join("folder", "file.txt"))  # 'folder/file.txt'

import sys

print(sys.version)    # Python version string
print(sys.platform)   # 'linux', 'darwin', 'win32', etc.
sys.exit(0)           # terminate the program with exit code 0

json — Codificación y decodificación JSON

import json

data = {"name": "Alice", "age": 30, "active": True}

# Python → JSON string
json_string = json.dumps(data, indent=2)
print(json_string)

# JSON string → Python
parsed = json.loads(json_string)
print(parsed["name"])   # Alice

Consulta Python JSON para lectura y escritura basada en archivos.

collections — Estructuras de datos especializadas

from collections import Counter, defaultdict

# Count occurrences
words = ["apple", "banana", "apple", "cherry", "banana", "apple"]
counts = Counter(words)
print(counts)              # Counter({'apple': 3, 'banana': 2, 'cherry': 1})
print(counts.most_common(2))  # [('apple', 3), ('banana', 2)]

# Dict with default values
scores = defaultdict(int)
scores["Alice"] += 10
scores["Bob"] += 5
print(dict(scores))   # {'Alice': 10, 'Bob': 5}

Consulta Python Collections Module para namedtuple, deque y OrderedDict.

Crear tu propio módulo

Estructura básica

Los módulos funcionan mejor cuando hacen una sola cosa bien. Una buena regla general: si un grupo de funciones comparten un tema, colócalas en su propio archivo.

# mathutils.py

def clamp(value, minimum, maximum):
    """Restrict value to the range [minimum, maximum]."""
    return max(minimum, min(value, maximum))

def average(numbers):
    """Return the arithmetic mean of a list of numbers."""
    if not numbers:
        raise ValueError("Cannot average an empty list")
    return sum(numbers) / len(numbers)

def is_prime(n):
    """Return True if n is a prime number."""
    if n < 2:
        return False
    for i in range(2, int(n ** 0.5) + 1):
        if n % i == 0:
            return False
    return True

# main.py
from mathutils import clamp, average, is_prime

print(clamp(15, 0, 10))          # 10
print(average([2, 4, 6, 8]))     # 5.0
print(is_prime(17))              # True

Docstrings en módulos

Agrega una docstring a nivel de módulo al comienzo del archivo. Herramientas como help() y los generadores de documentación la utilizan.

"""
mathutils.py — Utility functions for common mathematical operations.

Functions:
    clamp(value, minimum, maximum) -> number
    average(numbers) -> float
    is_prime(n) -> bool
"""

Variables de módulo: __all__

__all__ es una lista de nombres que deben exportarse cuando alguien hace from module import *. También sirve como documentación sobre la API pública del módulo.

# mathutils.py
__all__ = ["clamp", "average", "is_prime"]

def _helper():   # leading underscore marks it as private
    pass

Recargar un módulo

Python almacena en caché los módulos importados en sys.modules. Importar el mismo módulo dos veces no lo vuelve a ejecutar — Python devuelve la versión en caché. Durante el desarrollo interactivo o la depuración puedes forzar una recarga:

import importlib
import greetings

importlib.reload(greetings)

Esto se necesita principalmente en sesiones REPL o cuadernos Jupyter después de editar un archivo de módulo.

Errores comunes

Importaciones circulares

Si module_a importa module_b y module_b importa module_a, se produce una importación circular. Python puede manejar algunas importaciones circulares, pero son confusas y a menudo indican un problema de diseño. La solución suele ser reestructurar el código — mover la lógica compartida a un tercer módulo, o retrasar la importación al interior de una función.

Sobreescribir un módulo de la biblioteca estándar

Si nombras tu archivo math.py, random.py o json.py, eclipsarás el módulo de la biblioteca estándar y romperás cualquier código que lo importe. Usa nombres específicos y descriptivos para tus propios módulos.

# BAD: naming your file math.py shadows the stdlib
# GOOD: name it mathutils.py or geometry.py

ImportError y ModuleNotFoundError

ModuleNotFoundError (una subclase de ImportError) significa que Python no pudo encontrar el módulo en ningún lugar de sys.path. Causas comunes:

• Un error tipográfico en el nombre del módulo
• El módulo no está instalado (pip install <package-name>)
• El archivo del módulo está en un directorio que no está en sys.path

try:
    import nonexistent_module
except ModuleNotFoundError as e:
    print(f"Import failed: {e}")
    # Import failed: No module named 'nonexistent_module'

Módulos vs. Paquetes

Un módulo es un único archivo .py. Un paquete es un directorio que contiene múltiples módulos y un archivo __init__.py. Los paquetes permiten construir bibliotecas más grandes con una estructura jerárquica. Consulta Python Packages para la explicación completa.

Módulos de terceros populares

Más allá de la biblioteca estándar, el ecosistema Python en PyPI tiene cientos de miles de paquetes. Instálalos con pip.

Práctica