# Instalación de módulos de Python (versión antigua)

Autor:

  Greg Ward

Nota

Todo el paquete `distutils` ha quedado obsoleto y se eliminará en Python 3.12. Esta documentación se conserva solo como referencia y se eliminará con el paquete. Consulte la entrada Qué hay de nuevo para obtener más información.

Ver también

Instalando módulos de Python

  La documentación actualizada de instalación de módulos. Para el uso regular de Python, es casi seguro que desee ese documento en lugar de este.

Nota

Este documento se conserva únicamente hasta que la documentación de `setuptools` en https://setuptools.readthedocs.io/en/latest/setuptools.html cubra de forma independiente toda la información relevante que se incluye actualmente aquí.

Nota

Esta guía solamente cubre las herramientas básicas para construir y distribuir extensiones que se proporcionan como parte de esta versión de Python. Herramientas de terceros ofrecen alternativas más sencillas y seguras . Consulte la sección de recomendaciones en la Guía de Usuario de Empaquetamiento de Python para mayor detalle.

## Introducción

En Python 2.0, la API `distutils` fue el primer módulo en ser agregado a la biblioteca estándar. Esto proporcionó a los mantenedores de distribución de Linux una forma estándar de convertir proyectos de Python en paquetes de distribución de Linux, y a los administradores de sistemas con una forma estándar de instalarlos directamente en los sistemas de destino.

En los muchos años transcurridos desde el lanzamiento de Python 2.0, el acoplamiento estrecho del sistema de compilación y el instalador del paquete al ciclo de lanzamiento del lenguaje ha sido un problema, ahora se recomienda que los proyectos utilicen el instalador del paquete `pip` y el sistema de compilación `setuptools`, en lugar de utilizar directamente `distutils`.

Ver Instalando módulos de Python y Distribuir módulos de Python para mayor detalles.

Esta documentación heredada se conservará hasta que se esté seguro que la documentación de `setuptools` cubre todo lo necesario.

### Distutils basado la distribuciones de la fuente

Si descarga la distribución fuente de un módulo, puede saber con bastante rapidez si se empaquetó y distribuyó de la manera estándar, es decir, utilizando Distutils. En primer lugar, el nombre de la distribución y el número de versión aparecerán destacados en el nombre del archivo descargado, p. ej. `foo-1.0.tar.gz` o `widget-0.9.7.zip`. A continuación, el archivo se desempaquetará en un directorio con un nombre similar: `foo-1.0` o `widget-0.9.7`. Además, la distribución contendrá un script de configuración `setup.py` y un archivo llamado `README.txt` o posiblemente solo `README`, lo que debería explicar que construir e instalar la distribución del módulo es una simple cuestión de ejecutar un comando desde una terminal:

    python setup.py install

Para Windows, este comando debería ejecutarse desde la linea de comandos.(Start ‣ Accessories):

    setup.py install

Si todo es correcto, entonces ya sabe cómo construir e instalar los módulos que acaba de descargar: ejecute el comando anterior. Al menos que se necesite instalar cosas de una manera no estándar o personalizar el proceso de compilación, no necesitará hacer esto de manera manual. Más bien, el comando anterior es todo lo que necesita obtener de este manual.

## Construcción e instalación estándar

Como se describe en la sección Distutils basado la distribuciones de la fuente, construir e instalar una distribución de módulos usando Distutils suele ser un comando simple para ejecutar desde un terminal:

    python setup.py install

### Variaciones de acuerdo a la plataforma

Siempre debe ejecutar el comando de configuración desde el directorio raíz de distribución, por ejemplo el subdirectorio de nivel superior en el que se descomprime la distribución fuente del módulo. Por ejemplo, si acaba de descargar una distribución fuente del módulo `foo-1.0.tar.gz` en un sistema Unix, lo normal es:

    gunzip -c foo-1.0.tar.gz | tar xf -    # unpacks into directory foo-1.0
    cd foo-1.0
    python setup.py install

En Windows, probablemente se descargaría `foo-1.0.zip`. Si descargó el archivo en `C:Temp`, se descomprimirá en `C:Tempfoo-1.0`; puede usar un manipulador de archivo con una interfaz gráfica de usuario (como WinZip) o una herramienta de línea de comandos (como unzip o pkunzip) para descomprimir el archivo. Luego, abra una ventana de símbolo del sistema y ejecute:

    cd c:\Temp\foo-1.0
    python setup.py install

### Dividiendo el trabajo

La ejecución de `setup.py install` compila e instala todos los módulos en una sola ejecución. Si prefiere trabajar de forma incremental, especialmente útil si desea personalizar el proceso de compilación, o si las cosas van mal, puede usar el script de configuración para hacer una cosa a la vez. Esto es particularmente útil cuando la compilación y la instalación serán realizadas por diferentes usuarios, por ejemplo, es posible que desee compilar una distribución de módulos y entregarla a un administrador del sistema para su instalación (o hágalo usted mismo, con privilegios de superusuario )

Por ejemplo, puede compilar todo en un solo paso y luego instalarlo en un segundo paso, invocando el script de configuración dos veces:

    python setup.py build
    python setup.py install

Si hace esto, notará que al ejecutar el comando install primero ejecuta el comando build, que — en este caso — rápidamente se da cuenta de que no tiene nada que hacer, ya que todo en la carpeta `build` está actualizado.

