Reglas de Python

Reglas

py_binary 

py_binary(name, deps, srcs, data, args, compatible_with, deprecation, distribs, env, exec_compatible_with, exec_properties, features, imports, legacy_create_init, licenses, main, output_licenses, python_version, restricted_to, srcs_version, stamp, tags, target_compatible_with, testonly, toolchains, visibility)

Un py_binary es un programa ejecutable de Python que consta de una colección de archivos fuente .py (posibles que pertenecen a otras reglas py_library), un árbol de directorios *.runfiles que contiene todo el código y los datos que necesita el programa en el tiempo de ejecución y una secuencia de comandos de stub que inicia el programa con el entorno y los datos iniciales correctos.

Ejemplos

py_binary(
    name = "foo",
    srcs = ["foo.py"],
    data = [":transform"],  # a cc_binary which we invoke at run time
    deps = [
        ":foolib",  # a py_library
    ],
)

Si deseas ejecutar un py_binary desde otro objeto binario o prueba (por ejemplo, ejecutar un objeto binario de Python para configurar algún recurso simulado desde una java_test), el enfoque correcto es hacer que el otro objeto binario o prueba dependa del py_binary en su sección de datos. El otro objeto binario puede ubicar el py_binary en relación con el directorio del código fuente. 

py_binary(
    name = "test_main",
    srcs = ["test_main.py"],
    deps = [":testlib"],
)

java_library(
    name = "testing",
    srcs = glob(["*.java"]),
    data = [":test_main"]
)

Argumentos

Atributos
name

Name; required

Un nombre único para este destino.


Si no se especifica main, debe ser el mismo que el nombre del archivo de origen que es el punto de entrada principal de la aplicación, menos la extensión. Por ejemplo, si tu punto de entrada se llama main.py, tu nombre debe ser main.
deps

List of labels; optional

Es la lista de otras bibliotecas que se vincularán al destino binario. Consulta los comentarios generales sobre deps en Atributos típicos definidos por la mayoría de las reglas de compilación. Por lo general, son reglas de py_library.
srcs

List of labels; required

La lista de archivos de origen (.py) que se procesan para crear el destino. Esto incluye todo el código de registro y los archivos fuente generados. Los destinos de biblioteca pertenecen a deps, mientras que los otros archivos binarios necesarios en el tiempo de ejecución pertenecen a data.
imports

List of strings; optional

Lista de directorios de importación que se agregarán a PYTHONPATH.

Sujeto a la sustitución "Make variable". Se agregarán estos directorios de importación para esta regla y todas las reglas que dependan de ella (nota: no son las reglas de las que depende esta regla. Las reglas de py_binary que dependen de esta regla agregarán cada directorio a PYTHONPATH.

No se permiten las rutas de acceso absolutas (que comienzan con /) ni que hacen referencia a una ruta por encima de la raíz de ejecución, y se generará un error.

legacy_create_init

Integer; optional; default is -1

Si se crean de manera implícita archivos __init__.py en el árbol de archivos de ejecución. Estos se crean en todos los directorios que contienen el código fuente de Python o las bibliotecas compartidas, y en cada directorio principal de esos directorios, excepto el directorio raíz del repositorio. El valor predeterminado, automático, significa verdadero, a menos que se use --incompatible_default_to_explicit_init_py. Si es falso, el usuario es responsable de crear archivos __init__.py (posiblemente vacíos) y agregarlos al srcs de los destinos de Python según sea necesario.
main

Label; optional

El nombre del archivo de origen que es el punto de entrada principal de la aplicación. Este archivo también debe aparecer en la lista de srcs. Si no se especifica, se usa name en su lugar (consulta la sección anterior). Si name no coincide con ningún nombre de archivo en srcs, se debe especificar main.
python_version

String; optional; nonconfigurable; default is "_INTERNAL_SENTINEL"

Establece si se debe compilar este destino (y su deps transitivo) para Python 2 o Python 3. Los valores válidos son "PY2" y "PY3" (el valor predeterminado).

La versión de Python siempre se restablece (posiblemente de forma predeterminada) a la versión que especifique este atributo, sin importar la versión especificada en la línea de comandos o por otros destinos superiores que dependan de este.

Si deseas usar select() en la versión actual de Python, puedes inspeccionar el valor de @rules_python//python:python_version. Consulta este vínculo para obtener más información.

Advertencia de error: Este atributo establece la versión para la que Bazel compila tu destino. Sin embargo, debido a #4815, es posible que la secuencia de comandos de stub resultante aún invoque la versión incorrecta del intérprete en el entorno de ejecución. Consulta esta solución alternativa, que implica definir un destino py_runtime que apunte a cualquier versión de Python según sea necesario y activar este py_runtime mediante la configuración de --python_top.

srcs_version

String; optional; default is "PY2AND3"

Este atributo declara que el srcs del destino es compatible con Python 2, Python 3 o ambos. Para configurar realmente la versión del entorno de ejecución de Python, usa el atributo python_version de una regla ejecutable de Python (py_binary o py_test).

Los valores permitidos son "PY2AND3", "PY2" y "PY3". Los valores "PY2ONLY" y "PY3ONLY" también se permiten por razones históricas, pero, en esencia, son iguales a "PY2" y "PY3", y se deben evitar.

Ten en cuenta que solo las reglas ejecutables (py_binary y py_library ) verifican la versión actual de Python con el valor de este atributo. (Esta es una función; dado que py_library no cambia la versión actual de Python, si hiciera la validación, es imposible compilar las bibliotecas PY2ONLY y PY3ONLY en la misma invocación). Además, si la versión no coincide, el error solo se informa en la fase de ejecución. En particular, el error no aparecerá en una invocación bazel build --nobuild).

