Quy tắc Python

Quy tắc

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 là một chương trình Python có thể thực thi bao gồm một tập hợp các tệp nguồn .py (có thể thuộc các quy tắc py_library khác), một cây thư mục *.runfiles chứa tất cả mã và dữ liệu mà chương trình cần vào thời gian chạy và một tập lệnh mã giả lập để khởi động chương trình bằng dữ liệu và môi trường ban đầu chính xác.

Ví dụ

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

Nếu bạn muốn chạy py_binary từ trong một tệp nhị phân hoặc bài kiểm thử khác (ví dụ: chạy tệp nhị phân python để thiết lập một số tài nguyên mô phỏng từ trong java_test), thì phương pháp chính xác là tạo tệp nhị phân hoặc kiểm thử khác phụ thuộc vào py_binary trong phần dữ liệu. Sau đó, tệp nhị phân khác có thể tìm py_binary tương ứng với thư mục nguồn. 

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

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

Đối số

Thuộc tính
name

Name; required

Tên dành riêng cho mục tiêu này.


Nếu bạn không chỉ định main, thì tên này phải giống với tên của tệp nguồn là điểm truy cập chính của ứng dụng, trừ phần đuôi. Ví dụ: nếu điểm truy cập của bạn có tên là main.py, thì tên của bạn phải là main.
deps

List of labels; optional

Danh sách các thư viện khác được liên kết đến đích nhị phân. Hãy xem nhận xét chung về deps tại Các thuộc tính thông thường được xác định theo hầu hết các quy tắc tạo bản dựng. Đây thường là các quy tắc py_library.
srcs

List of labels; required

Danh sách các tệp nguồn (.py) được xử lý để tạo mục tiêu. Dữ liệu này bao gồm tất cả mã xác nhận và mọi tệp nguồn đã tạo. Các mục tiêu thư viện thuộc về deps, trong khi các tệp nhị phân khác cần thiết trong thời gian chạy thuộc về data.
imports

List of strings; optional

Danh sách các thư mục nhập sẽ được thêm vào PYTHONPATH.

Phải thay thế "Tạo biến". Các thư mục nhập này sẽ được thêm cho quy tắc này và tất cả các quy tắc phụ thuộc vào quy tắc này (lưu ý: không phải các quy tắc mà quy tắc này phụ thuộc. Mỗi thư mục sẽ được thêm vào PYTHONPATH bằng các quy tắc py_binary phụ thuộc vào quy tắc này.

Bạn không được phép sử dụng đường dẫn tuyệt đối (đường dẫn bắt đầu bằng /) và đường dẫn tham chiếu đến một đường dẫn phía trên thư mục gốc thực thi và sẽ gây ra lỗi.

legacy_create_init

Integer; optional; default is -1

Liệu có ngầm tạo các tệp __init__.py trống trong cây runfiles hay không. Các tệp này được tạo trong mọi thư mục chứa mã nguồn Python hoặc thư viện dùng chung và mọi thư mục mẹ của các thư mục đó, ngoại trừ thư mục gốc của kho lưu trữ. Giá trị mặc định là tự động có nghĩa là true (đúng) trừ phi bạn sử dụng --incompatible_default_to_explicit_init_py. Nếu giá trị là false, người dùng sẽ chịu trách nhiệm tạo các tệp __init__.py (có thể trống) và thêm các tệp đó vào srcs mục tiêu Python theo yêu cầu.
main

Label; optional

Tên của tệp nguồn là điểm truy cập chính của ứng dụng. Tệp này cũng phải được liệt kê trong srcs. Nếu không xác định, name sẽ được sử dụng (xem ở trên). Nếu name không khớp với tên tệp nào trong srcs, thì bạn phải chỉ định main.
python_version

String; optional; nonconfigurable; default is "_INTERNAL_SENTINEL"

Xác định việc tạo mục tiêu này (và deps bắc cầu của mục tiêu này) cho Python 2 hay Python 3. Các giá trị hợp lệ là "PY2" và "PY3" (giá trị mặc định).

Phiên bản Python luôn được đặt lại (có thể theo mặc định) thành bất kỳ phiên bản nào được thuộc tính này chỉ định, bất kể phiên bản được chỉ định trên dòng lệnh hoặc bởi các mục tiêu cao hơn khác phụ thuộc vào phiên bản này.

Nếu muốn select() trên phiên bản Python hiện tại, bạn có thể kiểm tra giá trị của @rules_python//python:python_version. Hãy xem tại đây để biết thêm thông tin.

Cảnh báo lỗi: Thuộc tính này đặt phiên bản mà Bazel tạo mục tiêu cho bạn, nhưng do #4815, tập lệnh mã giả lập có thể vẫn gọi phiên bản thông dịch không chính xác trong thời gian chạy. Hãy xem giải pháp này, bao gồm cả việc xác định mục tiêu py_runtime trỏ đến phiên bản Python nếu cần và kích hoạt py_runtime này bằng cách đặt --python_top.

srcs_version

String; optional; default is "PY2AND3"

Thuộc tính này khai báo srcs của mục tiêu tương thích với Python 2, Python 3 hoặc cả hai. Để thực sự thiết lập phiên bản thời gian chạy Python, hãy sử dụng thuộc tính python_version của quy tắc Python có thể thực thi (py_binary hoặc py_test).

Các giá trị được cho phép là: "PY2AND3", "PY2" và "PY3". Bạn nên tránh sử dụng các giá trị "PY2ONLY" và "PY3ONLY" vì lý do lịch sử, nhưng về cơ bản các giá trị này giống với "PY2" và "PY3".

Xin lưu ý rằng chỉ các quy tắc thực thi (py_binary và py_library ) mới thực sự xác minh phiên bản Python hiện tại dựa trên giá trị của thuộc tính này. (Đây là một tính năng; vì py_library không thay đổi phiên bản Python hiện tại nên nếu đã xác thực thì bạn không thể tạo cả hai thư viện PY2ONLY và PY3ONLY trong cùng một lệnh gọi.) Hơn nữa, nếu có phiên bản không khớp, lỗi chỉ được báo cáo trong giai đoạn thực thi. Cụ thể, lỗi sẽ không xuất hiện trong lệnh gọi bazel build --nobuild.)

