Módulos y Paquetes en Python: Organiza tu Código como un Profesional

¿Qué son los Módulos?

Un módulo es simplemente un archivo .py que contiene código Python (funciones, clases, variables). Los módulos permiten organizar y reutilizar código.

Crear un Módulo Simple

Crea un archivo llamado matematicas.py:

# matematicas.py

def suma(a, b):
    return a + b

def resta(a, b):
    return a - b

def multiplicar(a, b):
    return a * b

def dividir(a, b):
    if b == 0:
        return "No se puede dividir por cero"
    return a / b

PI = 3.14159

print("Módulo matemáticas cargado")

Importar Módulos

Método 1: Import Simple

# main.py
import matematicas

resultado = matematicas.suma(10, 5)
print(resultado)  # 15

print(matematicas.PI)  # 3.14159

Método 2: Import con Alias

import matematicas as mat

resultado = mat.suma(10, 5)
print(resultado)  # 15

Método 3: From Import

# Importar funciones específicas
from matematicas import suma, resta

resultado = suma(10, 5)  # No necesita matematicas.
print(resultado)  # 15

Método 4: Import Todo (no recomendado)

from matematicas import *

# Acceso directo a todo
resultado = suma(10, 5)
print(PI)

Módulos de la Biblioteca Estándar

# math - Funciones matemáticas
import math

print(math.sqrt(16))      # 4.0
print(math.pi)            # 3.141592653589793
print(math.ceil(4.3))     # 5
print(math.floor(4.7))    # 4

# random - Números aleatorios
import random

print(random.randint(1, 10))        # Número entre 1 y 10
print(random.choice(['a', 'b', 'c']))  # Elemento aleatorio
print(random.random())              # Float entre 0 y 1

# datetime - Fechas y horas
from datetime import datetime, timedelta

ahora = datetime.now()
print(ahora)
print(ahora.year, ahora.month, ahora.day)

mañana = ahora + timedelta(days=1)
print(mañana)

# os - Sistema operativo
import os

print(os.getcwd())  # Directorio actual
print(os.listdir('.'))  # Lista archivos

# sys - Sistema Python
import sys

print(sys.version)  # Versión de Python
print(sys.path)     # Rutas de módulos

Atributos Especiales de Módulos

# matematicas.py
def suma(a, b):
    return a + b

# Variable especial
__name__  # Nombre del módulo
__file__  # Ruta del archivo

if __name__ == "__main__":
    # Este código solo se ejecuta si el archivo se ejecuta directamente
    print("Ejecutando como script principal")
    print(suma(5, 3))
else:
    print(f"Módulo {__name__} importado")

¿Qué son los Paquetes?

Un paquete es una colección de módulos organizados en directorios. Cada paquete debe contener un archivo __init__.py.

Estructura de un Paquete

mi_proyecto/
│
├── main.py
│
└── utilidades/
    ├── __init__.py
    ├── matematicas.py
    ├── texto.py
    └── fechas.py

Crear el Paquete

utilidades/__init__.py

# Este archivo puede estar vacío o contener código de inicialización
print("Paquete utilidades cargado")

# Definir qué se exporta con from utilidades import *
__all__ = ['matematicas', 'texto']

utilidades/matematicas.py

def suma(a, b):
    return a + b

def resta(a, b):
    return a - b

utilidades/texto.py

def mayusculas(texto):
    return texto.upper()

def minusculas(texto):
    return texto.lower()

def contar_palabras(texto):
    return len(texto.split())

utilidades/fechas.py

from datetime import datetime

def fecha_actual():
    return datetime.now().strftime("%Y-%m-%d")

def hora_actual():
    return datetime.now().strftime("%H:%M:%S")

Importar desde Paquetes

# main.py

# Método 1: Importar módulo completo
import utilidades.matematicas
resultado = utilidades.matematicas.suma(10, 5)

# Método 2: From import
from utilidades import matematicas
resultado = matematicas.suma(10, 5)

# Método 3: Importar función específica
from utilidades.matematicas import suma
resultado = suma(10, 5)

# Método 4: Importar de múltiples módulos
from utilidades.matematicas import suma
from utilidades.texto import mayusculas
from utilidades.fechas import fecha_actual

print(suma(10, 5))
print(mayusculas("hola"))
print(fecha_actual())

Paquetes Anidados

mi_proyecto/
│
├── main.py
│
└── aplicacion/
    ├── __init__.py
    ├── core/
    │   ├── __init__.py
    │   └── procesador.py
    └── utilidades/
        ├── __init__.py
        └── helpers.py

# Importar desde paquetes anidados
from aplicacion.core.procesador import procesar_datos
from aplicacion.utilidades.helpers import validar_entrada

Imports Relativos

Dentro de un paquete, puedes usar imports relativos:

# aplicacion/core/procesador.py

