BazelCon 2022 מגיע בין 16 ל-17 בנובמבר לניו יורק באינטרנט.
הירשמו עוד היום!

כללי Python

קל לארגן דפים בעזרת אוספים אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.

כללים

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 היא תוכנית ב-Python להרצה, הכוללת אוסף של .py קובצי מקור (ייתכן שהם שייכים לכללי py_library נוספים), עץ ספריות מסוג *.runfiles שמכיל כל הקוד והנתונים הנדרשים על ידי התוכנית בזמן הריצה, וסקריפט עצירה שמפעיל את התוכנית עם הסביבה והנתונים הנכונים.

דוגמאות

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

אם ברצונך להריץ py_binary מתוך בדיקה בינארית אחרת או על ידי בדיקה אחרת (לדוגמה, הפעלת בינארי של פיתון כדי להגדיר משאב מדומה מתוך Java_test), הגישה הנכונה היא ליצור הבינארי או הבדיקה תלויים בpy_binary בקטע הנתונים שלו. הקובץ הבינארי השני יוכל לאתר את py_binary ביחס לספריית המקור.

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

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

ארגומנטים

מאפיינים
name

Name; required

שם ייחודי ליעד זה.


אם main לא צוין, הוא צריך להיות זהה לשם קובץ המקור שהוא נקודת הכניסה הראשית של האפליקציה, פחות התוסף. לדוגמה, אם נקודת הכניסה שלך נקראת main.py, השם שלך צריך להיות main.
deps

List of labels; optional

רשימת הספריות האחרות המקושרות ליעד הבינארי. אפשר לראות תגובות כלליות על deps במאפיינים האופייניים שמוגדרים ברוב כללי הבנייה. בדרך כלל מדובר ב-py_library כללים.
srcs

List of labels; required

רשימת קובצי המקור (.py) המעובדים ליצירת היעד. זה כולל את כל קודי הצ'ק-אין שלך וקובצי המקור שנוצרו. יעדי הספרייה שייכים לdeps במקום זאת, בעוד שקבצים בינאריים אחרים הנדרשים בזמן ריצה שייכים ל-data.
imports

List of strings; optional

רשימה של ספריות ייבוא להוספה אל PYTHONPATH.