Es posible que no necesite esta capacidad de desglosar las cosas si todo lo que hace es instalar módulos descargados de la red, pero es muy útil para tareas más avanzadas. Si llega a distribuir sus propios módulos y extensiones de Python, ejecutará muchos comandos Distutils individuales por su cuenta.

### Como funciona la construcción

Como se indicó anteriormente, el comando build es responsable de colocar los archivos para instalar en un directorio de compilación. Por defecto, esto es `build` bajo la raíz de distribución; si está demasiado preocupado por la velocidad, o si desea mantener el árbol de origen prístino, puede cambiar el directorio de compilación con la opción `--build-base`. Por ejemplo:

    python setup.py build --build-base=/path/to/pybuild/foo-1.0

(O puede hacer esto permanentemente con una directiva en su sistema o archivo de configuración personal de Distutils; ver la sección Archivos de Configuración de Distutils.) Normalmente, esto no es necesario.

El diseño predeterminado para el árbol de compilación es el siguiente:

    --- build/ --- lib/
    or
    --- build/ --- lib.<plat>/
                   temp.<plat>/

donde `<plat>` se expande a una breve descripción de la plataforma actual de SO/hardware y la versión de Python. La primera forma, con solo un directorio `lib`, se usa para «distribuciones de módulos puros»— es decir, distribuciones de módulos que incluyen solo módulos puros de Python. Si la distribución de un módulo contiene alguna extensión (módulos escritos en C/C ++), se utiliza la segunda forma, con dos directorios `<plat>`. En ese caso, el directorio `temp.plat` contiene archivos temporales generados por el proceso de compilación/enlace que en realidad no se instalan. En cualquier caso, el directorio `lib` (o `lib.plat`) contiene todos los módulos de Python (Python puro y extensiones) que se instalarán.

En el futuro, se agregarán más directorios para manejar scripts de Python, documentación, ejecutables binarios y todo lo que sea necesario para manejar el trabajo de instalación de módulos y aplicaciones de Python.

### Como funciona la instalación

Después de que se ejecute el comando build (ya sea que lo ejecute explícitamente, o el comando install lo hace por usted), el trabajo del comando install es relativamente simple: todo lo que tiene hacer es copiar todo lo que se encuentra en el directorio `build/lib` (o `build/lib.plat`) en el directorio de instalación elegido.

Si no se elige un directorio de instalación —es decir, si solo ejecuta `setup.py install`-– entonces el comando install se instala en la ubicación estándar para módulos Python de terceros . Esta ubicación varía según la plataforma y la forma en la que se compiló/instaló Python. En Unix (y macOS, que también está basado en Unix), depende de si la distribución del módulo que se está instalando es Python puro o contiene extensiones («no puro»):

Plataforma | Lugar de instalación estándar | Valor por defecto | Notas
--- | --- | --- | ---
Unix (puro) | `prefix/lib/pythonX.Y/site-packages` | `/usr/local/lib/pythonX.Y/site-packages` | (1)
Unix (no puro) | `exec-prefix/lib/pythonX.Y/site-packages` | `/usr/local/lib/pythonX.Y/site-packages` | (1)
Windows | `prefix\Lib\site-packages` | `C:\PythonXY\Lib\site-packages` | (2)

Notas:

1. La mayoría de las distribuciones de Linux incluyen Python como una parte estándar del sistema, por lo que `prefix` y `exec-prefix` generalmente son ambos: file: /usr en Linux. Si construye Python usted mismo en Linux (o en cualquier sistema similar a Unix), el valor predeterminado `prefix` y `exec-prefix` son `/usr /local`.

2. El directorio de instalación predeterminado en Windows era `C:\ Archivos de programa \Python` en Python 1.6a1, 1.5.2 y versiones anteriores.

