Aturan Python

Nightly · 8.4 · 8.3 · 8.2 · 8.1 · 8.0 · 7.6

Aturan

py_binary

Lihat sumber aturan 
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), struktur direktori *.runfiles yang berisi semua kode dan data yang diperlukan oleh program saat runtime, 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 lain kemudian dapat menemukan py_binary relatif terhadap direktori sumber. 

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

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

Argumen

Atribut
name

Nama; wajib

Nama unik untuk target ini.


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

Daftar label; defaultnya adalah []

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 py_library.
srcs

Daftar label; wajib diisi

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 sebaiknya berada di deps, sedangkan file biner lain yang diperlukan saat runtime sebaiknya berada di data.
imports

Daftar string; defaultnya adalah []

Daftar direktori impor yang akan ditambahkan ke PYTHONPATH.

Tunduk pada penggantian "Buat variabel". Direktori impor ini akan ditambahkan untuk aturan ini dan semua aturan yang bergantung padanya (catatan: bukan aturan yang bergantung pada 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 mereferensikan jalur di atas root eksekusi tidak diizinkan dan akan menyebabkan error.

legacy_create_init

Bilangan bulat; defaultnya adalah -1

Apakah akan membuat file __init__.py kosong secara implisit di pohon runfile. File ini dibuat di setiap direktori yang berisi kode sumber Python atau library bersama, dan setiap direktori induk dari direktori tersebut, kecuali direktori root repo. Default, otomatis, berarti benar kecuali jika --incompatible_default_to_explicit_init_py digunakan. Jika salah (false), pengguna bertanggung jawab untuk membuat file __init__.py (mungkin kosong) dan menambahkannya ke srcs target Python sesuai kebutuhan.
main

Label; defaultnya adalah None

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

String; tidak dapat dikonfigurasi; defaultnya adalah "_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 di command line atau oleh target yang lebih tinggi lainnya yang bergantung pada target ini.

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

Peringatan bug: Atribut ini menetapkan versi yang digunakan Bazel untuk membangun target Anda, tetapi karena #4815, skrip stub yang dihasilkan mungkin masih memanggil versi interpreter yang salah saat runtime. Lihat solusi ini, yang melibatkan penentuan target py_runtime yang mengarah ke salah satu versi Python sesuai kebutuhan, dan mengaktifkan py_runtime ini dengan menetapkan --python_top.

srcs_version

String; default-nya adalah "PY2AND3"

Atribut ini mendeklarasikan srcs target agar kompatibel dengan Python 2, Python 3, atau keduanya. Untuk benar-benar menyetel 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 karena 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 validasi dilakukan, PY2ONLY dan PY3ONLY tidak akan dapat dibangun dalam pemanggilan yang sama.) Selain itu, jika ada ketidakcocokan versi, error hanya dilaporkan pada fase eksekusi. Secara khusus, error tidak akan muncul dalam pemanggilan bazel build --nobuild.)

Untuk mendapatkan informasi diagnostik tentang dependensi mana 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 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

Bilangan bulat; defaultnya adalah -1

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

Biner yang diberi stempel tidak dibangun ulang kecuali jika dependensinya berubah.

py_library

Lihat sumber aturan 
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

Nama; wajib

Nama unik untuk target ini.
deps

Daftar label; defaultnya adalah []

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 py_library.
srcs

Daftar label; defaultnya adalah []

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

Daftar string; defaultnya adalah []

Daftar direktori impor yang akan ditambahkan ke PYTHONPATH.

Tunduk pada penggantian "Buat variabel". Direktori impor ini akan ditambahkan untuk aturan ini dan semua aturan yang bergantung padanya (catatan: bukan aturan yang bergantung pada 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 mereferensikan jalur di atas root eksekusi tidak diizinkan dan akan menyebabkan error.

srcs_version

String; default-nya adalah "PY2AND3"

Atribut ini mendeklarasikan srcs target agar kompatibel dengan Python 2, Python 3, atau keduanya. Untuk benar-benar menyetel 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 karena 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 validasi dilakukan, PY2ONLY dan PY3ONLY tidak akan dapat dibangun dalam pemanggilan yang sama.) Selain itu, jika ada ketidakcocokan versi, error hanya dilaporkan pada fase eksekusi. Secara khusus, error tidak akan muncul dalam pemanggilan bazel build --nobuild.)

Untuk mendapatkan informasi diagnostik tentang dependensi mana 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 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.

py_test

Lihat sumber aturan 
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

Nama; wajib

Nama unik untuk target ini.
deps

Daftar label; defaultnya adalah []

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 py_library.
srcs

