Quy tắc Python

Báo cáo sự cố Xem nguồn

Quy tắc

nhị phân

Xem nguồn quy tắc 
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 về 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 cần thiết cho chương trình tại thời điểm chạy, và một tập lệnh giả lập khởi động chương trình với 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 muốn chạy py_binary từ bên trong tệp nhị phân hoặc 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ì cách tiếp cận 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 của tệp. Sau đó, tệp nhị phân khác có thể định vị py_binary so với thư mục nguồn. 

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

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 main không được chỉ định, 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 đuôi tệp. Ví dụ: nếu điểm truy cập gọi 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 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 các quy tắc xây 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. Điều này bao gồm tất cả mã đã đăng ký của bạn và mọi tệp nguồn được tạo. Các 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 trong thời gian chạy thuộc về data.
imports

List of strings; optional

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

Tuỳ chọn thay thế "Tạo biến". Những thư mục nhập này sẽ được thêm vào 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 là quy tắc mà quy tắc này phụ thuộc vào. Mỗi thư mục sẽ được thêm vào PYTHONPATH theo quy tắc py_binary phụ thuộc vào quy tắc này.

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 gốc thực thi. Điều này sẽ dẫn đến lỗi.

legacy_create_init

Integer; optional; default is -1

Liệu có tạo ngầm ẩn các tệp __init__.pypy trong cây runfiles hay không. Những thư mục 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 repo. Theo mặc định, giá trị mặc định là tự động có nghĩa là trừ phi bạn sử dụng --incompatible_default_to_explicit_init_py. Nếu giá trị là false thì người dùng có trách nhiệm tạo (có thể trống) __init__..py tệp và thêm các tệp đó vào srcs của 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ê ở srcs. Nếu không chỉ định, name sẽ được sử dụng (xem ở trên). Nếu name không khớp với bất kỳ 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 xem nên tạo mục tiêu này (và deps bắc cầu) cho Python 2 hay Python 3. Các giá trị hợp lệ là "PY2" và "PY3" (mặc định).

Phiên bản Python luôn đặt lại (có thể là theo mặc định) về bất kỳ phiên bản nào mà 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 bằng các mục tiêu cao hơn khác phụ thuộc vào thuộc tính 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 của bạn, nhưng do #4815 nên tập lệnh mã giả lập vẫn có thể gọi nhầm phiên bản trình phiên dịch trong thời gian chạy. Hãy xem giải pháp này, bao gồm việc xác định một mục tiêu py_runtime trỏ đến một 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ự đặ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 cho phép là: "PY2AND3", "PY2" và "PY3". Chúng tôi cũng chấp nhận các giá trị "PY2ONLY" và "PY3ONLY" vì những lý do liên quan trước đây. Tuy nhiên, về cơ bản các giá trị này giống với "PY2" và "PY3", và bạn nên tránh sử dụng.

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 so với 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 phiên bản này xác thực, thì không thể tạo cả thư viện PY2ONLY và PY3ONLY trong cùng một lệnh gọi.) Hơn nữa, nếu có một 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ề phần phụ thuộc nào giới thiệu các yêu cầu về phiên bản, bạn có thể chạy chương trình 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 mục tiêu của bạn yêu cầu phiên bản Python hoặc phiên bản khác. Lưu ý rằng khối này hoạt động ngay cả khi không tạo được mục tiêu nhất định do xung đột phiên bản.

stamp

Integer; optional; default is -1

Liệu có mã hóa 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ế độ này có thể tắt bộ nhớ đệm từ xa cho tệp nhị phân và mọi hành động xuôi dòng phụ thuộc vào tệp đó.
  • stamp = 0: Luôn thay thế thông tin bản dựng bằng các giá trị không đổi. Điều này giúp cải thiện đáng kể việc lưu kết quả xây dựng vào bộ nhớ đệm.
  • stamp = -1: Việc nhúng thông tin bản dựng được kiểm soát bởi cờ --[no]stamp.

Các tệp nhị phân có dấu không được tạo lại trừ khi các phần phụ thuộc thay đổi.

thư viện py

Xem nguồn quy tắc 
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 các quy tắc xây 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. Điều này bao gồm tất cả mã đã đăng ký của bạn và mọi tệp nguồn được tạo.
imports

List of strings; optional

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

Tuỳ chọn thay thế "Tạo biến". Những thư mục nhập này sẽ được thêm vào 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 là quy tắc mà quy tắc này phụ thuộc vào. Mỗi thư mục sẽ được thêm vào PYTHONPATH theo quy tắc py_binary phụ thuộc vào quy tắc này.

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 gốc thực thi. Điều này 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 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 cho phép là: "PY2AND3", "PY2" và "PY3". Chúng tôi cũng chấp nhận các giá trị "PY2ONLY" và "PY3ONLY" vì những lý do liên quan trước đây. Tuy nhiên, về cơ bản các giá trị này giống với "PY2" và "PY3", và bạn nên tránh sử dụng.

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 so với 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 phiên bản này xác thực, thì không thể tạo cả thư viện PY2ONLY và PY3ONLY trong cùng một lệnh gọi.) Hơn nữa, nếu có một 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ề phần phụ thuộc nào giới thiệu các yêu cầu về phiên bản, bạn có thể chạy chương trình 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 mục tiêu của bạn yêu cầu phiên bản Python hoặc phiên bản khác. Lưu ý rằng khối này hoạt động ngay cả khi không tạo được mục tiêu nhất định do xung đột phiên bản.

