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

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