בכפוף להחלפה "הפוך למשתנה". ספריות הייבוא האלה יתווספו לכלל הזה ולכל הכללים שתלויים בו (הערה: הכללים שהכלל הזה תלוי בהם. כל ספרייה תתווסף ל-PYTHONPATH על ידי py_binary כללים שמסתמכים על כלל זה.

אין להשתמש בנתיבים מוחלטים (נתיבים שמתחילים ב-/) ונתיבים שמפנים לנתיב שמעל לשורש הביצוע, ויובילו לשגיאה.

legacy_create_init

Integer; optional; default is -1

האם ליצור באופן לא מפורש קבצים __init__.py ריקים בעץ Runfile. הן נוצרות בכל ספרייה שמכילה קוד מקור של Python או בספריות משותפות, ובכל ספריית אב של הספריות האלה, למעט ספריית הבסיס של repo. ברירת המחדל היא אוטומטית, אלא אם נעשה שימוש ב---incompatible_default_to_explicit_init_py. אם הערך הוא False, המשתמש אחראי ליצור קובצי __init__.py (אולי ריקים) ולהוסיף אותם ל-srcs היעדים של Python לפי הצורך.
main

Label; optional

השם של קובץ המקור שהוא נקודת הכניסה הראשית של האפליקציה. הקובץ חייב להיות רשום גם ב-srcs. אם השדה לא צוין, נעשה שימוש בפונקציה name במקום זאת (מידע למעלה). אם name לא תואם לשם של קובץ כלשהו ב-srcs, יש לציין את main.
python_version

String; optional; nonconfigurable; default is "_INTERNAL_SENTINEL"

האם לבנות את היעד הזה (ואת deps הטרסיבי שלו) עבור Python 2 או Python 3. הערכים החוקיים הם "PY2" ו-"PY3" (ברירת המחדל).

גרסת ה-Python תמיד מאופסת (אולי כברירת מחדל) לכל גרסה שמצוינת באמצעות המאפיין הזה, ללא קשר לגרסה שצוינה בשורת הפקודה או על ידי יעדים גבוהים יותר שתלויים בתכונה הזו.

כדי להשתמש ב-select() בגרסה הנוכחית של Python, אפשר לבדוק את הערך של @rules_python//python:python_version. מידע נוסף זמין כאן.

אזהרה על באג: מאפיין זה מגדיר את הגרסה שעבורם Bazel בונה את היעד שלך, אך עקב #4815, ייתכן שסקריפט ה-Sub שמתקבל יפעל בצורה שגויה תרגום שיחה פעילה בזמן הריצה. ניתן לעיין בפתרון העקיפה הזה. תהליך זה כולל הגדרה של יעד מסוג py_runtime שמפנה לאחת מגרסאות ה-Python לפי הצורך והפעלה של py_runtime זה על ידי הגדרה --python_top.

srcs_version

String; optional; default is "PY2AND3"

מאפיין זה מצהיר על המאפיין srcs של היעד כך שיתאים ל-Python 2, ל-Python 3 או לשניהם. כדי להגדיר בפועל את גרסת זמן הריצה של Python, יש להשתמש במאפיין python_version של כלל Python ניתן להפעלה (py_binary או py_test).

הערכים המותרים הם: "PY2AND3", "PY2" ו-"PY3". הערכים "PY2ONLY" ו-"PY3ONLY" מותרים גם למטרות היסטוריות, אבל בעיקרון הם זהים ל-"PY2" ול-"PY3", ויש להימנע מהם.

לתשומת ליבך, רק כללי ההפעלה (py_binary ו-py_library ) מאמתים בפועל את הגרסה הנוכחית של Python לעומת הערך של המאפיין הזה. (זו תכונה; כי py_library לא משנה את גרסת ה-Python הנוכחית, אם היא ביצעה אימות, לא תהיה אפשרות לבנות הן את הספריות של PY2ONLY והן את PY3ONLY ב אותה הפעלה). בנוסף, אם יש אי-התאמה של הגרסה, השגיאה מדווחת רק בשלב ההפעלה. באופן ספציפי, השגיאה לא תופיע בהפעלת bazel build --nobuild.)

כדי לקבל מידע על האבחון לגבי יחסי תלות שכוללים דרישות גרסה, אפשר להריץ את היבט find_requirements על היעד:

          bazel build <your target> \
              --aspects=@rules_python//python:defs.bzl%find_requirements \
              --output_groups=pyversioninfo
          
פעולה זו תבנה קובץ עם הסיומת -pyversioninfo.txt שנתת כאן מוסבר למה צריך להשתמש ב-Python בגרסה אחרת. חשוב לשים לב שהיא פועלת גם אם בניית היעד נכשלה עקב התנגשות בין גרסאות.

stamp

Integer; optional; default is -1

האם לקודד מידע build לתוך הקובץ הבינארי. ערכים אפשריים:
  • stamp = 1: יש להחתים תמיד את פרטי ה-build בקובץ הבינארי, גם ב-build --nostamp. יש להימנע משימוש בהגדרה הזו, כי היא עלולה לסגור את המטמון במטמון של קובץ בינארי או של כל פעולה במורד הזרם שתלויה בו.
  • stamp = 0: יש להחליף תמיד את פרטי ה-build בערכים קבועים. זה מאפשר לשמור במטמון תוצאות טובות של גרסאות build.
  • stamp = -1: הטמעה של פרטי build נשלטת על ידי הסימון --[no]stamp.

הקבצים הבינאריים המוטבעים לא נוצרים מחדש, אלא אם התלות שלהם השתנתה.

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)

ארגומנטים

מאפיינים
name

Name; required

שם ייחודי ליעד זה.

deps

List of labels; optional

