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 của tập hợp .py tệp nguồn (có thể thuộc về với các quy tắc py_library khác), *.runfiles cây thư mục chứa tất cả mã và dữ liệu cần thiết cho chương trình trong 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 môi trường và dữ liệu 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 khác hoặc kiểm thử (ví dụ: chạy một 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à làm cho tệp nhị phân hoặc chương trình kiểm thử này phụ thuộc vào py_binary trong phần dữ liệu. Khác thì tệp nhị phân có thể xác định vị trí py_binary tương ứng với nguồn thư mục. 

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 duy nhất 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ừ đi số mở rộng. Ví dụ: nếu điểm truy cập của bạn được gọi main.py, khi đó tên của bạn sẽ là main.
deps

List of labels; optional

Danh sách các thư viện khác được liên kết đến mục tiêu nhị phân. Xem nhận xét chung về deps tại Các thuộc tính điển hình được xác định theo hầu hết quy tắc xây dựng. Đây thường là Quy tắc py_library.
srcs

List of labels; required

Danh sách tệp nguồn (.py) được xử lý để tạo mục tiêu. Tệp này bao gồm tất cả mã đăng ký và mọi tệp nguồn đã tạo. Mục tiêu của 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 lại 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.

Đối với sự thay thế "Tạo biến". Các quy tắc nhập này các thư mục 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 đó (lưu ý: không phải 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ách py_binary quy tắc phụ thuộc vào quy tắc này.

Đườ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 gốc thực thi không được phép và sẽ dẫn đến 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 runfile hay không. Các mã này được tạo trong mỗi thư mục chứa mã nguồn Python hoặc cá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ữ thư mục. Mặc định, tự động, có nghĩa là đúng trừ khi --incompatible_default_to_explicit_init_py được dùng. Nếu đặt là false, người dùng chịu trách nhiệm tạo (có thể trống) __init__.py tệp và thêm chúng vào srcs mục tiêu Python theo yêu cầu.
main

Label; optional

Tên của tệp nguồn đóng vai trò 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 bạn không chỉ định, Thay vào đó, name sẽ được sử dụng (xem ở trên). Nếu name không khớp với tên tệp bất kỳ trong srcs, thì bạn phải chỉ định main.
python_version

String; optional; nonconfigurable; default is "_INTERNAL_SENTINEL"

Liệu nên tạo mục tiêu này (và deps chuyển tiếp của nó) cho Python 2 hay Python 3. 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) về bất kỳ phiên bản nào do thuộc tính này chỉ định, bất kể phiên bản được chỉ định trên dòng lệnh hay do các mục tiêu cao hơn phụ thuộc vào chỉ số 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ị @rules_python//python:python_version. 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 sử dụng để xây dựng mục tiêu của bạn. nhưng do #4815, kết quả là tập lệnh mã giả lập vẫn có thể gọi ra phiên bản phiên dịch không chính xác trong thời gian chạy. Xem thế này giải pháp tạm thời, bao gồm việc xác định mục tiêu py_runtime trỏ đến hoặc là 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 phải tương thích với Python 2, Python 3 hoặc cả hai. Để thực sự đặt phiên bản thời gian chạy Python, hãy sử dụng Thuộc tính python_version của một quy tắc Python có thể thực thi (py_binary hoặc py_test).

Các giá trị được phép là: "PY2AND3", "PY2" và "PY3". Các giá trị "PY2ONLY" và "PY3ONLY" cũng được phép cho báo cáo lịch sử nhưng về cơ bản, chúng giống với "PY2" và "PY3" và nên tránh.

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 Python hiện tại nếu đã xác thực, bạn sẽ không thể tạo cả 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, thì 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 thành phần find_requirements trên mục tiêu của mình: 

          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 khiến mục tiêu của bạn yêu cầu một phiên bản Python hoặc một phiên bản khác. Xin lưu ý rằng quy trình này hoạt động ngay cả khi không thể tạo mục tiêu đã xác định 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 thành tệp nhị phân hay không. Các giá trị có thể có:
  • stamp = 1: Luôn đóng dấu thông tin bản dựng vào tệp nhị phân, ngay cả trong --nostamp bản dựng. Chiến dịch này nên tránh cài đặt, vì nó có thể tắt chức năng lưu vào bộ nhớ đệm từ xa đối với tệp nhị phân và mọi thao tác hạ nguồn phụ thuộc vào mã đó.
  • stamp = 0: Luôn thay thế thông tin bản dựng bằng các giá trị hằng số. Chiến dịch này cho phép lưu kết quả bản dựng tốt vào bộ nhớ đệm.
  • stamp = -1: Bạn có thể kiểm soát việc nhúng thông tin bản dựng bằng Cờ --[no]stamp.

Tệp nhị phân đã đóng dấu không được tạo lại trừ phi các 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 duy nhất 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 mục tiêu nhị phân. Xem nhận xét chung về deps tại Các thuộc tính điển hình được xác định theo hầu hết quy tắc xây dựng. Đây thường là Quy tắc py_library.
srcs

List of labels; optional

Danh sách tệp nguồn (.py) được xử lý để tạo mục tiêu. Tệp này bao gồm tất cả mã đăng ký 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.

Đối với sự thay thế "Tạo biến". Các quy tắc nhập này các thư mục 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 đó (lưu ý: không phải 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ách py_binary quy tắc phụ thuộc vào quy tắc này.

Đườ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 gốc thực thi không được phép và sẽ dẫn đến 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 phải tương thích với Python 2, Python 3 hoặc cả hai. Để thực sự đặt phiên bản thời gian chạy Python, hãy sử dụng Thuộc tính python_version của một quy tắc Python có thể thực thi (py_binary hoặc py_test).

Các giá trị được phép là: "PY2AND3", "PY2" và "PY3". Các giá trị "PY2ONLY" và "PY3ONLY" cũng được phép cho báo cáo lịch sử nhưng về cơ bản, chúng giống với "PY2" và "PY3" và nên tránh.

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 Python hiện tại nếu đã xác thực, bạn sẽ không thể tạo cả 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, thì 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 thành phần find_requirements trên mục tiêu của mình: 

          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 khiến mục tiêu của bạn yêu cầu một phiên bản Python hoặc một phiên bản khác. Xin lưu ý rằng quy trình này hoạt động ngay cả khi không thể tạo mục tiêu đã xác định 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 hoạt động 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ô-đ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 duy nhất 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 mục tiêu nhị phân. Xem nhận xét chung về deps tại Các thuộc tính điển hình được xác định theo hầu hết quy tắc xây dựng. Đây thường là Quy tắc py_library.
srcs

List of labels; required

Danh sách tệp nguồn (.py) được xử lý để tạo mục tiêu. Tệp này bao gồm tất cả mã đăng ký và mọi tệp nguồn đã tạo. Mục tiêu của 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 lại 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.

Đối với sự thay thế "Tạo biến". Các quy tắc nhập này các thư mục 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 đó (lưu ý: không phải 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ách py_binary quy tắc phụ thuộc vào quy tắc này.

Đườ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 gốc thực thi không được phép và sẽ dẫn đến 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 runfile hay không. Các mã này được tạo trong mỗi thư mục chứa mã nguồn Python hoặc cá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ữ thư mục. Mặc định, tự động, có nghĩa là đúng trừ khi --incompatible_default_to_explicit_init_py được dùng. Nếu đặt là false, người dùng chịu trách nhiệm tạo (có thể trống) __init__.py tệp và thêm chúng vào srcs mục tiêu Python theo yêu cầu.
main

Label; optional

Tên của tệp nguồn đóng vai trò 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 bạn không chỉ định, Thay vào đó, name sẽ được sử dụng (xem ở trên). Nếu name không khớp với tên tệp bất kỳ trong srcs, thì bạn phải chỉ định main.
python_version

String; optional; nonconfigurable; default is "_INTERNAL_SENTINEL"

Liệu nên tạo mục tiêu này (và deps chuyển tiếp của nó) cho Python 2 hay Python 3. 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) về bất kỳ phiên bản nào do thuộc tính này chỉ định, bất kể phiên bản được chỉ định trên dòng lệnh hay do các mục tiêu cao hơn phụ thuộc vào chỉ số 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ị @rules_python//python:python_version. 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 sử dụng để xây dựng mục tiêu của bạn. nhưng do #4815, kết quả là tập lệnh mã giả lập vẫn có thể gọi ra phiên bản phiên dịch không chính xác trong thời gian chạy. Xem thế này giải pháp tạm thời, bao gồm việc xác định mục tiêu py_runtime trỏ đến hoặc là 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 phải tương thích với Python 2, Python 3 hoặc cả hai. Để thực sự đặt phiên bản thời gian chạy Python, hãy sử dụng Thuộc tính python_version của một quy tắc Python có thể thực thi (py_binary hoặc py_test).

Các giá trị được phép là: "PY2AND3", "PY2" và "PY3". Các giá trị "PY2ONLY" và "PY3ONLY" cũng được phép cho báo cáo lịch sử nhưng về cơ bản, chúng giống với "PY2" và "PY3" và nên tránh.

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 Python hiện tại nếu đã xác thực, bạn sẽ không thể tạo cả 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, thì 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 thành phần find_requirements trên mục tiêu của mình: 

          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 khiến mục tiêu của bạn yêu cầu một phiên bản Python hoặc một phiên bản khác. Xin lưu ý rằng quy trình này hoạt động ngay cả khi không thể tạo mục tiêu đã xác định do xung đột phiên bản.
stamp

Integer; optional; default is 0

Xem phần về đối số py_binary(), ngoại trừ rằng đối số tem được đặt thành 0 theo mặc định cho các chương trình 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.

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

Về bản chất, môi trường thời gian chạy của nền tảng là không gián đoạn. Quy tắc này áp dụng một yêu cầu đối với nền tảng mục tiêu bố trí thông dịch viên tại một lộ trình cụ thể. Môi trường thời gian chạy trong bản dựng có thể hoặc không phải là thời gian khép kín, tuỳ thuộc vào việc mã này trỏ đến trình thông dịch xác nhận có mặt hay một tập lệnh trình bao bọc truy cập vào phiên 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 duy nhất cho mục tiêu này.
coverage_tool

Label; optional

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

Nếu được đặt, thì mục tiêu phải tạo ra 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 đơn hoặc tệp thực thi nếu mục tiêu là tệp thực thi, xác định điểm truy cập cho công cụ xác định mức độ sử dụng python. Mục tiêu và các tệp runfile 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ụ này phải tải được bằng trình thông dịch python (ví dụ: .py hoặc .pyc). Hàm này phải chấp nhận các đối số dòng lệnh là coverage.py, ít nhất bao gồm lệnh con run và lcov.

files

List of labels; optional

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

Label; optional

Đối với thời gian chạy đang được tạo bản dựng, đây là mục tiêu để gọi làm trình thông dịch. Đối với nền tảng trong thời gian chạy, 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 mục tiêu 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 có dành cho Python phiên bản lớn 2 hay 3 hay không. 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à thuộc tính bắt buộc và không có giá trị mặc định.

stub_shebang

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

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

Xem vấn đề 8685 để động lực của bản thân.

Không áp dụng cho Windows.