Aturan Python

Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

Aturan

pi_biner

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 aturan py_library lainnya), hierarki direktori *.runfiles yang berisi semua kode dan data yang diperlukan oleh program pada waktu proses, dan skrip stub 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 atau pengujian lain (misalnya, menjalankan biner python untuk menyiapkan beberapa resource tiruan dari dalam java_test), pendekatan yang benar adalah membuat biner atau pengujian lain bergantung pada py_binary di bagian datanya. Biner lainnya kemudian dapat menemukan py_binary secara relatif terhadap direktori sumber.

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, nilainya harus sama dengan nama file sumber yang merupakan titik masuk utama aplikasi, tanpa ekstensi. Misalnya, jika titik entri Anda disebut main.py, nama Anda harus berupa 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. Aturan ini umumnya adalah aturan py_library.
srcs

List of labels; required

Daftar file sumber (.py) yang diproses untuk membuat target. Ini termasuk semua kode check-in dan file sumber yang dihasilkan. Target library berada di deps, sementara file biner lain yang diperlukan pada runtime berada di data.
imports

List of strings; optional

Daftar direktori impor yang akan ditambahkan ke PYTHONPATH.

Tunduk pada substitusi "Buat variabel". Direktori impor ini akan ditambahkan untuk aturan ini dan semua aturan yang bergantung padanya (catatan: bukan aturan yang diandalkan aturan ini. Setiap direktori akan ditambahkan ke PYTHONPATH oleh aturan py_binary yang bergantung pada aturan ini.

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

legacy_create_init

Integer; optional; default is -1

Apakah akan membuat file __init__.py kosong secara implisit di hierarki runfiles. Nama ini dibuat di setiap direktori yang berisi kode sumber Python atau library bersama, dan setiap direktori induk dari direktori tersebut, tidak termasuk direktori utama repo. Default, otomatis, berarti benar kecuali jika --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 dalam srcs. Jika tidak ditentukan, name akan digunakan (lihat di atas). Jika name tidak sesuai dengan nama file mana pun di srcs, main harus ditentukan.
python_version

String; optional; nonconfigurable; default is "_INTERNAL_SENTINEL"

Apakah akan mem-build 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 command line atau oleh target lebih tinggi lainnya yang bergantung pada ini.

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

Peringatan bug: Atribut ini menetapkan versi yang digunakan Bazel untuk membuat target Anda, tetapi karena #4815, skrip stub yang dihasilkan mungkin masih memanggil versi penafsir yang salah pada runtime. Lihat solusi ini, yang melibatkan penentuan target py_runtime yang mengarah ke versi Python sesuai kebutuhan, dan mengaktifkan py_runtime ini dengan menetapkan --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 atribut python_version dari aturan Python yang dapat dieksekusi (py_binary atau py_test).

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

Perhatikan 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 versi Python saat ini, jika dilakukan, tidak mungkin mem-build library PY2ONLY dan PY3ONLY dalam pemanggilan yang sama.) Selain itu, jika terdapat ketidakcocokan versi, error hanya akan dilaporkan dalam fase eksekusi. Khususnya, 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 Anda:

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

stamp

Integer; optional; default is -1

Apakah akan mengenkode informasi build ke dalam biner. Nilai yang memungkinkan:
  • stamp = 1: Selalu cap informasi build ke dalam biner, bahkan dalam build --nostamp. Setelan ini harus dihindari, karena berpotensi menghentikan caching jarak jauh untuk biner dan tindakan downstream yang bergantung padanya.
  • stamp = 0: Selalu ganti informasi build dengan nilai konstan. Hal ini memberikan cache hasil build yang baik.
  • stamp = -1: Penyematan informasi build dikontrol oleh flag --[no]stamp.

Biner yang dicap tidak akan dibuat ulang kecuali jika dependensinya berubah.

library_py

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. Aturan ini umumnya adalah aturan py_library.
srcs

List of labels; optional

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

List of strings; optional

Daftar direktori impor yang akan ditambahkan ke PYTHONPATH.

Tunduk pada substitusi "Buat variabel". Direktori impor ini akan ditambahkan untuk aturan ini dan semua aturan yang bergantung padanya (catatan: bukan aturan yang diandalkan aturan ini. Setiap direktori akan ditambahkan ke PYTHONPATH oleh aturan py_binary yang bergantung pada aturan ini.

Jalur absolut (jalur yang dimulai dengan /) dan jalur yang merujuk ke jalur di atas root eksekusi tidak diizinkan dan akan menyebabkan 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 atribut python_version dari aturan Python yang dapat dieksekusi (py_binary atau py_test).

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

Perhatikan 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 versi Python saat ini, jika dilakukan, tidak mungkin mem-build library PY2ONLY dan PY3ONLY dalam pemanggilan yang sama.) Selain itu, jika terdapat ketidakcocokan versi, error hanya akan dilaporkan dalam fase eksekusi. Khususnya, 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 Anda:

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

