¿Qué argumentos de palabras clave acepta setuptools.setup ()?

¿Cuál es la lista completa de argumentos de palabras clave que acepta la función setuptools.setup ()? (Incluya una descripción de lo que significa cada argumento, si es posible).

He buscado en toda la web y no puedo creer que esto no esté documentado.

Encontré estos documentos:

• https://docs.python.org/3.7/distutils/setupscript.html#additional-meta-data
• https://setuptools.readthedocs.io/en/latest/setuptools.html#new-and-changed-setup-keywords

Pero incluso cuando combino estos, les faltan otros argumentos como

• guiones
• paquetes
• proporciona
• obsoletos

... y no sé cuántos argumentos más faltan.

¿Cuál es la lista completa de argumentos de palabras clave que acepta la función setuptools.setup ()?

setuptools.setup()llama distutils.core.setup()y pasa es **kwargsel único parámetro, por lo que cualquier palabra clave que distutilsacepte también será aceptada por setuptools. Si vamos miramosdistutils

    setup_keywords = ('distclass', 'script_name', 'script_args', 
                      'options', 'name', 'version', 'author', 
                      'author_email', 'maintainer', 'maintainer_email', 
                      'url', 'license', 'description', 
                      'long_description', 'keywords', 'platforms', 
                      'classifiers', 'download_url', 'requires', 
                      'provides', 'obsoletes',
                  )

La mayoría de estos están documentados aquí , pero algunos no están incluidos en la tabla: paquetes , package_dir , package_data , guiones , obsoletos , proviodes , py_modules y data_files .

Algunos de estos también faltan en la setup_keywordstupla. Y si lo buscas setup_keywordsno parece que en realidad esté referenciado en ningún lado ... Pero esa es una historia para otro día. De todos modos, aquí está la lista (con suerte completa).

argumentos de palabras clave distutils.core.setup ()

( Obligatorio : nombre , versión y al menos uno del autor o mantenedor )

autor:

nombre del autor del paquete (obligatorio si no se proporciona el responsable del mantenimiento)

autor_email:

dirección de correo electrónico del autor del paquete

clasificadores:

