2.1 Un ejemplo simple

El guion de instalación suele ser bastante simple, aunque, por estar escrito en Python, no hay límites arbitrarios sobre lo que se puede hacer con él.¹Si sólo quieres distribuir un módulo denominado foo, contenido en un fichero foo.py, tu guion de instalación puede reducirse a esto:

from distutils.core import setup
setup (name = "foo",
       version = "1.0",
       py_modules = ["foo"])

Observaciones:

la mayoría de la información que se proporciona a las Distutils va en forma de argumentos clave a la función setup()
dichos argumentos pertenecen a dos categorías: meta-datos del paquete (nombre, número de versión) e información sobre lo contenido en el paquete (una lista de módulos en Python puro, en este caso)
los módulos se especifican por nombre de módulo, no nombre de fichero (esto se aplica también a los paquetes y extensiones)
se recomienda que proporciones más meta-datos, en particular tu nombre, dirección electrónica de correo y un URL del proyecto (consulta la sección si quieres ver un ejemplo)

Para crear una distribución de código fuente para este módulo, crearías un guion de instalación, setup.py, que contuviera el código anterior, y lo ejecutarías:

python setup.py sdist

lo que crearía un fichero comprimido (por ejemplo, un fichero tar de Unix, un zip en Windows) que contendría tu guion de instalación, setup.py y tu módulo, foo.py. El fichero se llamaría Foo-1.0.tar.gz (o .zip) y se desempaquetaría en un directorio Foo-1.0.

Si un usuario/a desea instalar tu módulo foo module, sólo tiene que descargar Foo-1.0.tar.gz (o .zip), desempaquetarlo y, desde el directorio Foo-1.0, ejecutar

python setup.py install

lo que finalmente copiaría foo.py al directorio adecuado para módulos de terceros en su instalación de Python.

Este sencillo ejemplo muestra algunos conceptos fundamentales de las Distutils: Primero, tanto los desarrolladores como los instaladores tienen la misma interfaz de usuario básica, el guion de instalación. La diferencia radica en qué órdenes de Distutils utilizan: la orden sdist es utilizada casi exclusivamente por desarrolladores de módulos, mientras que la orden install es más común para los instaladores (aunque la mayoría de los desarrolladores querrán instalar su propio código ocasionalmente).

Si deseas ponerles las cosas realmente fáciles a tus usuarios, puedes crear una o más distribuciones compiladas para ellos. Por ejemplo, si estás funcionando en una máquina Windows y quieres facilitarles las cosas a otros usuarios de Windows, puedes crear un instalador ejecutable (el tipo de distribución compilada más adecuado para esta plataforma) con la orden bdist_wininst. Por ejemplo:

python setup.py bdist_wininst

creará un instalador ejecutable, Foo-1.0.win32.exe, en el directorio actual.

** no implementado aún ** (Otro modo de crear instaladores ejecutables para Windows es con la orden bdist_wise, que hace uso de Wise, el generador de instaladores que se utiliza en el propio Python, para generar el instalador. Los instaladores basados en Wise son más adecuados para aplicaciones de peso, que necesitan las funciones de un instalador ``de verdad''. bdist_wininst crea un fichero zip autoextraíble con una interfaz de usuario mínima, suficiente para colecciones de módulos pequeñas y medianas. Necesitarás tener instalada la versión XXX de Wise en tu sistema para que la orden bdist_wise funcione. Está disponible en http://foo/bar/baz.)

En la actualidad (Distutils 0.9.2), el único formato de distribución compilado es el RPM, implementado por la orden bdist_rpm. Por ejemplo, la siguiente orden creará un fichero RPM llamado Foo-1.0.noarch.rpm:

python setup.py bdist_rpm

(utiliza la orden rpm, por lo que ha de ser ejecutado en un sistema basado en RPM, como Red Hat Linux, SuSE Linux o Mandrake Linux).

Se puede consultar qué formatos de distribución están disponibles en cualquier momento ejecutando

python setup.py bdist --help-formats

Notas al pie

... él.¹: Pero modérate respecto a poner operaciones arbitrariamente costosas en el guion de instalación. Al contrario de los guiones del tipo de autoconf [N. del T.: autoconf es la herramienta de GNU de configuración multiplataforma], es posible que el guion de instalación se ejecute varias veces en el curso de la compilación e instalación de la distribución del módulo. Si es necesario que incluyas pasos potencialmente costosos en proceso dentro de la cadena de Distutils, consulta la sección sobre la extensión de las Distutils.

Ver Sobre este documento... para obtener información sobre sugerencias.