Để nhận thông tin chẩn đoán về những phần phụ thuộc đưa ra yêu cầu về phiên bản, bạn có thể chạy khía cạnh find_requirements trên mục tiêu: 

          bazel build <your target> \
              --aspects=@rules_python//python:defs.bzl%find_requirements \
              --output_groups=pyversioninfo
Thao tác này sẽ tạo một tệp có hậu tố -pyversioninfo.txt cung cấp thông tin về lý do mục tiêu của bạn cần một phiên bản Python hoặc phiên bản khác. Xin lưu ý rằng mã này hoạt động ngay cả khi không tạo được mục tiêu đã cho do xung đột phiên bản.

stamp

Integer; optional; default is -1

Liệu có mã hoá thông tin bản dựng vào tệp nhị phân hay không. Có thể là những giá trị sau đây:
  • stamp = 1: Luôn đóng dấu thông tin bản dựng vào tệp nhị phân, ngay cả trong các bản dựng --nostamp. Bạn nên tránh sử dụng chế độ cài đặt này, vì chế độ cài đặt này có thể tắt hoạt động lưu vào bộ nhớ đệm từ xa đối với tệp nhị phân và mọi thao tác xuôi dòng phụ thuộc vào chế độ cài đặt này.
  • stamp = 0: Luôn thay thế thông tin bản dựng bằng các giá trị không đổi. Chức năng này lưu kết quả bản dựng vào bộ nhớ đệm tốt.
  • stamp = -1: Việc nhúng thông tin bản dựng chịu sự kiểm soát của cờ --[no]stamp.

Tệp nhị phân được đóng dấu không được tạo lại trừ phi phần phụ thuộc của chúng thay đổi.

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)

Đối số

Thuộc tính
name

Name; required

Tên dành riêng cho mục tiêu này.
deps

List of labels; optional

Danh sách các thư viện khác được liên kết đến đích nhị phân. Hãy xem nhận xét chung về deps tại Các thuộc tính thông thường được xác định theo hầu hết các quy tắc tạo bản dựng. Đây thường là các quy tắc py_library.
srcs

List of labels; optional

Danh sách các tệp nguồn (.py) được xử lý để tạo mục tiêu. Dữ liệu này bao gồm tất cả mã xác nhận và mọi tệp nguồn đã tạo.
imports

