Aturan Python

Aturan

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)

py_binary adalah program Python yang dapat dieksekusi yang terdiri dari kumpulan file sumber .py (mungkin milik ke aturan py_library lainnya), *.runfiles direktori yang berisi semua kode dan data yang dibutuhkan oleh program saat runtime, dan skrip rintisan yang memulai program dengan lingkungan dan data awal yang benar.

Contoh

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

Jika Anda ingin menjalankan py_binary dari dalam biner lain atau (misalnya, menjalankan biner python untuk menyiapkan beberapa resource tiruan dari dalam java_test) maka pendekatan yang tepat adalah membuat biner lain atau pengujian bergantung pada py_binary di bagian datanya. Lainnya maka biner dapat menemukan py_binary relatif terhadap sumbernya saat ini. 

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

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

Argumen

Atribut
name

Name; required

Nama unik untuk target ini.


Jika main tidak ditentukan, namanya harus sama dengan dari file sumber yang merupakan titik masuk utama aplikasi, tanpa ekstensi. Misalnya, jika titik entri Anda main.py, maka nama Anda harus main.
deps

List of labels; optional

Daftar library lain yang akan ditautkan ke target biner. Lihat komentar umum tentang deps di Atribut umum yang ditentukan oleh sebagian besar aturan build. Ini umumnya py_library aturan.
srcs

List of labels; required

Daftar file sumber (.py) yang diproses untuk membuat target. Ini mencakup semua kode yang Anda check-in dan semua file sumber yang dihasilkan. Target library termasuk dalam deps, sedangkan file biner lain yang diperlukan saat runtime termasuk dalam data.
imports

List of strings; optional

Daftar direktori impor yang akan ditambahkan ke PYTHONPATH.

Tunduk pada substitusi "Buat variabel". Impor ini direktori akan ditambahkan untuk aturan ini dan semua aturan yang bergantung padanya (catatan: bukan aturan yang menjadi dependensi aturan ini. Setiap direktori akan ditambahkan ke PYTHONPATH dengan py_binary aturan yang bergantung pada aturan ini.

Jalur absolut (jalur yang diawali dengan /) dan jalur yang merujuk ke jalur di atas root eksekusi tidak diizinkan dan akan mengakibatkan error.

legacy_create_init

Integer; optional; default is -1

Apakah akan membuat file __init__.py kosong secara implisit di hierarki runfiles. Ini dibuat di setiap direktori yang berisi kode sumber Python atau bersama, dan setiap direktori induk dari direktori tersebut, tidak termasuk root repo saat ini. Nilai {i>default<i}, {i>auto<i}, berarti benar (true) kecuali --incompatible_default_to_explicit_init_py digunakan. Jika salah, pengguna bertanggung jawab untuk membuat (mungkin kosong) file __init__.py dan menambahkannya ke srcs target Python sesuai kebutuhan.
main

Label; optional

Nama file sumber yang merupakan titik entri utama aplikasi. File ini juga harus dicantumkan di srcs. Jika tidak ditentukan, name digunakan sebagai gantinya (lihat di atas). Jika name tidak cocok dengan nama file apa pun dalam srcs, main harus ditentukan.
python_version

String; optional; nonconfigurable; default is "_INTERNAL_SENTINEL"

Apakah akan membangun target ini (dan deps transitifnya) untuk Python 2 atau Python 3. Nilai yang valid adalah "PY2" dan "PY3" (default).

Versi Python selalu direset (mungkin secara default) ke versi apa pun yang ditentukan oleh atribut ini, terlepas dari versi yang ditentukan pada baris perintah atau dengan target lain yang lebih tinggi yang bergantung pada hal ini.

Jika ingin melakukan select() pada versi Python saat ini, Anda dapat memeriksa senilai @rules_python//python:python_version. Lihat di sini untuk informasi selengkapnya.

Peringatan bug: Atribut ini menetapkan versi target Anda yang akan dibuat oleh Bazel. tetapi karena #4815, skrip potongan yang dihasilkan masih bisa memanggil versi penerjemah yang salah pada saat runtime. Lihat ini solusi, yang melibatkan penentuan target py_runtime yang mengarah ke salah satu versi Python sesuai kebutuhan, dan mengaktifkan py_runtime ini dengan menyetel --python_top.

srcs_version

String; optional; default is "PY2AND3"

Atribut ini mendeklarasikan srcs target agar kompatibel dengan Python 2, Python 3, atau keduanya. Untuk menetapkan versi runtime Python, gunakan metode Atribut python_version dari aturan Python (py_binary atau py_test).

Nilai yang diizinkan adalah: "PY2AND3", "PY2", dan "PY3". Nilai "PY2ONLY" dan "PY3ONLY" juga diizinkan untuk histori alasan, tetapi pada dasarnya sama dengan "PY2" dan "PY3" dan harus dihindari.

Perlu diperhatikan bahwa hanya aturan yang dapat dieksekusi (py_binary dan py_library ) yang benar-benar memverifikasi versi Python saat ini terhadap nilai atribut ini. (Ini adalah fitur; karena py_library tidak mengubah Python saat ini Jika melakukan validasi, maka tidak mungkin membuat PY2ONLY dan PY3ONLY dalam pemanggilan yang sama.) Selain itu, jika ada ketidakcocokan versi, error hanya dilaporkan pada fase eksekusi. Secara khusus, model error tidak akan muncul dalam pemanggilan bazel build --nobuild.)