Para obtener información de diagnóstico sobre qué dependencias presentan requisitos de versión, puedes ejecutar el aspecto find_requirements en tu destino: 

          bazel build <your target> \
              --aspects=@rules_python//python:defs.bzl%find_requirements \
              --output_groups=pyversioninfo
De esta manera, se compilará un archivo con el sufijo -pyversioninfo.txt que brinda información sobre por qué el destino requiere una versión de Python. Ten en cuenta que funciona incluso si el destino determinado no se pudo compilar debido a un conflicto de versión.

stamp

Integer; optional; default is -1

Indica si se debe codificar la información de compilación en el objeto binario. Valores posibles:
  • stamp = 1: Siempre marca la información de compilación en el objeto binario, incluso en compilaciones de --nostamp. Esta configuración debe evitarse, ya que podría finalizar el almacenamiento en caché remoto del objeto binario y todas las acciones descendentes que dependen de él.
  • stamp = 0: Siempre reemplaza la información de compilación por valores constantes. Esto proporciona un buen almacenamiento en caché de resultados de compilación.
  • stamp = -1: La marca --[no]stamp controla la incorporación de la información de compilación.

Los objetos binarios sellados no se vuelven a compilar, a menos que cambien sus dependencias.

py_library 

py_library(name, deps, srcs, data, compatible_with, deprecation, distribs, exec_compatible_with, exec_properties, features, imports, licenses, restricted_to, srcs_version, tags, target_compatible_with, testonly, visibility)

Argumentos

Atributos
name

Name; required

Un nombre único para este destino.
deps

List of labels; optional

Es la lista de otras bibliotecas que se vincularán al destino binario. Consulta los comentarios generales sobre deps en Atributos típicos definidos por la mayoría de las reglas de compilación. Por lo general, son reglas de py_library.
srcs

List of labels; optional

La lista de archivos de origen (.py) que se procesan para crear el destino. Esto incluye todo el código de registro y los archivos fuente generados.
imports

List of strings; optional

Lista de directorios de importación que se agregarán a PYTHONPATH.

Sujeto a la sustitución "Make variable". Se agregarán estos directorios de importación para esta regla y todas las reglas que dependan de ella (nota: no son las reglas de las que depende esta regla. Las reglas de py_binary que dependen de esta regla agregarán cada directorio a PYTHONPATH.

No se permiten las rutas de acceso absolutas (que comienzan con /) ni que hacen referencia a una ruta por encima de la raíz de ejecución, y se generará un error.

srcs_version

String; optional; default is "PY2AND3"

Este atributo declara que el srcs del destino es compatible con Python 2, Python 3 o ambos. Para configurar realmente la versión del entorno de ejecución de Python, usa el atributo python_version de una regla ejecutable de Python (py_binary o py_test).

Los valores permitidos son "PY2AND3", "PY2" y "PY3". Los valores "PY2ONLY" y "PY3ONLY" también se permiten por razones históricas, pero, en esencia, son iguales a "PY2" y "PY3", y se deben evitar.

Ten en cuenta que solo las reglas ejecutables (py_binary y py_library ) verifican la versión actual de Python con el valor de este atributo. (Esta es una función; dado que py_library no cambia la versión actual de Python, si hiciera la validación, es imposible compilar las bibliotecas PY2ONLY y PY3ONLY en la misma invocación). Además, si la versión no coincide, el error solo se informa en la fase de ejecución. En particular, el error no aparecerá en una invocación bazel build --nobuild).

Para obtener información de diagnóstico sobre qué dependencias presentan requisitos de versión, puedes ejecutar el aspecto find_requirements en tu destino: 

          bazel build <your target> \
              --aspects=@rules_python//python:defs.bzl%find_requirements \
              --output_groups=pyversioninfo
