Quy tắc Python

Nightly · 8.4 · 8.3 · 8.2 · 8.1 · 8.0 · 7.7

Quy tắc

py_binary

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 mà chương trình cần tại thời gian chạy và một tập lệnh gốc 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 bạn muốn chạy một py_binary từ một 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 phù hợp là làm cho 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 nhị phân hoặc kiểm thử đó. Sau đó, tệp nhị phân khác có thể xác định vị trí 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

Tên; bắt buộc

Tên 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

Danh sách nhãn; mặc định là []

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

Danh sách nhãn; bắt buộc

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ã đã kiểm tra và mọi tệp nguồn được tạo. Các mục tiêu thư viện thuộc deps, trong khi các tệp nhị phân khác cần thiết trong thời gian chạy thuộc data.
imports

Danh sách các chuỗi; mặc định là []

Danh sách các thư mục nhập cần thêm vào PYTHONPATH.

Chịu sự 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 vào. Mỗi thư mục sẽ được thêm vào PYTHONPATH theo các quy tắc py_binary 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 thư mục gốc thực thi không được phép và sẽ dẫn đến lỗi.

legacy_create_init

Số nguyên; giá trị mặc định là -1

Có tạo ngầm 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, cũng như 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à auto, tức là true trừ phi --incompatible_default_to_explicit_init_py được dùng. Nếu là false, người dùng 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 của các mục tiêu Python khi cần.
main

Nhãn; mặc định là None

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ó trong srcs. Nếu bạn không chỉ định, hệ thống sẽ sử dụng name (xem ở trên). Nếu name không khớp với tên tệp nào trong srcs, bạn phải chỉ định main.
python_version

Chuỗi; không thể định cấu hình; mặc định là "_INTERNAL_SENTINEL"