`prefix` y `exec-prefix` representan los directorios en los que está instalado Python y donde encuentra sus bibliotecas en tiempo de ejecución. Siempre son los mismos en Windows, y muy a menudo los mismos en Unix y macOS. Puede averiguar qué utiliza el Python que tiene instalado para `prefix` y `exec-prefix` ejecutando Python en modo interactivo y escribiendo algunos comandos simples. En Unix, simplemente escriba `python` en el indicador de comandos de la shell. En Windows, elija Inicio->Programas->Python X.Y->Python (línea de comando). Una vez que se inicia el intérprete, escriba el código Python en el indicador. Por ejemplo, si en mi sistema Linux, escribo las tres declaraciones de Python que se muestran a continuación, y con ello obtengo el resultado como se muestra a continuación, averiguo mi `prefix` y `exec-prefix`:

    Python 2.4 (#26, Aug  7 2004, 17:19:02)
    Type "help", "copyright", "credits" or "license" for more information.
    >>> import sys
    >>> sys.prefix
    '/usr'
    >>> sys.exec_prefix
    '/usr'

En este documento se utilizan algunos otros marcadores de posición: `X.Y` representa la versión de Python, por ejemplo, `3.2`; `abiflags` será reemplazado por el valor de `sys.abiflags` o la cadena vacía para plataformas que no definen flags ABI; `distname` será reemplazado por el nombre de la distribución del módulo que se está instalando. Los puntos y las mayúsculas son importantes en los las direcciones; por ejemplo, un valor que usa `python3.2` en UNIX generalmente usará `Python32` en Windows.

Si no desea instalar módulos en la ubicación estándar, o si no tiene permiso para escribir allí, debe leer acerca de las instalaciones alternativas en la sección Instalación alternativa. Si desea personalizar más sus directorios de instalación, consulte la sección Instalación personalizada en instalaciones personalizadas.

## Instalación alternativa

A menudo, es necesario o deseable instalar módulos en una ubicación distinta de la ubicación estándar para módulos Python de terceros. Por ejemplo, en un sistema Unix, es posible que no tenga permiso para escribir en el directorio estándar de módulos de terceros. O quizás desee probar un módulo antes de convertirlo en una parte estándar de su instalación local de Python. Esto es especialmente cierto cuando se actualiza una distribución ya presente: desea asegurarse de que su base de scripts existente todavía funcione con la nueva versión antes de actualizar realmente.

El comando Distutils install está diseñado para hacer que la instalación de distribuciones de módulos en una ubicación alternativa sea simple e indolora. La idea básica es que proporcione un directorio base para la instalación, y el comando install selecciona un conjunto de directorios (llamado esquema de instalación) en este directorio base en el que instalar los archivos. Los detalles difieren entre plataformas, por lo tanto, lea la sección que corresponda a usted.

Tenga en cuenta que los diversos esquemas de instalación alternativos son mutuamente excluyentes: se le puede pasar `--user`, o `--home`, o `--prefix` y `--exec-prefix`, o `--install-base` y `--install-platbase`, pero no puede mezclar desde estos grupos.

### Instalación alternativa: el esquema de usuario

This scheme is designed to be the most convenient solution for users that don’t have write permission to the global site-packages directory or don’t want to install into it. It is enabled with a simple option:

    python setup.py install --user

Files will be installed into subdirectories of `site.USER_BASE` (written as `userbase` hereafter). This scheme installs pure Python modules and extension modules in the same location (also known as `site.USER_SITE`). Here are the values for UNIX, including macOS:

Tipo de archivo | Directorio de instalación
--- | ---
módulos | `userbase/lib/pythonX.Y/site-packages`
scripts | `userbase/bin`
dato | `userbase`
Cabeceras C | `userbase/include/pythonX.Yabiflags/distname`

Y aquí están los valores usados en Windows:

Tipo de archivo | Directorio de instalación
--- | ---
módulos | `userbase\PythonXY\site-packages`
scripts | `userbase\PythonXY\Scripts`
dato | `userbase`
Cabeceras C | `userbase\PythonXY\Include{distname}`

La ventaja de usar este esquema en comparación con los otros descritos a continuación es que el directorio de paquetes de sitio del usuario está en condiciones normales siempre incluido en `sys.path` (ver `site` para más información), que significa que no hay que realizar ningún paso adicional después de ejecutar el script `setup.py` para finalizar la instalación.

El comando build_ext también tiene una opción `--user` para agregar `userbase/include` a la ruta de búsqueda del compilador para archivos de encabezado y `userbase/lib` a la ruta de búsqueda del compilador para bibliotecas, así como a la ruta de búsqueda de tiempo de ejecución para bibliotecas C compartidas (rpath).

### Instalación alternativa: el esquema de la casa

La idea detrás del «esquema de inicio» es crear y mantener una reserva personal de módulos Python. El nombre de este esquema se deriva de la idea de un directorio «de inicio» en Unix, ya que no es inusual que un usuario de Unix haga que su directorio de inicio tenga un diseño similar a `/usr/` o `/usr/local/`. Cualquiera puede utilizar este esquema, independientemente del sistema operativo para el que se esté instalando.

Instalar un nuevo módulo de distribución es tan simple como:

    python setup.py install --home=<dir>

dónde se puede suministrar cualquier directorio que desee para la opción `-inicio`. En Unix, los mecanógrafos perezosos pueden simplemente escribir una tilde (`~`); el comando install expandirá esto a su directorio de inicio:

    python setup.py install --home=~

To make Python find the distributions installed with this scheme, you may have to modify Python’s search path or edit `sitecustomize` (see `site`) to call `site.addsitedir()` or edit `sys.path`.

La opción `-inicio` define el directorio base de instalación. Los archivos se instalan en los siguientes directorios bajo la base de instalación de la siguiente manera:

Tipo de archivo | Directorio de instalación
--- | ---
módulos | `home/lib/python`
scripts | `home/bin`
dato | `home`
Cabeceras C | `home/include/python/distname`

(Reemplace mentalmente las barras diagonales con barras diagonales inversas si está en Windows.)

### Instalación alternativa: Unix (el esquema de prefijo)

El «esquema de prefijo» es útil cuando desea utilizar una instalación de Python para realizar la compilación / instalación (por ejemplo, para ejecutar el script de configuración), pero instalar módulos en el directorio de módulos de terceros de una instalación de Python diferente (o algo que parece una instalación diferente de Python). Si esto suena un poco inusual, es — es por eso que el usuario y los esquemas de inicio vienen antes. Sin embargo, hay al menos dos casos conocidos en los que el esquema de prefijo será útil.

Primero, considere que muchas distribuciones de Linux ponen Python en `/usr`, en lugar del tradicional `/usr/local`. Esto es completamente apropiado, ya que en esos casos Python es parte del «sistema» en lugar de un complemento local. Sin embargo, si está instalando módulos de Python desde la fuente, probablemente desee que entren en `/usr/local/lib/python2.X` en lugar de `/usr/lib/python2.X`. Esto se puede hacer con

    /usr/bin/python setup.py install --prefix=/usr/local

Otra posibilidad es un sistema de archivos de red donde el nombre utilizado para escribir en un directorio remoto es diferente del nombre utilizado para leerlo: por ejemplo, el intérprete de Python al que se accede como `/usr/local/bin/python` podría buscar módulos en `/usr/local/lib/python2.X`, pero esos módulos tendrían que instalarse en, por ejemplo, `/mnt/@servidor/export/lib/python2.X`. Esto podría hacerse con

    /usr/local/bin/python setup.py install --prefix=/mnt/@server/export

En cualquier caso, la opción `--prefix` define la base de instalación, y la opción `--exec-prefix` define la base de instalación específica de la plataforma, que se utiliza para archivos específicos de la plataforma . (Actualmente, esto solo significa distribuciones de módulos no puras, pero podría expandirse a bibliotecas C, ejecutables binarios, etc.) Si `--exec-prefix` no se proporciona, el valor predeterminado es `--prefix`. Los archivos se instalan de la siguiente manera:

Tipo de archivo | Directorio de instalación
--- | ---
Modules de Python | `prefix/lib/pythonX.Y/site-packages`
extensión de módulos | `exec-prefix/lib/pythonX.Y/site-packages`
scripts | `prefix/bin`
dato | `prefix`
Cabeceras C | `prefix/include/pythonX.Yabiflags/distname`

No es necesario que `--prefix` o `--exec-prefix` realmente apunte a una instalación alternativa de Python; Si los directorios enumerados anteriormente no existen, se crean en el momento de la instalación.

Por cierto, la verdadera razón por la que el esquema de prefijos es importante es simplemente que una instalación estándar de Unix usa el esquema de prefijos, pero con `--prefix` y `--exec-prefix` suministrado por Python como `sys.prefix` y `sys.exec_prefix`. Por lo tanto, puede pensar que nunca usará el esquema de prefijo, pero cada vez que ejecuta `python setup.py install` sin ninguna otra opción, lo está usando.

Tenga en cuenta que la instalación de extensiones en una instalación alternativa de Python no tiene efecto sobre cómo se construyen esas extensiones: en particular, los archivos de encabezado de Python (`Python.h` y amigos) instalados con el intérprete de Python utilizado para ejecutar el script de configuración ser utilizado en la compilación de extensiones. Es su responsabilidad asegurarse de que el intérprete utilizado para ejecutar las extensiones instaladas de esta manera sea compatible con el intérprete utilizado para construirlas. La mejor manera de hacer esto es asegurarse de que los dos intérpretes sean la misma versión de Python (posiblemente compilaciones diferentes, o posiblemente copias de la misma compilación). (Por supuesto, si su `--prefix` y `-- exec-prefix` ni siquiera apuntan a una instalación alternativa de Python, esto es irrelevante).

### Instalación alternativa: Windows (el esquema de prefijo)

Windows no tiene el concepto del directorio de inicio de un usuario, y dado que la instalación estándar de Python en Windows es más simple que en Unix, la opción `--prefix` se ha usado tradicionalmente para instalar paquetes adicionales en ubicaciones separadas en Windows.

    python setup.py install --prefix="\Temp\Python"

instalar los módulos en el directorio `\Temp\Python` en el disco actual.

La base de instalación se define mediante la opción `--prefix`; la opción `--exec-prefix` no es compatible con Windows, lo que significa que los módulos Python puros y los módulos de extensión están instalados en la misma ubicación. Los archivos se instalan de la siguiente manera:

Tipo de archivo | Directorio de instalación
--- | ---
módulos | `prefix\Lib\site-packages`
scripts | `prefix\Scripts`
dato | `prefix`
Cabeceras C | `prefix\Include{distname}`

## Instalación personalizada

A veces, los esquemas de instalación alternativos descritos en la sección Instalación alternativa simplemente no hacen lo que quieres. Es posible que desee ajustar solo uno o dos directorios mientras mantiene todo bajo el mismo directorio base, o puede que desee redefinir completamente el esquema de instalación. En cualquier caso, está creando un esquema de instalación personalizado.

Para crear un esquema de instalación personalizado, comience con uno de los esquemas alternativos y anule algunos de los directorios de instalación utilizados para los distintos tipos de archivos, utilizando estas opciones:

Tipo de archivo | Sobreescribir opciones
--- | ---
Modules de Python | `--install-purelib`
extensión de módulos | `--install-platlib`
todos los módulos | `--install-lib`
scripts | `--install-scripts`
dato | `--install-data`
Cabeceras C | `--install-headers`

Estas opciones de invalidación pueden ser relativas, absolutas o definidas explícitamente en términos de uno de los directorios base de instalación. (Hay dos directorios base de instalación, y normalmente son los mismos— sólo difieren cuando se utiliza el «esquema de prefijo» de Unix y se proporcionan diferentes opciones de `--prefijo` y `--exec-prefix`; usando `--install-lib` anulará los valores calculados o dados para `install-purelib` y `--install-platlib`, y se recomienda para esquemas que no hacen diferencia entre Python y extensión.

Por ejemplo, supongamos que se está instalando una distribución de módulos en su directorio de inicio en Unix—pero se desea que los scripts vayan en `/scripts` en lugar de `/bin`. Como es de esperar, puede invalidar este directorio con la opción `--install-scripts`; en este caso, tiene más sentido proporcionar una ruta relativa, que se interpretará en relación con el directorio base de la instalación (su directorio principal, en este caso):

    python setup.py install --home=~ --install-scripts=scripts

Otro ejemplo de Unix: supongamos que la instalación de Python se creó e instaló con un prefijo de `/usr/local/python`, por lo que bajo una instalación estándar los scripts terminarán en `/usr/local/python/bin`. Si los desea en `/usr/local/bin` en su lugar, debe proporcionar este directorio absoluto para la opción `--install-scripts`:

    python setup.py install --install-scripts=/usr/local/bin

(Esto realiza una instalación utilizando el «esquema de prefijo», donde el prefijo es lo que su intérprete de Python se instaló con— `/usr/local/python` en este caso.)

Si mantiene Python en Windows, es posible que desee que los módulos de terceros vivan en un subdirectorio de `prefix`, en lugar de directamente en `prefix`. Esto es casi tan fácil como personalizar el directorio de instalación del script; solo debe recordar que hay dos tipos de módulos de los que preocuparse, Python y los módulos de extensión, que pueden controlarse convenientemente mediante una opción:

    python setup.py install --install-lib=Site

El directorio de instalación especificado es relativo a `prefix`. Por supuesto, también debe asegurarse de que este directorio esté en la ruta de búsqueda de módulos de Python, por ejemplo, colocando un archivo `.pth` en un directorio del sitio (consulte `site`). Consulte la sección Modificando el Camino de Búsqueda de Python para saber cómo modificar la ruta de búsqueda de Python.

Si desea definir un esquema de instalación completo, sólo tiene que proporcionar todas las opciones del directorio de instalación. La forma recomendada de hacerlo es proporcionar rutas relativas; por ejemplo, si desea mantener todos los archivos relacionados con el módulo python en `python` en su directorio principal y desea un directorio independiente para cada plataforma desde la que utilice el directorio principal, puede definir el siguiente esquema de instalación:

    python setup.py install --home=~ \
                            --install-purelib=python/lib \
                            --install-platlib=python/lib.$PLAT \
                            --install-scripts=python/scripts
                            --install-data=python/data

o, equivalente,

    python setup.py install --home=~/python \
                            --install-purelib=lib \
                            --install-platlib='lib.$PLAT' \
                            --install-scripts=scripts
                            --install-data=data

`$PLAT` no es (necesariamente) una variable de entorno—se expandirá el Distutils a medida que analiza las opciones de línea de comandos, tal como lo hace al analizar los archivos de configuración.

Obviamente, especificar el esquema de instalación completo cada vez que instala un nuevo módulo de distribución sería muy tedioso. Por lo tanto, puede poner estas opciones en su archivo de configuración de Distutils (consulte la sección Archivos de Configuración de Distutils):

    [install]
    install-base=$HOME
    install-purelib=python/lib
    install-platlib=python/lib.$PLAT
    install-scripts=python/scripts
    install-data=python/data

o ,equivalente,

    [install]
    install-base=$HOME/python
    install-purelib=lib
    install-platlib=lib.$PLAT
    install-scripts=scripts
    install-data=data

Tenga en cuenta que estos dos son no equivalentes si proporciona un directorio base de instalación diferente cuando ejecuta el script de configuración. Por ejemplo,

    python setup.py install --install-base=/tmp

instalaría módulos puros en `/tmp/python/lib` en el primer caso, y en `/tmp/lib` en el segundo caso. (Para el segundo caso, probablemente desee proporcionar una base de instalación de `/tmp/python`.)

Probablemente haya notado el uso de `$HOME` y `$ PLAT` en la entrada del archivo de configuración de muestra. Estas son las variables de configuración de Distutils, que tienen un gran parecido con las variables de entorno. De hecho, puede usar variables de entorno en archivos de configuración en plataformas que tienen esa noción, pero los Distutils definen adicionalmente algunas variables adicionales que pueden no estar en su entorno, como `$PLAT`. (Y, por supuesto, en los sistemas que no tienen variables de entorno, como Mac OS 9, las variables de configuración proporcionadas por Distutils son las únicas que puede usar). Consulte la sección Archivos de Configuración de Distutils para detalles.

Nota

Cuando a entorno virtual está activado, cualquier opción que cambie la ruta de instalación será ignorada de todos los archivos de configuración de distutils para evitar la instalación accidental de proyectos fuera del entorno virtual.

### Modificando el Camino de Búsqueda de Python

Cuando el intérprete de Python ejecuta una declaración `import`, busca tanto el código de Python como los módulos de extensión a lo largo de una ruta de búsqueda. Un valor predeterminado para la ruta se configura en el binario de Python cuando se construye el intérprete. Puede determinar la ruta importando el módulo `sys` e imprimiendo el valor de `sys.path`.

    $ python
    Python 2.2 (#11, Oct  3 2002, 13:31:27)
    [GCC 2.96 20000731 (Red Hat Linux 7.3 2.96-112)] on linux2
    Type "help", "copyright", "credits" or "license" for more information.
    >>> import sys
    >>> sys.path
    ['', '/usr/local/lib/python2.3', '/usr/local/lib/python2.3/plat-linux2',
     '/usr/local/lib/python2.3/lib-tk', '/usr/local/lib/python2.3/lib-dynload',
     '/usr/local/lib/python2.3/site-packages']
    >>>

La cadena nula en `sys.path` representa el directorio de trabajo actual.

La convención esperada para los paquetes instalados localmente es ponerlos en el directorio `.../site-packages/`, pero es posible que desee instalar módulos de Python en algún directorio arbitrario. Por ejemplo, su sitio puede tener una convención de mantener todo el software relacionado con el servidor web en `/www`. Los módulos adicionales de Python pueden pertenecer a `/www/python`, y para importarlos, este directorio debe agregarse a `sys.path`. Hay varias formas diferentes de agregar el directorio.

La forma más conveniente es agregar un archivo de configuración de ruta a un directorio que ya está en la ruta de Python, generalmente al directorio `.../site-packages/`. Los archivos de configuración de ruta tienen una extensión de `.pth`, y cada línea debe contener una ruta única que se agregará a `sys.path`. (Debido a que las nuevas rutas se agregan a `sys.path`, los módulos en los directorios agregados no anularán los módulos estándar. Esto significa que no puede usar este mecanismo para instalar versiones fijas de módulos estándar).

Las rutas pueden ser absolutas o relativas, en cuyo caso son relativas al directorio que contiene el archivo `.pth`. Consulte la documentación del módulo `site` para obtener más información.

Una forma un poco menos conveniente es editar el archivo `site.py` en la biblioteca estándar de Python y modificar `sys.path`. `site.py` se importa automáticamente cuando se ejecuta el intérprete de Python, a menos que se proporcione el `-S` para suprimir este comportamiento. Entonces, simplemente puede editar `site.py` y agregarle dos líneas:

    import sys
    sys.path.append('/www/python/')

However, if you reinstall the same minor version of Python (perhaps when upgrading from 2.2 to 2.2.2, for example) `site.py` will be overwritten by the stock version. You’d have to remember that it was modified and save a copy before doing the installation.

Hay dos variables de entorno que pueden modificar `sys.path`. `PYTHONHOME` establece un valor alternativo para el prefijo de la instalación de Python. Por ejemplo, si `PYTHONHOME` está configurado en `/www/python`, la ruta de búsqueda se establecerá en `['', '/www/python/lib/pythonX.Y/', '/www/python/lib/pythonX.Y/plat-linux2', ...]`.

La variable `PYTHONPATH` se puede establecer en una lista de rutas que se agregarán al comienzo de `sys.path`. Por ejemplo, si `PYTHONPATH` está establecido en `/www/python:/opt /py`, la ruta de búsqueda comenzará con `['/www/python', '/opt/py']`. (Tenga en cuenta que los directorios deben existir para poder agregarlos a `sys.path`; el módulo `site` elimina las rutas que no existen).

Finalmente,``sys.path`` es solo una lista normal de Python, por lo que cualquier aplicación de Python puede modificarla agregando o eliminando entradas.

## Archivos de Configuración de Distutils

Como se mencionó anteriormente, puede usar los archivos de configuración de Distutils para registrar las preferencias personales o del sitio para cualquier opción de Distutils. Es decir, cualquier opción para cualquier comando puede almacenarse en uno de dos o tres (según su plataforma) archivos de configuración, que se consultarán antes de analizar la línea de comandos. Esto significa que los archivos de configuración anularán los valores predeterminados, y la línea de comandos a su vez anulará los archivos de configuración. Además, si se aplican varios archivos de configuración, los valores de los archivos «anteriores» se anulan por los archivos «posteriores».

### Ubicación y nombres de los archivos de configuración

Los nombres y las ubicaciones de los archivos de configuración varían ligeramente según las plataformas. En Unix y macOS, los tres archivos de configuración (en el orden en que se procesan) son:

Tipo de archivo | Ubicación y nombre de archivo | Notas
--- | --- | ---
sistema | `prefix/lib/pythonver/distutils/distutils.cfg` | (1)
personal | `$HOME/.pydistutils.cfg` | (2)
local | `setup.cfg` | (3)

Y en Windows, los archivos de configuración son:

Tipo de archivo | Ubicación y nombre de archivo | Notas
--- | --- | ---
sistema | `prefix\Lib\distutils\distutils.cfg` | (4)
personal | `%HOME%\pydistutils.cfg` | (5)
local | `setup.cfg` | (3)

En todas las plataformas, el archivo «personal» se puede desactivar temporalmente pasando la opción `--no-user-cfg`.

Notas:

1. Estrictamente hablando, el archivo de configuración de todo el sistema vive en el directorio donde están instalados los Distutils; bajo Python 1.6 y posterior en Unix, esto es como se muestra. Para Python 1.5.2, Distutils normalmente se instalará en `prefix/lib/python1.5/site-packages/distutils`, por lo que el archivo de configuración del sistema debe colocarse allí en Python 1.5.2.

2. On Unix, if the `HOME` environment variable is not defined, the user’s home directory will be determined with the `getpwuid()` function from the standard `pwd` module. This is done by the `os.path.expanduser()` function used by Distutils.

3. Por ejemplo, en el directorio actual (usualmente la ubicación del script de setup).

4. (Ver nota (1).) En Python 1.6 y posterior, el «prefijo de instalación» por defecto de Python es `C:\Python`, entonces el archivo de configuración de sistema es normalmente `C:\Python\Lib\distutils\distutils.cfg`. En Python 1.5.2, el prefijo por defecto era `C:\Program Files\Python`, y Distutils no eran parte de la biblioteca estándar—entonces el archivo de configuración de sistema debería ser `C:\Program Files\Python\distutils\distutils.cfg` en una instalación estándar de Python 1.5.2 en Windows.

5. En Windows, si la variable de entorno `HOME` no está definida, se probará `USERPROFILE` y luego `HOMEDRIVE` y `HOMEPATH`. Esto se realiza mediante la función `os.path.expanduser()` utilizada por Distutils.

### Archivos de configuración de sintaxis

Todos los archivos de configuración de Distutils tienen la misma sintaxis. Los archivos de configuración se agrupan en secciones. Hay una sección para cada comando de Distutils, más una sección `global` para las opciones globales que afectan a cada comando. Cada sección consta de una opción por línea, especificada como `opción=valor`.

Por ejemplo, el siguiente es un archivo de configuración completo que solo obliga a todos los comandos a ejecutarse silenciosamente de manera predeterminada:

    [global]
    verbose=0

Si se instala como el archivo de configuración del sistema, afectará todo el procesamiento de cualquier distribución del módulo Python por parte de cualquier usuario en el sistema actual. Si se instala como su archivo de configuración personal (en sistemas que los admiten), afectará solo las distribuciones de módulos procesadas por usted. Y si se usa como `setup.cfg` para una distribución de módulo en particular, solo afecta a esa distribución.

Puede anular el directorio «base de compilación» predeterminado y hacer que los comandos build* siempre reconstruyan a la fuerza todos los archivos con lo siguiente:

    [build]
    build-base=blib
    force=1

que corresponde a los argumentos de la línea de comandos

    python setup.py build --build-base=blib --force

excepto que incluir el comando build en la línea de comandos significa que ese comando se ejecutará. Incluir un comando particular en los archivos de configuración no tiene tal implicación; solo significa que si se ejecuta el comando, se aplicarán las opciones en el archivo de configuración. (O si se ejecutan otros comandos que derivan valores de él, utilizarán los valores en el archivo de configuración).

Puede encontrar la lista completa de opciones para cualquier comando usando la opción `--help`, por ejemplo:

    python setup.py build --help

y puede encontrar la lista completa de opciones globales usando `-help` sin un comando:

    python setup.py --help

Ver también la sección «Referencia» del manual de «Distribución de Módulos de Python».

## Construyendo Extensiones: Ayudas y trucos

Siempre que sea posible, los Distutils intentan utilizar la información de configuración disponible por el intérprete de Python utilizado para ejecutar el script `setup.py`. Por ejemplo, los mismos indicadores de compilador y enlazador utilizados para compilar Python también se usarán para compilar extensiones. Por lo general, esto funcionará bien, pero en situaciones complicadas esto puede ser inapropiado. Esta sección discute cómo anular el comportamiento habitual de Distutils.

### Ajustar las flags del compilador/enlazador

La compilación de una extensión de Python escrita en C o C ++ a veces requerirá especificar marcas personalizadas para el compilador y el enlazador para usar una biblioteca particular o producir un tipo especial de código de objeto. Esto es especialmente cierto si la extensión no ha sido probada en su plataforma, o si está intentando compilar Python de forma cruzada.

En el caso más general, el autor de la extensión podría haber previsto que compilar las extensiones sería complicado, y proporcionó un archivo `Setup` para que lo edite. Es probable que esto solo se haga si la distribución del módulo contiene muchos módulos de extensión separados, o si a menudo requieren conjuntos elaborados de indicadores de compilación para funcionar.

Un archivo `Setup`, si está presente, es parseado para obtener una lista de extensiones para compilar. Cada línea en un archivo `Setup` describe un solo módulo. Las líneas tienen la siguiente estructura

    module ... [sourcefile ...] [cpparg ...] [library ...]

Examinemos cada uno de los campos a su vez.

- módulo es el nombre del módulo de extensión que se creará, y debe ser un identificador válido de Python. No puede simplemente cambiar esto para cambiar el nombre de un módulo (también serían necesarias ediciones en el código fuente), por lo que esto debería dejarse solo.

- archivo fuente es cualquier cosa que probablemente sea un archivo de código fuente, al menos a juzgar por el nombre del archivo. Se supone que los nombres de archivo que terminan en `.c` están escritos en C, los nombres de archivo que terminan en `.C` , `.cc`, y `.c++` son de C ++, y se supone que los nombres de archivo que terminan en `.m` o `.mm` están en el Objetivo C.

- cpparg es un argumento para el preprocesador C, y es cualquier cosa que comience con `-I`, `-D`, `-U` or `-C`.

- biblioteca es todo aquello que termina con `.a` or empieza con `-l` o `-L`.

Si una plataforma en particular requiere una biblioteca especial en su plataforma, puede agregarla editando el archivo `Setup` y ejecutando `python setup.py build`. Por ejemplo, si el módulo definido por la línea

    foo foomodule.c

debe estar vinculado con la biblioteca matemática `libm.a` en su plataforma, simplemente agregue `-lm` a la línea

    foo foomodule.c -lm

Los conmutadores arbitrarios destinados al compilador o al enlazador se pueden suministrar con `-Xcompiler` arg y `-Xlinker` arg options:

    foo foomodule.c -Xcompiler -o32 -Xlinker -shared -lm

La siguiente opción después de `-Xcompiler` y `-Xlinker` se agregará a la línea de comando adecuada, por lo que en el ejemplo anterior se pasará al compilador la opción `-O32` , y se pasará al enlazador `-shared`. Si una opción del compilador requiere un argumento, deberá proporcionar varias opciones `-Xcompiler`; por ejemplo, para pasar `-x c++` el `Setup` debería contener `-Xcompiler -x -Xcompiler c++`.

Los indicadores del compilador también se pueden suministrar configurando la variable de entorno `CFLAGS`. Si se establece, el contenido de `CFLAGS` se agregará a los indicadores del compilador especificados en el archivo `Configuración`.

### Usando un compilador que no sea de Microsoft en Windows

#### Borland/CodeGear C++

Esta subsección describe los pasos necesarios para utilizar Distutils con el compilador Borland C++ versión 5.5. Primero, debe saber que el formato de archivo de objetos de Borland (OMF) es diferente del formato utilizado por la versión de Python que puede descargar del sitio web de Python o ActiveState. (Python está construido con Microsoft Visual C++, que usa COFF como formato de archivo de objeto). Por esta razón, debe convertir la biblioteca de Python `python25.lib` al formato Borland. Puede hacer esto de la siguiente manera:

    coff2omf python25.lib python25_bcpp.lib

El programa `coff2omf` viene con el compilador Borland. El archivo `python25.lib` está en el directorio `Libs` de su instalación de Python. Si su extensión usa otras bibliotecas (zlib, …), también debe convertirlas.

Los archivos convertidos tienen que residir en los mismos directorios que las bibliotecas normales.

¿Cómo logra Distutils usar estas bibliotecas con sus nombres cambiados? Si la extensión necesita una biblioteca (por ejemplo `foo`) Distutils verifica primero si encuentra una biblioteca con el sufijo `_bcpp` (por ejemplo `foo_bcpp.lib`) y luego usa esta biblioteca. En el caso de que no encuentre una biblioteca tan especial, usa el nombre predeterminado (`foo.lib`.) [1]

Para permitir que Distutils compile su extensión con Borland C++, ahora debe escribir:

    python setup.py build --compiler=bcpp

Si desea utilizar el compilador Borland C++ como predeterminado, puede especificar esto en su archivo de configuración personal o de todo el sistema para Distutils (consulte la sección Archivos de Configuración de Distutils.)

Ver también

Compilador *C++ Builder*

  Información sobre el compilador gratuito de C++ de Borland, incluidos enlaces a las páginas de descarga.

Crear Extensiones de Python usando el Compilador libre de Borland

  Documento que describe cómo usar el compilador C ++ de línea de comandos gratuito de Borland para construir Python.

#### GNU C / Cygwin / MinGW

Esta sección describe los pasos necesarios para usar Distutils con los compiladores GNU C/C++ en sus distribuciones Cygwin y MinGW. [2] Para un intérprete de Python que fue construido con Cygwin, todo debería funcionar sin ninguno de estos pasos.

No todas las extensiones se pueden construir con MinGW o Cygwin, pero muchas sí. Las extensiones que probablemente no funcionen son aquellas que usan C++ o dependen de las extensiones de Microsoft Visual C.

Para dejar que Distutils compile tu extensión con Cygwin tienes que escribir:

    python setup.py build --compiler=cygwin

y para Cygwin en modo no-cygwin [3] o para tipo MinGW:

    python setup.py build --compiler=mingw32

Si desea utilizar cualquiera de estas opciones/compiladores por defecto, debería considerar escribirlo en su archivo de configuración personal o de todo el sistema para Distutils (consulte la sección Archivos de Configuración de Distutils).

##### Versiones antiguas de Python y MinGW

Las siguientes instrucciones solo se aplican si está utilizando una versión de Python inferior a 2.4.1 con un MinGW inferior a 3.0.0 (con binutils-2.13.90-20030111-1).

Estos compiladores requieren algunas bibliotecas especiales. Esta tarea es más compleja que para C++ de Borland, porque no hay un programa para convertir la biblioteca. Primero debe crear una lista de símbolos que exporta la DLL de Python. (Puede encontrar un buen programa para esta tarea en https://sourceforge.net/projects/mingw/files/MinGW/Extension/pexports/).

    pexports python25.dll >python25.def

La ubicación de un instalado `python25.dll` dependerá de las opciones de instalación y la versión y el idioma de Windows. En una instalación «solo para mí», aparecerá en la raíz del directorio de instalación. En una instalación compartida, se ubicará en el directorio del sistema.

Luego puede crear a partir de esta información una biblioteca de importación para gcc.

    /cygwin/bin/dlltool --dllname python25.dll --def python25.def --output-lib libpython25.a

La biblioteca resultante debe colocarse en el mismo directorio que `python25.lib`. (Debe ser el directorio `libs` en el directorio de instalación de Python.)

Si su extensión usa otras bibliotecas (zlib, …), es posible que también deba convertirlas. Los archivos convertidos tienen que residir en los mismos directorios que las bibliotecas normales.

Ver también

Building Python modules on MS Windows platform with MinGW

  Información sobre la creación de las bibliotecas necesarias para el entorno MinGW.

Notas al pie

[1]

Esto también significa que puede reemplazar todas las bibliotecas COFF existentes con bibliotecas OMF del mismo nombre.

[2]

Diríjase a https://www.sourceware.org/cygwin/ para mayor información

[3]

Entonces no tiene disponible la emulación POSIX, pero tampoco necesita `cygwin1.dll`.