una lista de clasificadores (ver: https://pypi.org/classifiers/ )

data_files :

La data_filesopción se puede utilizar para especificar archivos adicionales necesarios para la distribución del módulo: archivos de configuración, catálogos de mensajes, archivos de datos, cualquier cosa que no se ajuste a las categorías anteriores.

data_filesespecifica una secuencia de (directory, files)pares de la siguiente manera:

setup(...,
      data_files=[('bitmaps', ['bm/b1.gif', 'bm/b2.gif']),
                  ('config', ['cfg/data.cfg'])],
     )

Cada (directory, files)par en la secuencia especifica el directorio de instalación y los archivos para instalar allí. Cada nombre de archivo en los archivos se interpreta en relación con el setup.pyscript.

descripción:

Descripción breve y resumida del paquete

download_url:

ubicación donde se puede descargar el paquete

palabras clave:

una lista de palabras clave (también toma una cadena. Si se separa por comas, se divide en una lista)

licencia:

licencia para el paquete (Úselo solo si la licencia no figura en la lista de "clasificadores de tesoros". Consulte: Clasificadores)

descripción larga:

Descripción más larga del paquete, utilizada por PyPI para construir la página del proyecto.

mantenedor:

nombre del responsable del paquete (obligatorio si no se proporciona el autor)

mantenedor_email:

dirección de correo electrónico del mantenedor del paquete

nombre:

nombre del paquete (requerido por distutils)

obsoletos :

Un paquete puede declarar que obsoleto otros paquetes usando el obsoletesargumento de la palabra clave. El valor para esto es similar al de la requirespalabra clave: una lista de cadenas que dan especificadores de módulo o paquete. Cada especificador consta de un nombre de módulo o paquete opcionalmente seguido de uno o más calificadores de versión. Los calificadores de versión se dan entre paréntesis después del nombre del módulo o paquete

paquete_datos :

Los datos del paquete se pueden agregar a los paquetes utilizando el package_dataargumento de palabra clave para la setup()función. El valor debe ser una asignación del nombre del paquete a una lista de nombres de ruta relativos que deben copiarse en el paquete. Las rutas se interpretan como relativas al directorio que contiene el paquete (la información de la package_dirasignación se usa si corresponde); es decir, se espera que los archivos formen parte del paquete en los directorios de origen.

package_dir :

Si usa una convención diferente para diseñar su directorio de origen, no hay problema: solo tiene que proporcionar la package_diropción de informar a Distutils sobre su convención. Por ejemplo, supongamos que mantiene toda la fuente de Python debajo lib, de modo que los módulos en el "paquete raíz" (es decir, que no estén en ningún paquete) estén dentro lib, los módulos en el foopaquete estén dentro lib/foo, etc. Entonces pondrías

package_dir = {'': 'lib'}

en tu script de configuración. Las claves de este diccionario son nombres de paquetes, y un nombre de paquete vacío representa el paquete raíz. Los valores son nombres de directorio relativos a su raíz de distribución. En este caso, cuando dices packages = ['foo'], estás prometiendo que el archivo lib/foo/__init__.pyexiste.

Otra posible convención es colocar el foopaquete directamente lib, el foo.barpaquete lib/bar, etc. Esto se escribiría en el script de configuración como

package_dir = {'foo': 'lib'}

Una package: direntrada en el package_dirdiccionario se aplica implícitamente a todos los paquetes debajo del paquete, por lo que el foo.barcaso se maneja automáticamente aquí. En este ejemplo, haber packages = ['foo', 'foo.bar']le dice a Distutils que busque lib/__init__.pyy lib/bar/__init__.py. (Tenga en cuenta que, aunque se package_diraplica de forma recursiva, debe enumerar explícitamente todos los paquetes en paquetes: Distutils no escaneará de forma recursiva su árbol de origen buscando ningún directorio con un __init__.pyarchivo).

paquetes :

Los datos del paquete se pueden agregar a los paquetes utilizando el package_dataargumento de palabra clave para la setup()función. El valor debe ser una asignación del nombre del paquete a una lista de nombres de ruta relativos que deben copiarse en el paquete. Las rutas se interpretan como relativas al directorio que contiene el paquete (la información de la package_dirasignación se usa si corresponde); es decir, se espera que los archivos formen parte del paquete en los directorios de origen. También pueden contener patrones glob.

plataformas:

una lista de plataformas (también toma una cadena. Si está separada por comas, se divide en una lista)

proporciona :

Ahora que podemos especificar dependencias, también debemos poder especificar qué proporcionamos que otras distribuciones pueden requerir. Esto se hace usando el providesargumento de palabra clave to setup().

py_modules :

Para una distribución de módulos pequeños, es posible que prefiera enumerar todos los módulos en lugar de enumerar los paquetes, especialmente el caso de un solo módulo que va en el "paquete raíz" (es decir, ningún paquete en absoluto).

py_modules = ['foo.py']

Aquí hay un ejemplo un poco más complicado:

py_modules = ['mod1', 'pkg.mod2']

Esto describe dos módulos, uno de ellos en el paquete "raíz", el otro en el pkgpaquete. Nuevamente, el diseño predeterminado del paquete / directorio implica que estos dos módulos se pueden encontrar en mod1.pyy pkg/mod2.py, y eso también pkg/__init__.pyexiste. Y nuevamente, puede anular la correspondencia paquete / directorio utilizando la package_diropción

guiones :

Los scripts son archivos que contienen el código fuente de Python, destinados a iniciarse desde la línea de comandos. Los scripts no requieren que Distutils haga nada muy complicado. La única característica inteligente es que si la primera línea del script comienza con #!y contiene la palabra "python", Distutils ajustará la primera línea para referirse a la ubicación actual del intérprete. Por defecto, se reemplaza con la ubicación actual del intérprete. La opción --ejecutable (o -e) permitirá que la ruta del intérprete se anule explícitamente.

La opción de secuencias de comandos simplemente es una lista de archivos que se manejarán de esta manera. Desde el script de configuración PyXML:

    setup(...,
          scripts=['scripts/xmlproc_parse', 'scripts/xmlproc_val']
          )

url:

página de inicio del paquete

versión:

versión de esta versión (requerida por distutils)

argumentos de la palabra clave setuptools.setup ()

Hay incluso más argumentos que setuptools.setup()aceptarán, más allá de los que son utilizados por distutils.

Aunque se llama "Palabras clave de configuración nuevas y modificadas" (que para mí sugiere un registro de cambios de versión), el texto de introducción dice que son "argumentos de palabras clave para la configuración () [que son] agregados o modificados por las herramientas de configuración", por lo que creo que el enlace realmente proporciona Una lista completa. Lo agregaré aquí para completar.

(Desde setuptools.setup()las llamadas distutils.core.setup(), los mismos parámetros son requeridos : nombre , versión , y al menos uno de autor o mantenedor )

convert_2to3_doctests:

Lista de los archivos de origen de doctest que deben convertirse con 2to3. Consulte Soporte de Python 2 y Python 3 con Setuptools para más detalles.

enlaces_dependencia:

Una lista de cadenas que nombran URL para buscar cuando se satisfacen dependencias. Estos enlaces se usarán si es necesario para instalar paquetes especificados por setup_requires o tests_require. También se escribirán en los metadatos del huevo para que las utilicen herramientas como EasyInstall al instalar un archivo .egg.

recursos_eager:

Una lista de recursos de nomenclatura de cadenas que se deben extraer juntos, si se necesita alguno de ellos, o si se importan las extensiones C incluidas en el proyecto. Este argumento solo es útil si el proyecto se instalará como un archivo zip y es necesario que todos los recursos enumerados se extraigan al sistema de archivos como una unidad. Los recursos enumerados aquí deben ser rutas separadas por '/', en relación con la raíz de origen, por lo que para enumerar un recurso foo.png en el paquete bar.baz, debe incluir la cadena bar / baz / foo.png en este argumento. Si solo necesita obtener recursos de uno en uno, o si no tiene ninguna extensión C que acceda a otros archivos en el proyecto (como archivos de datos o bibliotecas compartidas), probablemente NO necesite este argumento y no deba ensuciar con eso. Para más detalles sobre cómo funciona este argumento,

puntos de entrada:

Un diccionario que asigna nombres de grupos de puntos de entrada a cadenas o listas de cadenas que definen los puntos de entrada. Los puntos de entrada se utilizan para admitir el descubrimiento dinámico de servicios o complementos proporcionados por un proyecto. Consulte Descubrimiento dinámico de servicios y complementos para obtener detalles y ejemplos del formato de este argumento. Además, esta palabra clave se utiliza para admitir la creación automática de scripts.

exclude_package_data:

Nombres de paquetes de mapeo de diccionario a listas de patrones globales que deben excluirse de los directorios de paquetes. Puede usar esto para recortar cualquier exceso de archivos incluidos por include_package_data. Para obtener una descripción completa y ejemplos, consulte la siguiente sección sobre la inclusión de archivos de datos.

extras_require:

Un diccionario que asigna nombres de "extras" (características opcionales de su proyecto) a cadenas o listas de cadenas que especifican qué otras distribuciones deben instalarse para admitir esas características. Consulte la sección a continuación sobre Declarar dependencias para obtener detalles y ejemplos del formato de este argumento.

include_package_data:

Si se establece en Verdadero, esto le indica a setuptools que incluya automáticamente cualquier archivo de datos que encuentre dentro de los directorios de paquetes que especifique su archivo MANIFEST.in. Para obtener más información, consulte la siguiente sección sobre la inclusión de archivos de datos.

install_requires:

Una cadena o lista de cadenas que especifica qué otras distribuciones deben instalarse cuando esta es. Consulte la sección a continuación sobre Declarar dependencias para obtener detalles y ejemplos del formato de este argumento.

paquetes de espacio de nombres:

Una lista de cadenas que nombran los "paquetes de espacio de nombres" del proyecto. Un paquete de espacio de nombres es un paquete que puede dividirse en múltiples distribuciones de proyectos. Por ejemplo, el paquete zope de Zope 3 es un paquete de espacio de nombres, porque los subpaquetes como zope.interface y zope.publisher pueden distribuirse por separado. El sistema de tiempo de ejecución de huevo puede fusionar automáticamente dichos subpaquetes en un solo paquete primario en tiempo de ejecución, siempre que los declare en cada proyecto que contenga subpaquetes del paquete de espacio de nombres, y siempre que el archivo init .py del paquete de espacio de nombres no contenga ningún código que no sea una declaración de espacio de nombres. Consulte la siguiente sección sobre Paquetes de espacio de nombres para obtener más información.

paquete_datos:

Nombres de paquetes de mapeo de diccionario a listas de patrones globales. Para obtener una descripción completa y ejemplos, consulte la siguiente sección sobre la inclusión de archivos de datos. No necesita usar esta opción si está usando include_package_data, a menos que necesite agregar, por ejemplo, archivos generados por su script de configuración y proceso de compilación. (Y, por lo tanto, no están en el control de origen o son archivos que no desea incluir en su distribución de origen).

project_urls:

Un mapa arbitrario de nombres de URL a hipervínculos, que permite una documentación más extensible de dónde se pueden encontrar varios recursos que las opciones simples url y download_url.

python_requires:

Una cadena correspondiente a un especificador de versión (como se define en PEP 440) para la versión de Python, utilizada para especificar el Requiere-Python definido en PEP 345.

setup_requires:

Una cadena o lista de cadenas que especifica qué otras distribuciones deben estar presentes para que se ejecute el script de configuración. setuptools intentará obtenerlos (incluso llegando a descargarlos usando EasyInstall) antes de procesar el resto del script o comandos de configuración. Este argumento es necesario si está utilizando extensiones distutils como parte de su proceso de compilación; por ejemplo, extensiones que procesan argumentos de configuración () y los convierten en archivos de metadatos EGG-INFO. (Nota: los proyectos enumerados en setup_requires NO se instalarán automáticamente en el sistema donde se ejecuta el script de configuración. Simplemente se descargan al directorio ./.eggs si ya no están disponibles localmente. Si desea que se instalen , además de estar disponible cuando se ejecuta el script de configuración, debe agregarlos a install_requires y setup_requires).

test_loader:

Si desea utilizar una forma diferente de encontrar pruebas para ejecutar que la que normalmente usa setuptools, puede especificar un nombre de módulo y un nombre de clase en este argumento. La clase nombrada debe ser instanciable sin argumentos, y sus instancias deben admitir el método loadTestsFromNames () como se define en la clase TestLoader del módulo de prueba de unidad Python. Setuptools solo pasará un "nombre" de prueba en el argumento de nombres: el valor proporcionado para el argumento test_suite. El cargador que especifique puede interpretar esta cadena de la forma que desee, ya que no hay restricciones sobre lo que puede contener una cadena test_suite. El nombre del módulo y el nombre de la clase deben estar separados por:. El valor predeterminado de este argumento es "setuptools.command.test: ScanningLoader". Si desea utilizar el comportamiento predeterminado de unittest, puede especificar "unittest: TestLoader" como su argumento test_loader en su lugar. Esto evitará el escaneo automático de submódulos y subpaquetes. El módulo y la clase que especifique aquí pueden estar contenidos en otro paquete, siempre que use la opción tests_require para asegurarse de que el paquete que contiene la clase loader esté disponible cuando se ejecuta el comando de prueba.

Banco de pruebas:

Una cadena que nombra una subclase unittest.TestCase (o un paquete o módulo que contiene una o más de ellas, o un método de dicha subclase), o nombra una función que se puede invocar sin argumentos y devuelve un unittest.TestSuite. Si la suite nombrada es un módulo y el módulo tiene una función adicional_tests (), se llama y los resultados se agregan a las pruebas que se ejecutarán. Si la suite nombrada es un paquete, todos los submódulos y subpaquetes se agregan recursivamente a la suite de prueba general. La especificación de este argumento permite el uso del comando de prueba para ejecutar el conjunto de pruebas especificado, por ejemplo, a través de la prueba setup.py. Consulte la sección sobre el comando de prueba a continuación para obtener más detalles.

tests_require:

Si las pruebas de su proyecto necesitan uno o más paquetes adicionales además de los necesarios para instalarlo, puede usar esta opción para especificarlos. Debe ser una cadena o una lista de cadenas que especifique qué otras distribuciones deben estar presentes para que se ejecuten las pruebas del paquete. Cuando ejecuta el comando de prueba, setuptools intentará obtenerlos (incluso llegando a descargarlos usando EasyInstall). Tenga en cuenta que estos proyectos requeridos no se instalarán en el sistema donde se ejecutan las pruebas, sino que solo se descargarán al directorio de configuración del proyecto si aún no están instalados localmente.

use_2to3:

Convierta el código fuente de Python 2 a Python 3 con 2to3 durante el proceso de compilación. Consulte Soporte de Python 2 y Python 3 con Setuptools para más detalles.

use_2to3_exclude_fixers :

Por defecto, la conversión usa todos los arregladores en el lib2to3.fixerspaquete. Para usar reparadores adicionales, el parámetro use_2to3_fixersse puede establecer en una lista de nombres de paquetes que contienen reparadores. Para excluir los fijadores, el parámetro use_2to3_exclude_fixersse puede configurar para que se omitan los nombres de los fijadores .

use_2to3_fixers :

Una lista de módulos para buscar fijadores adicionales para usar durante la conversión 2to3. Consulte Soporte de Python 2 y Python 3 con Setuptools para más detalles.

zip_safe:

Un indicador booleano (verdadero o falso) que especifica si el proyecto se puede instalar y ejecutar de forma segura desde un archivo zip. Si no se proporciona este argumento, el comando bdist_egg tendrá que analizar todos los contenidos de su proyecto para detectar posibles problemas cada vez que genera un huevo.

Extensiones

Construir una extensión (en lugar de un módulo Python puro) es más complicado, ya que esencialmente requiere que especifique los parámetros y argumentos necesarios para construir con éxito la extensión desde los Carchivos fuente. Esto se hace a través de la ext_modulespalabra clave, que no es más que una lista de Extensioninstancias (importable dedistutils.core ). Los argumentos de palabras clave aceptados por el Extensionconstructor de la clase son el vector de entrada para especificar los pasos de compilación para compilar la extensión.

Dado que esta pregunta se trata setuptools.setup()específicamente, solo incluiré la definición de ext_modules, pero la documentación de la Extensionclase proporciona detalles completos. Para completar, esta es la lista de palabras clave aceptadas para el Extensionconstructor:

    extension_keywords = ('name', 'sources', 'include_dirs',
                          'define_macros', 'undef_macros',
                          'library_dirs', 'libraries', 
                          'runtime_library_dirs', 'extra_objects', 
                          'extra_compile_args', 'extra_link_args',
                          'swig_opts', 'export_symbols', 'depends', 
                          'language')

ext_modules :

Una lista de instancias de Extensión, cada una de las cuales describe un único módulo de extensión. Suponga que su distribución incluye una sola extensión, llamada foo e implementada por foo.c. Si no se necesitan instrucciones adicionales para el compilador / enlazador, describir esta extensión es bastante simple:

   from distutils.core import setup, Extension
   setup(name='foo',
         version='1.0',
         ext_modules=[Extension('foo', ['foo.c'])],
         )

Misceláneos

Finalmente, hay incluso más kwargs que se pueden encontrar implementados en setuptools.disty en otros lugares, pero por alguna razón nunca se agregaron a ninguna de las principales herramientas de configuración / distutils:

características (en desuso):

nombres de opciones de mapeo de diccionario a objetos 'setuptools.Feature'. Las características son una parte de la distribución que se puede incluir o excluir según las opciones del usuario, las dependencias entre funciones y la disponibilidad en el sistema actual. Las funciones excluidas se omiten de todos los comandos de configuración, incluidas las distribuciones de origen y binarias, por lo que puede crear múltiples distribuciones desde el mismo árbol de origen.

long_description_content_type (Por "Crear un archivo README compatible con PyPI ):

establezca un valor de estilo de tipo de contenido aceptado para el marcado de su archivo README, como text / plain, text / x-rst (para reStructuredText) o text / markdown.

provides_extras (por PEP566, que figuran como "Proporciona-Extra" ):

Una cadena que contiene el nombre de una característica opcional. Debe ser un identificador válido de Python. Se puede usar para condicionar una dependencia a si se ha solicitado la característica opcional.