Có nên tạo mục tiêu này (và deps bắc cầu của mục tiê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 được đặt lại (có thể theo mặc định) thành bất kỳ phiên bản nào được chỉ định bằng thuộc tính này, bất kể phiên bản được chỉ định trên dòng lệnh hay bởi các mục tiêu cao hơn khác phụ thuộc vào mục tiêu 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. Xem tại đây để biết thêm thông tin.

Cảnh báo về lỗi: Thuộc tính này đặt phiên bản mà Bazel sẽ tạo mục tiêu của bạn, nhưng do #4815, tập lệnh gốc kết quả vẫn có thể gọi phiên bản trình thông dịch không chính xác trong thời gian chạy. Xem giải pháp này. Giải pháp này liên quan đến 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

Chuỗi; giá trị mặc định là "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 phép là: "PY2AND3", "PY2" và "PY3". Các giá trị "PY2ONLY" và "PY3ONLY" cũng được cho phép vì lý do lịch sử, nhưng về cơ bản, chúng 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 có thể 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ì 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ó sự không khớp về phiên bản, 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 có 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 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 một phiên bản Python cụ thể. Xin lưu ý rằng quy tắc này vẫn hoạt động ngay cả khi mục tiêu đã cho không tạo được do xung đột phiên bản.
stamp

Số nguyên; giá trị mặc định là -1

Có mã hoá thông tin bản dựng vào tệp nhị phân hay không. Các giá trị có thể là:
  • 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 chế độ cài đặt này, vì chế độ này có thể loại bỏ tính năng lưu vào bộ nhớ đệm từ xa cho tệp nhị phân và mọi thao tác tiếp theo phụ thuộc vào tệp nhị phân đó.
  • stamp = 0: Luôn thay thế thông tin bản dựng bằng các giá trị hằng số. Điều này giúp lưu vào bộ nhớ đệm kết quả của bản dựng một cách hiệu quả.
  • stamp = -1: Việc nhúng thông tin bản dựng được kiểm soát bằng cờ --[no]stamp.

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

py_library

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

Tên; bắt buộc

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

Danh sách nhãn; mặc định là []

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

Danh sách nhãn; mặc định là []

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ã đã kiểm tra và mọi tệp nguồn được tạo.
imports

Danh sách các chuỗi; mặc định là []

Danh sách các thư mục nhập cần thêm vào PYTHONPATH.

Chịu sự 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 vào. Mỗi thư mục sẽ được thêm vào PYTHONPATH theo các quy tắc py_binary 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 thư mục gốc thực thi không được phép và sẽ dẫn đến lỗi.

srcs_version

Chuỗi; giá trị mặc định là "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 phép là: "PY2AND3", "PY2" và "PY3". Các giá trị "PY2ONLY" và "PY3ONLY" cũng được cho phép vì lý do lịch sử, nhưng về cơ bản, chúng 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 có thể 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ì 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ó sự không khớp về phiên bản, 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 có 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 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 một phiên bản Python cụ thể. Xin lưu ý rằng quy tắc này vẫn hoạt động ngay cả khi mục tiêu đã cho không tạo được do xung đột phiên bản.

py_test

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() sẽ biên dịch một quy trình 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

Tên; bắt buộc

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

Danh sách nhãn; mặc định là []

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

Danh sách nhãn; bắt buộc

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ã đã kiểm tra và mọi tệp nguồn được tạo. Các mục tiêu thư viện thuộc deps, trong khi các tệp nhị phân khác cần thiết trong thời gian chạy thuộc data.
imports

Danh sách các chuỗi; mặc định là []

Danh sách các thư mục nhập cần thêm vào PYTHONPATH.

Chịu sự 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 vào. Mỗi thư mục sẽ được thêm vào PYTHONPATH theo các quy tắc py_binary 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 thư mục gốc thực thi không được phép và sẽ dẫn đến lỗi.

legacy_create_init

Số nguyên; giá trị mặc định là -1

Có tạo ngầm 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, cũng như 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à auto, tức là true trừ phi --incompatible_default_to_explicit_init_py được dùng. Nếu là false, người dùng 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 của các mục tiêu Python khi cần.
main

Nhãn; mặc định là None

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ó trong srcs. Nếu bạn không chỉ định, hệ thống sẽ sử dụng name (xem ở trên). Nếu name không khớp với tên tệp nào trong srcs, bạn phải chỉ định main.
python_version

Chuỗi; không thể định cấu hình; mặc định là "_INTERNAL_SENTINEL"

Có nên tạo mục tiêu này (và deps bắc cầu của mục tiê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 được đặt lại (có thể theo mặc định) thành bất kỳ phiên bản nào được chỉ định bằng thuộc tính này, bất kể phiên bản được chỉ định trên dòng lệnh hay bởi các mục tiêu cao hơn khác phụ thuộc vào mục tiêu 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. Xem tại đây để biết thêm thông tin.

Cảnh báo về lỗi: Thuộc tính này đặt phiên bản mà Bazel sẽ tạo mục tiêu của bạn, nhưng do #4815, tập lệnh gốc kết quả vẫn có thể gọi phiên bản trình thông dịch không chính xác trong thời gian chạy. Xem giải pháp này. Giải pháp này liên quan đến 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

Chuỗi; giá trị mặc định là "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 phép là: "PY2AND3", "PY2" và "PY3". Các giá trị "PY2ONLY" và "PY3ONLY" cũng được cho phép vì lý do lịch sử, nhưng về cơ bản, chúng 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 có thể 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ì 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ó sự không khớp về phiên bản, 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 có 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 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 một phiên bản Python cụ thể. Xin lưu ý rằng quy tắc này vẫn hoạt động ngay cả khi mục tiêu đã cho không tạo được do xung đột phiên bản.
stamp

Số nguyên; giá trị mặc định là 0

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

py_runtime

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)

Biểu thị một 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. Thời gian chạy nền tảng truy cập vào một 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 thực thi đóng vai trò là trình thông dịch. Trong cả hai trường hợp, "trình thông dịch" có nghĩa là mọi tệp nhị phân thực thi hoặc tập lệnh bao bọc có khả năng chạy một 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 thông dịch CPython tiêu chuẩn.

Thời gian chạy nền tảng vốn dĩ không khép kín. Thao tác này áp đặt một yêu cầu đối với nền tảng mục tiêu là phải có một trình thông dịch nằm ở một đường dẫn cụ thể. Thời gian chạy trong bản dựng có thể hoặc không thể khép kín, tuỳ thuộc vào việc thời gian chạy đó trỏ đến một trình thông dịch đã được kiểm tra hay một tập lệnh trình bao truy cập vào 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

Tên; bắt buộc

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

Nhãn; mặc định là "@bazel_tools//tools/python:python_bootstrap_template.txt"

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

Nhãn; mặc định là None

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

Nếu được đặt, đích đến phải tạo ra một tệp duy nhất hoặc là đích đến có thể thực thi. Đường dẫn đến tệp đơn lẻ hoặc tệp thực thi (nếu đích đến là tệp thực thi) sẽ xác định điểm truy cập cho công cụ đo lường mức độ sử dụng Python. Mục tiêu và các tệp chạy của mục tiêu đó sẽ được thêm vào tệp chạy khi bạn bật tính năng đo lường mức độ phù hợp.

Trình thông dịch python phải tải được điểm truy cập của công cụ (ví dụ: tệp .py hoặc .pyc). Nó 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

Danh sách nhãn; mặc định là []

Đối với thời gian chạy trong 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 runfiles của các 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, bạn không được đặt thuộc tính này.
interpreter

Nhãn; mặc định là None

Đối với thời gian chạy trong bản dựng, đây là mục tiêu để gọi dưới dạng trình thông 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

Chuỗi; giá trị mặc định là ""

Đối với thời gian chạy nền tảng, đây là đường dẫn tuyệt đối của một 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

Chuỗi; giá trị mặc định là "_INTERNAL_SENTINEL"

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

Giá trị mặc định được kiểm soát bằng cờ --incompatible_py3_is_default. 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

Chuỗi; giá trị mặc định là "#!/usr/bin/env python3"

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

Hãy xem vấn đề 8685 để có thêm động lực.

Không áp dụng cho Windows.