List of strings; optional

Danh sách các thư mục nhập sẽ được thêm vào PYTHONPATH.

Phải thay thế "Tạo biến". Các thư mục nhập này sẽ được thêm cho quy tắc này và tất cả các quy tắc phụ thuộc vào quy tắc này (lưu ý: không phải các quy tắc mà quy tắc này phụ thuộc. Mỗi thư mục sẽ được thêm vào PYTHONPATH bằng các quy tắc py_binary phụ thuộc vào quy tắc này.

Bạn không được phép sử dụng đường dẫn tuyệt đối (đường dẫn bắt đầu bằng /) và đường dẫn tham chiếu đến một đường dẫn phía trên thư mục gốc thực thi và sẽ gây ra lỗi.

srcs_version

String; optional; default is "PY2AND3"

Thuộc tính này khai báo srcs của mục tiêu tương thích với Python 2, Python 3 hoặc cả hai. Để thực sự thiết lập phiên bản thời gian chạy Python, hãy sử dụng thuộc tính python_version của quy tắc Python có thể thực thi (py_binary hoặc py_test).

Các giá trị được cho phép là: "PY2AND3", "PY2" và "PY3". Bạn nên tránh sử dụng các giá trị "PY2ONLY" và "PY3ONLY" vì lý do lịch sử, nhưng về cơ bản các giá trị này giống với "PY2" và "PY3".

Xin lưu ý rằng chỉ các quy tắc thực thi (py_binary và py_library ) mới thực sự xác minh phiên bản Python hiện tại dựa trên giá trị của thuộc tính này. (Đây là một tính năng; vì py_library không thay đổi phiên bản Python hiện tại nên nếu đã xác thực thì bạn không thể tạo cả hai thư viện PY2ONLY và PY3ONLY trong cùng một lệnh gọi.) Hơn nữa, nếu có phiên bản không khớp, lỗi chỉ được báo cáo trong giai đoạn thực thi. Cụ thể, lỗi sẽ không xuất hiện trong lệnh gọi bazel build --nobuild.)

Để nhận thông tin chẩn đoán về những phần phụ thuộc đưa ra yêu cầu về phiên bản, bạn có thể chạy khía cạnh find_requirements trên mục tiêu: 

          bazel build <your target> \
              --aspects=@rules_python//python:defs.bzl%find_requirements \
              --output_groups=pyversioninfo
Thao tác này sẽ tạo một tệp có hậu tố -pyversioninfo.txt cung cấp thông tin về lý do mục tiêu của bạn cần một phiên bản Python hoặc phiên bản khác. Xin lưu ý rằng mã này hoạt động ngay cả khi không tạo được mục tiêu đã cho do xung đột phiên bản.

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)

Quy tắc py_test() biên dịch một bài kiểm thử. Kiểm thử là một trình bao bọc nhị phân xung quanh một số mã kiểm thử.

Ví dụ

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

Bạn cũng có thể chỉ định một mô-đun chính:

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

Đối số

Thuộc tính
name

Name; required

Tên dành riêng cho mục tiêu này.
deps

List of labels; optional

Danh sách các thư viện khác được liên kết đến đích nhị phân. Hãy xem nhận xét chung về deps tại Các thuộc tính thông thường được xác định theo hầu hết các quy tắc tạo bản dựng. Đây thường là các quy tắc py_library.
srcs

List of labels; required

Danh sách các tệp nguồn (.py) được xử lý để tạo mục tiêu. Dữ liệu này bao gồm tất cả mã xác nhận và mọi tệp nguồn đã tạo. Các mục tiêu thư viện thuộc về deps, trong khi các tệp nhị phân khác cần thiết trong thời gian chạy thuộc về data.
imports

List of strings; optional

Danh sách các thư mục nhập sẽ được thêm vào PYTHONPATH.