רשימת הספריות האחרות המקושרות ליעד הבינארי. אפשר לראות תגובות כלליות על deps במאפיינים האופייניים שמוגדרים ברוב כללי הבנייה. בדרך כלל מדובר ב-py_library כללים.
srcs

List of labels; optional

רשימת קובצי המקור (.py) המעובדים ליצירת היעד. זה כולל את כל קודי הצ'ק-אין שלך וקובצי המקור שנוצרו.
imports

List of strings; optional

רשימה של ספריות ייבוא להוספה אל PYTHONPATH.

בכפוף להחלפה "הפוך למשתנה". ספריות הייבוא האלה יתווספו לכלל הזה ולכל הכללים שתלויים בו (הערה: הכללים שהכלל הזה תלוי בהם. כל ספרייה תתווסף ל-PYTHONPATH על ידי py_binary כללים שמסתמכים על כלל זה.

אין להשתמש בנתיבים מוחלטים (נתיבים שמתחילים ב-/) ונתיבים שמפנים לנתיב שמעל לשורש הביצוע, ויובילו לשגיאה.

srcs_version

String; optional; default is "PY2AND3"

מאפיין זה מצהיר על המאפיין srcs של היעד כך שיתאים ל-Python 2, ל-Python 3 או לשניהם. כדי להגדיר בפועל את גרסת זמן הריצה של Python, יש להשתמש במאפיין python_version של כלל Python ניתן להפעלה (py_binary או py_test).

הערכים המותרים הם: "PY2AND3", "PY2" ו-"PY3". הערכים "PY2ONLY" ו-"PY3ONLY" מותרים גם למטרות היסטוריות, אבל בעיקרון הם זהים ל-"PY2" ול-"PY3", ויש להימנע מהם.

לתשומת ליבך, רק כללי ההפעלה (py_binary ו-py_library ) מאמתים בפועל את הגרסה הנוכחית של Python לעומת הערך של המאפיין הזה. (זו תכונה; כי py_library לא משנה את גרסת ה-Python הנוכחית, אם היא ביצעה אימות, לא תהיה אפשרות לבנות הן את הספריות של PY2ONLY והן את PY3ONLY ב אותה הפעלה). בנוסף, אם יש אי-התאמה של הגרסה, השגיאה מדווחת רק בשלב ההפעלה. באופן ספציפי, השגיאה לא תופיע בהפעלת bazel build --nobuild.)

כדי לקבל מידע על האבחון לגבי יחסי תלות שכוללים דרישות גרסה, אפשר להריץ את היבט find_requirements על היעד:

          bazel build <your target> \
              --aspects=@rules_python//python:defs.bzl%find_requirements \
              --output_groups=pyversioninfo
          
פעולה זו תבנה קובץ עם הסיומת -pyversioninfo.txt שנתת כאן מוסבר למה צריך להשתמש ב-Python בגרסה אחרת. חשוב לשים לב שהיא פועלת גם אם בניית היעד נכשלה עקב התנגשות בין גרסאות.

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)

כלל מסוג py_test() עורך בדיקה. בדיקה היא wrapper בינארי מסביב לקוד בדיקה כלשהו.

דוגמאות

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

ניתן גם לציין מודול ראשי:

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

ארגומנטים

מאפיינים
name

Name; required

שם ייחודי ליעד זה.

deps

List of labels; optional

רשימת הספריות האחרות המקושרות ליעד הבינארי. אפשר לראות תגובות כלליות על deps במאפיינים האופייניים שמוגדרים ברוב כללי הבנייה. בדרך כלל מדובר ב-py_library כללים.
srcs

List of labels; required

רשימת קובצי המקור (.py) המעובדים ליצירת היעד. זה כולל את כל קודי הצ'ק-אין שלך וקובצי המקור שנוצרו. יעדי הספרייה שייכים לdeps במקום זאת, בעוד שקבצים בינאריים אחרים הנדרשים בזמן ריצה שייכים ל-data.
imports

List of strings; optional

