¿Cómo funcionan los módulos, las importaciones y los paquetes?

Question

Accepted Answer

Un **módulo** es un único archivo `.py`; un **paquete** es un directorio de módulos. Las **importaciones** te permiten usar código de otros módulos, organizando un programa en piezas reutilizables.

## Módulos e importación

```python
# math_utils.py — a module
def add(a, b): return a + b
PI = 3.14159
```

```python
# main.py — different ways to import
import math_utils                  # import the whole module
math_utils.add(2, 3)               # access via the module name

from math_utils import add, PI     # import specific names
add(2, 3)                          # use directly

from math_utils import add as plus # import with an alias
import numpy as np                 # common aliasing convention
```

## Paquetes: directorios de módulos

```text
mypackage/
  __init__.py        ← marks it as a package (can be empty)
  module_a.py
  subpackage/
    __init__.py
    module_b.py
```

```python
from mypackage.module_a import something
from mypackage.subpackage.module_b import other
```

El archivo `__init__.py` marca un directorio como un paquete (y puede ejecutar código de inicialización del paquete o definir qué expone `from package import *`).

## El modismo `if __name__ == "__main__"`

```python
def main():
    print("running as a script")

if __name__ == "__main__":   # True only when run directly, not when imported
    main()
```

Esto permite que un archivo actúe a la vez como módulo importable *y* como script ejecutable: el código que está debajo se ejecuta solo cuando el archivo se ejecuta directamente (`python file.py`), no cuando se importa. Un modismo casi universal de Python.

## Dónde busca Python los módulos

```python
import sys
sys.path   # the list of directories Python searches for imports
# includes: the current directory, installed packages (site-packages), stdlib
```

## Biblioteca estándar y de terceros

```python
import os, json, datetime    # standard library — "batteries included"
import requests              # third-party — installed via pip from PyPI
```

## Por qué es importante

Los módulos y paquetes son la forma de organizar el código Python en unidades reutilizables y mantenibles en lugar de un único archivo gigante: fundamental para cualquier proyecto no trivial.

Comprender los estilos de importación, la estructura de paquetes (`__init__.py`), el modismo `if __name__ == "__main__"` (doble comportamiento script/módulo) y cómo encuentra Python los módulos (`sys.path`) es esencial para estructurar proyectos, reutilizar código y usar la vasta biblioteca estándar y el ecosistema de PyPI.

Los errores de importación y la confusión de estructura son obstáculos iniciales comunes que este conocimiento resuelve.

Módulos e importación

Paquetes: directorios de módulos

El modismo if __name__ == "__main__"

Dónde busca Python los módulos

Biblioteca estándar y de terceros

Por qué es importante

El modismo `if name == "main"`