Regras do Python

Regras

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)

Um py_binary é um programa Python executável que consiste em uma coleção de arquivos de origem .py (possivelmente pertencendo a outras regras py_library), uma árvore de diretórios *.runfiles que contém todo o código e os dados necessários para o programa no momento da execução e um script de stub que inicia o programa com o ambiente inicial e os dados corretos.

Exemplos

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

Se você quiser executar um py_binary de dentro de outro binário ou teste (por exemplo, executando um binário Python para configurar um recurso simulado de um java_test), a abordagem correta é fazer com que o outro binário ou teste dependa do py_binary na seção de dados. O outro binário poderá localizar o py_binary em relação ao diretório de origem. 

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

Um nome exclusivo para o destino.


Se main não for especificado, ele precisará ser o mesmo nome do arquivo de origem que é o ponto de entrada principal do aplicativo, menos a extensão. Por exemplo, se o ponto de entrada se chamar main.py, o nome precisará ser main.
deps

List of labels; optional

A lista de outras bibliotecas a serem vinculadas ao destino binário. Consulte comentários gerais sobre deps em Atributos típicos definidos pela maioria das regras de build. Geralmente, são regras py_library.
srcs

List of labels; required

A lista de arquivos de origem (.py) que são processados para criar o destino. Isso inclui todo o código adicionado e todos os arquivos de origem gerados. Os destinos de biblioteca pertencem a deps, enquanto outros arquivos binários necessários no momento da execução pertencem a data.
imports

List of strings; optional

Lista de diretórios de importação a serem adicionados ao PYTHONPATH.