Untuk mendapatkan informasi diagnostik tentang dependensi yang memperkenalkan persyaratan versi, Anda dapat menjalankan aspek find_requirements pada target: 

          bazel build <your target> \
              --aspects=@rules_python//python:defs.bzl%find_requirements \
              --output_groups=pyversioninfo
Tindakan ini akan membangun file dengan akhiran -pyversioninfo.txt yang memberikan informasi tentang mengapa target Anda memerlukan satu versi Python atau yang lainnya. Perhatikan bahwa ini tetap akan berfungsi meskipun target yang ditentukan gagal di-build karena adanya konflik versi.
stamp

Integer; optional; default is -1

Apakah ingin mengenkode informasi build ke dalam biner. Nilai yang mungkin:
  • stamp = 1: Selalu tambahkan informasi build ke dalam biner, bahkan dalam --nostamp build. Ini harus dihindari, karena berpotensi mematikan caching jarak jauh untuk biner dan tindakan downstream apa pun yang bergantung padanya.
  • stamp = 0: Selalu ganti informasi build dengan nilai konstanta. Ini memberikan cache hasil build yang baik.
  • stamp = -1: Penyematan informasi build dikontrol oleh Tanda --[no]stamp.

Biner yang distempel tidak dibangun ulang kecuali jika dependensinya berubah.

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)

Argumen

Atribut
name

Name; required

Nama unik untuk target ini.
deps

List of labels; optional

Daftar library lain yang akan ditautkan ke target biner. Lihat komentar umum tentang deps di Atribut umum yang ditentukan oleh sebagian besar aturan build. Ini umumnya py_library aturan.
srcs

List of labels; optional

Daftar file sumber (.py) yang diproses untuk membuat target. Ini mencakup semua kode yang Anda check-in dan semua file sumber yang dihasilkan.
imports

List of strings; optional

Daftar direktori impor yang akan ditambahkan ke PYTHONPATH.

Tunduk pada substitusi "Buat variabel". Impor ini direktori akan ditambahkan untuk aturan ini dan semua aturan yang bergantung padanya (catatan: bukan aturan yang menjadi dependensi aturan ini. Setiap direktori akan ditambahkan ke PYTHONPATH dengan py_binary aturan yang bergantung pada aturan ini.

Jalur absolut (jalur yang diawali dengan /) dan jalur yang merujuk ke jalur di atas root eksekusi tidak diizinkan dan akan mengakibatkan error.

srcs_version

String; optional; default is "PY2AND3"

Atribut ini mendeklarasikan srcs target agar kompatibel dengan Python 2, Python 3, atau keduanya. Untuk menetapkan versi runtime Python, gunakan metode Atribut python_version dari aturan Python (py_binary atau py_test).

Nilai yang diizinkan adalah: "PY2AND3", "PY2", dan "PY3". Nilai "PY2ONLY" dan "PY3ONLY" juga diizinkan untuk histori alasan, tetapi pada dasarnya sama dengan "PY2" dan "PY3" dan harus dihindari.

Perlu diperhatikan bahwa hanya aturan yang dapat dieksekusi (py_binary dan py_library ) yang benar-benar memverifikasi versi Python saat ini terhadap nilai atribut ini. (Ini adalah fitur; karena py_library tidak mengubah Python saat ini Jika melakukan validasi, maka tidak mungkin membuat PY2ONLY dan PY3ONLY dalam pemanggilan yang sama.) Selain itu, jika ada ketidakcocokan versi, error hanya dilaporkan pada fase eksekusi. Secara khusus, model error tidak akan muncul dalam pemanggilan bazel build --nobuild.)