thử_nghiệm

Xem nguồn quy tắc 
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 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 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 các quy tắc xây 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. Điều này bao gồm tất cả mã đã đăng ký của bạn và mọi tệp nguồn được tạo. Các 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 trong thời gian chạy thuộc về data.
imports

List of strings; optional

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

Tuỳ chọn thay thế "Tạo biến". Những thư mục nhập này sẽ được thêm vào 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 là quy tắc mà quy tắc này phụ thuộc vào. Mỗi thư mục sẽ được thêm vào PYTHONPATH theo quy tắc py_binary phụ thuộc vào quy tắc này.

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 gốc thực thi. Điều này sẽ dẫn đến lỗi.

legacy_create_init

Integer; optional; default is -1

Liệu có tạo ngầm ẩn các tệp __init__.pypy trong cây runfiles hay không. Những thư mục 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 repo. Theo mặc định, giá trị mặc định là tự động có nghĩa là trừ phi bạn sử dụng --incompatible_default_to_explicit_init_py. Nếu giá trị là false thì người dùng có trách nhiệm tạo (có thể trống) __init__..py tệp và thêm các tệp đó vào srcs của 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ê ở srcs. Nếu không chỉ định, name sẽ được sử dụng (xem ở trên). Nếu name không khớp với bất kỳ 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 xem nên tạo mục tiêu này (và deps bắc cầu) cho Python 2 hay Python 3. Các giá trị hợp lệ là "PY2" và "PY3" (mặc định).

Phiên bản Python luôn đặt lại (có thể là theo mặc định) về bất kỳ phiên bản nào mà 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 bằng các mục tiêu cao hơn khác phụ thuộc vào thuộc tính 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 của bạn, nhưng do #4815 nên tập lệnh mã giả lập vẫn có thể gọi nhầm phiên bản trình phiên dịch trong thời gian chạy. Hãy xem giải pháp này, bao gồm việc xác định một mục tiêu py_runtime trỏ đến một 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ự đặ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 cho phép là: "PY2AND3", "PY2" và "PY3". Chúng tôi cũng chấp nhận các giá trị "PY2ONLY" và "PY3ONLY" vì những lý do liên quan trước đây. Tuy nhiên, về cơ bản các giá trị này giống với "PY2" và "PY3", và bạn nên tránh sử dụng.

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 so với 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 phiên bản này xác thực, thì không thể tạo cả thư viện PY2ONLY và PY3ONLY trong cùng một lệnh gọi.) Hơn nữa, nếu có một 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ề phần phụ thuộc nào giới thiệu các yêu cầu về phiên bản, bạn có thể chạy chương trình 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 mục tiêu của bạn yêu cầu phiên bản Python hoặc phiên bản khác. Lưu ý rằng khối này hoạt động ngay cả khi không tạo được mục tiêu nhất định do xung đột phiên bản.

stamp

Integer; optional; default is 0

Xem phần về các đối số py_binary(), ngoại trừ đối số con dấu được đặt thành 0 theo mặc định cho kiểm thử.

thời gian chạy py

Xem nguồn quy tắc 
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)

Thể hiện thời gian chạy Python dùng để thực thi mã Python.

Mục tiêu py_runtime có thể biểu thị 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 của nền tảng truy cập trình phiên dịch do hệ thống cài đặt tại một đường dẫn đã biết, trong khi môi trường 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 phiên dịch. Trong cả hai trường hợp, một "trình phiên dịch" có nghĩa là mọi tập lệnh nhị phân hoặc trình bao bọc thực thi có khả năng chạy tập lệnh Python được truyền trên dòng lệnh, tuân theo các quy ước tương tự như trình phiên dịch CPython chuẩn.

Thời gian chạy nền tảng theo bản chất không phải là gói thuê bao. Công cụ này đặt ra yêu cầu trên nền tảng mục tiêu về việc biên 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ể có hoặc không có tính khép kín, tuỳ thuộc vào việc trình duyệt đó trỏ đến một trình phiên dịch đã đăng ký hay một tập lệnh trình bao bọc truy cập vào trình 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.
bootstrap_template

Label; optional; default is @bazel_tools//tools/python:python_bootstrap_template.txt

Trước đây được gọi là "tập lệnh mã giả lập Python", đây là điểm truy cập vào mọi mục tiêu thực thi Python.
coverage_tool

Label; optional

Đây là một mục tiêu 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 hoặc mục tiêu 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ụ bảo hiểm python. Mục tiêu và các tệp chạy của mục tiêu đó sẽ được thêm vào các tệp chạy khi tính năng mức độ phù hợp được bật.

Điểm truy cập cho công cụ này phải có thể tải được bằng trình phiên dịch python (ví dụ: tệp .py hoặc .pyc). Thuộc tính 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 trong bản dựng, đây là tập hợp các tệp chứa thời gian chạy này. Những tệp này sẽ được thêm vào các tệp nhị phân của Python sử dụng thời gian chạy này. Đối với thời gian chạy 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 đang được tạo, đây là mục tiêu để gọi làm trình phiên dịch. Đối với thời gian chạy 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 phiên dịch Python trên nền tảng mục tiêu. Không được đặt thuộc tính này trong thời gian chạy trong bản dựng.
python_version

String; optional; default is "_INTERNAL_SENTINEL"

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

Giá trị mặc định được 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 tập lệnh Python khởi độ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.