uji_py

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 di sekitar beberapa kode pengujian.

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. Aturan ini umumnya adalah aturan py_library.
srcs

List of labels; required

Daftar file sumber (.py) yang diproses untuk membuat target. Ini termasuk semua kode check-in dan file sumber yang dihasilkan. Target library berada di deps, sementara file biner lain yang diperlukan pada runtime berada di data.
imports

List of strings; optional

Daftar direktori impor yang akan ditambahkan ke PYTHONPATH.

Tunduk pada substitusi "Buat variabel". Direktori impor ini akan ditambahkan untuk aturan ini dan semua aturan yang bergantung padanya (catatan: bukan aturan yang diandalkan aturan ini. Setiap direktori akan ditambahkan ke PYTHONPATH oleh aturan py_binary yang bergantung pada aturan ini.

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

legacy_create_init

Integer; optional; default is -1

Apakah akan membuat file __init__.py kosong secara implisit di hierarki runfiles. Nama ini dibuat di setiap direktori yang berisi kode sumber Python atau library bersama, dan setiap direktori induk dari direktori tersebut, tidak termasuk direktori utama repo. Default, otomatis, berarti benar kecuali jika --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 dalam srcs. Jika tidak ditentukan, name akan digunakan (lihat di atas). Jika name tidak sesuai dengan nama file mana pun di srcs, main harus ditentukan.
python_version

String; optional; nonconfigurable; default is "_INTERNAL_SENTINEL"

Apakah akan mem-build 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 command line atau oleh target lebih tinggi lainnya yang bergantung pada ini.

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

Peringatan bug: Atribut ini menetapkan versi yang digunakan Bazel untuk membuat target Anda, tetapi karena #4815, skrip stub yang dihasilkan mungkin masih memanggil versi penafsir yang salah pada runtime. Lihat solusi ini, yang melibatkan penentuan target py_runtime yang mengarah ke versi Python sesuai kebutuhan, dan mengaktifkan py_runtime ini dengan menetapkan --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 atribut python_version dari aturan Python yang dapat dieksekusi (py_binary atau py_test).

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

Perhatikan 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 versi Python saat ini, jika dilakukan, tidak mungkin mem-build library PY2ONLY dan PY3ONLY dalam pemanggilan yang sama.) Selain itu, jika terdapat ketidakcocokan versi, error hanya akan dilaporkan dalam fase eksekusi. Khususnya, 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 Anda:

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

stamp

Integer; optional; default is 0

Lihat bagian argumen py_binary(), kecuali argumen stempel ditetapkan ke 0 secara default 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 dalam build. Runtime platform mengakses penafsir yang diinstal sistem pada jalur yang diketahui, sedangkan runtime dalam build mengarah ke target yang dapat dieksekusi yang bertindak sebagai penafsir. Dalam kedua kasus, "Interpreter" berarti setiap skrip biner atau wrapper yang dapat dieksekusi yang mampu menjalankan skrip Python yang diteruskan pada command line, mengikuti konvensi yang sama dengan penafsir CPython standar.

Runtime platform pada dasarnya bersifat non-hermetik. Fitur ini menerapkan persyaratan pada platform target untuk menempatkan penafsir yang berada di jalur tertentu. Runtime in-build mungkin atau mungkin tidak hermetik, bergantung pada apakah runtime tersebut mengarah ke penafsir check-in atau skrip wrapper yang mengakses penafsir 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

Ini adalah target yang digunakan untuk mengumpulkan informasi cakupan kode dari target py_binary dan py_test.

Jika ditetapkan, target harus menghasilkan satu file atau menjadi target yang dapat dieksekusi. Jalur ke satu file, atau file yang dapat dieksekusi jika target dapat dieksekusi, akan menentukan titik entri untuk alat cakupan python. Target dan runfile-nya akan ditambahkan ke runfile saat cakupan diaktifkan.

Titik entri untuk alat ini harus dapat dimuat oleh penafsir python (misalnya, file .py atau .pyc). Argumen command line harus menerima coverage.py, setidaknya yang menyertakan 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 waktu proses platform, atribut ini tidak boleh ditetapkan.
interpreter

Label; optional

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

String; optional

Untuk runtime platform, ini adalah jalur absolut penafsir Python di platform target. Untuk waktu proses build, atribut ini tidak boleh ditetapkan.
python_version

String; optional; default is "_INTERNAL_SENTINEL"

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

Nilai default dikontrol oleh flag --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 sebelum skrip stub Python bootstrap yang digunakan saat menjalankan target py_binary.

Lihat masalah 8685 untuk motivasi.

Tidak berlaku untuk Windows.