Untuk mendapatkan informasi diagnostik tentang dependensi yang memperkenalkan persyaratan versi, Anda dapat menjalankan aspek find_requirements pada target: 

          bazel build <your target> \
              --aspects=@rules_python//python:defs.bzl%find_requirements \
              --output_groups=pyversioninfo
Tindakan ini akan membangun file dengan akhiran -pyversioninfo.txt yang memberikan informasi tentang mengapa target Anda memerlukan satu versi Python atau yang lainnya. Perhatikan bahwa ini tetap akan berfungsi meskipun target yang ditentukan gagal di-build karena adanya konflik versi.

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)

Aturan py_test() mengompilasi pengujian. Pengujian adalah wrapper biner pada beberapa kode uji.

Contoh

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

Anda juga dapat menentukan modul utama:

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

Argumen

Atribut
name

Name; required

Nama unik untuk target ini.
deps

List of labels; optional

Daftar library lain yang akan ditautkan ke target biner. Lihat komentar umum tentang deps di Atribut umum yang ditentukan oleh sebagian besar aturan build. Ini umumnya py_library aturan.
srcs

List of labels; required

Daftar file sumber (.py) yang diproses untuk membuat target. Ini mencakup semua kode yang Anda check-in dan semua file sumber yang dihasilkan. Target library termasuk dalam deps, sedangkan file biner lain yang diperlukan saat runtime termasuk dalam data.
imports

List of strings; optional

Daftar direktori impor yang akan ditambahkan ke PYTHONPATH.

Tunduk pada substitusi "Buat variabel". Impor ini direktori akan ditambahkan untuk aturan ini dan semua aturan yang bergantung padanya (catatan: bukan aturan yang menjadi dependensi aturan ini. Setiap direktori akan ditambahkan ke PYTHONPATH dengan py_binary aturan yang bergantung pada aturan ini.

Jalur absolut (jalur yang diawali dengan /) dan jalur yang merujuk ke jalur di atas root eksekusi tidak diizinkan dan akan mengakibatkan error.

legacy_create_init

Integer; optional; default is -1

Apakah akan membuat file __init__.py kosong secara implisit di hierarki runfiles. Ini dibuat di setiap direktori yang berisi kode sumber Python atau bersama, dan setiap direktori induk dari direktori tersebut, tidak termasuk root repo saat ini. Nilai {i>default<i}, {i>auto<i}, berarti benar (true) kecuali --incompatible_default_to_explicit_init_py digunakan. Jika salah, pengguna bertanggung jawab untuk membuat (mungkin kosong) file __init__.py dan menambahkannya ke srcs target Python sesuai kebutuhan.
main

Label; optional

Nama file sumber yang merupakan titik entri utama aplikasi. File ini juga harus dicantumkan di srcs. Jika tidak ditentukan, name digunakan sebagai gantinya (lihat di atas). Jika name tidak cocok dengan nama file apa pun dalam srcs, main harus ditentukan.
python_version

String; optional; nonconfigurable; default is "_INTERNAL_SENTINEL"

Apakah akan membangun target ini (dan deps transitifnya) untuk Python 2 atau Python 3. Nilai yang valid adalah "PY2" dan "PY3" (default).

Versi Python selalu direset (mungkin secara default) ke versi apa pun yang ditentukan oleh atribut ini, terlepas dari versi yang ditentukan pada baris perintah atau dengan target lain yang lebih tinggi yang bergantung pada hal ini.

Jika ingin melakukan select() pada versi Python saat ini, Anda dapat memeriksa senilai @rules_python//python:python_version. Lihat di sini untuk informasi selengkapnya.

Peringatan bug: Atribut ini menetapkan versi target Anda yang akan dibuat oleh Bazel. tetapi karena #4815, skrip potongan yang dihasilkan masih bisa memanggil versi penerjemah yang salah pada saat runtime. Lihat ini solusi, yang melibatkan penentuan target py_runtime yang mengarah ke salah satu versi Python sesuai kebutuhan, dan mengaktifkan py_runtime ini dengan menyetel --python_top.

srcs_version

String; optional; default is "PY2AND3"

Atribut ini mendeklarasikan srcs target agar kompatibel dengan Python 2, Python 3, atau keduanya. Untuk menetapkan versi runtime Python, gunakan metode Atribut python_version dari aturan Python (py_binary atau py_test).

Nilai yang diizinkan adalah: "PY2AND3", "PY2", dan "PY3". Nilai "PY2ONLY" dan "PY3ONLY" juga diizinkan untuk histori alasan, tetapi pada dasarnya sama dengan "PY2" dan "PY3" dan harus dihindari.

Perlu diperhatikan bahwa hanya aturan yang dapat dieksekusi (py_binary dan py_library ) yang benar-benar memverifikasi versi Python saat ini terhadap nilai atribut ini. (Ini adalah fitur; karena py_library tidak mengubah Python saat ini Jika melakukan validasi, maka tidak mungkin membuat PY2ONLY dan PY3ONLY dalam pemanggilan yang sama.) Selain itu, jika ada ketidakcocokan versi, error hanya dilaporkan pada fase eksekusi. Secara khusus, model error tidak akan muncul dalam pemanggilan bazel build --nobuild.)

