El mundo de la programación en Python

Python: importar módulos con rutas relativas, guía y errores

Bibliotecas externas, API y comunicación
目次

1. Descripción general de la instrucción import y de las importaciones relativas en Python

Al crear programas en Python, se utiliza la instrucción import para reutilizar módulos de forma eficiente. En esta instrucción import, las importaciones relativas son especialmente útiles cuando se manejan dependencias flexibles entre módulos. En este artículo, explicamos cómo usar rutas relativas en la instrucción import de Python y sus ventajas.

¿Qué es una importación relativa?

Una importación relativa es un método para importar otros módulos tomando como referencia la ubicación del módulo actual. Es especialmente útil en proyectos de gran tamaño o en el desarrollo de paquetes con múltiples módulos. Al usar importaciones relativas, las dependencias entre módulos quedan más claras y el mantenimiento del proyecto se facilita. Por ejemplo, supongamos que tenemos la siguiente estructura de directorios.
project/
    ├── main.py
    ├── package/
    │   ├── module_a.py
    │   └── sub_package/
    │       └── module_b.py
Si se desea importar module_a.py desde module_b.py usando una ruta relativa, se escribe lo siguiente.
from ..module_a import some_function
Así, con rutas relativas puedes importar módulos de forma flexible basándote en la jerarquía de directorios.

2. Diferencias entre rutas relativas y absolutas

En Python, la sentencia import tiene dos modalidades: ruta relativa y ruta absoluta. Estas dos difieren en cómo se especifica el módulo que se va a importar.

Importación con ruta absoluta

La importación con ruta absoluta es el método de especificar el módulo a importar empezando desde el directorio raíz del proyecto. Por ejemplo, en un proyecto con una estructura como la siguiente, para importar module_a.py desde main.py usando una ruta absoluta, se escribe así:
from package.module_a import some_function
Este método es útil cuando la estructura global del proyecto es clara y la ubicación de los módulos es consistente.

Importación con ruta relativa

Por otro lado, la importación con ruta relativa importa módulos en función de la ubicación del módulo actual. La importación relativa puede adaptarse con relativa flexibilidad, especialmente cuando cambia la estructura del proyecto. Con ello es posible mantener las dependencias entre módulos y, al mismo tiempo, mejorar la reutilización del código. Por ejemplo, el siguiente código muestra cómo importar un módulo que se encuentra un nivel por encima del módulo actual.
from ..module_a import some_function
La elección entre una u otra depende del tamaño y la complejidad del proyecto; en general, si la ubicación de los módulos es fija conviene la ruta absoluta, y si hay cambios frecuentes, la ruta relativa es más adecuada.
RUNTEQ（ランテック）｜超実戦型エンジニア育成スクール

3. Método de importación mediante rutas relativas

Importar un módulo del mismo directorio

Al importar un módulo que está en el mismo directorio, no se necesita ninguna indicación compleja; basta con especificar el nombre del módulo. Por ejemplo, si module_a.py y module_b.py están en el mismo directorio, se puede importar así.
import module_a
Además, para importar una función o clase específica, se hace de la siguiente manera.
from module_a import some_function

Importar desde un directorio superior

Para importar un módulo que está en un directorio superior, se utiliza .. para subir un nivel y luego se especifica el módulo. Por ejemplo, para importar desde el directorio inmediatamente superior, se escribe así.
from ..module_a import some_function

Importar desde un subdirectorio

Al importar un módulo desde un subdirectorio, se especifican el nombre del directorio y el del módulo separados por puntos. Por ejemplo, se importa un módulo del subdirectorio de la siguiente manera.
from sub_package.module_b import some_function
El uso de rutas relativas tiene la gran ventaja de que el código puede adaptarse con flexibilidad incluso si cambia la estructura de directorios del proyecto.

4. Importación de módulos dentro de un paquete

Python cuenta con el concepto de “paquete” para organizar los módulos. Los paquetes son útiles para manejar varios módulos en conjunto y resultan especialmente útiles en proyectos de gran tamaño. También es posible importar módulos dentro de un paquete empleando rutas relativas.

Estructura del paquete y el archivo __init__.py

