Manejo de la dualidad de módulos en Python: script y módulo

Cuando trabajas con archivos Python, es común querer que un mismo archivo funcione tanto como módulo importable desde otro archivo como script ejecutable directamente desde la terminal. Esta dualidad puede generar comportamientos inesperados si no se controla correctamente, y la solución está en una línea que encontrarás en prácticamente todos los proyectos profesionales de Python.

¿Cuál es el problema de la dualidad entre módulos y scripts?

Un archivo .py en Python puede ejecutarse de dos formas. La primera es como módulo, donde defines funciones y las importas desde otro archivo. Por ejemplo, un archivo utils.py con funciones que se importan desde main.py [0:18]. La segunda es como script, ejecutándolo directamente desde la terminal con el comando python seguido de la ruta del archivo [0:40].

El conflicto aparece cuando importas un archivo que contiene código ejecutable fuera de funciones. Al hacer import main desde un archivo example.py, todo el código de main.py se ejecuta automáticamente [2:07]. Esto significa que si main.py tiene un input() o cualquier lógica directa, se disparará sin que lo desees.

¿Cómo evitar que un módulo se ejecute al importarlo?

La primera estrategia es encapsular el código dentro de una función. En lugar de tener instrucciones sueltas en el archivo, creas una función llamada run() y colocas toda la lógica dentro de su scope o alcance [3:08].

python def run(): country = input('Escribe un país: ') # lógica del programa

De esta manera, al importar el módulo desde otro archivo, el código no se ejecuta automáticamente. Solo se ejecuta cuando llamas explícitamente a main.run() [3:30].

• El código queda protegido dentro de la función.
• La ejecución se controla de forma explícita.
• Las variables definidas fuera de la función, como data, siguen siendo accesibles mediante main.data [4:05].

¿Qué hace if name == "main" y por qué es esencial?

Al encapsular todo en una función run(), resuelves el problema de la importación. Pero ahora pierdes la capacidad de ejecutar el archivo directamente como script, porque nadie llama a run() cuando lo ejecutas desde la terminal [4:50].

Aquí entra el patrón más importante de Python para manejar esta dualidad. Se trata de un condicional que evalúa la variable especial __name__ [5:30]:

python if name == "main": run()

Esta variable __name__ es una propiedad interna que Python asigna automáticamente a cada archivo. Cuando ejecutas un archivo directamente desde la terminal, Python le asigna el valor "__main__". Cuando el archivo es importado desde otro módulo, __name__ toma el nombre del archivo.

¿Cómo funciona en la práctica este condicional?

El comportamiento resultante es exactamente la dualidad controlada que necesitas:

• Si ejecutas python app/main.py desde la terminal, el condicional se cumple y run() se ejecuta [6:22].
• Si importas main desde example.py, el bloque if no se ejecuta, y solo corres lo que llames explícitamente como main.run() [6:05].

python data = [1, 2, 3]

def run(): country = input('Escribe un país: ') # lógica del programa

if name == "main": run()

Sin este if, perderías la posibilidad de que el archivo funcione como script independiente [6:42]. Con él, tienes un archivo que sirve como módulo reutilizable y como punto de entrada directo.

¿Por qué la modularización importa en proyectos Python?

La modularización consiste en organizar el código en archivos separados con responsabilidades claras. Cada archivo .py es considerado un módulo, incluso main.py [1:20]. Esto permite reutilizar funciones sin duplicar código.

El patrón if __name__ == "__main__" es una pregunta frecuente en entrevistas y una práctica estándar en proyectos profesionales [6:55]. Dominarlo te permite escribir código que es tanto importable como ejecutable, algo fundamental cuando tus proyectos crecen y necesitas trabajar con paquetes, el siguiente paso natural en la organización de código Python.

¿Has encontrado errores al importar módulos que se ejecutaban sin querer? Comparte tu experiencia y cómo lo resolviste.