רשימה של ספריות ייבוא להוספה אל PYTHONPATH.

בכפוף להחלפה "הפוך למשתנה". ספריות הייבוא האלה יתווספו לכלל הזה ולכל הכללים שתלויים בו (הערה: הכללים שהכלל הזה תלוי בהם. כל ספרייה תתווסף ל-PYTHONPATH על ידי py_binary כללים שמסתמכים על כלל זה.

אין להשתמש בנתיבים מוחלטים (נתיבים שמתחילים ב-/) ונתיבים שמפנים לנתיב שמעל לשורש הביצוע, ויובילו לשגיאה.

legacy_create_init

Integer; optional; default is -1

האם ליצור באופן לא מפורש קבצים __init__.py ריקים בעץ Runfile. הן נוצרות בכל ספרייה שמכילה קוד מקור של Python או בספריות משותפות, ובכל ספריית אב של הספריות האלה, למעט ספריית הבסיס של repo. ברירת המחדל היא אוטומטית, אלא אם נעשה שימוש ב---incompatible_default_to_explicit_init_py. אם הערך הוא False, המשתמש אחראי ליצור קובצי __init__.py (אולי ריקים) ולהוסיף אותם ל-srcs היעדים של Python לפי הצורך.
main

Label; optional

השם של קובץ המקור שהוא נקודת הכניסה הראשית של האפליקציה. הקובץ חייב להיות רשום גם ב-srcs. אם השדה לא צוין, נעשה שימוש בפונקציה name במקום זאת (מידע למעלה). אם name לא תואם לשם של קובץ כלשהו ב-srcs, יש לציין את main.
python_version

String; optional; nonconfigurable; default is "_INTERNAL_SENTINEL"

האם לבנות את היעד הזה (ואת deps הטרסיבי שלו) עבור Python 2 או Python 3. הערכים החוקיים הם "PY2" ו-"PY3" (ברירת המחדל).

גרסת ה-Python תמיד מאופסת (אולי כברירת מחדל) לכל גרסה שמצוינת באמצעות המאפיין הזה, ללא קשר לגרסה שצוינה בשורת הפקודה או על ידי יעדים גבוהים יותר שתלויים בתכונה הזו.

כדי להשתמש ב-select() בגרסה הנוכחית של Python, אפשר לבדוק את הערך של @rules_python//python:python_version. מידע נוסף זמין כאן.

אזהרה על באג: מאפיין זה מגדיר את הגרסה שעבורם Bazel בונה את היעד שלך, אך עקב #4815, ייתכן שסקריפט ה-Sub שמתקבל יפעל בצורה שגויה תרגום שיחה פעילה בזמן הריצה. ניתן לעיין בפתרון העוקף הזה, הכולל הגדרה של יעד py_runtime שמפנה לפי גרסת Python לפי הצורך, והפעלת py_runtime זה על ידי הגדרה --python_top.

srcs_version

String; optional; default is "PY2AND3"

מאפיין זה מצהיר על המאפיין srcs של היעד כך שיתאים ל-Python 2, ל-Python 3 או לשניהם. כדי להגדיר בפועל את גרסת זמן הריצה של Python, יש להשתמש במאפיין python_version של כלל Python ניתן להפעלה (py_binary או py_test).

הערכים המותרים הם: "PY2AND3", "PY2" ו-"PY3". הערכים "PY2ONLY" ו-"PY3ONLY" מותרים גם למטרות היסטוריות, אבל בעיקרון הם זהים ל-"PY2" ול-"PY3", ויש להימנע מהם.

לתשומת ליבך, רק כללי ההפעלה (py_binary ו-py_library ) מאמתים בפועל את הגרסה הנוכחית של Python לעומת הערך של המאפיין הזה. (זו תכונה; כי py_library לא משנה את גרסת ה-Python הנוכחית, אם היא ביצעה אימות, לא תהיה אפשרות לבנות הן את הספריות של PY2ONLY והן את PY3ONLY ב אותה הפעלה). בנוסף, אם יש אי-התאמה של הגרסה, השגיאה מדווחת רק בשלב ההפעלה. באופן ספציפי, השגיאה לא תופיע בהפעלת bazel build --nobuild.)

