9. Referencia de la API
***********************

Ver también:

  Argumentos nuevos y cambiados de setup.py en setuptools
     El proyecto "setuptools" añade nuevas capacidades a la función
     "setup" y otras API, hace que la API sea coherente en diferentes
     versiones de Python y, por lo tanto, se recomienda usar
     "distutils" directamente.

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í.


9.1. "distutils.core" --- Funcionalidad Core Distutils
======================================================

El módulo "distutils.core" es el único módulo que necesita ser
instalado para utilizar *Distutils*. Proporciona el "setup()" (que es
llamado desde el script de configuración). Indirectamente proporciona
la clase "distutils.dist.Distribution" y la clase
"distutils.cmd.Command".

distutils.core.setup(arguments)

   La función básica *do-everything* hace casi todo lo que podrías
   pedir de un método *Distutils*.

   La función de configuración toma un gran número de argumentos.
   Estos se presentan en la siguiente tabla.

   +----------------------+----------------------------------+---------------------------------------------------------------+
   | nombre del argumento | valor                            | tipo                                                          |
   |======================|==================================|===============================================================|
   | *name*               | El nombre del paquete            | un string                                                     |
   +----------------------+----------------------------------+---------------------------------------------------------------+
   | *version*            | El número de versión del         | un string                                                     |
   |                      | paquete; ver "distutils.version" |                                                               |
   +----------------------+----------------------------------+---------------------------------------------------------------+
   | *description*        | Una sola línea describiendo el   | un string                                                     |
   |                      | paquete                          |                                                               |
   +----------------------+----------------------------------+---------------------------------------------------------------+
   | *long_description*   | Descripción larga del paquete    | un string                                                     |
   +----------------------+----------------------------------+---------------------------------------------------------------+
   | *author*             | El nombre del autor del paquete  | un string                                                     |
   +----------------------+----------------------------------+---------------------------------------------------------------+
   | *author_email*       | La dirección de correo           | un string                                                     |
   |                      | electrónico del autor del        |                                                               |
   |                      | paquete                          |                                                               |
   +----------------------+----------------------------------+---------------------------------------------------------------+
   | *maintainer*         | El nombre del mantenedor actual, | un string                                                     |
   |                      | si es diferente del autor. Ten   |                                                               |
   |                      | en cuenta que si se proporciona  |                                                               |
   |                      | el mantenedor, *distuils* lo     |                                                               |
   |                      | usará como el autor en "PKG-     |                                                               |
   |                      | INFO"                            |                                                               |
   +----------------------+----------------------------------+---------------------------------------------------------------+
   | *maintainer_email*   | La dirección de correo           | un string                                                     |
   |                      | electrónico del mantenedor       |                                                               |
   |                      | actual, si es diferente del      |                                                               |
   |                      | autor                            |                                                               |
   +----------------------+----------------------------------+---------------------------------------------------------------+
   | *url*                | Una URL para el paquete (página  | un string                                                     |
   |                      | principal)                       |                                                               |
   +----------------------+----------------------------------+---------------------------------------------------------------+
   | *download_url*       | Una URL para descargar el        | un string                                                     |
   |                      | paquete                          |                                                               |
   +----------------------+----------------------------------+---------------------------------------------------------------+
   | *packages*           | Una lista de paquetes Python que | una lista de strings                                          |
   |                      | *distutils* podrá manipular      |                                                               |
   +----------------------+----------------------------------+---------------------------------------------------------------+
   | *py_modules*         | Una lista de módulos Python que  | una lista de strings                                          |
   |                      | *distutils* podrá manipular      |                                                               |
   +----------------------+----------------------------------+---------------------------------------------------------------+
   | *scripts*            | Una lista de archivos únicos de  | una lista de strings                                          |
   |                      | scripts que serán creados e      |                                                               |
   |                      | instalados                       |                                                               |
   +----------------------+----------------------------------+---------------------------------------------------------------+
   | *ext_modules*        | Una lista de extensiones Python  | una lista de las instancias de la clase                       |
   |                      | para ser creadas                 | "distutils.core.Extension"                                    |
   +----------------------+----------------------------------+---------------------------------------------------------------+
   | *classifiers*        | Una lista de categorías para el  | una lista de strings; los clasificadores válidos están        |
   |                      | paquete                          | listados en PyPI.                                             |
   +----------------------+----------------------------------+---------------------------------------------------------------+
   | *distclass*          | la clase para usar la clase      | una sub-clase de la clase "distutils.core.Distribution"       |
   |                      | "Distribution"                   |                                                               |
   +----------------------+----------------------------------+---------------------------------------------------------------+
   | *script_name*        | El nombre del script del         | un string                                                     |
   |                      | setup.py - el predeterminado es  |                                                               |
   |                      | "sys.argv[0]"                    |                                                               |
   +----------------------+----------------------------------+---------------------------------------------------------------+
   | *script_args*        | Argumentos para suministrar el   | una lista de strings                                          |
   |                      | script de configuración          |                                                               |
   +----------------------+----------------------------------+---------------------------------------------------------------+
   | *options*            | opciones por defecto para el     | un diccionario                                                |
   |                      | script de configuración          |                                                               |
   +----------------------+----------------------------------+---------------------------------------------------------------+
   | *license*            | La licencia para el paquete      | un string                                                     |
   +----------------------+----------------------------------+---------------------------------------------------------------+
   | *keywords*           | Metadatos descriptivos, ver      | una lista de strings o un string separado por comas           |
   |                      | **PEP 314**                      |                                                               |
   +----------------------+----------------------------------+---------------------------------------------------------------+
   | *platforms*          |                                  | una lista de strings o un string separado por comas           |
   +----------------------+----------------------------------+---------------------------------------------------------------+
   | *cmdclass*           | Una asignación de los nombres de | un diccionario                                                |
   |                      | los comandos a las sub-clases de |                                                               |
   |                      | la clase "Command"               |                                                               |
   +----------------------+----------------------------------+---------------------------------------------------------------+
   | *data_files*         | Una lista de archivos de datos   | una lista                                                     |
   |                      | para instalar                    |                                                               |
   +----------------------+----------------------------------+---------------------------------------------------------------+
   | *package_dir*        | Una asignación de directorios a  | un diccionario                                                |
   |                      | los nombres de los paquetes      |                                                               |
   +----------------------+----------------------------------+---------------------------------------------------------------+

distutils.core.run_setup(script_name[, script_args=None, stop_after='run'])

   Ejecuta un script de instalación en un entorno algo controlado y
   retorna la instancia de la clase "distutils.dist.Distribution" que
   maneja las cosas. Esto es útil si se necesitan encontrar los
   metadatos de distribución (pasados como palabra clave *args* desde
   un script a la función "setup()"), o el contenido de los archivos
   de configuración o la línea de comandos.

   *script_name* o nombre del script es un archivo que será leído y
   ejecutado con la función "exec()". "sys.argv[0]" será reemplazado
   con un script durante la duración de la llamada. *script_args* es
   una lista de strings; si se proporciona, "sys.argv[1:]" será
   reemplazado por *script_args* durante la duración de la llamada.

   *stop_after* le dice a la función "setup()" cuando parar el
   procesamiento; los valores posibles son:

   +-----------------+-----------------------------------------------+
   | valor           | descripción                                   |
   |=================|===============================================|
   | *init*          | Detiene después de que la instancia de la     |
   |                 | clase "Distribution" haya sido creada y       |
   |                 | llenada con los argumentos de la palabra      |
   |                 | clave para la función "setup()"               |
   +-----------------+-----------------------------------------------+
   | *config*        | Detiene después que los archivos de           |
   |                 | configuración hayan sido analizados (y sus    |
   |                 | datos almacenados en la instancia de la clase |
   |                 | "Distribution")                               |
   +-----------------+-----------------------------------------------+
   | *commandline*   | Detiene después de que la línea de comandos   |
   |                 | ("sys.argv[1:]" o *script_args*) se haya      |
   |                 | analizado (y los datos almacenados en la      |
   |                 | instancia de la clase "Distribution".)        |
   +-----------------+-----------------------------------------------+
   | *run*           | Detiene después de que todos los comandos     |
   |                 | hayan sido ejecutados (lo mismo que si la     |
   |                 | función "setup()" haya sido llamada de forma  |
   |                 | habitual). Este es el valor predeterminado.   |
   +-----------------+-----------------------------------------------+

Además, el módulo "distutils.core" expuso una serie de clases que
residen en otros lugares.

* la clase "Extension" del módulo "distutils.extension"

* la clase "Command" del módulo "distutils.cmd"

* la clase "Distribution" del módulo "distutils.dist"

A continuación una breve descripción de cada uno de estos, pero para
una referencia completa consulta el módulo correspondiente.

