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

If you download a module source distribution, you can tell pretty quickly if it was packaged and distributed in the standard way, i.e. using the Distutils. First, the distribution’s name and version number will be featured prominently in the name of the downloaded archive, e.g. foo-1.0.tar.gz or widget-0.9.7.zip. Next, the archive will unpack into a similarly named directory: foo-1.0 or widget-0.9.7. Additionally, the distribution will contain a setup script setup.py, and a file named README.txt or possibly just README, which should explain that building and installing the module distribution is a simple matter of running one command from a 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

Los archivos se instalarán en subdirectorios de site.USER_BASE (escrito como userbase en adelante). Este esquema instala módulos Python puros y módulos de extensión en la misma ubicación (también conocida como site.USER_SITE). Estos son los valores para UNIX, incluido 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=~

Para hacer que Python encuentre las distribuciones instaladas con este esquema, puede que tenga que modificar la ruta de búsqueda de Python o editar sitecustomize (ver site) para llamar site.addsitedir() o 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:option:!–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 prefijo, en lugar de hacerlo en prefijo en sí. Esto es casi tan fácil como personalizar el directorio de instalación de script—sólo hay que recordar que hay dos tipos de módulos de los que preocuparse, Python y módulos de extensión, que pueden ser convenientemente controlados por una opción:

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

El directorio de instalación especificado es relativo a -prefijo. Por supuesto, también tiene que asegurarse de que este directorio está en la ruta de búsqueda del módulo de Python, por ejemplo, colocando un archivo .pth en un directorio de sitio (consulte site). Consulte la sección Modificando el Camino de Búsqueda de Python para averiguar 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/')

Sin embargo, si reinstala la misma versión principal de Python (tal vez al actualizar de 2.2 a 2.2.2, por ejemplo) la versión de archivo sobrescribirá el site.py. Debería recordar que se modificó y guardar una copia antes de realizar la instalación.

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)

On all platforms, the «personal» file can be temporarily disabled by passing the --no-user-cfg option.

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 prefijo/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. En Unix, si la variable de entorno HOME no está definida, el directorio de inicio del usuario se determinará con la función getpwuid() del módulo estándar pwd. Esto se realiza mediante la función os.path.expanduser() utilizada por 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.