כדי לקבל מידע על האבחון לגבי יחסי תלות שכוללים דרישות גרסה, אפשר להריץ את היבט find_requirements על היעד:

          bazel build <your target> \
              --aspects=@rules_python//python:defs.bzl%find_requirements \
              --output_groups=pyversioninfo
          
פעולה זו תבנה קובץ עם הסיומת -pyversioninfo.txt שנתת כאן מוסבר למה צריך להשתמש ב-Python בגרסה אחרת. חשוב לשים לב שהיא פועלת גם אם בניית היעד נכשלה עקב התנגשות בין גרסאות.

stamp

Integer; optional; default is 0

עיין בקטע על ארגומנטים מסוג py_binary(), מלבד הארגומנט חותמת המוגדר כברירת מחדל לבדיקות.

py_runtime

py_runtime(name, compatible_with, deprecation, distribs, features, files, interpreter, interpreter_path, licenses, python_version, restricted_to, stub_shebang, tags, target_compatible_with, testonly, visibility)

מייצג זמן ריצה של Python המשמש להפעלת קוד Python.

יעד py_runtime יכול לייצג זמן ריצה של פלטפורמה או זמן ריצה מובנה. זמן ריצה של פלטפורמה ניגש למתפרש שהותקנו על ידי המערכת בנתיב ידוע, בעוד שזמן ריצה מובנה מצביע על יעד הפעלה המשמש כמתורגמן. בשני המקרים, "מתפרש" פירושו כל סקריפט בינארי או wrapper הניתן להרצה, המסוגל להפעיל סקריפט Python המועבר בשורת הפקודה, בהתאם למוסכמות הבאות של המתורגמן של CPython.

זמן ריצה של פלטפורמה הוא מטבעו אינו הרמטי. דרישה זו נותנת דרישה בפלטפורמת היעד למתורגמן שממוקם בנתיב ספציפי. זמן ריצה מובנה יכול להיות הרמטי, אבל לא בהכרח, תלוי אם הוא מפנה למפענח צ'ק-אין או לסקריפט wrapper שניגש למתורגמן של המערכת.

דוגמה:

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

ארגומנטים

מאפיינים
name

Name; required

שם ייחודי ליעד זה.

files

List of labels; optional

עבור זמן ריצה מובנה, קבוצת הקבצים שכוללת את זמן הריצה הזה. הקבצים האלה יתווספו לקובצי הריצה הבינאריים של Python שמשתמשים בזמן הריצה הזה. לגבי זמן ריצה של פלטפורמה, אין להגדיר את המאפיין הזה.
interpreter

Label; optional

עבור זמן ריצה מובנה, היעד הוא להפעיל כמתורגמן. לגבי זמן ריצה של פלטפורמה, אין להגדיר את המאפיין הזה.
interpreter_path

String; optional

עבור זמן ריצה של פלטפורמה, זהו הנתיב המוחלט של מכשיר התרגום של Python בפלטפורמת היעד. לא ניתן להגדיר את המאפיין הזה בזמן ריצה מובנה.
python_version

String; optional; default is "_INTERNAL_SENTINEL"

אם זמן הריצה הוא של Python ראשי בגרסה 2 או 3. הערכים החוקיים הם "PY2" ו-"PY3".

ערך ברירת המחדל נקבע על ידי הסימון --incompatible_py3_is_default. עם זאת, בעתיד, המאפיין הזה יהיה חובה ולא יהיה לו ערך ברירת מחדל.

stub_shebang

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

הביטוי "Shebang" התחיל לפני סקריפט ה-stobapping של Python שהיה בשימוש בעת הפעלת py_binary היעדים.

אפשר לעיין בבעיה 8685 כדי לקבל מוטיבציה.

לא רלוונטי ל-Windows.