class distutils.core.Extension

   La clase *Extension* describe un solo módulo de extensión C o C++
   en un script de configuración. Acepta los siguientes argumentos de
   palabras clave de su constructor:

   +--------------------------+----------------------------------+-----------------------------+
   | nombre del argumento     | valor                            | tipo                        |
   |==========================|==================================|=============================|
   | *name*                   | el nombre completo de la         | un string                   |
   |                          | extensión, incluidos los         |                             |
   |                          | paquetes --- es decir, no un     |                             |
   |                          | nombre de archivo o ruta, sino   |                             |
   |                          | un nombre punteado Python        |                             |
   +--------------------------+----------------------------------+-----------------------------+
   | *sources*                | lista de nombres de archivos de  | una lista de strings        |
   |                          | origen, en relación con la raíz  |                             |
   |                          | de distribución (donde reside el |                             |
   |                          | script de configuración), en     |                             |
   |                          | forma Unix (separados por        |                             |
   |                          | barras) para su portabilidad.    |                             |
   |                          | Los archivos fuente pueden ser   |                             |
   |                          | C, C ++, SWIG (.i), archivos de  |                             |
   |                          | recursos específicos de la       |                             |
   |                          | plataforma o cualquier otra cosa |                             |
   |                          | que el comando **build_ext**     |                             |
   |                          | reconozca como fuente para una   |                             |
   |                          | extensión de Python.             |                             |
   +--------------------------+----------------------------------+-----------------------------+
   | *include_dirs*           | lista de los directorios para    | una lista de strings        |
   |                          | buscar archivos de encabezados   |                             |
   |                          | de C/C++ (en forma de Unix para  |                             |
   |                          | portabilidad)                    |                             |
   +--------------------------+----------------------------------+-----------------------------+
   | *define_macros*          | lista de macros para definir;    | una lista de tuplas         |
   |                          | cada macro se define usando una  |                             |
   |                          | tupla de 2 "(*name*, *value*)",  |                             |
   |                          | donde *value* es el string para  |                             |
   |                          | definirla o "None" para          |                             |
   |                          | definirla sin un valor           |                             |
   |                          | particular (equivalente a        |                             |
   |                          | "#define FOO" en la fuente o     |                             |
   |                          | "-DFOO" en la línea de comandos  |                             |
   |                          | de un compilador de Unix C)      |                             |
   +--------------------------+----------------------------------+-----------------------------+
   | *undef_macros*           | lista de macros para indefinir   | una lista de strings        |
   |                          | explícitamente                   |                             |
   +--------------------------+----------------------------------+-----------------------------+
   | *library_dirs*           | lista de directorios para buscar | una lista de strings        |
   |                          | bibliotecas C/C++ en el momento  |                             |
   |                          | del enlace                       |                             |
   +--------------------------+----------------------------------+-----------------------------+
   | *libraries*              | lista de nombres de bibliotecas  | una lista de strings        |
   |                          | para vincular (no nombres de     |                             |
   |                          | archivos o rutas)                |                             |
   +--------------------------+----------------------------------+-----------------------------+
   | *runtime_library_dirs*   | lista de directorios para buscar | una lista de strings        |
   |                          | bibliotecas C/C++ en tiempo de   |                             |
   |                          | ejecución (para extensiones      |                             |
   |                          | compartidas, esto es cuando se   |                             |
   |                          | carga una extensión)             |                             |
   +--------------------------+----------------------------------+-----------------------------+
   | *extra_objects*          | lista de archivos adicionales    | una lista de strings        |
   |                          | para vincular (por ejemplo,      |                             |
   |                          | archivos de objeto no implícitos |                             |
   |                          | en **sources**, una biblioteca   |                             |
   |                          | estática que debe especificarse  |                             |
   |                          | explicitamente, archivos de      |                             |
   |                          | recursos binarios, etc.)         |                             |
   +--------------------------+----------------------------------+-----------------------------+
   | *extra_compile_args*     | cualquier adicional específico   | una lista de strings        |
   |                          | de la plataforma y del           |                             |
   |                          | compilador para usar cuando      |                             |
   |                          | compila los archivos fuente en   |                             |
   |                          | **sources**. Para plataformas y  |                             |
   |                          | compiladores donde una línea de  |                             |
   |                          | comando tiene sentido, esta es   |                             |
   |                          | típicamente una lista de         |                             |
   |                          | argumentos de línea de comando   |                             |
   |                          | pero para otras plataformas      |                             |
   |                          | podría ser cualquier cosa.       |                             |
   +--------------------------+----------------------------------+-----------------------------+
   | *extra_link_args*        | cualquier adicional específico   | una lista de strings        |
   |                          | de la plataforma y del           |                             |
   |                          | compilador para usar al vincular |                             |
   |                          | archivos del tipo objeto para    |                             |
   |                          | crear la extensión (o para crear |                             |
   |                          | un nuevo intérprete de Python    |                             |
   |                          | estático). Interpretación        |                             |
   |                          | similar a la de                  |                             |
   |                          | **extra_compile_args**.          |                             |
   +--------------------------+----------------------------------+-----------------------------+
   | *export_symbols*         | lista de símbolos que se         | una lista de strings        |
   |                          | exportarán desde una extensión   |                             |
   |                          | compartida. No se usa en todas   |                             |
   |                          | las plataformas y, en general,   |                             |
   |                          | no es necesario para las         |                             |
   |                          | extensiones de Python, que       |                             |
   |                          | normalmente exportan exactamente |                             |
   |                          | un símbolo: "init" +             |                             |
   |                          | *extension_name*.                |                             |
   +--------------------------+----------------------------------+-----------------------------+
   | *depends*                | lista de archivos de los que     | una lista de strings        |
   |                          | depende la extensión             |                             |
   +--------------------------+----------------------------------+-----------------------------+
   | *language*               | lenguaje de extensión (es decir, | un string                   |
   |                          | "'c'", "'c++'", "'objc'"). Se    |                             |
   |                          | detectará en las extensiones de  |                             |
   |                          | origen si no se proporcionan.    |                             |
   +--------------------------+----------------------------------+-----------------------------+
   | *optional*               | especifica que una falla de      | un booleano                 |
   |                          | compilación en la extensión no   |                             |
   |                          | debe abortar el proceso de       |                             |
   |                          | compilación, sino simplemente    |                             |
   |                          | omitir la extensión.             |                             |
   +--------------------------+----------------------------------+-----------------------------+

   Distinto en la versión 3.8: En Unix, las extensiones C ya no están
   vinculadas a libpython excepto en Android y Cygwin.

class distutils.core.Distribution

   Una clase "Distribution" describe cómo construir, instalar y
   empaquetar un paquete de software Python.

   Consulta la función "setup()" para obtener una lista de argumentos
   de palabras clave aceptados por el constructor de distribución. La
   función "setup()" crea una instancia de distribución.

   Distinto en la versión 3.7: La clase "Distribution" ahora advierte
   si los campos "*classifiers*", "*keywords*" y "*platforms*" no se
   especifican como una lista o un string.

class distutils.core.Command

   Una clase "Command" (o más bien, una instancia de una de sus
   subclases) implementa un solo comando distutils.


9.2. "distutils.ccompiler" --- Clase base CCompiler
===================================================

Este módulo proporciona la clase base abstracta para las clases
"CCompiler". Una instancia de la clase "CCompiler" se puede usar para
todos los pasos de compilación y enlace necesarios para construir un
solo proyecto. Se proporcionan métodos para establecer opciones para
el compilador --- definiciones de macros, que incluyen directorios,
ruta de enlace, bibliotecas y similares.

Este módulo proporciona las siguientes funciones.

distutils.ccompiler.gen_lib_options(compiler, library_dirs, runtime_library_dirs, libraries)

   Genera opciones de vinculador para buscar directorios de
   bibliotecas y vincular con bibliotecas específicas. *libraries* y *
   library_dirs* son, respectivamente, listas de nombres de
   bibliotecas (no nombres de archivos!) y directorios de búsqueda.
   Retorna una lista de opciones de línea de comandos adecuadas para
   su uso con algún compilador (dependiendo de los dos strings de
   formato suministrados).

distutils.ccompiler.gen_preprocess_options(macros, include_dirs)

   Genera opciones de preprocesador de C ("-D", "-U", "-I") tal como
   lo utilizan al menos dos tipos de compiladores: el compilador
   típico de Unix y el Visual C++. *macros* es lo habitual, una lista
   de 1 o 2 tuplas, donde "(*name*,)" significa indefinir ("-U") macro
   *name*, y "(*name*, *value*)" significa definir ("-D") macro de
   *name* a *value*. *include_dirs* es solo una lista de nombres de
   directorio que se agregarán a la ruta de búsqueda del archivo de
   encabezado ("-I"). Retorna una lista de opciones de línea de
   comandos adecuadas para compiladores de Unix o Visual C++.

distutils.ccompiler.get_default_compiler(osname, platform)

   Determina el compilador predeterminado que se utilizará para la
   plataforma dada.

   *osname* debe ser uno de los nombres estándar de Python OS (es
   decir, los retornados por "os.name") y *platform* el valor común
   retornado por "sys.platform" para la plataforma en cuestión.

   Los valores predeterminados son "os.name" y "sys.platform" en caso
   de que no se proporcionen los parámetros.

distutils.ccompiler.new_compiler(plat=None, compiler=None, verbose=0, dry_run=0, force=0)

   Función de fábrica para generar una instancia de alguna subclase
   *CCompiler* para la combinación de plataforma/compilador
   proporcionada. *plat* por defecto es "os.name" (por ejemplo,
   "'posix'", "'nt'"), y *compiler* por defecto es el compilador por
   defecto para esa plataforma. Actualmente solo se admiten "'posix'"
   y "'nt'", y los compiladores predeterminados son la "interfaz Unix
   tradicional" (clase "UnixCCompiler") y Visual C++ (clase
   "MSVCCompiler"). Tenga en cuenta que es perfectamente posible
   solicitar un objeto de compilador de Unix en Windows y un objeto de
   compilador de Microsoft en Unix --- si proporciona un valor para
   *compiler*, *plat* es ignorado.

distutils.ccompiler.show_compilers()

   Imprime la lista de compiladores disponibles (usado por las
   opciones " - help-compiler" para **build**, :command: *build_ext*,
   **build_clib**).

