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ónsetup
y otras API, hace que la API sea coherente en diferentes versiones de Python y, por lo tanto, se recomienda usardistutils
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 actualmente se incluye 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ónsetup()
), 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ónsetup()
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 claseDistribution
.)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ódulodistutils.extension
la clase
Command
del módulodistutils.cmd
la clase
Distribution
del módulodistutils.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 oNone
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ónsetup()
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.
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 porsys.platform
para la plataforma en cuestión.Los valores predeterminados son
os.name
ysys.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» (claseUnixCCompiler
) y Visual C++ (claseMSVCCompiler
). 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 deCCompiler
o una de sus subclases directamente; usa la función de fábricadistutils.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 aadd_include_dir()
agrega a la lista pasada aset_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/oset_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()
yset_libraries()
. Se le indicará al enlazador que busque bibliotecas en el orden en que se suministran aadd_library_dir()
y/oset_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 porundefine_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 acompile()
), 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) ylanguage_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 enfoo/bar.o
(para una implementación de Unix); si output_dir es build, entonces se compilaría enbuild/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 esNone
, 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/oset_link_objects()
, las bibliotecas suministradas aadd_library()
y/oset_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 yfoo.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/oset_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()
ycreate_static_lib()
, con la ligera distinción de que en realidad es relevante en la mayoría de las plataformas (a diferencia decreate_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()
.
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()
.
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 condefine_macro()
yundefine_macro()
. include_dirs es una lista de nombres de directorio que se agregarán a la lista predeterminada, de la misma manera queadd_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 formaliblibname.a
, mientras que lib_type de'dynamic'
tendrá la formaliblibname.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.
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.
-
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
otar
). base_name es el nombre del archivo a crear, menos cualquier extensión específica del formato; format es el formato de archivo: comozip
,tar
,gztar
,bztar
,xztar
oztar
. root_dir es un directorio que será el directorio raíz del archivo; es decir, normalmentechdir
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
” oNone
. 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 archivotar
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 Pythonzipfile
(si está disponible) o la utilidad InfoZIPzip
(si está instalada y se encuentra en la ruta de búsqueda predeterminada). Si ninguna de las herramientas está disponible, lanzaDistutilsExecError
. 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 unOSError
desdeos.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 conmkpath()
. 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 paracopy_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 (usandoos.symlink()
) en lugar de copiar: configúralo en'hard'
o'sym'
; si esNone
(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 Mac OS X, 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 Mac OS X, 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 esfat64
y para los binarios universales de 4 vías la arquitectura esuniversal
. A partir de Python 2.7 y Python 3.2, la arquitecturafat3
se usa para una compilación universal de 3 vías (ppc, i386, x86_64) eintel
se usa para una compilación universal con las arquitecturas i386 y x86_64Ejemplos de valores retornados en Mac OS X:
macosx-10.3-ppc
macosx-10.3-fat
macosx-10.5-universal
macosx-10.6-intel
-
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 (consultaget_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 enos.environ
si no está en local_vars. os.environ primero se comprueba/aumenta para garantizar que contiene ciertos valores: vercheck_environ()
. LanzaValueError
para cualquier variable que no se encuentre en local_vars uos.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
y1
; los valores falsos sonn
,no
,f
,false
,off
and0
. LanzaValueError
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 optimizar1
- optimización normal (comopython -O
)2
- extra optimización (comopython -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 quebyte_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 enNone
.Distinto en la versión 3.2.3: Crea archivos
.pyc
con una etiqueta mágicaimport
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.
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 completolas 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 paraFancyGetopt
. 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étodogetopt()
de la claseFancyGetopt
). args es la lista de argumentos. Usarásys.argv [1:]
si pasaNone
como args.
-
distutils.fancy_getopt.
wrap_text
(text, width)¶ Envuelve text a menos de width ancho.
-
class
distutils.fancy_getopt.
FancyGetopt
([option_table=None])¶ 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, utilizasys.argv [1:]
. Si object esNone
o no se proporciona, crea una nueva instanciaOptionDummy
, que allí almacena valores de opción y retorna una tupla(args, object)
. Si se proporciona object, se modifica en su lugar ygetopt()
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 degetopt()
LanzaRuntimeError
sigetopt()
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 deEXEC_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 deEXEC_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 proporcionaunreadline()
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 sonNone
. filename debe ser un string, y file un archive de objeto (o algo que proporcione los métodosreadline()
yclose()
). Se recomienda que proporcione al menos filename, para queTextFile
pueda incluirlo en mensajes de advertencia. Si no se proporciona file,TextFile
crea uno propio usando la función incorporadaopen()
.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 invertidaverdadero
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étodoreadline()
del objeto de archivo integrado. En particular,readline()
retornaNone
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 awarn()
despuésreadline()
emite una advertencia sobre las líneas físicas que acaba de leer. RetornaNone
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» conunreadline()
no se vuelven a limpiar posteriormente (se eliminan los espacios en blanco o lo que sea) cuando se leen conreadline()
. Si se realizan varias llamadas aunreadline()
antes de una llamada areadline()
, 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) enfinalize_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 tantofinalize_options()
. El cuerpo de la subrutina, donde hace todo su trabajo basado en los valores de sus opciones, es el métodorun()
, 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 asignacionesself.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 enfinalize_options()
. Toda la salida de la terminal y la interacción del sistema de archivos debe realizarse medianterun()
.
-
Command.
sub_commands
¶ sub_commands formaliza la noción de una «familia» de comandos, p. ej.
install
como padre con subcomandosinstall_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 oNone
. 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 esNone
, 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
¶ 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 instaladorbdist_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()
.