De esta manera, se compilará un archivo con el sufijo -pyversioninfo.txt que brinda información sobre por qué el destino requiere una versión de Python. Ten en cuenta que funciona incluso si el destino determinado no se pudo compilar debido a un conflicto de versión.

py_test 

py_test(name, deps, srcs, data, args, compatible_with, deprecation, distribs, env, env_inherit, exec_compatible_with, exec_properties, features, flaky, imports, legacy_create_init, licenses, local, main, python_version, restricted_to, shard_count, size, srcs_version, stamp, tags, target_compatible_with, testonly, timeout, toolchains, visibility)

Una regla py_test() compila una prueba. Una prueba es un wrapper binario alrededor de un código de prueba.

Ejemplos

py_test(
    name = "runtest_test",
    srcs = ["runtest_test.py"],
    deps = [
        "//path/to/a/py/library",
    ],
)

También es posible especificar un módulo principal:

py_test(
    name = "runtest_test",
    srcs = [
        "runtest_main.py",
        "runtest_lib.py",
    ],
    main = "runtest_main.py",
)

Argumentos

Atributos
name

Name; required

Un nombre único para este destino.
deps

List of labels; optional

Es la lista de otras bibliotecas que se vincularán al destino binario. Consulta los comentarios generales sobre deps en Atributos típicos definidos por la mayoría de las reglas de compilación. Por lo general, son reglas de py_library.
srcs

List of labels; required

La lista de archivos de origen (.py) que se procesan para crear el destino. Esto incluye todo el código de registro y los archivos fuente generados. Los destinos de biblioteca pertenecen a deps, mientras que los otros archivos binarios necesarios en el tiempo de ejecución pertenecen a data.
imports

List of strings; optional

Lista de directorios de importación que se agregarán a PYTHONPATH.

Sujeto a la sustitución "Make variable". Se agregarán estos directorios de importación para esta regla y todas las reglas que dependan de ella (nota: no son las reglas de las que depende esta regla. Las reglas de py_binary que dependen de esta regla agregarán cada directorio a PYTHONPATH.

No se permiten las rutas de acceso absolutas (que comienzan con /) ni que hacen referencia a una ruta por encima de la raíz de ejecución, y se generará un error.

legacy_create_init

Integer; optional; default is -1

Si se crean de manera implícita archivos __init__.py en el árbol de archivos de ejecución. Estos se crean en todos los directorios que contienen el código fuente de Python o las bibliotecas compartidas, y en cada directorio principal de esos directorios, excepto el directorio raíz del repositorio. El valor predeterminado, automático, significa verdadero, a menos que se use --incompatible_default_to_explicit_init_py. Si es falso, el usuario es responsable de crear archivos __init__.py (posiblemente vacíos) y agregarlos al srcs de los destinos de Python según sea necesario.
main

Label; optional

El nombre del archivo de origen que es el punto de entrada principal de la aplicación. Este archivo también debe aparecer en la lista de srcs. Si no se especifica, se usa name en su lugar (consulta la sección anterior). Si name no coincide con ningún nombre de archivo en srcs, se debe especificar main.
python_version

String; optional; nonconfigurable; default is "_INTERNAL_SENTINEL"

Establece si se debe compilar este destino (y su deps transitivo) para Python 2 o Python 3. Los valores válidos son "PY2" y "PY3" (el valor predeterminado).

La versión de Python siempre se restablece (posiblemente de forma predeterminada) a la versión que especifique este atributo, sin importar la versión especificada en la línea de comandos o por otros destinos superiores que dependan de este.

Si deseas usar select() en la versión actual de Python, puedes inspeccionar el valor de @rules_python//python:python_version. Consulta este vínculo para obtener más información.

Advertencia de error: Este atributo establece la versión para la que Bazel compila tu destino. Sin embargo, debido a #4815, es posible que la secuencia de comandos de stub resultante aún invoque la versión incorrecta del intérprete en el entorno de ejecución. Consulta esta solución alternativa, que implica definir un destino py_runtime que apunte a cualquier versión de Python según sea necesario y activar este py_runtime mediante la configuración de --python_top.

srcs_version

String; optional; default is "PY2AND3"

Este atributo declara que el srcs del destino es compatible con Python 2, Python 3 o ambos. Para configurar realmente la versión del entorno de ejecución de Python, usa el atributo python_version de una regla ejecutable de Python (py_binary o py_test).

Los valores permitidos son "PY2AND3", "PY2" y "PY3". Los valores "PY2ONLY" y "PY3ONLY" también se permiten por razones históricas, pero, en esencia, son iguales a "PY2" y "PY3", y se deben evitar.

Ten en cuenta que solo las reglas ejecutables (py_binary y py_library ) verifican la versión actual de Python con el valor de este atributo. (Esta es una función; dado que py_library no cambia la versión actual de Python, si hiciera la validación, es imposible compilar las bibliotecas PY2ONLY y PY3ONLY en la misma invocación). Además, si la versión no coincide, el error solo se informa en la fase de ejecución. En particular, el error no aparecerá en una invocación bazel build --nobuild).