class distutils.ccompiler.CCompiler([verbose=0, dry_run=0, force=0])

   La clase base abstracta "CCompiler" define la interfaz que deben
   implementar las clases de compiladores reales. La clase también
   tiene algunos métodos de utilidad utilizados por varias clases de
   compiladores.

   La idea básica detrás de una clase de abstracción de compilador es
   que cada instancia se puede usar para todos los pasos de
   compilación/enlace en la construcción de un solo proyecto. Por lo
   tanto, los atributos comunes a todos esos pasos de compilación y
   enlace --- incluyen directorios, macros para definir, bibliotecas
   para enlazar, etc. --- son atributos de la instancia del
   compilador. Para permitir la variabilidad en la forma en que se
   tratan los archivos individuales, la mayoría de esos atributos se
   pueden variar por compilación o por enlace.

   El constructor de cada subclase crea una instancia del objeto
   *Compiler*. Los indicadores son *verbose* (muestra un resultado
   detallado), *dry_run* (en realidad no ejecuta los pasos) y *force*
   (reconstruye todo, independientemente de las dependencias). Todos
   estos indicadores están predeterminados en "0" (desactivado). Ten
   en cuenta que probablemente no desees crear una instancia de
   "CCompiler" o una de sus subclases directamente; usa la función de
   fábrica "distutils.CCompiler.new_compiler()" en su lugar.

   Los siguientes métodos te permiten modificar manualmente las
   opciones del compilador para la instancia de la clase *Compiler*.

   add_include_dir(dir)

      Agrega *dir* a la lista de directorios en los que se buscarán
      archivos de encabezado. Se le indica al compilador que busque
      directorios en el orden en que son proporcionados por llamadas
      sucesivas a "add_include_dir()".

   set_include_dirs(dirs)

      Establece la lista de directorios que se buscarán en *dirs* (una
      lista de strings). Anula cualquier llamada anterior a
      "add_include_dir()"; llamadas posteriores a "add_include_dir()"
      agrega a la lista pasada a "set_include_dirs()". Esto no afecta
      a ninguna lista de directorios de inclusión estándar que el
      compilador pueda buscar de forma predeterminada.

   add_library(libname)

      Agrega *libname* a la lista de bibliotecas que se incluirán en
      todos los enlaces manejados por este compilador de objeto. Ten
      en cuenta que *libname* debería no ser el nombre de un archivo
      que contenga una biblioteca, sino el nombre de la biblioteca en
      sí: el enlazador, el compilador o la clase del compilador
      deducirán el nombre del archivo actual (según el plataforma).

      Se le indicará al enlazador que se vincule con las bibliotecas
      en el orden en que se proporcionaron "add_library()" y/o
      "set_libraries()". Es perfectamente válido duplicar nombres de
      bibliotecas; se le indicará al enlazador que se vincule con las
      bibliotecas tantas veces como se mencionen.

   set_libraries(libnames)

      Establece la lista de bibliotecas que se incluirán en todos los
      enlaces manejados por este compilador de objeto en *libnames*
      (una lista de strings). Esto no afecta a las bibliotecas del
      sistema estándar que el vinculador pueda incluir de forma
      predeterminada.

   add_library_dir(dir)

      Agrega *dir* a la lista de directorios en los que se buscarán
      las bibliotecas especificadas para "add_library()" y
      "set_libraries()". Se le indicará al enlazador que busque
      bibliotecas en el orden en que se suministran a
      "add_library_dir()" y/o "set_library_dirs()".

   set_library_dirs(dirs)

      Establece la lista de directorios de búsqueda de bibliotecas en
      *dirs* (una lista de strings). Esto no afecta a ninguna ruta de
      búsqueda de biblioteca estándar que el enlazador pueda buscar de
      forma predeterminada.

   add_runtime_library_dir(dir)

      Agrega *dir* a la lista de directorios en los que se buscarán
      bibliotecas compartidas en tiempo de ejecución.

   set_runtime_library_dirs(dirs)

      Establece la lista de directorios para buscar bibliotecas
      compartidas en tiempo de ejecución en *dirs* (una lista de
      strings). Esto no afecta a ninguna ruta de búsqueda estándar que
      el enlazador en tiempo de ejecución pueda buscar de forma
      predeterminada.

   define_macro(name[, value=None])

      Define una macro de preprocesador para todas las compilaciones
      impulsadas por este objeto compilador. El parámetro opcional
      *value* debe ser un string; si no se proporciona, la macro se
      definirá sin un valor explícito y el resultado exacto depende
      del compilador utilizado.

   undefine_macro(name)

      Anula la definición de una macro de preprocesador para todas las
      compilaciones impulsadas por este compilador de objeto. Si la
      misma macro está definida por "define_macro()" y la indefinida
      por "undefine_macro()", la última llamada tiene prioridad
      (incluidas varias redefiniciones o indefiniciones). Si la macro
      está redefinida/indefinida por compilación (es decir, en la
      llamada a "compile()"), entonces eso tiene prioridad.

   add_link_object(object)

      Agrega *object* a la lista de archivos de objeto (o análogos,
      como archivos de biblioteca nombrados explícitamente o la salida
      de "*resource compilers*" o compiladores de recursos) para que
      se incluyan en cada enlace impulsado por este objeto de
      compilador.

   set_link_objects(objects)

      Establece la lista de archivos de objetos (o análogos) que se
      incluirán en cada enlace a *objects*. Esto no afecta a ningún
      archivo de objeto estándar que el enlazador pueda incluir de
      forma predeterminada (como las bibliotecas del sistema).

   Los siguientes métodos implementan métodos para la detección
   automática de opciones del compilador, proporcionando alguna
   funcionalidad similar a GNU :program: *autoconf*.

   detect_language(sources)

      Detecta el idioma de un archivo determinado o una lista de
      archivos. Utiliza los atributos de instancia "language_map" (un
      diccionario) y "language_order" (una lista) para hacer el
      trabajo.

   find_library_file(dirs, lib[, debug=0])

      Busca en la lista especificada de directorios un archivo de
      biblioteca estático o compartido y retorna la ruta completa a
      ese archive *lib*. Si *debug* es verdadero, busca una versión de
      depuración (si tiene sentido en la plataforma actual). Retorna
      "None" si *lib* no se encontró en ninguno de los directorios
      especificados.

   has_function(funcname[, includes=None, include_dirs=None, libraries=None, library_dirs=None])

      Retorna un valor booleano que indica si *funcname* es compatible
      con la plataforma actual. Los argumentos opcionales se pueden
      utilizar para aumentar el entorno de compilación proporcionando
      archivos y rutas de inclusión adicionales y bibliotecas y rutas.

   library_dir_option(dir)

      Retorna la opción del compilador para agregar *dir* a la lista
      de directorios buscados por bibliotecas.

   library_option(lib)

      Retorna la opción del compilador para agregar *lib* a la lista
      de bibliotecas vinculadas a la biblioteca compartida o
      ejecutable.

   runtime_library_dir_option(dir)

      Retorna la opción del compilador para agregar *dir* a la lista
      de directorios buscados por bibliotecas en tiempo de ejecución.

   set_executables(**args)

      Define los ejecutables (y las opciones para ellos) que se
      ejecutarán para realizar las distintas etapas de compilación. El
      conjunto exacto de ejecutables que se pueden especificar aquí
      depende de la clase del compilador (a través del atributo de
      clase '*executables*'), pero la mayoría tendrá:

      +----------------+--------------------------------------------+
      | atributo       | descripción                                |
      |================|============================================|
      | *compiler*     | el compilador C/C++                        |
      +----------------+--------------------------------------------+
      | *linker_so*    | enlazador utilizado para crear bibliotecas |
      |                | y objetos compartidos                      |
      +----------------+--------------------------------------------+
      | *linker_exe*   | enlazador utilizado para crear ejecutables |
      |                | binarios                                   |
      +----------------+--------------------------------------------+
      | *archiver*     | creador de biblioteca estática             |
      +----------------+--------------------------------------------+

      En plataformas con una línea de comandos (Unix, DOS/Windows),
      cada uno de estos es un string que se dividirá en un nombre
      ejecutable y una lista de argumentos (opcional). (La división de
      la cadena se realiza de manera similar a como funcionan los
      *shells* de Unix: las palabras están delimitadas por espacios,
      pero las comillas y las barras invertidas pueden anular esto.
      Ver "distutils.util.split_quoted()".)

   Los siguientes métodos invocan etapas en el proceso de
   construcción.

   compile(sources[, output_dir=None, macros=None, include_dirs=None, debug=0, extra_preargs=None, extra_postargs=None, depends=None])

      Compila uno o más archivos fuente. Genera archivos de objeto
      (por ejemplo, transforma un archivo ".c" en un archivo ".o").

      *sources* debe ser una lista de nombres de archivo,
      probablemente archivos C/C ++, pero en realidad cualquier cosa
      que pueda ser manejada por un compilador particular y un
      compilador de clase (por ejemplo "MSVCCompiler" puede manejar
      archivos de recursos en *source*). Retorna una lista de nombres
      de archivos de objetos, uno por nombre de archivo fuente en
      *sources*. Dependiendo de la implementación, no se compilarán
      necesariamente todos los archivos fuente, pero se retornarán
      todos los nombres de archivo de objeto correspondientes.

      Si se indica el *output_dir*, los objeto de archivos se
      colocarán debajo de él, conservando su componente de ruta
      original. Es decir, "foo/bar.c" normalmente se compila en
      "foo/bar.o" (para una implementación de Unix); si *output_dir*
      es *build*, entonces se compilaría en "build/foo/bar.o".

      *macros*, si se proporciona, debe ser una lista de definiciones
      de una macro. Una definición de una macro es un "(*name*,
      *value*)" 2-tupla o un "(*name*,)" 1-tupla. El primero define
      una macro; si el valor es "None", la macro se define sin un
      valor explícito. El caso de 1 tupla no define una macro. Las
      definiciones/redefiniciones/indefiniciones posteriores tienen
      prioridad.

      *include_dirs*, si se proporciona, debe ser una lista de
      strings, para esta compilación solo se agregarán a la ruta de
      búsqueda de archivos los directorios de inclusión
      predeterminada.

      *debug* es un booleano; si es verdadero, se le indicará al
      compilador que genere símbolos de depuración en (o junto a) los
      archivos de objetos.

      *extra_preargs* y *extra_postargs* dependen de la
      implementación. En plataformas que tienen la noción de línea de
      comandos (por ejemplo, Unix, DOS/Windows), lo más probable es
      que sean listas de strings: argumentos de línea de comandos
      adicionales para anteponer/agregar a la línea de comandos del
      compilador. En otras plataformas, consulta la documentación de
      la clase de implementación. En cualquier caso, están pensados
      como una vía de escape para aquellas ocasiones en las que la
      marco del compilador abstracto no es suficiente.

      *depends*, si se proporciona, es una lista de nombres de
      archivos de los que dependen todos los destinos. Si un archivo
      de origen es más antiguo que cualquier archivo en *depends*, se
      volverá a compilar el archivo de origen. Esto admite el
      seguimiento de dependencias, pero solo con una granularidad
      aproximada.

      Lanza "CompileError" en caso de falla.

   create_static_lib(objects, output_libname[, output_dir=None, debug=0, target_lang=None])

      Enlaza un montón de cosas para crear un archivo de biblioteca
      estático. El "montón de cosas" o "*bunch of stuff*" consiste en
      la lista de archivos de objeto suministrados como *objects*, los
      archivos de objeto adicionales suministrados a
      "add_link_object()" y/o "set_link_objects()", las bibliotecas
      suministradas a "add_library()" y/o "set_libraries()", y las
      bibliotecas proporcionadas como *libraries* (si las hay).

      *output_libname* debe ser un nombre de biblioteca, no un nombre
      de archivo; el nombre del archivo se deducirá del nombre de la
      biblioteca. *output_dir* es el directorio donde se colocará el
      archivo de la biblioteca.

      *debug* es un booleano; si es verdadero, la depuración se
      incluirá en la biblioteca (ten en cuenta que en la mayoría de
      las plataformas, es el paso de compilación donde esto es
      importante: el indicador *debug* se incluye aquí solo por
      coherencia).

      *target_lang* es el idioma de destino para el que se compilan
      los objetos dados. Esto permite un tratamiento específico del
      tiempo de vinculación de ciertos idiomas.

      Lanza "LibError" en caso de falla.

   link(target_desc, objects, output_filename[, output_dir=None, libraries=None, library_dirs=None, runtime_library_dirs=None, export_symbols=None, debug=0, extra_preargs=None, extra_postargs=None, build_temp=None, target_lang=None])

      Enlaza un montón de cosas (o *bunch of stuff*) juntos para crear
      un archivo de biblioteca ejecutable o compartido.

      El "montón de cosas" o (*bunch of stuff*) consiste en la lista
      de archivos de objeto suministrados como *objects *.
      *output_filename* debe ser un nombre del archivo. Si se
      proporciona *output_dir*, *output_filename* es relativo a él (es
      decir, *output_filename* puede proporcionar componentes de
      directorio si es necesario).

      *libraries* es una lista de bibliotecas para enlazar. Estos son
      nombres de bibliotecas, no nombres de archivos, ya que se
      traducen a nombres de archivos de una manera específica de la
      plataforma (por ejemplo, *foo* se convierte en "libfoo.a" en
      Unix y "foo.lib" en DOS/Windows). Sin embargo, pueden incluir un
      componente de directorio, lo que significa que el enlazador
      buscará en ese directorio específico en lugar de buscar en todas
      las ubicaciones normales.

      *library_dirs*, si se proporciona, debe ser una lista de
      directorios para buscar bibliotecas que se especificaron como
      nombres de bibliotecas descubiertos (es decir, sin componentes
      de directorio). Estos están en la parte superior del sistema
      predeterminado y los suministrados a "add_library_dir()" y/o
      "set_library_dirs()". *runtime_library_dirs* es una lista de
      directorios que se incrustarán en la biblioteca compartida y se
      usarán para buscar otras bibliotecas compartidas de las que
      depende en tiempo de ejecución. (Esto solo puede ser relevante
      en Unix).

      *export_symbols* es una lista de símbolos que exportará la
      biblioteca compartida. (Esto parece ser relevante solo en
      Windows).

      *debug* es para métodos como "compile()" y
      "create_static_lib()", con la ligera distinción de que en
      realidad es relevante en la mayoría de las plataformas (a
      diferencia de "create_static_lib()", que incluye un indicador
      *debug* principalmente por el bien de la forma).

      *extra_preargs* y *extra_postargs* son para métodos como
      "compile()" (excepto, por supuesto, que proporcionan argumentos
      de línea de comandos para el enlazador particular que se está
      utilizando).

      *target_lang* es el idioma de destino para el que se compilan
      los objetos dados. Esto permite un tratamiento específico del
      tiempo de vinculación de ciertos idiomas.

      Lanza "LinkError" en caso de falla.

   link_executable(objects, output_progname[, output_dir=None, libraries=None, library_dirs=None, runtime_library_dirs=None, debug=0, extra_preargs=None, extra_postargs=None, target_lang=None])

      Enlaza un ejecutable. *output_progname* es el nombre del archivo
      ejecutable, mientras que *objects* son una lista de nombres de
      archivos de objetos para vincular. Otros argumentos son para
      métodos como "link()".

   link_shared_lib(objects, output_libname[, output_dir=None, libraries=None, library_dirs=None, runtime_library_dirs=None, export_symbols=None, debug=0, extra_preargs=None, extra_postargs=None, build_temp=None, target_lang=None])

      Enlaza una biblioteca compartida. *output_libname* es el nombre
      de la biblioteca de salida, mientras que *objects* es una lista
      de nombres de archivos de objetos para vincular. Otros
      argumentos son para métodos como "link()".

   link_shared_object(objects, output_filename[, output_dir=None, libraries=None, library_dirs=None, runtime_library_dirs=None, export_symbols=None, debug=0, extra_preargs=None, extra_postargs=None, build_temp=None, target_lang=None])

      Enlaza un objeto compartido. *output_filename* es el nombre del
      objeto compartido que se creará, mientras que *objects* es una
      lista de nombres de archivos de objetos para vincular. Otros
      argumentos son para métodos como "link()".

   preprocess(source[, output_file=None, macros=None, include_dirs=None, extra_preargs=None, extra_postargs=None])

      Preprocesa un solo archivo fuente C/C ++, nombrado en *source*.
      La salida se escribirá en el archivo llamado *output_file*, o
      *stdout* si *output_file* no se proporciona. *macros* es una
      lista de definiciones de macros para métodos como "compile()",
      que aumentará el conjunto de macros con "define_macro()" y
      "undefine_macro()". *include_dirs* es una lista de nombres de
      directorio que se agregarán a la lista predeterminada, de la
      misma manera que "add_include_dir()".

      Lanza "PreprocessError" en caso de falla.

   Los siguientes métodos de utilidad están definidos por la clase
   "CCompiler", para uso de las distintas subclases concretas.

   executable_filename(basename[, strip_dir=0, output_dir=''])

      Retorna el nombre de archivo del ejecutable para el *basename*
      dado. Por lo general, para las plataformas que no son de
      Windows, este es el mismo que el nombre base, mientras que
      Windows obtendrá un archivo ".exe" agregado.

   library_filename(libname[, lib_type='static', strip_dir=0, output_dir=''])

      Retorna el nombre de archivo para el nombre de biblioteca dado
      en la plataforma actual. En Unix, una biblioteca con *lib_type*
      de "'static'" normalmente tendrá la forma "liblibname.a",
      mientras que *lib_type* de "'dynamic'" tendrá la forma
      "liblibname.so".

   object_filenames(source_filenames[, strip_dir=0, output_dir=''])

      Retorna el nombre de los archivos de objeto para los archivos de
      origen dados. *source_filenames* debe ser una lista de nombres
      de archivo.

   shared_object_filename(basename[, strip_dir=0, output_dir=''])

      Retorna el nombre de un archivo de objeto compartido para el
      nombre de archivo *basename*.

   execute(func, args[, msg=None, level=1])

      Invoca el método "distutils.util.execute()". Este método invoca
      una función de Python *func* con los argumentos *args* dados,
      después de iniciar sesión y teniendo en cuenta el indicador
      *dry_run*.

   spawn(cmd)

      Invoca "distutils.util.spawn()". Esto invoca un proceso externo
      para ejecutar el comando dado.

   mkpath(name[, mode=511])

      Invoca "distutils.dir_util.mkpath()". Esto crea un directorio y
      los directorios ancestros que faltan.

   move_file(src, dst)

      Invoca "distutils.file_util.move_file()". Cambia el nombre de
      *src* a *dst*.

   announce(msg[, level=1])

      Escribe un mensaje usando "distutils.log.debug()".

   warn(msg)

      Escribe un mensaje de advertencia *msg* al error estándar.

   debug_print(msg)

      Si el indicador *debug* está configurado en la instancia de la
      clase "CCompiler", imprime *msg* en la salida estándar; de lo
      contrario, no hace nada.