# Import absoluto
from aplicacion.utilidades.helpers import validar_entrada

# Import relativo
from ..utilidades.helpers import validar_entrada  # Subir un nivel
from .modulo_local import funcion  # Mismo nivel

Recargar Módulos

import matematicas
import importlib

# Usar el módulo
resultado = matematicas.suma(5, 3)

# Si modificas matematicas.py y quieres recargar
importlib.reload(matematicas)

# Ahora usa la versión actualizada
resultado = matematicas.suma(5, 3)

Buscar Ubicación de Módulos

import sys
import os

# Ver rutas donde Python busca módulos
for path in sys.path:
    print(path)

# Agregar ruta personalizada
sys.path.append('/ruta/a/mis/modulos')

# Ver ubicación de un módulo
import matematicas
print(matematicas.__file__)

Crear un Módulo Instalable

Estructura para distribuir tu paquete:

mi_paquete/
├── setup.py
├── README.md
├── LICENSE
└── mi_paquete/
    ├── __init__.py
    ├── modulo1.py
    └── modulo2.py

setup.py

from setuptools import setup, find_packages

setup(
    name='mi_paquete',
    version='1.0.0',
    author='Tu Nombre',
    author_email='tu@email.com',
    description='Descripción del paquete',
    packages=find_packages(),
    install_requires=[
        'requests',
        'numpy',
    ],
    python_requires='>=3.7',
)

Instalar tu paquete localmente:

pip install -e .

Ejemplo Práctico: Aplicación Modular

Estructura de una aplicación web simple:

mi_app/
├── main.py
├── config.py
└── app/
    ├── __init__.py
    ├── modelos/
    │   ├── __init__.py
    │   └── usuario.py
    ├── controladores/
    │   ├── __init__.py
    │   └── auth.py
    └── utilidades/
        ├── __init__.py
        ├── validadores.py
        └── helpers.py

config.py

DEBUG = True
DATABASE = 'sqlite:///app.db'
SECRET_KEY = 'clave-secreta-aqui'

app/modelos/usuario.py

class Usuario:
    def __init__(self, nombre, email):
        self.nombre = nombre
        self.email = email
    
    def __str__(self):
        return f"Usuario: {self.nombre} ({self.email})"

app/utilidades/validadores.py

import re

def validar_email(email):
    patron = r'^[\w\.-]+@[\w\.-]+\.\w+$'
    return re.match(patron, email) is not None

def validar_password(password):
    return len(password) >= 8

app/controladores/auth.py

from ..modelos.usuario import Usuario
from ..utilidades.validadores import validar_email, validar_password

def registrar_usuario(nombre, email, password):
    if not validar_email(email):
        return "Email inválido"
    
    if not validar_password(password):
        return "Password debe tener al menos 8 caracteres"
    
    usuario = Usuario(nombre, email)
    return f"Usuario {usuario.nombre} registrado exitosamente"

main.py

import config
from app.controladores.auth import registrar_usuario

if config.DEBUG:
    print("Modo DEBUG activado")

resultado = registrar_usuario("Ana", "ana@email.com", "password123")
print(resultado)

Módulos Útiles de la Biblioteca Estándar

# json - Trabajar con JSON
import json

datos = {"nombre": "Ana", "edad": 25}
json_string = json.dumps(datos)
print(json_string)

# re - Expresiones regulares
import re

patron = r'\d+'
numeros = re.findall(patron, "Tengo 5 perros y 3 gatos")
print(numeros)  # ['5', '3']

# collections - Estructuras de datos adicionales
from collections import Counter, defaultdict

palabras = ['python', 'java', 'python', 'c++', 'python']
contador = Counter(palabras)
print(contador)  # Counter({'python': 3, 'java': 1, 'c++': 1})

# itertools - Herramientas de iteración
from itertools import combinations, permutations

lista = [1, 2, 3]
print(list(combinations(lista, 2)))  # [(1, 2), (1, 3), (2, 3)]

# pathlib - Manejo de rutas (moderno)
from pathlib import Path

ruta = Path('carpeta/archivo.txt')
print(ruta.exists())
print(ruta.parent)
print(ruta.name)

Buenas Prácticas

• Un módulo, una responsabilidad: Cada módulo debe tener un propósito claro
• Nombres descriptivos: Usa nombres claros para módulos y paquetes
• __init__.py: Úsalo para inicialización y definir API pública
• Documenta: Usa docstrings en módulos, clases y funciones
• Evita imports circulares: Diseña bien la estructura para evitarlos
• if __name__ == "__main__": Usa esto para código de prueba

Conclusión

Los módulos y paquetes son fundamentales para organizar código Python de manera profesional. Permiten crear aplicaciones escalables, mantenibles y reutilizables. Dominar esta estructura es esencial para proyectos de cualquier tamaño.