Untuk mendapatkan informasi diagnostik tentang dependensi yang memperkenalkan persyaratan versi, Anda dapat menjalankan aspek find_requirements pada target: 

          bazel build <your target> \
              --aspects=@rules_python//python:defs.bzl%find_requirements \
              --output_groups=pyversioninfo
Tindakan ini akan membangun file dengan akhiran -pyversioninfo.txt yang memberikan informasi tentang mengapa target Anda memerlukan satu versi Python atau yang lainnya. Perhatikan bahwa ini tetap akan berfungsi meskipun target yang ditentukan gagal di-build karena adanya konflik versi.
stamp

Integer; optional; default is 0

Lihat bagian tentang argumen py_binary(), kecuali bahwa argumen {i>cap<i} disetel ke 0 secara {i>default<i} untuk pengujian.

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)

Mewakili runtime Python yang digunakan untuk mengeksekusi kode Python.

Target py_runtime dapat mewakili runtime platform atau runtime in-build. Runtime platform mengakses penafsir yang diinstal sistem pada sedangkan runtime dalam build menunjuk ke target yang dapat dieksekusi yang bertindak sebagai penafsir. Di beberapa kedua kasus tersebut, seorang "penafsir" berarti setiap skrip biner atau wrapper yang dapat dieksekusi yang mampu menjalankan skrip Python yang diteruskan pada baris perintah, mengikuti konvensi yang sama dengan Penerjemah CPython.

Runtime platform pada dasarnya bersifat non-hermetik. Menerapkan persyaratan pada platform target memiliki penerjemah yang terletak di jalur tertentu. Runtime in-build mungkin bersifat hermetik atau tidak, tergantung pada apakah skrip itu menunjuk ke {i>check-in interpreter<i} atau skrip wrapper yang mengakses penerjemah sistem.

Contoh:

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",
)

Argumen

Atribut
name

Name; required

Nama unik untuk target ini.
coverage_tool

Label; optional

Target ini adalah target yang akan digunakan untuk mengumpulkan informasi cakupan kode dari py_binary dan py_test target.

Jika ditetapkan, target harus menghasilkan satu file atau menjadi target yang dapat dieksekusi. Jalur ke file tunggal, atau {i>executable<i} jika target dapat dieksekusi, menentukan titik entri untuk alat cakupan python. Target dan runfiles akan ditambahkan ke runfile saat cakupan diaktifkan.

Titik entri untuk alat harus dapat dimuat oleh penafsir python (mis. File .py atau .pyc). Aplikasi harus menerima argumen command line coverage.py, setidaknya termasuk subperintah run dan lcov.

files

List of labels; optional

Untuk runtime dalam build, ini adalah kumpulan file yang terdiri dari runtime ini. File ini akan ditambahkan ke runfile biner Python yang menggunakan runtime ini. Untuk runtime platform atribut ini tidak boleh ditetapkan.
interpreter

Label; optional

Untuk runtime dalam build, ini adalah target yang akan dipanggil sebagai penafsir. Untuk platform atribut ini tidak boleh ditetapkan.
interpreter_path

String; optional

Untuk runtime platform, ini adalah jalur absolut penafsir Python pada target terkelola sepenuhnya. Untuk runtime dalam build, atribut ini tidak boleh ditetapkan.
python_version

String; optional; default is "_INTERNAL_SENTINEL"

Apakah runtime ini ditujukan untuk Python versi utama 2 atau 3. Nilai yang valid adalah "PY2" dan "PY3".

Nilai default dikontrol oleh tanda --incompatible_py3_is_default. Namun, di masa mendatang, atribut ini akan bersifat wajib dan tidak memiliki nilai default.

stub_shebang

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

"Shebang" ekspresi ditambahkan ke skrip stub Python bootstrap yang digunakan saat mengeksekusi py_binary target.

Lihat masalah 8685 untuk motivasi.

Tidak berlaku untuk Windows.