9.3. "distutils.unixccompiler" --- Unix CCompiler
=================================================

Este módulo proporciona la clase "UnixCCompiler", una subclase de
"CCompiler" que maneja el típico compilador C de línea de comandos
estilo Unix:

* macros definidas con "-Dname[= value]"

* macros definidas con "-Uname"

* incluye directorios de búsqueda especificados con "-Idir"

* bibliotecas especificadas con "-llib"

* directorios de búsqueda de bibliotecas especificados con "-Ldir"

* compilación manejada por **cc** (o similar) ejecutable con "-c"
  opción: compilar ".c" a ".o"

* enlaza la biblioteca estática manejada por el comando **ar**
  (posiblemente con **ranlib**)

* enlaza la biblioteca compartida manejada por **cc** "-shared"


9.4. "distutils.msvccompiler" --- Compilador de Microsoft
=========================================================

Este módulo proporciona "MSVCCompiler", una implementación de la clase
abstracta "CCompiler" para Microsoft Visual Studio. Por lo general,
los módulos de extensión deben compilarse con el mismo compilador
Python que se utilizó para compilar. Para Python 2.3 y versiones
anteriores, el compilador fue Visual Studio 6. Para Python 2.4 y 2.5,
el compilador es Visual Studio .NET 2003.

"MSVCCompiler" normalmente elegirá el compilador, enlazador, etc.
correcto por sí solo. Para anular esta opción, las variables de
entorno *DISTUTILS_USE_SDK* y *MSSdk* deben estar configuradas.
*MSSdk* indica que el entorno actual ha sido configurado por el script
"SetEnv.Cmd" del SDK, o que las variables de entorno se habían
registrado cuando se instaló el SDK; *DISTUTILS_USE_SDK* indica que el
usuario de *distutils* ha hecho una elección explícita para anular la
selección del compilador por "MSVCCompiler".


9.5. "distutils.bcppcompiler" --- Compilador Borland
====================================================

Este módulo proporciona "BorlandCCompiler", una subclase de la clase
abstracta "CCompiler" para el compilador Borland C++.


9.6. "distutils.cygwincompiler" --- Compilador Cygwin
=====================================================

Este módulo proporciona la clase "CygwinCCompiler", una subclase de
"UnixCCompiler" que maneja el puerto Cygwin del compilador GNU C a
Windows. También contiene la clase Mingw32CCompiler que maneja el
puerto mingw32 de GCC (igual que cygwin en modo no-cygwin).


9.7. "distutils.archive_util" --- Utilidades de archivo
=======================================================

Este módulo proporciona algunas funciones para crear archivos de
almacenamiento, como *tarballs* o *zipfiles*.

distutils.archive_util.make_archive(base_name, format[, root_dir=None, base_dir=None, verbose=0, dry_run=0])

   Crea un archivo de almacenamiento (por ejemplo, "zip" o "tar").
   *base_name* es el nombre del archivo a crear, menos cualquier
   extensión específica del formato; *format* es el formato de
   archivo: como "zip", "tar", "gztar", "bztar", "xztar" o "ztar".
   *root_dir* es un directorio que será el directorio raíz del
   archivo; es decir, normalmente "chdir" en *root_dir* antes de crear
   el archivo. *base_dir* es el directorio desde donde comenzamos a
   archivar; es decir, *base_dir* será el prefijo común de todos los
   archivos y directorios del archivo. *root_dir* y *base_dir* ambos
   predeterminados al directorio actual. Retorna el nombre del archivo
   de almacenamiento.

   Distinto en la versión 3.5: Se agregó soporte para el formato
   "xztar".