Para obtener información de diagnóstico sobre qué dependencias presentan requisitos de versión, puedes ejecutar el aspecto find_requirements en tu destino: 

          bazel build <your target> \
              --aspects=@rules_python//python:defs.bzl%find_requirements \
              --output_groups=pyversioninfo
De esta manera, se compilará un archivo con el sufijo -pyversioninfo.txt que brinda información sobre por qué el destino requiere una versión de Python. Ten en cuenta que funciona incluso si el destino determinado no se pudo compilar debido a un conflicto de versión.

stamp

Integer; optional; default is 0

Consulta la sección sobre los argumentos py_binary(), excepto que el argumento de sello está configurado en 0 de forma predeterminada para las pruebas.

py_runtime 

py_runtime(name, compatible_with, coverage_tool, deprecation, distribs, features, files, interpreter, interpreter_path, licenses, python_version, restricted_to, stub_shebang, tags, target_compatible_with, testonly, visibility)

Representa un entorno de ejecución de Python que se usa para ejecutar el código de Python.

Un destino py_runtime puede representar un entorno de ejecución de la plataforma o un entorno de ejecución integrado en la compilación. Un entorno de ejecución de plataforma accede a un intérprete instalado en el sistema en una ruta de acceso conocida, mientras que un entorno de ejecución integrado en la compilación apunta a un destino ejecutable que actúa como intérprete. En ambos casos, “intérprete” se refiere a cualquier secuencia de comandos binaria o wrapper ejecutable que sea capaz de ejecutar una secuencia de comandos de Python pasada en la línea de comandos, siguiendo las mismas convenciones que el intérprete estándar de CPython.

Un entorno de ejecución de plataforma es, por su naturaleza, no hermético. En la plataforma de destino, se impone un requisito que tiene que tener un intérprete ubicado en una ruta de acceso específica. Un entorno de ejecución en la compilación puede ser hermético o no, dependiendo de si apunta a un intérprete registrado o a una secuencia de comandos de wrapper que accede al intérprete del sistema.

Ejemplo:

py_runtime(
    name = "python-2.7.12",
    files = glob(["python-2.7.12/**"]),
    interpreter = "python-2.7.12/bin/python",
)

py_runtime(
    name = "python-3.6.0",
    interpreter_path = "/opt/pyenv/versions/3.6.0/bin/python",
)

Argumentos

Atributos
name

Name; required

Un nombre único para este destino.
coverage_tool

Label; optional

Este es un objetivo que se puede usar para recopilar información de cobertura de código de objetivos py_binary y py_test.

Si se establece, el destino debe producir un solo archivo o ser un destino ejecutable. La ruta al archivo único, o el ejecutable si el destino es ejecutable, determina el punto de entrada para la herramienta de cobertura de Python. El destino y sus archivos de ejecución se agregarán a los archivos de ejecución cuando se habilite la cobertura.

Un intérprete de Python (p.ej., un archivo .py o .pyc) debe poder cargar el punto de entrada de la herramienta. Debe aceptar los argumentos de la línea de comandos de coverage.py, al menos incluidos los subcomandos run y lcov.

files

List of labels; optional

Para un entorno de ejecución en compilación, este es el conjunto de archivos que componen el entorno de ejecución. Estos archivos se agregarán a los archivos de ejecución de los objetos binarios de Python que usan este entorno de ejecución. Para un tiempo de ejecución de la plataforma, este atributo no se debe establecer.
interpreter

Label; optional

Para un entorno de ejecución compilado, este es el destino que se debe invocar como intérprete. Para un entorno de ejecución de la plataforma, no se debe establecer este atributo.
interpreter_path

String; optional

Para un entorno de ejecución de plataforma, esta es la ruta de acceso absoluta de un intérprete de Python en la plataforma de destino. Para un entorno de ejecución en la compilación, no se debe configurar este atributo.
python_version

String; optional; default is "_INTERNAL_SENTINEL"

Si este entorno de ejecución es para la versión principal 2 o 3 de Python. Los valores válidos son "PY2" y "PY3".

El valor predeterminado se controla con la marca --incompatible_py3_is_default. Sin embargo, en el futuro, este atributo será obligatorio y no tendrá un valor predeterminado.

stub_shebang

String; optional; default is "#!/usr/bin/env python3"

La expresión “Shebang” antepuesta a la secuencia de comandos de stub de arranque de Python que se usa cuando se ejecutan objetivos py_binary.

Consulta el error 8685 para obtener motivación.

No se aplica a Windows.