BazelCon 2022 akan hadir pada 16-17 November ke New York dan online.
Daftar sekarang.

Aturan Python

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

Aturan

py_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 termasuk dalam aturan py_library lainnya), hierarki direktori *.runfiles yang berisi semua kode dan data yang diperlukan oleh program pada 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 tepat adalah membuat metode biner atau pengujian bergantung pada py_binary di bagian datanya. Selanjutnya, biner lainnya dapat menemukan py_binary terkait dengan 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, nama ini harus sama dengan nama file sumber yang merupakan titik entri utama aplikasi, tanpa ekstensi. Misalnya, jika titik entri Anda disebut main.py, 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. Umumnya adalah aturan py_library.
srcs

List of labels; required

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

List of strings; optional

Daftar direktori impor yang akan ditambahkan ke PYTHONPATH.

Tunduk pada substitusi "Make variable". Direktori impor ini akan ditambahkan untuk aturan ini dan semua aturan yang bergantung padanya (perhatikan: bukan aturan yang menjadi dependensi 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 menghasilkan error.

legacy_create_init

Integer; optional; default is -1

Apakah akan secara implisit membuat file __init__.py kosong di hierarki runfiles. Ini dibuat di setiap direktori yang berisi kode sumber Python atau library bersama, dan setiap direktori induk dari direktori tersebut, tidak termasuk direktori root repo. Defaultnya, otomatis, berarti true kecuali jika --incompatible_default_to_explicit_init_py digunakan. Jika salah, pengguna bertanggung jawab membuat file __init__.py (mungkin kosong) dan menambahkannya ke srcs target Python sesuai kebutuhan.
main

Label; optional

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 apa 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 lain yang lebih tinggi yang bergantung pada versi ini.

Jika 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 untuk Bazel yang membuat target Anda, tetapi karena #4815, skrip stub yang dihasilkan mungkin masih menyebabkan kesalahan pada 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 menyetel --python_top.

srcs_version

String; optional; default is "PY2AND3"

Atribut ini mendeklarasikan srcs target kompatibel dengan Python 2, Python 3, atau keduanya. Untuk benar-benar 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 karena alasan historis, 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 versi Python saat ini, jika melakukan validasi, tidak akan mungkin membuat library PY2ONLY dan PY3ONLY di pemanggilan yang sama.) Selain itu, jika ada ketidakcocokan versi, error hanya dilaporkan pada tahap eksekusi. Secara khusus, error tersebut tidak akan muncul dalam pemanggilan bazel build --nobuild.)

Untuk mendapatkan informasi diagnostik terkait 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 membuat file dengan akhiran -pyversioninfo.txt diberikan informasi tentang alasan target Anda memerlukan satu versi Python atau versi lain. Perlu diperhatikan bahwa metode ini berfungsi meskipun target yang ditentukan gagal di-build karena bertentangan dengan versi.

stamp

Integer; optional; default is -1

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

Biner yang distempel tidak dibuat 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. Umumnya adalah aturan py_library.
srcs

List of labels; optional

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

List of strings; optional

Daftar direktori impor yang akan ditambahkan ke PYTHONPATH.

Tunduk pada substitusi "Make variable". Direktori impor ini akan ditambahkan untuk aturan ini dan semua aturan yang bergantung padanya (perhatikan: bukan aturan yang menjadi dependensi 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 menghasilkan error.

srcs_version

String; optional; default is "PY2AND3"

Atribut ini mendeklarasikan srcs target kompatibel dengan Python 2, Python 3, atau keduanya. Untuk benar-benar 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 karena alasan historis, 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 versi Python saat ini, jika melakukan validasi, tidak akan mungkin membuat library PY2ONLY dan PY3ONLY di pemanggilan yang sama.) Selain itu, jika ada ketidakcocokan versi, error hanya dilaporkan pada tahap eksekusi. Secara khusus, error tersebut tidak akan muncul dalam pemanggilan bazel build --nobuild.)