distutils.archive_util.make_tarball(base_name, base_dir[, compress='gzip', verbose=0, dry_run=0])

   Crea un archivo (opcionalmente comprimido) como un archivo "tar" de
   todos los archivos en y bajo *base_dir*. *compress* debe ser
   "'gzip'" (el valor predeterminado), "'bzip2'", "'xz'", "'compress"'
   o "None". Para el método "'compress'", la utilidad de compresión
   nombrada por **compress** debe estar en la ruta de búsqueda del
   programa predeterminada, por lo que probablemente sea específica de
   Unix. El archivo "tar" de salida se llamará "base_dir.tar",
   posiblemente más la extensión de compresión apropiada
   (".gz",``.bz2``,``.xz`` o ".Z"). Retorna el nombre del archivo de
   salida.

   Distinto en la versión 3.5: Se agregó soporte para la compresión
   "xz".

distutils.archive_util.make_zipfile(base_name, base_dir[, verbose=0, dry_run=0])

   Crea un archivo *zip* a partir de todos los archivos incluidos en
   *base_dir*. El archivo *zip* de salida se llamará *base_name* +
   ".zip". Utiliza el módulo Python "zipfile" (si está disponible) o
   la utilidad InfoZIP "zip" (si está instalada y se encuentra en la
   ruta de búsqueda predeterminada). Si ninguna de las herramientas
   está disponible, lanza "DistutilsExecError". Retorna el nombre del
   archivo *zip* de salida.


9.8. "distutils.dep_util" --- Comprobación de dependencias
==========================================================

Este módulo proporciona funciones para realizar una dependencia simple
basada en marcas de tiempo de archivos y grupos de archivos; también,
funciones basadas completamente en dicho análisis de dependencia de
marca de tiempo.

distutils.dep_util.newer(source, target)

   Retorna verdadero si *source* existe y se ha modificado más
   recientemente que *target*, o si *source* existe y *target* no.
   Retorna falso si ambos existen y si *target* tiene el mismo tiempo
   o es más reciente que *source*. Lanza "DistutilsFileError" si
   *source* no existe.

distutils.dep_util.newer_pairwise(sources, targets)

   Recorre dos listas de nombres de archivos en paralelo, probando si
   cada fuente es más nueva que su correspondiente destino. Retorna un
   par de listas (*sources*, *target*) donde la fuente es más nueva
   que el destino, de acuerdo con la semántica de "newer()".

distutils.dep_util.newer_group(sources, target[, missing='error'])

   Retorna verdadero si *target* no está actualizado con respecto a
   cualquier archivo listado en *sources*. En otras palabras, si
   *target* existe y es más reciente que todos los archivos en
   *sources*, retorna falso; de lo contrario, retorna verdadero.
   *missing* controla lo que hacemos cuando falta un archivo fuente;
   el valor predeterminado ("'error'") explota con un "OSError" desde
   "os.stat()"; si es "'ignore'", eliminamos silenciosamente cualquier
   archivo fuente faltante; si es "'newer'", cualquier archivo fuente
   que falte nos hace suponer que *target* está desactualizado (esto
   es útil en el modo de "*dry-run*" (o ejecución en seco): que hará
   que pretenda ejecutar comandos que no funcionaría porque faltan
   entradas, pero no importa porque en realidad no va a ejecutar los
   comandos).


9.9. "distutils.dir_util" --- Operaciones del árbol de directorios
==================================================================

Este módulo proporciona funciones para operar en directorios y árboles
de directorios.

distutils.dir_util.mkpath(name[, mode=0o777, verbose=0, dry_run=0])

   Crea un directorio y cualquier directorio ancestro que falte. Si el
   directorio ya existe (o si *name* es el string vacío, significa que
   el directorio actual, por supuesto existe), no hace nada. Lanza
   "DistutilsFileError" si no puede crear algún directorio en el
   camino (por ejemplo, existe alguna subruta, pero es un archivo en
   lugar de un directorio). Si *verbose* es verdadero, imprime un
   resumen de una línea de cada *mkdir* en *stdout*. Retorna la lista
   de directorios realmente creados.

distutils.dir_util.create_tree(base_dir, files[, mode=0o777, verbose=0, dry_run=0])

   Crea todos los directorios vacíos en *base_dir* necesarios para
   colocar *files* allí. *base_dir* es solo el nombre de un directorio
   que no existe necesariamente todavía; *files* es una lista de
   nombres de archivos que se interpretarán en relación con
   *base_dir*. *base_dir* + la parte del directorio de cada archivo en
   *files* se creará si aún no existe. Los indicadores *mode*,
   *verbose* y *dry_run* son para funciones como "mkpath()".

distutils.dir_util.copy_tree(src, dst[, preserve_mode=1, preserve_times=1, preserve_symlinks=0, update=0, verbose=0, dry_run=0])

   Copia un árbol de directorio completo *src* en una nueva ubicación
   *dst*. Tanto *src* como *dst* deben ser nombres de directorio. Si
   *src* no es un directorio, lanza "DistutilsFileError". Si *dst* no
   existe, se crea con "mkpath()". El resultado final de la copia es
   que todos los archivos de *src* se copian en *dst*, y los
   directorios de *src* se copian de forma recursiva en *dst*. Retorna
   la lista de archivos que se copiaron o que podrían haberse copiado,
   utilizando su nombre de salida. El valor de retorno no se ve
   afectado por *update* o *dry_run*: es simplemente la lista de todos
   los archivos bajo *src *, con los nombres cambiados para estar bajo
   *dst*.

   *preserve_mode* y *preserve_times* son los mismos que para
   "distutils.file_util.copy_file()"; ten en cuenta que solo se
   aplican a archivos normales, no a directorios. Si
   *preserve_symlinks* es verdadero, los enlaces simbólicos se
   copiarán como enlaces simbólicos (en plataformas que los admitan!);
   de lo contrario (por defecto), se copiará el destino del enlace
   simbólico. *update* y *verbose* son los mismos que para
   "copy_file()".

   Files in *src* that begin with ".nfs" are skipped (more information
   on these files is available in answer D2 of the NFS FAQ page).

   Distinto en la versión 3.3.1: Se ignoran los archivos NFS.

distutils.dir_util.remove_tree(directory[, verbose=0, dry_run=0])

   Elimina de forma recursiva *directory* y todos los archivos y
   directorios que se encuentran debajo. Cualquier error se ignora
   (aparte de ser informado a "sys.stdout" si *verbose* es verdadero).


9.10. "distutils.file_util" --- Operaciones de un solo archivo
==============================================================

Este módulo contiene algunas funciones de utilidad para operar en
archivos individuales.

distutils.file_util.copy_file(src, dst[, preserve_mode=1, preserve_times=1, update=0, link=None, verbose=0, dry_run=0])

   Copia el archivo desde *src* a *dst*. Si *dst* es un directorio,
   entonces *src* se copia allí con el mismo nombre; de lo contrario,
   debe ser un nombre de archivo. (Si el archivo existe, será
   atacado). Si *preserve_mode* es verdadero (el valor
   predeterminado), se copia el modo del archivo (*bits* de tipo y
   permiso, o lo que sea análogo en la plataforma actual). Si
   *preserve_times* es verdadero (el valor predeterminado), también se
   copian las horas de última modificación y de último acceso. Si
   *update* es verdadero, *src* solo se copiará si *dst* no existe, o
   si *dst* existe pero es anterior a *src*.

   *link* te permite crear enlaces físicos (usando "os.link()") o
   enlaces simbólicos (usando "os.symlink()") en lugar de copiar:
   configúralo en "'hard'" o "'sym'"; si es "None" (el
   predeterminado), los archivos se copian. No establezcas *link* en
   sistemas que no lo admitan: "copy_file()" pues no comprueba si hay
   enlaces físicos o simbólicos disponibles. Utiliza
   "_copy_file_contents()" para copiar el contenido del archivo.

   Retorna una tupla "(dest_name, copied)": *dest_name* es el nombre
   real del archivo de salida, y *copied* es verdadero si el archivo
   fue copiado (o se habría copiado, si *dry_run* es verdadero).

distutils.file_util.move_file(src, dst[, verbose, dry_run])

   Mueve el archivo *src* a *dst*. Si *dst* es un directorio, el
   archivo se moverá a el con el mismo nombre; de lo contrario, *src*
   simplemente se renombra a *dst*. Retorna el nuevo nombre completo
   del archivo.

   Advertencia:

     Maneja movimientos entre dispositivos en Unix usando
     "copy_file()". ¿Qué pasa con otros sistemas?

distutils.file_util.write_file(filename, contents)

   Crea un archivo llamado *filename* y escribe *contents* (una
   secuencia de strings sin terminadores de línea) en el.


9.11. "distutils.util" --- Otras funciones de utilidad varias
=============================================================

Este módulo contiene otras partes y piezas variadas que no encajan en
ningún otro módulo de utilidad.

