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/python*X.Y*/site-packages"              | "/usr/local/lib/python*X.Y*/site-packages"         | (1)     |
+-------------------+-------------------------------------------------------+----------------------------------------------------+---------+
| Unix (no puro)    | "*exec-prefix*/lib/python*X.Y*/site-packages"         | "/usr/local/lib/python*X.Y*/site-packages"         | (1)     |
+-------------------+-------------------------------------------------------+----------------------------------------------------+---------+
| Windows           | "*prefix*\Lib\site-packages"                          | "C:\Python*XY*\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/python*X.Y*/site-packages"                  |
+-----------------+-------------------------------------------------------------+
| scripts         | "*userbase*/bin"                                            |
+-----------------+-------------------------------------------------------------+
| dato            | "*userbase*"                                                |
+-----------------+-------------------------------------------------------------+
| Cabeceras C     | "*userbase*/include/python*X.Y**abiflags*/*distname*"       |
+-----------------+-------------------------------------------------------------+

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

+-----------------+-------------------------------------------------------------+
| Tipo de archivo | Directorio de instalación                                   |
|=================|=============================================================|
| módulos         | "*userbase*\Python*XY*\site-packages"                       |
+-----------------+-------------------------------------------------------------+
| scripts         | "*userbase*\Python*XY*\Scripts"                             |
+-----------------+-------------------------------------------------------------+
| dato            | "*userbase*"                                                |
+-----------------+-------------------------------------------------------------+
| Cabeceras C     | "*userbase*\Python*XY*\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/python*X.Y*/site-packages"                   |
+-------------------+------------------------------------------------------------+
| extensión de      | "*exec-prefix*/lib/python*X.Y*/site-packages"              |
| módulos           |                                                            |
+-------------------+------------------------------------------------------------+
| scripts           | "*prefix*/bin"                                             |
+-------------------+------------------------------------------------------------+
| dato              | "*prefix*"                                                 |
+-------------------+------------------------------------------------------------+
| Cabeceras C       | "*prefix*/include/python*X.Y**abiflags*/*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        | Ubicación y nombre de archivo                              | Notas   |
| archivo        |                                                            |         |
|================|============================================================|=========|
| sistema        | "*prefix*/lib/python*ver*/distutils/distutils.cfg"         | (1)     |
+----------------+------------------------------------------------------------+---------+
| personal       | "$HOME/.pydistutils.cfg"                                   | (2)     |
+----------------+------------------------------------------------------------+---------+
| local          | "setup.cfg"                                                | (3)     |
+----------------+------------------------------------------------------------+---------+

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

+----------------+---------------------------------------------------+---------+
| Tipo de        | Ubicación y nombre de archivo                     | Notas   |
| archivo        |                                                   |         |
|================|===================================================|=========|
| 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/fi
les/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".
