Regras do Python

Report an issue View source Nightly · 8.0 7.4 . 7.3 · 7.2 · 7.1 · 7.0 · 6.5

Regras

py_binary

Acessar a origem da regra 
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 pertencentes 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 tempo de execução e um script stub que inicia o programa com o ambiente e os dados iniciais 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 em outro teste ou binário (por exemplo, executar um binário Python para configurar um recurso simulado em um java_test), a abordagem correta é fazer com que o outro teste ou binário dependa do py_binary na seção de dados. O outro binário pode localizar o py_binary em relação ao diretório de origem. 

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

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

Argumentos

Atributos
name

Nome: obrigatório

Um nome exclusivo para essa segmentação.


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

Lista de rótulos; o padrão é []

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

Lista de rótulos; obrigatório

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

Lista de strings. O padrão é [].

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

Sujeito à substituição de "Make variable". Esses diretórios de importação serão adicionados a essa regra e a todas as regras que dependem dela (não as regras em que essa regra depende). Cada diretório será adicionado a PYTHONPATH pelas regras py_binary que dependem dessa regra.

Caminhos absolutos (que começam com /) e caminhos que referenciam um caminho acima da raiz de execução não são permitidos e resultarão em um erro.

legacy_create_init

Inteiro; padrão é -1

Define se os arquivos __init__.py vazios serão criados implicitamente na árvore de arquivos de execução. Elas são criadas em todos os diretórios que contêm código-fonte do Python ou bibliotecas compartilhadas e em todos os diretórios pais desses diretórios, excluindo o diretório raiz do repositório. O padrão, "auto", 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 do Python conforme necessário.
main

Rótulo: o padrão é None.

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; não configurável; o padrão é "_INTERNAL_SENTINEL"

Define se esse destino (e o deps transitivo dele) será criado para Python 2 ou Python 3. Os valores válidos são "PY2" e "PY3" (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 mais altos que dependem dela.

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

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

srcs_version

String; o padrão é "PY2AND3"

Esse atributo declara que o srcs do destino é compatível com o 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 iguais a "PY2" e "PY3" e devem ser evitados.

Somente 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 muda a versão atual do Python, se ele fizesse a validação, seria 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 vai aparecer em uma invocação de bazel build --nobuild.

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

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

Inteiro; padrão é -1

Define se as informações de build serão codificadas no binário. Valores possíveis:
  • stamp = 1: sempre carimbe as informações do build no binário, mesmo em --nostamp. Evite essa configuração, porque ela pode interromper o armazenamento em cache remoto do binário e de qualquer ação downstream que dependa dele.
  • stamp = 0: sempre substitua as informações de build por valores constantes. Isso gera um bom cache de resultados de build.
  • stamp = -1: a incorporação de informações de build é controlada pela flag --[no]stamp.

Os binários carimbados não são reconstruídos, a menos que as dependências mudem.

py_library

Acessar a origem da regra 
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

Nome: obrigatório

Um nome exclusivo para essa segmentação.
deps

Lista de rótulos; o padrão é []

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

Lista de rótulos; o padrão é []

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

Lista de strings. O padrão é [].

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

Sujeito à substituição de "Make variable". Esses diretórios de importação serão adicionados a essa regra e a todas as regras que dependem dela (não as regras em que essa regra depende). Cada diretório será adicionado a PYTHONPATH pelas regras py_binary que dependem dessa regra.

Caminhos absolutos (que começam com /) e caminhos que referenciam um caminho acima da raiz de execução não são permitidos e resultarão em um erro.

srcs_version

String; o padrão é "PY2AND3"

Esse atributo declara que o srcs do destino é compatível com o 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 iguais a "PY2" e "PY3" e devem ser evitados.

Somente 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 muda a versão atual do Python, se ele fizesse a validação, seria 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 vai aparecer em uma invocação de bazel build --nobuild.

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

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

py_test

Acessar a origem da regra 
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

Nome: obrigatório

Um nome exclusivo para essa segmentação.
deps

Lista de rótulos; o padrão é []

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

Lista de rótulos; obrigatório

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

Lista de strings. O padrão é [].

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

Sujeito à substituição de "Make variable". Esses diretórios de importação serão adicionados a essa regra e a todas as regras que dependem dela (não as regras em que essa regra depende). Cada diretório será adicionado a PYTHONPATH pelas regras py_binary que dependem dessa regra.

Caminhos absolutos (que começam com /) e caminhos que referenciam um caminho acima da raiz de execução não são permitidos e resultarão em um erro.

legacy_create_init

Inteiro; padrão é -1

Define se os arquivos __init__.py vazios serão criados implicitamente na árvore de arquivos de execução. Elas são criadas em todos os diretórios que contêm código-fonte do Python ou bibliotecas compartilhadas e em todos os diretórios pais desses diretórios, excluindo o diretório raiz do repositório. O padrão, "auto", 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 do Python conforme necessário.
main

Rótulo: o padrão é None.

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; não configurável; o padrão é "_INTERNAL_SENTINEL"

Define se esse destino (e o deps transitivo dele) será criado para Python 2 ou Python 3. Os valores válidos são "PY2" e "PY3" (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 mais altos que dependem dela.

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

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

srcs_version

String; o padrão é "PY2AND3"

Esse atributo declara que o srcs do destino é compatível com o 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 iguais a "PY2" e "PY3" e devem ser evitados.

Somente 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 muda a versão atual do Python, se ele fizesse a validação, seria 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 vai aparecer em uma invocação de bazel build --nobuild.

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

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

Inteiro; padrão é 0

Consulte a seção sobre argumentos py_binary(), exceto que o argumento de carimbo é definido como 0 por padrão para testes.

py_runtime

Acessar a origem da regra 
py_runtime(name, bootstrap_template, 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 código Python.

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

Por natureza, o ambiente de execução da plataforma não é hermético. Ele impõe um requisito à plataforma de destino para ter um intérprete localizado em um caminho específico. Um ambiente de execução integrado pode ou não ser hermético, dependendo se ele aponta para um interpretador registrado ou um script de wrapper que acessa o interpretador do sistema.

Exemplo:

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

Nome: obrigatório

Um nome exclusivo para essa segmentação.
bootstrap_template

Rótulo: o padrão é "@bazel_tools//tools/python:python_bootstrap_template.txt".

Anteriormente chamado de "script de stub do Python", esse é o ponto de entrada para todas as finalidades executáveis do Python.
coverage_tool

Rótulo: o padrão é None.

É 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 da ferramenta de cobertura do Python. O destino e os runfiles serão adicionados aos runfiles quando a cobertura for ativada.

O ponto de entrada da ferramenta precisa ser carregado por um interpretador 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

Lista de rótulos; o padrão é []

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

Rótulo: o padrão é None.

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

String; o padrão é ""

Para um ambiente de execução de plataforma, esse é o caminho absoluto de um interpretador do Python na plataforma de destino. Para um ambiente de execução integrado, esse atributo não precisa ser definido.
python_version

String; o padrão é "_INTERNAL_SENTINEL"

Indica se o 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 flag --incompatible_py3_is_default. No entanto, no futuro, esse atributo será obrigatório e não terá um valor padrão.

stub_shebang

String; o padrão é "#!/usr/bin/env python3"

A expressão "Shebang" foi adicionada ao script de inicialização do Python usado ao executar destinos py_binary.

Consulte o problema 8685 para saber mais.

Não se aplica ao Windows.