# 3. Writing the Setup Configuration File

Nota

Este documento está siendo mantenido solamente hasta que la documentación de `setuptools` en https://setuptools.readthedocs.io/en/latest/setuptools.html cubra independientemente toda la información relevante actualmente incluida aquí.

A menudo, no es posible escribir todo lo necesario para construir una distribución a priori: es posible que deba obtener alguna información del usuario, o del sistema del usuario, para poder continuar. Mientras que esa información sea bastante simple —una lista de directorios para buscar archivos de encabezado de o bibliotecas, por ejemplo— proporcionar un archivo de configuración, `setup.cfg`, para que los usuarios lo editen es una forma fácil y barata de solicitarla. Los archivos de configuración también permiten proporcionar valores predeterminados para cualquier opción de comando, que el instalador puede invalidar en la línea de comando o editando el archivo de configuración.

The setup configuration file is a useful middle-ground between the setup script—which, ideally, would be opaque to installers 1—and the command-line to the setup script, which is outside of your control and entirely up to the installer. In fact, `setup.cfg` (and any other Distutils configuration files present on the target system) are processed after the contents of the setup script, but before the command-line. This has several useful consequences:

- los instaladores pueden anular o invalidar algo que pongas en `setup.py` editando `setup.cfg`

- puedes proporcionar valores predeterminados no estándares para las opciones que se pueden configurar fácilmente en `setup.py`

- los instaladores pueden invalidar cualquier cosa en `setup.cfg` usando las opciones de línea de comandos para `setup.py`

La sintaxis básica del archivo de configuración es simple:

    [command]
    option=value
    ...

donde command es uno de los comandos de Distutils (por ejemplo: build_py, install), y option es una de las opciones que el comando admite. Se puede proporcionar cualquier cantidad de opciones para cada comando, y se puede incluir cualquier número de secciones de comando en el archivo. Las líneas en blanco son ignoradas, al igual que los comentarios, que empiezan desde el carácter `'#'` hasta el final de la línea. Los valores de opción largos pueden dividirse en varias líneas simplemente indentando las líneas a continuación.

Puedes encontrar la lista de opciones admitidas por un comando particular con la opción universal `--help`, por ej.

    $ python setup.py --help build_ext
    [...]
    Options for 'build_ext' command:
      --build-lib (-b)     directory for compiled extension modules
      --build-temp (-t)    directory for temporary files (build by-products)
      --inplace (-i)       ignore build-lib and put compiled extensions into the
                           source directory alongside your pure Python modules
      --include-dirs (-I)  list of directories to search for header files
      --define (-D)        C preprocessor macros to define
      --undef (-U)         C preprocessor macros to undefine
      --swig-opts          list of SWIG command line options
    [...]

Tenga en cuenta que una opción escrita `--foo-bar` en la línea de comandos es escribe `foo_bar` en los archivos de configuración.

Por ejemplo, digamos que quiere que sus extensiones se construyan «en el lugar» (in-place)—esto es, tienes una extensión `pkg.ext`, y quieres el archivo de extensión compilado (`ext.so` en Unix, digamos) para ser colocado en el mismo directorio origen que los módulos de Python puro `pkg.mod1` y `pkg.mod2`. Siempre puedes utilizar la opción `--inplace` en la línea de comandos para asegurarte de eso:

    python setup.py build_ext --inplace

Pero esto requiere que siempre especifiques el comando build_ext explícitamente, y recuerdes proporcionarle `--inplace`. Una forma mas fácil es «configurar y olvidar» esta opción, poniéndolo en `setup.cfg`, el archivo de configuración para esta distribución:

    [build_ext]
    inplace=1

Esto afectará a todas las compilaciones de la distribución de este módulo, independientemente de si especificas o no explícitamente build_ext. Si incluyes `setup.cfg` en tu distribución de origen, también afectará las compilaciones de los usuarios finales— lo que probablemente sea una mala idea para esta opción, ya que siempre construir extensiones en el lugar interrumpiría la instalación de la distribución del módulo. En ciertos casos particulares, sin embargo, los módulos son compilados directamente en el directorio de instalación, por lo que sería una habilidad útil. (Sin embargo, distribuir extensiones que se espera que sean compiladas en su directorio de instalación es casi siempre una mala idea).

Otro ejemplo: ciertos comandos toman muchas opciones que no cambian de ejecución a ejecución; por ejemplo, bdist_rpm necesita conocer todo lo necesario para generar un archivo «spec» para crear una distribución RPM. Parte de esta información proviene del script de configuración, y otra es generada automáticamente por Distutils (como la lista de archivos instalados). Pero parte de esto tiene que ser suministrado como opciones para bdist_rpm, lo cual sería muy tedioso hacer en la línea de comandos para cada ejecución. Por lo tanto, aquí hay un fragmento del propio de Distutils `setup.cfg`:

    [bdist_rpm]
    release = 1
    packager = Greg Ward <gward@python.net>
    doc_files = CHANGES.txt
                README.txt
                USAGE.txt
                doc/
                examples/

Tenga en cuenta que la opción `doc_files` es simplemente una cadena de texto separada por espacios dividida en varias líneas para facilitar la lectura.

Ver también

Archivos de configuración de sintaxis en «Instalar módulos de Python»

  Más información sobre los archivos de configuración está disponible en el manual para administradores del sistema.

Notas al pie

1

  Es probable que este ideal no se logre hasta que la configuración automática sea completamente admitida por Distutils.