Calificar nombres en módulos y paquetes anidados (package.subpackage.module.name)

Cuando un proyecto crece más allá de unos pocos archivos, los módulos se agrupan en paquetes (packages), que son directorios de módulos, y los paquetes pueden contener subpaquetes. Para llegar a un objeto en lo profundo de ese árbol usas una ruta con puntos que refleja la estructura de directorios. Para un archivo extra/good/best/sigma.py que define una función funS(), el nombre totalmente calificado es extra.good.best.sigma.funS. Cada punto baja un nivel: paquete, subpaquete, sub-subpaquete, módulo y, por último, el objeto dentro del módulo.

Cuánto de esa ruta debes escribir depende de cómo importaste. Con import extra.good.best.sigma, Python enlaza solo el nombre de nivel superior extra en tu namespace, y siempre debes escribir la ruta completa: extra.good.best.sigma.funS(). Esto sorprende a muchos, pero es coherente: la sentencia import garantiza que cada paquete a lo largo de la ruta se carga y se adjunta como atributo de su padre, así que la cadena de búsquedas de atributos funciona a partir de extra.

Un alias lo acorta: import extra.good.best.sigma as sig enlaza sig directamente al módulo, así que llamas sig.funS(). La forma from te permite detenerte en cualquier nivel. from extra.good.best import sigma enlaza sigma, así que escribes sigma.funS(); from extra.good.best.sigma import funS enlaza la función misma, así que escribes funS(). Ten en cuenta que en la forma simple import a.b.c el último elemento debe ser un módulo o paquete, no una función; import extra.good.best.sigma.funS falla con ModuleNotFoundError porque funS no es un módulo.

# Árbol de directorios (cada directorio de paquete tiene __init__.py):
# extra/
#     good/
#         best/
#             sigma.py   -> def funS(): return 'sigma'

import extra.good.best.sigma
print(extra.good.best.sigma.funS())

from extra.good.best.sigma import funS
print(funS())

import extra.good.best.sigma as sig
print(sig.funS())

Para que esto funcione, el directorio de nivel superior, aquí extra, debe poder encontrarse: tiene que estar dentro de alguna de las carpetas listadas en sys.path, como la carpeta que contiene tu script principal. No agregas las carpetas internas a sys.path; Python recorre el árbol hacia abajo usando el nombre con puntos. Tradicionalmente cada directorio contiene un archivo __init__.py que lo marca como paquete regular, y ese archivo se ejecuta cuando el paquete se importa por primera vez.

Un hábito útil al leer código del examen es anotar primero el árbol de directorios y luego comprobar que cada nombre con puntos coincida exactamente con él, incluida la ortografía y el nivel que contiene la función. Muchas respuestas incorrectas usan una ruta que se salta un nivel o ponen el nombre de la función donde debería ir un módulo.

Términos clave

Package (paquete)

Un directorio de módulos (y posiblemente subpaquetes) que Python puede importar por nombre.

Subpackage (subpaquete)

Un paquete anidado dentro de otro, al que se llega con un punto, como extra.good.

Fully qualified name (nombre totalmente calificado)

La ruta completa con puntos desde el paquete superior hasta un objeto, como extra.good.best.sigma.funS.

Comprueba lo que sabes