distutils.util.get_platform()

   Retorna un string que identifica la plataforma actual. Se utiliza
   principalmente para distinguir los directorios de compilación
   específicos de la plataforma y las distribuciones compiladas
   específicas de la plataforma. Por lo general, incluye el nombre y
   la versión del sistema operativo y la arquitectura (como lo
   proporciona 'os.uname ()'), aunque incluir la exacta depende del
   sistema operativo; por ejemplo, en Linux, la versión del kernel no
   es particularmente importante.

   Ejemplos de valores retornados:

   * "linux-i586"

   * "linux-alpha"

   * "solaris-2.6-sun4u"

   Para las plataformas que no son POSIX, actualmente solo retorna
   "sys.platform".

   Para los sistemas macOS, la versión del SO refleja la versión
   mínima en la que se ejecutarán los binarios (es decir, el valor de
   "MACOSX_DEPLOYMENT_TARGET" durante la compilación de Python), no la
   versión del SO del sistema actual.

   Para las compilaciones binarias universales en macOS, el valor de
   la arquitectura refleja el estado binario universal en lugar de la
   arquitectura del procesador actual. Para los binarios universales
   de 32 bits, la arquitectura es "fat", para los binarios universales
   de 64 bits la arquitectura es "fat64" y para los binarios
   universales de 4 vías la arquitectura es "universal". A partir de
   Python 2.7 y Python 3.2, la arquitectura "fat3" se usa para una
   compilación universal de 3 vías (ppc, i386, x86_64) e "intel" se
   usa para una compilación universal con las arquitecturas i386 y
   x86_64

   Ejemplos de valores retornados en macOS:

   * "macosx-10.3-ppc"

   * "macosx-10.3-fat"

   * "macosx-10.5-universal"

   * "macosx-10.6-intel"

   Para AIX, Python 3.9 y versiones posteriores retornan una cadena
   que comienza con "aix", seguida de campos adicionales (separados
   por "'-'") que representan los valores combinados de Versión de
   AIX, Release y Nivel de tecnología (primer campo), Fecha de
   Construcción (segundo campo) y tamaño de bits (tercer campo).
   Python 3.8 y anteriores retornaban solo un campo adicional con la
   versión y lanzamiento de AIX.

   Ejemplos de valores retornados en AIX:

   * "aix-5307-0747-32" # construcción 32-bit en AIX "oslevel -s":
     5300-07-00-0000

   * "aix-7105-1731-64" # construcción 64-bit en AIX "oslevel -s":
     7100-05-01-1731

   * "aix-7.2"          # Forma heredada informada en Python 3.8 y
     versiones anteriores

   Distinto en la versión 3.9: El formato de cadena de caracteres de
   la plataforma AIX ahora también incluye el nivel de tecnología, la
   fecha de construcción y el tamaño de bits de ABI.

distutils.util.convert_path(pathname)

   Retorna '*pathname*' (o nombre de ruta), como un nombre que
   funcionará en el sistema de archivos nativo, es decir, divídelo con
   '/' y vuelve a armarlo usando el separador de directorio actual.
   Necesario porque los nombres de archivo en el script de
   configuración siempre se proporcionan en estilo Unix y deben
   convertirse a la convención local antes de que podamos usarlos en
   el sistema de archivos. Lanza "ValueError" en sistemas que no son
   Unix-ish si *pathname* comienza o termina con una barra.

distutils.util.change_root(new_root, pathname)

   Retorna *pathname* con *new_root* precedido. Si *pathname* es
   relativo, esto es equivalente a "os.path.join (new_root,
   pathname)". De lo contrario, requiere hacer que *pathname* sea
   relativo y luego unir los dos, lo cual es complicado en
   DOS/Windows.

distutils.util.check_environ()

   Asegúrate de que '*os.environ*' tenga todas las variables de
   entorno garantizamos que los usuarios pueden usar en archivos de
   configuración, opciones de línea de comandos, etc. Actualmente,
   esto incluye:

   * "HOME" - directorio de inicio del usuario (solo Unix)

   * "PLAT" - descripción de la plataforma actual, incluido el
     hardware y el sistema operativo (consulta "get_platform()")

distutils.util.subst_vars(s, local_vars)

   Realiza la sustitución de variables de estilo shell/Perl en *s*.
   Cada aparición de "$" seguido de un nombre se considera una
   variable, y la variable se sustituye por el valor que se encuentra
   en el diccionario *local_vars*, o en "os.environ" si no está en
   *local_vars*. *os.environ* primero se comprueba/aumenta para
   garantizar que contiene ciertos valores: ver "check_environ()".
   Lanza "ValueError" para cualquier variable que no se encuentre en
   *local_vars* u "os.environ".

   Tenga en cuenta que esta no es una función de interpolación de
   cadenas completa. Un "$variable" válido solo puede constar de
   letras mayúsculas y minúsculas, números y un guión bajo. No hay
   comillas de estilo { } o ( ) disponibles.

distutils.util.split_quoted(s)

   Divide un string de acuerdo con las reglas de tipo *shell* de Unix
   para comillas y barras invertidas. En resumen: las palabras están
   delimitadas por espacios, siempre que esos espacios no se escapen
   con una barra invertida o dentro de un string entre comillas. Las
   comillas simples y dobles son equivalentes, y los caracteres de las
   comillas pueden tener un escape de barra invertida. La barra
   invertida se elimina de cualquier secuencia de escape de dos
   caracteres, dejando solo el carácter de escape. Los caracteres de
   comillas se eliminan de cualquier string entre comillas. Retorna
   una lista de palabras.

distutils.util.execute(func, args[, msg=None, verbose=0, dry_run=0])

   Realiza alguna acción que afecta al mundo exterior (por ejemplo,
   escribir en el sistema de archivos). Tales acciones son especiales
   porque están deshabilitadas por el indicador *dry_run*. Este método
   se encarga de toda esa burocracia por ti; todo lo que tienes que
   hacer es proporcionar la función a llamar y una tupla de argumentos
   para esta (para incorporar la "acción externa" que se está
   realizando), y un mensaje opcional para imprimir.

distutils.util.strtobool(val)

   Convierte una representación real de un string a verdadero (1) o
   falso (0).

   Los valores verdaderos son "y", "yes", "t", "true", "on" y "1"; los
   valores falsos son "n", "no", "f", "false", "off" and "0". Lanza
   "ValueError" si *val* es cualquier otra cosa.

distutils.util.byte_compile(py_files[, optimize=0, force=0, prefix=None, base_dir=None, verbose=1, dry_run=0, direct=None])

   *Byte-compile* es una colección de archivos fuente de Python de
   ".pyc" en un subdirectorio "__pycache__" (ver **PEP 3147** y **PEP
   488**). *py_files* es una lista de archivos para compilar;
   cualquier archivo que no termine en ".py" se omite silenciosamente.
   *optimize* debe ser uno de los siguientes:

   * "0" - no optimizar

   * "1" - optimización normal (como "python -O")

   * "2" - extra optimización (como "python -OO")

   Si *force* es verdadero, todos los archivos se vuelven a compilar
   independientemente de las marcas de tiempo.

   El nombre del archivo de origen codificado en cada archivo
   *bytecode* tiene por defecto los nombres de archivo listados en
   *py_files*; puede modificarlos con *prefix* y *basedir*. *prefix*
   es un string que se eliminará de cada nombre de archivo de origen,
   y *base_dir* es un nombre de directorio que se antepondrá (después
   de eliminar *prefix*). Puedes proporcionar uno o ambos (o ninguno)
   de *prefix* y * base_dir*, como desees.

   Si *dry_run* es verdadero, actualmente no hace nada que pueda
   afectar el sistema de archivos.

   La compilación de *bytes* se realiza directamente en este proceso
   de interpretación con el módulo estándar "py_compile", o
   indirectamente escribiendo un script temporal y ejecutándolo.
   Normalmente, debería dejar que "byte_compile()" se dé cuenta de si
   usar la compilación directa o no (consulta la fuente para obtener
   más detalles). El indicador *direct* es utilizado por el script
   generado en modo indirecto; a menos que sepa lo que está haciendo,
   se deja configurado en "None".

   Distinto en la versión 3.2.3: Crea archivos ".pyc" con una etiqueta
   mágica "import" en su nombre, en un subdirectorio "__pycache__" en
   lugar de archivos sin etiqueta en el directorio actual.

   Distinto en la versión 3.5: Crea archivos ".pyc" de acuerdo a **PEP
   488**.

distutils.util.rfc822_escape(header)

   Retorna una versión de *header* para su inclusión en un encabezado
   **RFC 822**, asegurándose de que haya 8 espacios después de cada
   nueva línea. Ten en cuenta que no hace ninguna otra modificación
   del string.


9.12. "distutils.dist" --- La clase *Distribution*
==================================================

Este módulo proporciona la clase "Distribution", que representa la
distribución del módulo que se está
construyendo/instalando/distribuyendo.


9.13. "distutils.extension" --- La clase *Extension*
====================================================

Este módulo proporciona la clase "Extension", que se utiliza para
describir los módulos de extensión C/C ++ en los scripts de
configuración.


9.14. "distutils.debug" --- modo de depuración *Distutils*
==========================================================

Este módulo proporciona el indicador *DEBUG*.


9.15. "distutils.errors" --- excepciones *Distutils*
====================================================

Proporciona excepciones utilizadas por los módulos *Distutils*. Ten en
cuenta que los módulos de Distutils pueden lanzar excepciones
estándar; en particular, *SystemExit* generalmente se lanza por
errores que obviamente son culpa del usuario final (por ejemplo,
argumentos incorrectos en la línea de comandos).

Este módulo es seguro de usar en el modo "from ... import*"; solo
exporta símbolos cuyos nombres comienzan con "Distutils" y terminan
con "Error".


9.16. "distutils.fancy_getopt" --- *Wrapper* alrededor del módulo estándar *getopt*
===================================================================================

Este módulo proporciona una envoltura alrededor del modulo estándar
"getopt" que proporciona las siguientes características adicionales:

* las opciones cortas y largas están unidas

* las opciones tienen strings de ayuda, por lo que "fancy_getopt()"
  podría potencialmente crear un resumen de uso completo

* las opciones establecen atributos de un objeto pasado

* las opciones booleanas pueden tener "alias negativos" --- p. ej. si
  "-quiet" es el "alias negativo" de "-verbose", entonces "-quiet" en
  la línea de comando establece falso a *verbose*.

distutils.fancy_getopt.fancy_getopt(options, negative_opt, object, args)

   Función *Wrapper*. *options* es una lista de "(*long_option*,
   *short_option*, *help_string*)" 3-tuplas como se describe en el
   constructor para "FancyGetopt". *negative_opt* debe ser un
   diccionario de mapeo de nombres de opciones a nombres de opciones,
   tanto la clave como el valor deben estar en la lista de *options*.
   *object* es un objeto que se usará para almacenar valores (ver el
   método "getopt()" de la clase "FancyGetopt"). *args* es la lista de
   argumentos. Usará "sys.argv [1:]" si pasa "None" como *args*.

distutils.fancy_getopt.wrap_text(text, width)

   Envuelve *text* a menos de *width* ancho.

class distutils.fancy_getopt.FancyGetopt([option_table=None])

   La opción option_table es una lista de 3 tuplas: "(long_option,
   short_option, help_string)"

   Si una opción toma un argumento, su *long_option* debería tener
   "'='" anexado; *short_option* debe ser solo un carácter, sin "':'"
   en cualquier caso. *short_option* debe ser "None" si *long_option*
   no tiene una *short_option* correspondiente. Todas las tuplas de
   opciones deben tener opciones largas.

