Quy tắc Python

Báo cáo vấn đề Xem nguồn

Quy tắc

• py_binary
• py_library
• py_test
• py_runtime

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 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 trong thời gian chạy và một tập lệnh mã giả lập giúp khởi động chương trình với 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 kiểm thử khác (ví dụ: chạy một tệp nhị phân python để thiết lập một tài nguyên mô phỏng nào đó trong một java_test), thì phương pháp chính xác 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 đó. Sau đó, tệp nhị phân khác có thể xác định vị trí py_binary tương ứng 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 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 phần mở rộng. Ví dụ: nếu điểm truy cập 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 đượ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à các quy tắc py_library.
srcs	Danh sách nhãn; bắt buộc 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. Thay vào đó, 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 chuỗi; mặc định là [] 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 thư mục nhập này sẽ được thêm vào cho quy tắc này và mọi 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 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 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 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 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à auto (tự động) có nghĩa là true trừ phi --incompatible_default_to_explicit_init_py được sử dụng. 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 của các mục tiêu Python theo yêu cầu.
main	Nhãn; mặc định là None 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, 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	Chuỗi; không thể định cấu hình; giá trị mặc định là "_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) thành 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 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 sẽ thiết lập phiên bản mà Bazel tạo mục tiêu của bạn, nhưng do #4815, tập lệnh mã giả lập kết quả vẫn có thể gọi không chính xác phiên bản trình phiên dịch trong thời gian chạy. Xem giải pháp này, bao gồm 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 phải tương thích với Python 2, Python 3 hoặc cả hai. Để 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 phép là: "PY2AND3", "PY2" và "PY3". Các giá trị "PY2ONLY" và "PY3ONLY" cũng được phép sử dụng vì các lý do trước đây, nhưng 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. 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, bạn sẽ 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ó 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.) Để biết thông tin chẩn đoán về những phần phụ thuộc dẫn đến 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 yêu cầu một phiên bản Python hay một phiên bản khác. Xin lưu ý rằng phương thức này 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 Liệu có mã hoá thông tin bản dựng thành tệp nhị phân hay không. Có thể dùng các giá trị sau: 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ể 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 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 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

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 duy nhất 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 đượ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à các quy tắc py_library.
srcs	Danh sách nhãn; mặc định là [] 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	Danh sách chuỗi; mặc định là [] 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 thư mục nhập này sẽ được thêm vào cho quy tắc này và mọi 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 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 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 phải tương thích với Python 2, Python 3 hoặc cả hai. Để 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 phép là: "PY2AND3", "PY2" và "PY3". Các giá trị "PY2ONLY" và "PY3ONLY" cũng được phép sử dụng vì các lý do trước đây, nhưng 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. 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, bạn sẽ 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ó 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.) Để biết thông tin chẩn đoán về những phần phụ thuộc dẫn đến 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 yêu cầu một phiên bản Python hay một phiên bản khác. Xin lưu ý rằng phương thức này 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() 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	Tên; bắt buộc Tên duy nhất 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 đượ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à các quy tắc py_library.
srcs	Danh sách nhãn; bắt buộc 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. Thay vào đó, 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 chuỗi; mặc định là [] 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 thư mục nhập này sẽ được thêm vào cho quy tắc này và mọi 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 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 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 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 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à auto (tự động) có nghĩa là true trừ phi --incompatible_default_to_explicit_init_py được sử dụng. 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 của các mục tiêu Python theo yêu cầu.
main	Nhãn; mặc định là None 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, 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	Chuỗi; không thể định cấu hình; giá trị mặc định là "_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) thành 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 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 sẽ thiết lập phiên bản mà Bazel tạo mục tiêu của bạn, nhưng do #4815, tập lệnh mã giả lập kết quả vẫn có thể gọi không chính xác phiên bản trình phiên dịch trong thời gian chạy. Xem giải pháp này, bao gồm 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 phải tương thích với Python 2, Python 3 hoặc cả hai. Để 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 phép là: "PY2AND3", "PY2" và "PY3". Các giá trị "PY2ONLY" và "PY3ONLY" cũng được phép sử dụng vì các lý do trước đây, nhưng 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. 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, bạn sẽ 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ó 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.) Để biết thông tin chẩn đoán về những phần phụ thuộc dẫn đến 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 yêu cầu một phiên bản Python hay một phiên bản khác. Xin lưu ý rằng phương thức này 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ề đối số py_binary(), ngoại trừ việc đối số dấu được đặt thành 0 theo mặc định cho các hoạt động 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)

Đạ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 một 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 nền tảng 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 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à bất kỳ tập lệnh nhị phân hoặc trình bao bọc nào có thể 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 giống như trình biên 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 là không gián đoạn. Phương thức này đặt ra yêu cầu trên nền tảng mục tiêu về việc phải có thông dịch viên tại một đường dẫn cụ thể. Môi trường thời gian chạy trong bản dựng có thể mang tính chất kín hoặc không, tuỳ thuộc vào việc môi trường đó trỏ đến một trình thông 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	Tên; bắt buộc Tên duy nhất 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 mã giả lập Python", đây là điểm nhập vào mọi mục tiêu thực thi 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 độ sử dụng mã từ các mục tiêu py_binary và py_test. 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 một tệp 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ụ xác định mức độ sử dụng python. Mục tiêu và các tệp chạy của nó sẽ được thêm vào các tệp chạy khi mức độ sử dụng được bật. Đ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ụ: tệp .py hoặc .pyc). Lớ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	Danh sách nhãn; mặc định là [] Đố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, 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 đ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 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 của 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 mục tiêu. Đố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" 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	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 đang tự 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.