La opción de línea de comando -m permite ejecutar un módulo como si fuera un programa. Cuando se ejecuta así un módulo que está dentro de un paquete, las importaciones relativas no funcionaban correctamente. Las importaciones relativas permiten a un módulo importar otros módulos dentro de un paquete usando rutas relativas, lo que permite cambiar la ubicación de todo el paquete a otra rama del sistema de directorio sin problemas.

Este error se ha corregido en Python 2.6 añadiendo un atributo __package__ a los módulos. Si este atributo está definido en el módulo, las importaciones relativas se realizarán en relación a su valor, en vez de al valor del atributo __name__.

Los importadores definidos según la PEP 302 pueden definir el atributo __package__ como crean necesario. El módulo runpy, que implementa la opción -m ya lo hace, de modo que si tenías módulos que actuaban también como programas y hacían uso de la importación relativa, ahora funcionan. Este cambio no implica, por lo tanto, ningún problema para la migración de nuestro código.

Importaciones relativas

Para ampliar un poco el tema de las importaciones relativas, añado un extracto del PEP-328 (Imports: Multi-Line and Absolute/Relative).

Después de una interesante y amplia discusión, se ha aceptado que los imports relativos usarán puntos como prefijos para indicar los niveles de anidamiento. Un único punto indica que es un import relativo, y se refiere al nivel actual. Dos o más puntos indican padres y demás ascendientes del nivel actual, indicando cada nivel con un punto. Por ejemplo, si tuviéramos la siguiente estructura en nuestro paquete (con perdón):

package/
    __init__.py
    subpackage1/
        __init__.py
        moduleX.py
        moduleY.py
    subpackage2/
        __init__.py
        moduleZ.py
    moduleA.py

Y suponiendo que el fichero actual es moduleX.py o subpackage1/__init__.py, los siguientes ejemplos de importación relativa son válidos:

from .moduleY import spam
from .moduleY import spam as ham
from . import moduleY
from ..subpackage1 import moduleY
from ..subpackage2.moduleZ import eggs
from ..moduleA import foo
from ...package import bar
from ...sys import path

Obsérvese que, aunque el último ejemplo es válido, está claramente desaconsejado (Guido lo definió como "chaladura").

Las importaciones relativas siempre deben usar la forma from X import; la forma import X siempre es absoluta. También debe quedar claro que se puede seguir haciendo importaciones absolutas con la primera forma, solo hay que excluir los puntos prefijos.

En la versión anterior, Python 2.5, se añadió la sentencia with como una capacidad opcional, por lo que debíamos activarla explícitamente con una directiva from __future__ import. En esta nueva versión viene activada por defecto. La única incompatibilidad con nuestro código sería que tuviéramos definida alguna variable/función/clase/loquesea con el nombre with (Mala idea, por cierto). Si fuera este el caso, renombrando la variable resolveríamos el problema. Cualquier IDE moderno nos permitirá cambiar el nombre de la variable, aunque aparezca en varios ficheros.

Por lo demás, la explicación de qué es y para qué sirve esta nueva sentencia es idéntica a la que se se dio en su día cuando se introdujo esta capacidad en Python 2.5. Podemos, por tanto, consultar esta detallada explicación de la sentencia with en Python.

La documentación original de Python se preparó usando LaTeX, y llevaba así desde sus inicios, en 1989. Por entonces la documentación se preparaba para ser impresa, más que para ser vista en pantalla. Una de las principales virtudes de LaTeX es su capacidad para generar una salida impresa atractiva, a la vez que resultaba relativamente fácil de escribir, una vez que se aprendían las reglas elementales.

LaTeX es todavía una de las mejores opciones para preparar textos impresos, pero el entorno de herramientas de los desarrolladores ha cambiado. Ahora es más frecuente usar el navegador, en vez de imprimir toda la documentación de una vez. Es por ello que Html se ha convertido en el principal formato de salida.

Desgraciadamente, convertir LaTeX a Html ha demostrado ser un asunto farragoso, y Fred L. Drake Jr., que lleva bastante tiempo como editor de la documentación, perdía mucho tiempo en la conversión. De vez en cuando la gente sugería pasarse a SGML o XML, pero una conversión correcta implicaba también un trabajo considerable que, por una razón u otra, nunca se llevó a cabo.

Durante el ciclo de desarrollo de la versión 2.6, Georg Brandl trabajó arduamente en preparar un nuevo sistema de documentación, llamado sphinx, y disponible en http://sphinx.pocoo.org/ El punto fuerte de Sphinx es la generación de código HTML moderno y atractivo. La salida impresa sigue siendo posible, mediante conversión a LaTeX. El formato de entrada es reStructuredText, que es un formato de marcado, con posiblidad de definir nuevas extensiones y directivas, y ampliamente usado en la comunidad Python. Sphinx es un proyecto con existencia independiente, y ha sido usado para escribir la documentación de, por ahora, casi dos docenas de proyectos diferentes.