La clase "FancyGetopt" proporciona los siguientes métodos:

FancyGetopt.getopt([args=None, object=None])

   Analiza las opciones de la línea de comandos en *args*. Almacena
   como atributos en *object*.

   Si *args* es "None" o no se proporciona, utiliza "sys.argv [1:]".
   Si *object* es "None" o no se proporciona, crea una nueva instancia
   "OptionDummy", que allí almacena valores de opción y retorna una
   tupla "(args, object)". Si se proporciona *object*, se modifica en
   su lugar y "getopt()" simplemente retorna *args*; en ambos casos,
   el *args* retornado es una copia modificada de la lista *args*
   pasada, que se deja intacta.

FancyGetopt.get_option_order()

   Retorna la lista de tuplas "(*option*, *value*)" procesadas por la
   ejecución anterior de "getopt()" Lanza "RuntimeError" si "getopt()"
   aún no se ha llamado.

FancyGetopt.generate_help([header=None])

   Genera un texto de ayuda (una lista de strings, una por cada línea
   de salida sugerida) de la tabla de opciones para este objeto
   "FancyGetopt".

   Si se suministra, imprime el *header* suministrado en la parte
   superior de la ayuda.


9.17. "distutils.filelist" --- La clase *FileList*
==================================================

Este módulo proporciona la clase "FileList", utilizada para hurgar en
el sistema de archivos y crear listas de archivos.


9.18. "distutils.log" --- Simple **PEP 282**-registro de estilo
===============================================================


9.19. "distutils.spawn" --- Genera un subproceso
================================================

Este módulo proporciona la función "spawn()", un *front-end* para
varias funciones específicas de la plataforma para iniciar otro
programa en un subproceso. También proporciona "find_executable()"
para buscar en la ruta un nombre ejecutable determinado.


9.20. "distutils.sysconfig" --- Información de configuración del sistema
========================================================================

Obsoleto desde la versión 3.10: "distutils.sysconfig" se ha fusionado
en "sysconfig".

El modulo "distutils.sysconfig" proporciona acceso a la configuración
de bajo nivel de Python. Las variables de configuración específicas
disponibles dependen en gran medida de la plataforma y la
configuración. Las variables específicas dependen del proceso de
compilación de la versión específica de Python que se está ejecutando;
las variables son las que se encuentran en el archivo "Makefile" y el
encabezado de configuración que se instalan con Python en sistemas
Unix. El encabezado de configuración se llama "pyconfig.h" para las
versiones de Python que comienzan con 2.2, y "config.h" para versiones
anteriores de Python.

Se proporcionan algunas funciones adicionales que realizan algunas
manipulaciones útiles para otras partes del paquete "distutils".

distutils.sysconfig.PREFIX

   El resultado de "os.path.normpath(sys.prefix)".

distutils.sysconfig.EXEC_PREFIX

   El resultado de "os.path.normpath(sys.exec_prefix)".

distutils.sysconfig.get_config_var(name)

   Retorna el valor de una sola variable. Esto es equivalente a
   "get_config_vars ().get(name)".

distutils.sysconfig.get_config_vars(...)

   Retorna un conjunto de definiciones de variables. Si no hay
   argumentos, esto retorna un diccionario que asigna los nombres de
   las variables de configuración a los valores. Si se proporcionan
   argumentos, deben ser strings y el valor de retorno será una
   secuencia que proporcione los valores asociados. Si un nombre de
   pila no tiene un valor correspondiente, se incluirá "None" para esa
   variable.

distutils.sysconfig.get_config_h_filename()

   Retorna el nombre completo de la ruta del encabezado de
   configuración. Para Unix, este será el encabezado generado por el
   script **configure**; para otras plataformas, el encabezado habrá
   sido proporcionado directamente por la distribución fuente de
   Python. El archivo es un archivo de texto específico de la
   plataforma.

distutils.sysconfig.get_makefile_filename()

   Retorna el nombre completo de la ruta del archivo "Makefile" usado
   para construir Python. Para Unix, este será un archivo generado por
   el script **configure**; el significado para otras plataformas
   variará. El archivo es un archivo de texto específico de la
   plataforma, si existe. Esta función solo es útil en plataformas
   POSIX.

Las siguientes funciones están obsoletas junto con este módulo y no
tienen reemplazo directo.

distutils.sysconfig.get_python_inc([plat_specific[, prefix]])

   Retorna el directorio para los archivos de inclusión de C generales
   o dependientes de la plataforma. Si *plat_specific* es verdadero,
   se retorna el directorio de inclusión dependiente de la plataforma;
   si es falso o se omite, se retorna el directorio independiente de
   la plataforma. Si se proporciona *prefix*, se usa como prefijo en
   lugar de "PREFIX", o como *exec-prefix* en lugar de "EXEC_PREFIX"
   si *plat_specific* es verdadero.

distutils.sysconfig.get_python_lib([plat_specific[, standard_lib[, prefix]]])

   Retorna el directorio para la instalación de la biblioteca general
   o dependiente de la plataforma. Si *plat_specific* es verdadero, se
   retorna el directorio de inclusión dependiente de la plataforma; si
   es falso o se omite, se retorna el directorio independiente de la
   plataforma. Si se proporciona *prefix*, se usa como prefijo en
   lugar de "PREFIX", o como *exec-prefix* en lugar de "EXEC_PREFIX"
   si *plat_specific* es verdadero. Si *standard_lib* es verdadero, se
   retorna el directorio de la biblioteca estándar en lugar del
   directorio para la instalación de extensiones de terceros.

La siguiente función solo está pensada para su uso dentro del paquete
"distutils".

distutils.sysconfig.customize_compiler(compiler)

   Realiza cualquier personalización específica de la plataforma de
   una instancia "distutils.ccompiler.CCompiler".

   Esta función solo es necesaria en Unix en este momento, pero se
   debe llamar de manera consistente para admitir la compatibilidad
   con versiones posteriores. Inserta la información que varía según
   los tipos de Unix y se almacena en el archivo de Python "Makefile".
   Esta incluye el compilador seleccionado, las opciones del
   compilador y del enlazador, y la extensión utilizada por el
   enlazador para los objetos compartidos.

Esta función tiene un propósito aún más especial y solo debe usarse
desde los propios procedimientos de compilación de Python.

distutils.sysconfig.set_python_build()

   Informa al módulo "distutils.sysconfig" que se está utilizando como
   parte del proceso de compilación de Python. Esto cambia muchas
   ubicaciones relativas de los archivos, lo que les permite ubicarse
   en el área de compilación en lugar de en un Python instalado.


9.21. "distutils.text_file" --- La clase *TextFile*
===================================================

Este módulo proporciona la clase "TextFile", que proporciona una
interfaz a los archivos de texto que (opcionalmente) se encarga de
eliminar los comentarios, ignorar las líneas en blanco y unir líneas
con barras invertidas.

class distutils.text_file.TextFile([filename=None, file=None, **options])

   Esta clase proporciona un objeto similar a un archivo que se
   encarga de todas las cosas que comúnmente desea hacer al procesar
   un archivo de texto que tiene alguna sintaxis línea por línea:
   elimina comentarios (siempre que "#" sea su carácter de
   comentario), omite líneas en blanco, une líneas adyacentes
   escapando de la nueva línea (es decir, barra invertida al final de
   la línea), elimina los espacios en blanco iniciales o finales.
   Todos estos son opcionales y controlables de forma independiente.

   La clase proporciona un método "warn()" para que pueda generar
   mensajes de advertencia que informen el número de línea física,
   incluso si la línea lógica en cuestión abarca varias líneas
   físicas. También proporciona "unreadline()" para implementar una
   búsqueda anticipada de línea a la vez.

   Las instancias de "TextFile" se crean con *filename*, *file* o
   ambos. "RuntimeError" se lanza si ambos son "None". *filename* debe
   ser un string, y *file* un archive de objeto (o algo que
   proporcione los métodos "readline()" y "close()"). Se recomienda
   que proporcione al menos *filename*, para que "TextFile" pueda
   incluirlo en mensajes de advertencia. Si no se proporciona *file*,
   "TextFile" crea uno propio usando la función incorporada "open()".

   Todas las opciones son booleanas y afectan los valores retornados
   por "readline()"

   +--------------------+----------------------------------+-----------+
   | nombre de la       | descripción                      | predeter  |
   | opción             |                                  | minado    |
   |====================|==================================|===========|
   | *strip_comments*   | elimina desde "'#'" hasta el     | verdadero |
   |                    | final de la línea, así como      |           |
   |                    | cualquier espacio en blanco que  |           |
   |                    | conduzca al "'#'" --- a menos    |           |
   |                    | que se escape por una barra      |           |
   |                    | invertida                        |           |
   +--------------------+----------------------------------+-----------+
   | *lstrip_ws*        | elimina los espacios en blanco   | falso     |
   |                    | iniciales de cada línea antes de |           |
   |                    | retornarlo                       |           |
   +--------------------+----------------------------------+-----------+
   | *rstrip_ws*        | elimina los espacios en blanco   | verdadero |
   |                    | finales (incluido el terminador  |           |
   |                    | de línea!) de cada línea antes   |           |
   |                    | de retornarlo.                   |           |
   +--------------------+----------------------------------+-----------+
   | *skip_blanks*      | omite las líneas que están       | verdadero |
   |                    | vacías * después de* elimina los |           |
   |                    | comentarios y los espacios en    |           |
   |                    | blanco. (Si tanto *lstrip_ws*    |           |
   |                    | como *rstrip_ws* son falsos,     |           |
   |                    | algunas líneas pueden consistir  |           |
   |                    | únicamente en espacios en        |           |
   |                    | blanco: estos no se omitirán,    |           |
   |                    | incluso si *skip_blanks* es      |           |
   |                    | verdadero).                      |           |
   +--------------------+----------------------------------+-----------+
   | *join_lines*       | si una barra invertida es el     | falso     |
   |                    | último carácter que no es una    |           |
   |                    | nueva línea en una línea después |           |
   |                    | de eliminar los comentarios y    |           |
   |                    | los espacios en blanco, únela a  |           |
   |                    | la siguiente línea para formar   |           |
   |                    | una línea lógica; si N líneas    |           |
   |                    | consecutivas terminan con una    |           |
   |                    | barra invertida, entonces N + 1  |           |
   |                    | líneas físicas se unirán para    |           |
   |                    | formar una línea lógica.         |           |
   +--------------------+----------------------------------+-----------+
   | *collapse_join*    | elimina los espacios en blanco   | falso     |
   |                    | iniciales de las líneas que      |           |
   |                    | están unidas a su predecesor;    |           |
   |                    | solo importa si "(*join_lines* y |           |
   |                    | no *lstrip_ws*)"                 |           |
   +--------------------+----------------------------------+-----------+

   Ten en cuenta que, dado que *rstrip_ws* puede eliminar la nueva
   línea final, la semántica de "readline()" debe diferir de las del
   método "readline()" del objeto de archivo integrado. En particular,
   "readline()" retorna "None" para el final del archivo: un string
   vacío puede ser solo una línea en blanco (o una línea con espacios
   en blanco), si *rstrip_ws* es verdadero pero *skip_blanks* no es.

   open(filename)

      Abre un nuevo archivo *filename*. Esto anula cualquier *file* o
      *filename* argumentado del constructor.

   close()

      Cierra el archivo actual y olvida todo lo que sabemos sobre él
      (incluido el nombre del archivo y el número de línea actual).

   warn(msg[, line=None])

      Imprime (a *stderr*) un mensaje de advertencia vinculado a la
      línea lógica actual en el archivo actual. Si la línea lógica
      actual en el archivo abarca varias líneas físicas, la
      advertencia se refiere a todo el rango, como ""lines 3-5"". Si
      se proporciona *line*, anula el número de línea actual; puede
      ser una lista o tupla para indicar un rango de líneas físicas, o
      un número entero para una sola línea física.

   readline()

      Lee y retorna una sola línea lógica del archivo actual (o de un
      búfer interno si las líneas han sido "no leídas" previamente con
      "unreadline()"). Si la opción *join_lines* es verdadera, esto
      puede implicar la lectura de varias líneas físicas concatenadas
      en una sola cadena. Actualiza el número de línea actual, por lo
      que llamar a "warn()" después "readline()" emite una advertencia
      sobre las líneas físicas que acaba de leer. Retorna "None" al
      final del archivo, ya que un string vacío puede aparecer si
      *rstrip_ws* es verdadero pero *strip_blanks* no lo es.

   readlines()

      Lee y retorna la lista de todas las líneas lógicas restantes en
      el archivo actual. Esto actualiza el número de línea actual a la
      última línea del archivo.

   unreadline(line)

      Empuja *line* (un string) en un búfer interno que será
      verificado por futuras llamadas a "readline()". Útil para
      implementar un analizador con búsqueda anticipada de línea a la
      vez. Tenga en cuenta que las líneas que están "no leídas" con
      "unreadline()" no se vuelven a limpiar posteriormente (se
      eliminan los espacios en blanco o lo que sea) cuando se leen con
      "readline()". Si se realizan varias llamadas a "unreadline()"
      antes de una llamada a "readline()", la mayoría de las líneas se
      retornarán en el primer orden más reciente.