Untuk mendapatkan informasi diagnostik terkait 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 membuat file dengan akhiran -pyversioninfo.txt diberikan informasi tentang alasan target Anda memerlukan satu versi Python atau versi lain. Perlu diperhatikan bahwa metode ini berfungsi meskipun target yang ditentukan gagal di-build karena bertentangan dengan versi.

tes_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. Umumnya adalah aturan py_library.
srcs

List of labels; required

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

List of strings; optional

Daftar direktori impor yang akan ditambahkan ke PYTHONPATH.

Tunduk pada substitusi "Make variable". Direktori impor ini akan ditambahkan untuk aturan ini dan semua aturan yang bergantung padanya (perhatikan: bukan aturan yang menjadi dependensi 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 menghasilkan error.

legacy_create_init

Integer; optional; default is -1

Apakah akan secara implisit membuat file __init__.py kosong di hierarki runfiles. Ini dibuat di setiap direktori yang berisi kode sumber Python atau library bersama, dan setiap direktori induk dari direktori tersebut, tidak termasuk direktori root repo. Defaultnya, otomatis, berarti true kecuali jika --incompatible_default_to_explicit_init_py digunakan. Jika salah, pengguna bertanggung jawab membuat file __init__.py (mungkin kosong) dan menambahkannya ke srcs target Python sesuai kebutuhan.
main

Label; optional

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 apa 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 lain yang lebih tinggi yang bergantung pada versi ini.

Jika 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 untuk Bazel yang membuat target Anda, tetapi karena #4815, skrip stub yang dihasilkan mungkin masih menyebabkan kesalahan pada 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 menyetel --python_top.

srcs_version

String; optional; default is "PY2AND3"

Atribut ini mendeklarasikan srcs target kompatibel dengan Python 2, Python 3, atau keduanya. Untuk benar-benar 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 karena alasan historis, 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 versi Python saat ini, jika melakukan validasi, tidak akan mungkin membuat library PY2ONLY dan PY3ONLY di pemanggilan yang sama.) Selain itu, jika ada ketidakcocokan versi, error hanya dilaporkan pada tahap eksekusi. Secara khusus, error tersebut tidak akan muncul dalam pemanggilan bazel build --nobuild.)

Untuk mendapatkan informasi diagnostik terkait 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 membuat file dengan akhiran -pyversioninfo.txt diberikan informasi tentang alasan target Anda memerlukan satu versi Python atau versi lain. Perlu diperhatikan bahwa metode ini berfungsi meskipun target yang ditentukan gagal di-build karena bertentangan dengan versi.

stamp

Integer; optional; default is 0

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

py_runtime 

py_runtime(name, compatible_with, 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 di jalur yang diketahui, sedangkan runtime dalam build mengarah ke target yang dapat dieksekusi yang bertindak sebagai penafsir. Dalam kedua kasus ini, "penafsir" berarti biner executable atau skrip wrapper yang mampu menjalankan skrip Python yang diteruskan pada command line, mengikuti konvensi yang sama dengan penafsir CPython standar.

Runtime platform biasanya bersifat non-hermetic. Sistem ini memberlakukan persyaratan pada platform target untuk memiliki penafsir yang terletak di jalur tertentu. Runtime dalam build mungkin bersifat hermetic atau tidak, bergantung apakah keduanya 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.
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 biner 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 runtime platform, atribut ini tidak boleh ditetapkan.
interpreter_path

String; optional

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

String; optional; default is "_INTERNAL_SENTINEL"

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

Nilai default dikontrol oleh tanda --incompatible_py3_is_default. Namun, atribut ini nantinya bersifat wajib dan tidak memiliki nilai default.

stub_shebang

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

Ekspresi "Shebang" ditambahkan ke skrip stub Python bootstrap yang digunakan saat menjalankan target py_binary.

Lihat Masalah 8685 untuk motivasi.

Tidak berlaku untuk Windows.