Phải thay thế "Tạo biến". Các thư mục nhập này sẽ được thêm cho quy tắc này và tất cả các quy tắc phụ thuộc vào quy tắc này (lưu ý: không phải các quy tắc mà quy tắc này phụ thuộc. Mỗi thư mục sẽ được thêm vào PYTHONPATH bằng các quy tắc py_binary phụ thuộc vào quy tắc này.

Bạn không được phép sử dụng đường dẫn tuyệt đối (đường dẫn bắt đầu bằng /) và đường dẫn tham chiếu đến một đường dẫn phía trên thư mục gốc thực thi và sẽ gây ra lỗi.

legacy_create_init

Integer; optional; default is -1

Liệu có ngầm tạo các tệp __init__.py trống trong cây runfiles hay không. Các tệp này được tạo trong mọi thư mục chứa mã nguồn Python hoặc thư viện dùng chung và mọi thư mục mẹ của các thư mục đó, ngoại trừ thư mục gốc của kho lưu trữ. Giá trị mặc định là tự động có nghĩa là true (đúng) trừ phi bạn sử dụng --incompatible_default_to_explicit_init_py. Nếu giá trị là false, người dùng sẽ chịu trách nhiệm tạo các tệp __init__.py (có thể trống) và thêm các tệp đó vào srcs mục tiêu Python theo yêu cầu.
main

Label; optional

Tên của tệp nguồn là điểm truy cập chính của ứng dụng. Tệp này cũng phải được liệt kê trong srcs. Nếu không xác định, name sẽ được sử dụng (xem ở trên). Nếu name không khớp với tên tệp nào trong srcs, thì bạn phải chỉ định main.
python_version

String; optional; nonconfigurable; default is "_INTERNAL_SENTINEL"

Xác định việc tạo mục tiêu này (và deps bắc cầu của mục tiêu này) cho Python 2 hay Python 3. Các giá trị hợp lệ là "PY2" và "PY3" (giá trị mặc định).

Phiên bản Python luôn được đặt lại (có thể theo mặc định) thành bất kỳ phiên bản nào được thuộc tính này chỉ định, bất kể phiên bản được chỉ định trên dòng lệnh hoặc bởi các mục tiêu cao hơn khác phụ thuộc vào phiên bản này.

Nếu muốn select() trên phiên bản Python hiện tại, bạn có thể kiểm tra giá trị của @rules_python//python:python_version. Hãy xem tại đây để biết thêm thông tin.

Cảnh báo lỗi: Thuộc tính này đặt phiên bản mà Bazel tạo mục tiêu cho bạn, nhưng do #4815, tập lệnh mã giả lập có thể vẫn gọi phiên bản thông dịch không chính xác trong thời gian chạy. Hãy xem giải pháp này, bao gồm cả việc xác định mục tiêu py_runtime trỏ đến phiên bản Python nếu cần và kích hoạt py_runtime này bằng cách đặt --python_top.

srcs_version

String; optional; default is "PY2AND3"

Thuộc tính này khai báo srcs của mục tiêu tương thích với Python 2, Python 3 hoặc cả hai. Để thực sự thiết lập phiên bản thời gian chạy Python, hãy sử dụng thuộc tính python_version của quy tắc Python có thể thực thi (py_binary hoặc py_test).

Các giá trị được cho phép là: "PY2AND3", "PY2" và "PY3". Bạn nên tránh sử dụng các giá trị "PY2ONLY" và "PY3ONLY" vì lý do lịch sử, nhưng về cơ bản các giá trị này giống với "PY2" và "PY3".

Xin lưu ý rằng chỉ các quy tắc thực thi (py_binary và py_library ) mới thực sự xác minh phiên bản Python hiện tại dựa trên giá trị của thuộc tính này. (Đây là một tính năng; vì py_library không thay đổi phiên bản Python hiện tại nên nếu đã xác thực thì bạn không thể tạo cả hai thư viện PY2ONLY và PY3ONLY trong cùng một lệnh gọi.) Hơn nữa, nếu có phiên bản không khớp, lỗi chỉ được báo cáo trong giai đoạn thực thi. Cụ thể, lỗi sẽ không xuất hiện trong lệnh gọi bazel build --nobuild.)

Để nhận thông tin chẩn đoán về những phần phụ thuộc đưa ra yêu cầu về phiên bản, bạn có thể chạy khía cạnh find_requirements trên mục tiêu: 

          bazel build <your target> \
              --aspects=@rules_python//python:defs.bzl%find_requirements \
              --output_groups=pyversioninfo