Daftar label; wajib diisi

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 sebaiknya berada di deps, sedangkan file biner lain yang diperlukan saat runtime sebaiknya berada di data.
imports

Daftar string; defaultnya adalah []

Daftar direktori impor yang akan ditambahkan ke PYTHONPATH.

Tunduk pada penggantian "Buat variabel". Direktori impor ini akan ditambahkan untuk aturan ini dan semua aturan yang bergantung padanya (catatan: bukan aturan yang bergantung pada 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 mereferensikan jalur di atas root eksekusi tidak diizinkan dan akan menyebabkan error.

legacy_create_init

Bilangan bulat; defaultnya adalah -1

Apakah akan membuat file __init__.py kosong secara implisit di pohon runfile. File ini dibuat di setiap direktori yang berisi kode sumber Python atau library bersama, dan setiap direktori induk dari direktori tersebut, kecuali direktori root repo. Default, otomatis, berarti benar kecuali jika --incompatible_default_to_explicit_init_py digunakan. Jika salah (false), pengguna bertanggung jawab untuk membuat file __init__.py (mungkin kosong) dan menambahkannya ke srcs target Python sesuai kebutuhan.
main

Label; defaultnya adalah None

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

String; tidak dapat dikonfigurasi; defaultnya adalah "_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 di command line atau oleh target yang lebih tinggi lainnya yang bergantung pada target ini.

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

Peringatan bug: Atribut ini menetapkan versi yang digunakan Bazel untuk membangun target Anda, tetapi karena #4815, skrip stub yang dihasilkan mungkin masih memanggil versi interpreter yang salah saat runtime. Lihat solusi ini, yang melibatkan penentuan target py_runtime yang mengarah ke salah satu versi Python sesuai kebutuhan, dan mengaktifkan py_runtime ini dengan menetapkan --python_top.

srcs_version

String; default-nya adalah "PY2AND3"

Atribut ini mendeklarasikan srcs target agar kompatibel dengan Python 2, Python 3, atau keduanya. Untuk benar-benar menyetel 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 karena 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 validasi dilakukan, PY2ONLY dan PY3ONLY tidak akan dapat dibangun dalam pemanggilan yang sama.) Selain itu, jika ada ketidakcocokan versi, error hanya dilaporkan pada fase eksekusi. Secara khusus, error tidak akan muncul dalam pemanggilan bazel build --nobuild.)

Untuk mendapatkan informasi diagnostik tentang dependensi mana 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 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

Bilangan bulat; defaultnya adalah 0

Lihat bagian tentang argumen py_binary(), kecuali argumen stempel disetel ke 0 secara default untuk pengujian.

py_runtime

Lihat sumber aturan 
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)

Mewakili runtime Python yang digunakan untuk menjalankan kode Python.

Target py_runtime dapat merepresentasikan runtime platform atau runtime dalam build. Runtime platform mengakses interpreter yang diinstal sistem di jalur yang diketahui, sedangkan runtime dalam build mengarah ke target yang dapat dieksekusi yang bertindak sebagai interpreter. Dalam kedua kasus, "interpreter" berarti biner yang dapat dieksekusi atau skrip wrapper yang mampu menjalankan skrip Python yang diteruskan di command line, mengikuti konvensi yang sama dengan interpreter CPython standar.

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

Nama; wajib

Nama unik untuk target ini.
bootstrap_template

Label; defaultnya adalah "@bazel_tools//tools/python:python_bootstrap_template.txt"

Sebelumnya disebut sebagai "skrip stub Python", ini adalah titik entri ke setiap target yang dapat dieksekusi Python.
coverage_tool

Label; defaultnya adalah None

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

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

Titik entri untuk alat harus dapat dimuat oleh interpreter python (misalnya, file .py atau .pyc). Harus menerima argumen command line dari coverage.py, setidaknya termasuk subperintah run dan lcov.

files

Daftar label; defaultnya adalah []

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

Label; defaultnya adalah None

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

String; default-nya adalah ""

Untuk runtime platform, ini adalah jalur absolut interpreter Python di platform target. Untuk runtime bawaan, atribut ini tidak boleh ditetapkan.
python_version

String; default-nya adalah "_INTERNAL_SENTINEL"

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

Nilai default dikontrol oleh flag --incompatible_py3_is_default. Namun, pada masa mendatang, atribut ini akan menjadi wajib dan tidak memiliki nilai default.

stub_shebang

String; default-nya adalah "#!/usr/bin/env python3"

Ekspresi "shebang" yang ditambahkan ke skrip Python bootstrapping yang digunakan saat menjalankan target py_binary.

Lihat masalah 8685 untuk motivasi.

Tidak berlaku untuk Windows.