This document is for an old version of Python that is no longer supported. You should upgrade, and read the Python documentation for the current stable release.

# 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

This document is being retained solely until the `setuptools` documentation at https://setuptools.readthedocs.io/en/latest/setuptools.html independently covers all of the relevant information currently included here.

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

`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 extensión, incluidos los paquetes — es decir, no un nombre de archivo o ruta, sino un nombre punteado Python | un string
  sources | lista de nombres de archivos de 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. | una lista de strings
  include_dirs | lista de los directorios para buscar archivos de encabezados de C/C++ (en forma de Unix para portabilidad) | una lista de strings
  define_macros | lista de macros para definir; 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) | una lista de tuplas
  undef_macros | lista de macros para indefinir explícitamente | una lista de strings
  library_dirs | lista de directorios para buscar bibliotecas C/C++ en el momento del enlace | una lista de strings
  libraries | lista de nombres de bibliotecas para vincular (no nombres de archivos o rutas) | una lista de strings
  runtime_library_dirs | lista de directorios para buscar bibliotecas C/C++ en tiempo de ejecución (para extensiones compartidas, esto es cuando se carga una extensión) | una lista de strings
  extra_objects | lista de archivos adicionales 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.) | una lista de strings
  extra_compile_args | cualquier adicional específico 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. | una lista de strings
  extra_link_args | cualquier adicional específico 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*. | una lista de strings
  export_symbols | lista de símbolos que se 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. | una lista de strings
  depends | lista de archivos de los que depende la extensión | una lista de strings
  language | lenguaje de extensión (es decir, `'c'`, `'c++'`, `'objc'`). Se detectará en las extensiones de origen si no se proporcionan. | un string
  optional | especifica que una falla de compilación en la extensión no debe abortar el proceso de compilación, sino simplemente omitir la extensión. | un booleano

  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()`.

  Los archivos en src que comienzan con `.nfs` se omiten (hay más sobre estos archivos disponible en la respuesta D2 de la página de preguntas frecuentes de`NFS <http://nfs.sourceforge.net/#section_d>`_ ).

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

  For macOS systems the OS version reflects the minimal version on which binaries will run (that is, the value of `MACOSX_DEPLOYMENT_TARGET` during the build of Python), not the OS version of the current system.

  For universal binary builds on macOS the architecture value reflects the universal binary status instead of the architecture of the current processor. For 32-bit universal binaries the architecture is `fat`, for 64-bit universal binaries the architecture is `fat64`, and for 4-way universal binaries the architecture is `universal`. Starting from Python 2.7 and Python 3.2 the architecture `fat3` is used for a 3-way universal build (ppc, i386, x86_64) and `intel` is used for a universal build with the i386 and x86_64 architectures

  Examples of returned values on 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`.

  Ten en cuenta que esta no es una función de interpolación de string completa. Una `$ variable` válida que puede constar solo de letras mayúsculas y minúsculas, números y un guión bajo. No hay citas 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: option:!-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

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.

`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 opción | descripción | predeterminado
  --- | --- | ---
  strip_comments | elimina desde `'#'` hasta el final de la línea, así como cualquier espacio en blanco que conduzca al `'#'` — a menos que se escape por una barra invertida | verdadero
  lstrip_ws | elimina los espacios en blanco iniciales de cada línea antes de retornarlo | falso
  rstrip_ws | elimina los espacios en blanco finales (incluido el terminador de línea!) de cada línea antes de retornarlo. | verdadero
  skip_blanks | omite las líneas que están 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). | verdadero
  join_lines | si una barra invertida es el ú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. | falso
  collapse_join | elimina los espacios en blanco iniciales de las líneas que están unidas a su predecesor; solo importa si `(*join_lines* y no *lstrip_ws*)` | falso

  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_msi` — Construye un paquete binario instalador de Microsoft

class `distutils.command.bdist_msi.``bdist_msi`

Obsoleto desde la versión 3.9: Utiliza bdist_wheel (paquetes wheel) en su lugar.

Construye un paquete binario Windows Installer (.msi)

En la mayoría de los casos, el instalador `bdist_msi` es una mejor opción que el instalador `bdist_wininst`, porque proporciona un mejor soporte para plataformas Win64, permite a los administradores realizar instalaciones no interactivas y permite la instalación a través de políticas de grupo.

## 9.30. `distutils.command.bdist_rpm` — Construye una distribución binaria como RedHat RPM y SRPM

## 9.31. `distutils.command.bdist_wininst` — Construye un instalador de Windows

Obsoleto desde la versión 3.8: Utiliza bdist_wheel (paquetes wheel) en su lugar.

## 9.32. `distutils.command.sdist` — Construye una distribución de código fuente

## 9.33. `distutils.command.build` — Construye todos los archivos de un paquete

## 9.34. `distutils.command.build_clib` — Construye cualquier biblioteca C en un paquete

## 9.35. `distutils.command.build_ext` — Construye cualquier extensión en un paquete

## 9.36. `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.37. `distutils.command.build_scripts` — Construye los scripts de un paquete

## 9.38. `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.39. `distutils.command.config` — Realiza la configuración de un paquete

## 9.40. `distutils.command.install` — Instala un paquete

## 9.41. `distutils.command.install_data` — Instala archivos de datos de un paquete

## 9.42. `distutils.command.install_headers` — Instala archivos de encabezado C/C++ desde un paquete

## 9.43. `distutils.command.install_lib` — Instala archivos de biblioteca desde un paquete

## 9.44. `distutils.command.install_scripts` — Instala archivos de script desde un paquete

## 9.45. `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.46. `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()`.