Sujeito à substituição "Criar variável". Esses diretórios de importação serão adicionados para esta regra e todas as regras que dependem dela (observação: não as regras de que esta regra depende. Cada diretório será adicionado a PYTHONPATH por regras py_binary que dependem desta regra.

Caminhos absolutos (que começam com /) e aqueles que fazem referência a um caminho acima da raiz de execução não são permitidos e resultarão em erro.

legacy_create_init

Integer; optional; default is -1

Define se arquivos __init__.py vazios implicitamente na árvore dos arquivos de execução serão criados implicitamente. Eles são criados em todos os diretórios que contêm o código-fonte do Python ou bibliotecas compartilhadas e em todos os diretórios pai desses diretórios, exceto o diretório raiz do repositório. O padrão (automático) significa "true", a menos que --incompatible_default_to_explicit_init_py seja usado. Se for falso, o usuário será responsável por criar arquivos __init__.py, possivelmente vazios, e adicioná-los ao srcs de destinos Python, conforme necessário.
main

Label; optional

O nome do arquivo de origem que é o ponto de entrada principal do aplicativo. Esse arquivo também precisa estar listado em srcs. Se não for especificado, name será usado (veja acima). Se name não corresponder a nenhum nome de arquivo em srcs, main precisará ser especificado.
python_version

String; optional; nonconfigurable; default is "_INTERNAL_SENTINEL"

Define se esse destino (e o deps transitivo correspondente) será criado para Python 2 ou Python 3. Os valores válidos são "PY2" e "PY3" (o padrão).

A versão do Python é sempre redefinida (possivelmente por padrão) para a versão especificada por esse atributo, independentemente da versão especificada na linha de comando ou por outros destinos superiores que dependam desse.

Se você quiser select() na versão atual do Python, inspecione o valor de @rules_python//python:python_version. Consulte este link para mais informações.

Aviso de bug:esse atributo define a versão para que o Bazel cria seu destino, mas devido ao #4815 (link em inglês), o script de stub resultante ainda pode invocar a versão incorreta do intérprete no momento da execução. Consulte esta solução alternativa, que envolve definir um destino py_runtime que aponta para qualquer versão do Python conforme necessário e ativar esse py_runtime definindo --python_top.

srcs_version

String; optional; default is "PY2AND3"

Esse atributo declara a srcs do destino como compatível com Python 2, Python 3 ou ambos. Para definir a versão do ambiente de execução do Python, use o atributo python_version de uma regra executável do Python (py_binary ou py_test).

Os valores permitidos são "PY2AND3", "PY2" e "PY3". Os valores "PY2ONLY" e "PY3ONLY" também são permitidos por motivos históricos, mas são essencialmente os mesmos de "PY2" e "PY3" e precisam ser evitados.

Apenas as regras executáveis (py_binary e py_library ) verificam a versão atual do Python em relação ao valor desse atributo. Esse é um recurso. Como py_library não altera a versão atual do Python, se ele tivesse feito a validação, será impossível criar as bibliotecas PY2ONLY e PY3ONLY na mesma invocação. Além disso, se houver uma incompatibilidade de versão, o erro só será informado na fase de execução. Especificamente, o erro não aparecerá em uma invocação bazel build --nobuild.

Para ver informações de diagnóstico sobre quais dependências introduzem requisitos de versão, execute o aspecto find_requirements no destino: 

          bazel build <your target> \
              --aspects=@rules_python//python:defs.bzl%find_requirements \
              --output_groups=pyversioninfo
. Isso criará um arquivo com o sufixo -pyversioninfo.txt, fornecendo informações sobre por que seu destino exige uma versão do Python ou outra. Observe que ela funciona mesmo se o destino especificado falhar na criação devido a um conflito de versões.

stamp

Integer; optional; default is -1

Define se as informações de compilação serão codificadas no binário. Valores possíveis:
  • stamp = 1: sempre inclua as informações do build no binário, mesmo em builds --nostamp. Essa configuração precisa ser evitada, porque ela pode eliminar o armazenamento remoto do armazenamento em cache do binário e de quaisquer ações downstream que dependam dele.
  • stamp = 0: sempre substitua as informações do build por valores constantes. Isso fornece um bom armazenamento em cache de resultados do build.
  • stamp = -1: a incorporação de informações de build é controlada pela flag --[no]stamp.

Os binários carimbos não são recriados, a menos que as dependências deles mudem.

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

Um nome exclusivo para o destino.
deps

List of labels; optional

A lista de outras bibliotecas a serem vinculadas ao destino binário. Consulte comentários gerais sobre deps em Atributos típicos definidos pela maioria das regras de build. Geralmente, são regras py_library.
srcs

List of labels; optional

A lista de arquivos de origem (.py) que são processados para criar o destino. Isso inclui todo o código adicionado e todos os arquivos de origem gerados.
imports

List of strings; optional

Lista de diretórios de importação a serem adicionados ao PYTHONPATH.

Sujeito à substituição "Criar variável". Esses diretórios de importação serão adicionados para esta regra e todas as regras que dependem dela (observação: não as regras de que esta regra depende. Cada diretório será adicionado a PYTHONPATH por regras py_binary que dependem desta regra.

Caminhos absolutos (que começam com /) e aqueles que fazem referência a um caminho acima da raiz de execução não são permitidos e resultarão em erro.

srcs_version

String; optional; default is "PY2AND3"

Esse atributo declara a srcs do destino como compatível com Python 2, Python 3 ou ambos. Para definir a versão do ambiente de execução do Python, use o atributo python_version de uma regra executável do Python (py_binary ou py_test).

Os valores permitidos são "PY2AND3", "PY2" e "PY3". Os valores "PY2ONLY" e "PY3ONLY" também são permitidos por motivos históricos, mas são essencialmente os mesmos de "PY2" e "PY3" e precisam ser evitados.

Apenas as regras executáveis (py_binary e py_library ) verificam a versão atual do Python em relação ao valor desse atributo. Esse é um recurso. Como py_library não altera a versão atual do Python, se ele tivesse feito a validação, será impossível criar as bibliotecas PY2ONLY e PY3ONLY na mesma invocação. Além disso, se houver uma incompatibilidade de versão, o erro só será informado na fase de execução. Especificamente, o erro não aparecerá em uma invocação bazel build --nobuild.

Para ver informações de diagnóstico sobre quais dependências introduzem requisitos de versão, execute o aspecto find_requirements no destino: 

          bazel build <your target> \
              --aspects=@rules_python//python:defs.bzl%find_requirements \
              --output_groups=pyversioninfo
. Isso criará um arquivo com o sufixo -pyversioninfo.txt, fornecendo informações sobre por que seu destino exige uma versão do Python ou outra. Observe que ela funciona mesmo se o destino especificado falhar na criação devido a um conflito de versões.

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)

Uma regra py_test() compila um teste. Um teste é um wrapper binário em torno de um código de teste.

Exemplos

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

Também é possível especificar um módulo principal:

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

Argumentos

Atributos
name

Name; required

Um nome exclusivo para o destino.
deps

List of labels; optional

A lista de outras bibliotecas a serem vinculadas ao destino binário. Consulte comentários gerais sobre deps em Atributos típicos definidos pela maioria das regras de build. Geralmente, são regras py_library.
srcs

List of labels; required

A lista de arquivos de origem (.py) que são processados para criar o destino. Isso inclui todo o código adicionado e todos os arquivos de origem gerados. Os destinos de biblioteca pertencem a deps, enquanto outros arquivos binários necessários no momento da execução pertencem a data.
imports

List of strings; optional

Lista de diretórios de importação a serem adicionados ao PYTHONPATH.

Sujeito à substituição "Criar variável". Esses diretórios de importação serão adicionados para esta regra e todas as regras que dependem dela (observação: não as regras de que esta regra depende. Cada diretório será adicionado a PYTHONPATH por regras py_binary que dependem desta regra.

Caminhos absolutos (que começam com /) e aqueles que fazem referência a um caminho acima da raiz de execução não são permitidos e resultarão em erro.

legacy_create_init

Integer; optional; default is -1

Define se arquivos __init__.py vazios implicitamente na árvore dos arquivos de execução serão criados implicitamente. Eles são criados em todos os diretórios que contêm o código-fonte do Python ou bibliotecas compartilhadas e em todos os diretórios pai desses diretórios, exceto o diretório raiz do repositório. O padrão (automático) significa "true", a menos que --incompatible_default_to_explicit_init_py seja usado. Se for falso, o usuário será responsável por criar arquivos __init__.py, possivelmente vazios, e adicioná-los ao srcs de destinos Python, conforme necessário.
main

Label; optional

O nome do arquivo de origem que é o ponto de entrada principal do aplicativo. Esse arquivo também precisa estar listado em srcs. Se não for especificado, name será usado (veja acima). Se name não corresponder a nenhum nome de arquivo em srcs, main precisará ser especificado.
python_version

String; optional; nonconfigurable; default is "_INTERNAL_SENTINEL"

Define se esse destino (e o deps transitivo correspondente) será criado para Python 2 ou Python 3. Os valores válidos são "PY2" e "PY3" (o padrão).

A versão do Python é sempre redefinida (possivelmente por padrão) para a versão especificada por esse atributo, independentemente da versão especificada na linha de comando ou por outros destinos superiores que dependam desse.

Se você quiser select() na versão atual do Python, inspecione o valor de @rules_python//python:python_version. Consulte este link para mais informações.

Aviso de bug:esse atributo define a versão para que o Bazel cria seu destino, mas devido ao #4815 (link em inglês), o script de stub resultante ainda pode invocar a versão incorreta do intérprete no momento da execução. Consulte esta solução alternativa, que envolve definir um destino py_runtime que aponta para qualquer versão do Python conforme necessário e ativar esse py_runtime definindo --python_top.

srcs_version

String; optional; default is "PY2AND3"

Esse atributo declara a srcs do destino como compatível com Python 2, Python 3 ou ambos. Para definir a versão do ambiente de execução do Python, use o atributo python_version de uma regra executável do Python (py_binary ou py_test).

Os valores permitidos são "PY2AND3", "PY2" e "PY3". Os valores "PY2ONLY" e "PY3ONLY" também são permitidos por motivos históricos, mas são essencialmente os mesmos de "PY2" e "PY3" e precisam ser evitados.

Apenas as regras executáveis (py_binary e py_library ) verificam a versão atual do Python em relação ao valor desse atributo. Esse é um recurso. Como py_library não altera a versão atual do Python, se ele tivesse feito a validação, será impossível criar as bibliotecas PY2ONLY e PY3ONLY na mesma invocação. Além disso, se houver uma incompatibilidade de versão, o erro só será informado na fase de execução. Especificamente, o erro não aparecerá em uma invocação bazel build --nobuild.

Para ver informações de diagnóstico sobre quais dependências introduzem requisitos de versão, execute o aspecto find_requirements no destino: 

          bazel build <your target> \
              --aspects=@rules_python//python:defs.bzl%find_requirements \
              --output_groups=pyversioninfo
. Isso criará um arquivo com o sufixo -pyversioninfo.txt, fornecendo informações sobre por que seu destino exige uma versão do Python ou outra. Observe que ela funciona mesmo se o destino especificado falhar na criação devido a um conflito de versões.

stamp

Integer; optional; default is 0

Consulte a seção sobre argumentos py_binary(), mas o argumento stamp é definido como 0 por padrão para testes.

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 um ambiente de execução do Python usado para executar o código Python.

Um destino py_runtime pode representar um ambiente de execução da plataforma ou um ambiente de execução no build. Um ambiente de execução da plataforma acessa um intérprete instalado pelo sistema em um caminho conhecido, enquanto um ambiente de execução no build aponta para um destino executável que atua como intérprete. Em ambos os casos, um "intérprete" significa qualquer script de wrapper ou binário executável capaz de executar um script Python transmitido na linha de comando, seguindo as mesmas convenções do interpretador CPython padrão.

Por sua natureza, o ambiente de execução da plataforma não é hermético. Ela impõe um requisito na plataforma de destino para que um intérprete esteja localizado em um caminho específico. Um ambiente de execução no build pode ou não ser hermético, dependendo se aponta para um intérprete verificado ou para um script de wrapper que acessa o intérprete do sistema.

Exemplos

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

Um nome exclusivo para o destino.
coverage_tool

Label; optional

Esse é um destino a ser usado para coletar informações de cobertura de código de destinos py_binary e py_test.

Se definido, o destino precisa produzir um único arquivo ou ser um destino executável. O caminho para o único arquivo, ou o executável, se o destino for executável, determina o ponto de entrada para a ferramenta de cobertura do Python. O destino e os arquivos de execução dele serão adicionados aos arquivos de execução quando a cobertura estiver ativada.

O ponto de entrada da ferramenta precisa ser carregável por um intérprete do Python (por exemplo, um arquivo .py ou .pyc). Ele precisa aceitar os argumentos de linha de comando de coverage.py, incluindo pelo menos os subcomandos run e lcov.

files

List of labels; optional

Para um ambiente de execução no build, esse é o conjunto de arquivos que compõem esse ambiente de execução. Esses arquivos serão adicionados aos arquivos de execução dos binários do Python que usam esse ambiente de execução. Para um ambiente de execução de plataforma, esse atributo não pode ser definido.
interpreter

Label; optional

Para um ambiente de execução no build, é o destino a ser invocado como intérprete. Para um ambiente de execução de plataforma, esse atributo não pode ser definido.
interpreter_path

String; optional

Para um ambiente de execução da plataforma, esse é o caminho absoluto de um intérprete de Python na plataforma de destino. Para um ambiente de execução no build, esse atributo não pode ser definido.
python_version

String; optional; default is "_INTERNAL_SENTINEL"

Indica se este ambiente de execução é para a versão principal 2 ou 3 do Python. Os valores válidos são "PY2" e "PY3".

O valor padrão é controlado pela sinalização --incompatible_py3_is_default. No futuro, esse atributo será obrigatório e não terá valor padrão.

stub_shebang

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

Expressão "Shebang" anexada ao script de stub do Python de inicialização usado ao executar destinos py_binary.

Consulte o problema 8685 (link em inglês) para motivação.

Não se aplica ao Windows.