Al crear un paquete, es necesario añadir un archivo llamado __init__.py en ese directorio. Este archivo hace que Python reconozca ese directorio como un “paquete”. A modo de ejemplo, consideremos la siguiente estructura de proyecto.
project/
    ├── main.py
    ├── package/
    │   ├── __init__.py
    │   ├── module_a.py
    │   └── sub_package/
    │       ├── __init__.py
    │       └── module_b.py

Importación relativa de módulos dentro de un paquete

Por ejemplo, para importar module_a.py desde module_b.py usando una ruta relativa, se escribe lo siguiente.
from ..module_a import some_function
Este .. indica subir un nivel desde el directorio actual. De este modo, se pueden compartir funciones y clases entre módulos del paquete. Asimismo, al importar con ruta relativa un módulo del mismo paquete, puede especificarse fácilmente usando un punto.
from .module_a import some_function
Con ello, los módulos del proyecto pueden interactuar entre sí de manera sencilla y, aunque cambie la estructura de directorios, no será necesario modificar mucho el código.
RUNTEQ（ランテック）｜超実戦型エンジニア育成スクール

5. Errores frecuentes y sus soluciones

En las importaciones de rutas relativas en Python, pueden producirse algunos errores típicos. En esta sección, explicamos estos errores y sus soluciones.

ImportError: attempted relative import with no known parent package

Este error suele producirse al intentar importar un módulo mediante una ruta relativa. Ocurre especialmente cuando el script se ejecuta directamente. Por ejemplo, el siguiente código puede causar problemas.
from ..module_a import some_function
Este error se produce porque Python no puede reconocer el paquete padre del script. En Python, debe estar claramente establecido que el módulo forma parte de un paquete. Si ejecutas el script directamente, es muy probable que usar rutas relativas provoque errores.

Solución

Para evitar este problema, una forma es configurar explícitamente la ruta de búsqueda de módulos utilizando sys.path. Por ejemplo, añade el directorio padre a la ruta de búsqueda con sys.path.append() como se muestra a continuación.
import sys
sys.path.append('..')
from module_a import some_function
Con esto, Python podrá encontrar el módulo correctamente.

ModuleNotFoundError

Otro error común es ModuleNotFoundError. Se produce cuando no se encuentra el módulo especificado. Al intentar importar un módulo mediante una ruta relativa, esto puede deberse a que la ubicación del módulo es incorrecta o a que sys.path no está configurado correctamente.

Solución

Para resolver este problema, es importante revisar la sentencia de importación y confirmar que el módulo realmente existe. Además, puedes evitar el error especificando explícitamente, mediante sys.path.append(), el directorio donde Python puede encontrar el módulo.

6. Ejemplos prácticos y aplicaciones

Aquí se presentan ejemplos concretos de código que utilizan importaciones mediante rutas relativas. Esto permite ver cómo aprovechar las rutas relativas en proyectos reales.

Ejemplo: Importación desde el directorio padre

Supongamos la siguiente estructura de proyecto.
project/
    ├── main.py
    ├── package/
    │   ├── module_a.py
    │   └── sub_package/
    │       └── module_b.py
El código para importar la función some_function de module_a.py desde module_b.py es el siguiente.
# module_b.py
from ..module_a import some_function

def use_function():
    some_function()
En este código, se usa .. para volver un directorio arriba y se importa la función desde module_a. Este método es útil para compartir funciones y clases entre módulos ubicados en varios directorios.

Ejemplo: Importación de módulos con sys.path

A continuación, se muestra un ejemplo de cómo importar un módulo del directorio padre usando sys.path.append().
# module_b.py
import sys
sys.path.append('..')
from module_a import some_function

def use_function():
    some_function()
Con este método, se añade el directorio padre a sys.path, por lo que Python puede encontrar module_a correctamente. Este enfoque es especialmente útil cuando se ejecutan scripts directamente.

7. Conclusión

En este artículo, explicamos en detalle las importaciones con rutas relativas en la instrucción import de Python. Las importaciones con rutas relativas permiten gestionar de forma flexible las dependencias entre los módulos de un proyecto, por lo que resultan especialmente útiles en proyectos de gran envergadura y en el desarrollo de paquetes. Sin embargo, dado que también pueden ser propensas a errores, es importante realizar una configuración adecuada y usar sys.path. Comprender las ventajas de las importaciones con rutas relativas y aplicarlas en proyectos reales permite una gestión del código más eficiente.
年収訴求