Thao tác này sẽ tạo một tệp có hậu tố -pyversioninfo.txt cung cấp thông tin về lý do mục tiêu của bạn cần một phiên bản Python hoặc phiên bản khác. Xin lưu ý rằng mã này hoạt động ngay cả khi không tạo được mục tiêu đã cho do xung đột phiên bản.

stamp

Integer; optional; default is 0

Hãy xem phần về đối số py_binary(), ngoại trừ việc đối số dấu được đặt thành 0 theo mặc định cho hoạt động kiểm thử.

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)

Đại diện cho một môi trường thời gian chạy Python dùng để thực thi mã Python.

Mục tiêu py_runtime có thể đại diện cho thời gian chạy nền tảng hoặc thời gian chạy trong bản dựng. Môi trường thời gian chạy trên nền tảng sẽ truy cập vào trình thông dịch do hệ thống cài đặt tại một đường dẫn đã biết, trong khi thời gian chạy trong bản dựng trỏ đến một mục tiêu có thể thực thi đóng vai trò là trình thông dịch. Trong cả hai trường hợp, "trình diễn giải" có nghĩa là mọi tập lệnh tệp nhị phân hoặc trình bao bọc có thể thực thi có khả năng chạy tập lệnh Python được chuyển vào dòng lệnh, tuân theo các quy ước giống như trình thông dịch CPython tiêu chuẩn.

Về bản chất, môi trường thời gian chạy của nền tảng không mang tính khép kín. Chính sách này đặt ra yêu cầu đối với nền tảng mục tiêu phải có thông dịch viên tại một đường dẫn cụ thể. Thời gian chạy trong bản dựng có thể mang tính khép kín, tuỳ thuộc vào việc thời gian chạy đó trỏ đến trình thông dịch đã đánh dấu hay tập lệnh trình bao bọc truy cập trình thông dịch hệ thống.

Ví dụ:

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

Đối số

Thuộc tính
name

Name; required

Tên dành riêng cho mục tiêu này.
coverage_tool

Label; optional

Đây là mục tiêu cần sử dụng để thu thập thông tin về mức độ sử dụng mã từ các mục tiêu py_binary và py_test.

Nếu được đặt, mục tiêu phải tạo một tệp duy nhất hoặc là mục tiêu có thể thực thi. Đường dẫn đến tệp duy nhất hoặc tệp thực thi nếu mục tiêu có thể thực thi sẽ xác định điểm truy cập cho công cụ mức độ bao phủ python. Mục tiêu và các tệp runfile của mục tiêu đó sẽ được thêm vào các tệp runfile khi bạn bật mức độ sử dụng.

Điểm truy cập của công cụ phải tải được bằng trình thông dịch python (ví dụ: tệp .py hoặc .pyc). Tệp này phải chấp nhận các đối số dòng lệnh của coverage.py, ít nhất là bao gồm các lệnh con run và lcov.

files

List of labels; optional

Đối với thời gian chạy tích hợp, đây là tập hợp các tệp chứa thời gian chạy này. Các tệp này sẽ được thêm vào tệp chạy của những tệp nhị phân Python sử dụng thời gian chạy này. Đối với thời gian chạy của nền tảng, bạn không được đặt thuộc tính này.
interpreter

Label; optional

Đối với thời gian chạy dạng bản dựng, đây là mục tiêu cần gọi dưới dạng trình thông dịch. Đối với thời gian chạy của nền tảng, bạn không được đặt thuộc tính này.
interpreter_path

String; optional

Đối với thời gian chạy nền tảng, đây là đường dẫn tuyệt đối của trình thông dịch Python trên nền tảng đích. Đối với thời gian chạy trong bản dựng, bạn không được đặt thuộc tính này.
python_version

String; optional; default is "_INTERNAL_SENTINEL"

Liệu thời gian chạy này dành cho Python phiên bản lớn 2 hay 3. Các giá trị hợp lệ là "PY2" và "PY3".

Giá trị mặc định do cờ --incompatible_py3_is_default kiểm soát. Tuy nhiên, trong tương lai, thuộc tính này sẽ là bắt buộc và không có giá trị mặc định.

stub_shebang

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

Biểu thức "Shebang" được thêm vào trước tập lệnh mã giả lập Python khởi động được dùng khi thực thi các mục tiêu py_binary.

Hãy xem vấn đề 8685 để biết động lực.

Không áp dụng cho Windows.