Los módulos y paquetes son conceptos clave para organizar código en Python. Un módulo es un archivo que cnotiene definiciones y sentencias, permitiendo la reutilización de funcionalidades. A medida que el código crece, los módulos se multiplican, lo que puede dificultar su mantenimiento. Aquí es donde entran los paquetes: directorios especiales que agrupan módulos relacionados, mejorando la estructura y escalabilidad del proyecto.

Un paquete se define como cualquier carpeta que incluya un archivo __init__.py. Este archivo puede estar vacío o contener código de inicialización. Su propósito principal es indicar a Python que el directorio debe tratarse como un paquete, permitiendo la importación jerárquica de módulos.

Considere la siguiente estructura de ejemplo:

mi_proyecto
    ├── __init__.py
    ├── api
        ├── __init__.py
        ├── politica.py
        └── versiones.py
    ├── comando
        ├── __init__.py
        └── gestionar.py
    └── base_datos
        ├── __init__.py
        └── modelos.py

Para importar un módulo específico, como politica.py, se pueden usar varias técnicas. Con la sentencia import, se debe especificar la ruta completa:

import mi_proyecto.api.politica
mi_proyecto.api.politica.obtener()

Esto puede ser verboso, por lo que se recomienda usar alias con as:

import mi_proyecto.api.politica as pol
pol.obtener()

Si se intenta importar solo el paquete raíz y luego acceder al módulo, Python no lo cargará automáticamente. Por ejemplo:

import mi_proyecto
mi_proyecto.api.politica.obtener()  # Esto fallará, ya que politica no se importa implícitamente

Una alternativa es usar from para importaciones más directas:

from mi_proyecto.api import politica
politica.obtener()

Para importar todos los módulos de un subpaquete, se debe configurar el archivo __init__.py corespondiente. Por ejemplo, en mi_proyecto/api/__init__.py:

from . import politica
from . import versiones

Luego, en un archivo externo como prueba.py, se puede importar el paquete completo:

import mi_proyecto
mi_proyecto.api.politica.obtener()  # Ahora funciona

El mecanismo de importación actúa como una cadena de delegación: al importar mi_proyecto, Python ejecuta su __init__.py, que a su vez importa subpaquetes, propagando la carga hasta los módulos individuales.

Un error común ocurre al intentar importar módulos entre archivos dentro del mismo paquete. Por ejemplo, si en politica.py se usa import versiones, funcionará localmente, pero al ejecuatr desde prueba.py podría fallar porque Python busca en las rutas del sistema. Para solucionarlo, se puede ajustar sys.path dinámicamente:

import os
import sys
sys.path.insert(0, os.path.dirname(__file__))

Para importar todos los módulos de un paquete con from ... import *, se debe definir __all__ en __init__.py o importar explícitamente cada módulo. Por ejemplo, en mi_proyecto/comando/__init__.py:

__all__ = ["gestionar"]
# o alternativamente:
from . import gestionar

Luego, en prueba.py:

from mi_proyecto.comando import *
gestionar.ejecutar()

Las rutas de importación pueden ser absolutas o relativas. Una ruta absoluta parte del paquete raíz, como from mi_proyecto.comando import gestionar. Una ruta relativa usa puntos para navegar la jerarquía: . indica el directorio actual, y .. el padre. Por ejemplo, desde mi_proyecto/api/versiones.py se puede importar gestionar así:

# Ruta absoluta:
from mi_proyecto.comando import gestionar
gestionar.iniciar()

# Ruta relativa:
from ..comando import gestionar
gestionar.iniciar()

Es importante probar las importaciones relativas desde archivos en el mismo nivel que el paquete raíz. En Python 3, los paquetes sin __init__.py se consideran paquetes de namespace y no generan errores, pero se recomienda incluirlo para compatibilidad.