9.22. "distutils.version" --- Clases de número de versión
=========================================================


9.23. "distutils.cmd" --- Clase base abstracta para comandos *Distutils*
========================================================================

Este módulo proporciona la clase base abstracta "Command".

class distutils.cmd.Command(dist)

   La clase base abstracta para definir clases de comando, las
   "*worker bees*" de *Distutils*. Una analogía útil para las clases
   de comando es pensar en ellas como subrutinas con variables locales
   llamadas *options*. Las opciones se declaran en
   "initialize_options()" y se definen (dados sus valores finales) en
   "finalize_options()", los cuales deben ser definidos por cada clase
   de comando. La distinción entre los dos es necesaria porque los
   valores de las opciones pueden provenir del mundo exterior (línea
   de comando, archivo de configuración, ...), y cualquier opción que
   dependa de otras opciones debe calcularse después de que se hayan
   procesado estas influencias externas --- por lo tanto
   "finalize_options()". El cuerpo de la subrutina, donde hace todo su
   trabajo basado en los valores de sus opciones, es el método
   "run()", que también debe ser implementado por cada clase de
   comando.

   El constructor de la clase toma un solo argumento *dist*, una
   instancia "Distribution".


9.24. Creando un nuevo comando *Distutils*
==========================================

Esta sección describe los pasos para crear un nuevo comando
*Distutils*.

Un nuevo comando reside en un módulo en el paquete
"distutils.command". Hay una plantilla de muestra en ese directorio
llamada "command_template". Copia este archivo en un nuevo módulo con
el mismo nombre que el nuevo comando que está implementando. Este
módulo debe implementar una clase con el mismo nombre que el módulo (y
el comando). Entonces, por ejemplo, para crear el comando
"peel_banana" (para que los usuarios puedan ejecutar "setup.py
peel_banana"), deben copiar "command_template" a
"distutils/command/peel_banana.py", luego edítelo para que implemente
la clase "peel_banana", una subclase de "distutils.cmd.Command".

Las subclases de "Command" deben definir los siguientes métodos.

Command.initialize_options()

   Establece valores predeterminados para todas las opciones que
   admite este comando. Ten en cuenta que estos valores
   predeterminados pueden ser anulados por otros comandos, por el
   script de configuración, por los archivos de configuración o por la
   línea de comandos. Por tanto, este no es el lugar para codificar
   dependencias entre opciones; generalmente, las implementaciones de
   "initialize_options()" son solo un montón de asignaciones "self.fo
   = None" .

Command.finalize_options()

   Establece valores finales para todas las opciones que admite este
   comando. Esto siempre se llama lo más tarde posible, es decir.
   después de que se hayan realizado las asignaciones de opciones
   desde la línea de comandos o desde otros comandos. Por lo tanto,
   este es el lugar para codificar las dependencias de opciones: si
   *foo* depende de *bar*, entonces es seguro establecer *foo* desde
   *bar* siempre que *foo* todavía tenga el mismo valor que se asignó
   en "initialize_options()".

Command.run()

   La razón de ser de un comando: llevar a cabo la acción que debe
   realizar, controlada por las opciones inicializadas en
   "initialize_options()", personalizadas por otros comandos, el
   script de configuración, la línea de comandos y los archivos de
   configuración, y finalizadas en "finalize_options()". Toda la
   salida de la terminal y la interacción del sistema de archivos debe
   realizarse mediante "run()".

Command.sub_commands

   *sub_commands* formaliza la noción de una "familia" de comandos, p.
   ej. "install" como padre con subcomandos "install_lib",
   "install_headers", etc. El padre de una familia de comandos define
   *sub_commands* como un atributo de clase; es una lista de 2 tuplas
   "(command_name, predicate)", con *command_name* un string y
   *predicate* una función, un string o "None". *predicate* es un
   método del comando padre que determina si el comando
   correspondiente es aplicable en la situación actual. (Por ejemplo,
   "install_headers" solo es aplicable si tenemos archivos de
   encabezado C para instalar). Si *predicate* es "None", ese comando
   siempre es aplicable.

   *sub_commands* generalmente se define al *end* de una clase, porque
   los predicados pueden ser métodos de la clase, por lo que ya deben
   haber sido definidos. El ejemplo canónico es el comando
   **install**.


9.25. "distutils.command" --- Comandos individuales de *Distutils*
==================================================================


9.26. "distutils.command.bdist" --- Construye un instalador binario
===================================================================


9.27. "distutils.command.bdist_packager" --- Clase base abstracta para empaquetadores
=====================================================================================


9.28. "distutils.command.bdist_dumb" --- Construye un instalador "*dump*"
=========================================================================


9.29. "distutils.command.bdist_rpm" --- Construye una distribución binaria como RedHat RPM y SRPM
=================================================================================================


9.30. "distutils.command.sdist" --- Construye una distribución de código fuente
===============================================================================


9.31. "distutils.command.build" --- Construye todos los archivos de un paquete
==============================================================================


9.32. "distutils.command.build_clib" --- Construye cualquier biblioteca C en un paquete
=======================================================================================


9.33. "distutils.command.build_ext" --- Construye cualquier extensión en un paquete
===================================================================================


9.34. "distutils.command.build_py" --- Construye los archivos .py/.pyc de un paquete
====================================================================================

class distutils.command.build_py.build_py

class distutils.command.build_py.build_py_2to3

   Implementación alternativa de *build_py* que también ejecuta la
   biblioteca de conversión *2to3* en cada archivo .py que se va a
   instalar. Para usar esto en un archivo *setup.py* de una
   distribución que está diseñada para ejecutarse con Python 2.x y
   3.x, agrega:

      try:
          from distutils.command.build_py import build_py_2to3 as build_py
      except ImportError:
          from distutils.command.build_py import build_py

   a su *setup.py*, y posteriormente:

      cmdclass = {'build_py': build_py}

   a la invocación de configuración setup().


9.35. "distutils.command.build_scripts" --- Construye los scripts de un paquete
===============================================================================


9.36. "distutils.command.clean" --- Limpia el área de construcción de un paquete
================================================================================

Este comando elimina los archivos temporales creados por el comando
**build** y sus subcomandos, como archivos de objeto compilados
intermediarios. Con la opción "--all", se eliminará el directorio de
compilación completo.

Los módulos de extensión construidos in place no se limpiarán, ya que
no están en el directorio de construcción.


9.37. "distutils.command.config" --- Realiza la configuración de un paquete
===========================================================================


9.38. "distutils.command.install" --- Instala un paquete
========================================================


9.39. "distutils.command.install_data" --- Instala archivos de datos de un paquete
==================================================================================


9.40. "distutils.command.install_headers" --- Instala archivos de encabezado C/C++ desde un paquete
===================================================================================================


9.41. "distutils.command.install_lib" --- Instala archivos de biblioteca desde un paquete
=========================================================================================


9.42. "distutils.command.install_scripts" --- Instala archivos de script desde un paquete
=========================================================================================


9.43. "distutils.command.register" --- Registra un módulo con el índice de paquetes de Python
=============================================================================================

El comando "register" registra el paquete con el índice de paquetes de
Python. Esto se describe con más detalle en **PEP 301**.


9.44. "distutils.command.check" --- Verificar los metadatos de un paquete
=========================================================================

El comando "check" realiza algunas pruebas en los metadatos de un
paquete. Por ejemplo, verifica que todos los metadatos requeridos se
proporcionen como argumentos pasados a la función "setup()".
