פיתוח אפליקציה ב-Python

‏Buildpacks תומכים בתצורת שפה אידיומטית באמצעות משתני סביבה.

ציון גרסת Python

כברירת מחדל, ה-buildpack של Python Runtime משתמש בגרסה היציבה והעדכנית ביותר של רכיב התרגום ב-Python. אם באפליקציה שלכם דרושה גרסה ספציפית, תוכלו לציין אותה על ידי הוספת קובץ .python-version לתיקיית השורש של האפליקציה.

3.14

שימוש ב-GOOGLE_PYTHON_VERSION

אפשר גם לציין את גרסת Python באמצעות משתנה הסביבה GOOGLE_PYTHON_VERSION. אם הגדרתם את שתי התצורות, הערך של GOOGLE_PYTHON_VERSION מקבל קדימות על פני הקובץ .python-version. כברירת מחדל, אם לא מציינים את הקובץ .python-version ואת משתנה הסביבה GOOGLE_PYTHON_VERSION, נעשה שימוש בגרסת ה-LTS העדכנית ביותר של Python.

כדי להגדיר שה-buildpack ישתמש בגרסת Python נתמכת כשפורסים את האפליקציה:

pack build sample-python --builder=gcr.io/buildpacks/builder \
  --env GOOGLE_PYTHON_VERSION="3.14.x"

אתם גם יכולים להשתמש במתאר של פרויקט project.toml כדי לקודד את משתנה הסביבה לצד קובצי הפרויקט. במאמר פיתוח אפליקציות באמצעות משתני סביבה מפורטות ההוראות.

ציון יחסי תלות

מציינים את יחסי התלות של האפליקציה בגרסאות Python נתמכות באמצעות אחת מהגישות הבאות:

  • משתמשים בקובץ requirements.txt בתיקיית השורש. הקובץ הזה צריך להיות באותה ספרייה שבה נמצא קובץ main.py שמכיל את קוד המקור. הקובץ requirements.txt מכיל שורה אחת לכל חבילה. כל שורה מכילה את שם החבילה, ואת הגרסה המבוקשת (אופציונלי). כדי למנוע השפעה של שינויים בגרסת התלות על הבנייה, כדאי להצמיד את חבילות התלות לגרסה ספציפית.

    קובץ requirements.txt לדוגמה:

    functions-framework
requests==2.20.0
numpy

  • משתמשים בקובץ pyproject.toml כדי לציין יחסי תלות. אם אתם מנהלים את יחסי התלות של האפליקציה בקובץ pyproject.toml במקום בקובץ requirements.txt, ה-buildpack של Python קובע את מנהל החבילות על סמך ההגדרה שציינתם בקובץ pyproject.toml. מידע נוסף זמין במאמר בנושא פריסת אפליקציות Python עם קובץ pyproject.toml.

    אם האפליקציה משתמשת גם בקובץ pyproject.toml וגם בקובץ requirements.txt, קובץ requirements.txt מקבל עדיפות.

    • קובץ pyproject.toml לדוגמה:

      [project]
name = "demo-app"
version = "0.1.0"
description = ""
requires-python = ">=3.10"
dependencies = [
    "flask>=3.1.1",
    "gunicorn>=23.0.0",
]

[build-system]
requires = ["setuptools>=61.0"]
build-backend = "setuptools.build_meta"

מערכות ניהול חבילות

אם אתם מנהלים את יחסי התלות באמצעות requirements.txt file, מנהל החבילות שמוגדר כברירת מחדל משתנה בהתאם לגרסת Python שהגדרתם.

אם אתם משתמשים בקובץ pyproject.toml כדי לנהל יחסי תלות במקום בקובץ requirements.txt, ה-buildpack של Python קובע את מנהל החבילות על סמך הגדרות התצורה בקובץ pyproject.toml. ה-buildpack תומך במנהלי חבילות pip, ‏ uv ו-Poetry. מידע נוסף זמין במאמר בנושא פריסת אפליקציות Python עם קובץ pyproject.toml.

‫Python 3.14 ואילך

החל מגרסה 3.14 של Python ואילך, ה-buildpack של Python משתמש במנהל החבילות uv כמתקין ברירת המחדל של יחסי התלות שצוינו בקובץ requirements.txt.

כדי להשתמש ב-pip כמנהל החבילות, מגדירים את משתנה הסביבה GOOGLE_PYTHON_PACKAGE_MANAGER="pip".

‫Python 3.13 וגרסאות קודמות

בגרסה Python 3.13 ובגרסאות קודמות, ה-buildpack של Python משתמש במנהל החבילות pip כדי להתקין את יחסי התלות שמוגדרים בקובץ requirements.txt.

כדי להשתמש ב-uv כמנהל החבילות, מגדירים את משתנה הסביבה GOOGLE_PYTHON_PACKAGE_MANAGER="uv".

הגדרת PIP

אפשר להגדיר את ההתנהגות של PIP באמצעות משתני סביבה:

pack build sample-python --builder=gcr.io/buildpacks/builder \
  --env PIP_DEFAULT_TIMEOUT='60'

יחסי תלות פרטיים מ-Artifact Registry

מאגר Python ב-Artifact Registry יכול לארח יחסי תלות פרטיים של פונקציית Python. כשמפתחים אפליקציה ב-Cloud Build, ה-buildpack של Python ייצור לחשבון השירות ב-Cloud Build פרטי כניסה ל-Artifact Registry באופן אוטומטי. צריך לכלול רק את כתובת ה-URL של Artifact Registry שב-requirements.txt בלי ליצור פרטי כניסה נוספים. לדוגמה:

--extra-index-url REPOSITORY_URL
sampleapp
Flask==0.10.1
google-cloud-storage

נקודת כניסה לאפליקציה

בקטע הבא מתואר ה-entrypoint שמוגדר כברירת מחדל ל-buildpack של Python.

נקודת כניסה לפריסות מקוד המקור ב-Cloud Run

התכונה הזו זמינה רק אם פורסים את קוד המקור ב-Cloud Run עם זמן הריצה של Python. התכונה הזו לא רלוונטית אם אתם יוצרים את קובץ אימג' של קונטיינר ישירות באמצעות pack build מחוץ לתהליך הפריסה של קוד המקור ב-Cloud Run.

‫Python buildpack תומך במסגרות אינטרנט מודרניות כמו FastAPI,‏ Gradio,‏ Streamlit ו-Agent Development Kit (ADK).

‫Python גרסה 3.12 ומטה

אם אתם משתמשים ב-Python בגרסה 3.12 ומגרסאות קודמות, ה-buildpack של Python משתמש ב-Gunicorn כשרת ברירת המחדל של WSGI HTTP בעומס העבודה. ה-buildpack של Python מגדיר את נקודת הכניסה (entrypoint) כברירת מחדל ל-gunicorn -b :8080 main:app.

גרסה Python 3.13 ואילך

ב-Python מגרסה 3.13 ואילך, ה-buildpack של Python מגדיר את נקודת הכניסה (entrypoint) שמוגדרת כברירת מחדל לפריסות של קוד מקור ב-Cloud Run על סמך התצורה של שרת האינטרנט או של המסגרת בקובץ requirements.txt. הגדרת ברירת המחדל הזו רלוונטית רק לפריסות של מקורות שירות ב-Cloud Run, ולא לפונקציות Cloud Run.

כשפורסים שירות Cloud Run ממקור באמצעות Python Runtime, ה-buildpack קובע את גרסת Python ואת נקודת הכניסה (entrypoint) שמוגדרת כברירת מחדל בדרכים הבאות:

  • אם לא מציינים גרסת Python בקובצי המקור, ה-buildpack של Python מגדיר כברירת מחדל את גרסת Python העדכנית הנתמכת. חבילת ה-buildpack קובעת את נקודת הכניסה שמוגדרת כברירת מחדל על סמך שרת האינטרנט או המסגרת שהגדרתם בקובץ requirements.txt.

  • אם לא מציינים שרת אינטרנט או framework בקובץ requirements.txt, ה-buildpack של Python משתמש כברירת מחדל ב-Gunicorn כשרת WSGI HTTP בעומס העבודה. ה-buildpack של Python מגדיר את נקודת הכניסה (entrypoint) כברירת מחדל ל-gunicorn -b :8080 main:app.

  • ‫buildpack של Python מגדיר את נקודת הכניסה כברירת מחדל על סמך סדר העדיפויות הבא, כפי שמוגדר בקובץ requirements.txt:

    1. gunicorn
    2. uvicorn
    3. fastapi[standard]
    4. gradio
    5. streamlit
    6. google-adk

הגדרת שרת האינטרנט או המסגרת

בטבלה הבאה מפורטות נקודות הכניסה שמוגדרות כברירת מחדל לכל אחת מההגדרות הנפוצות של Python בקובץ requirements.txt, כשפורסים ל-Cloud Run ממקור:

ההגדרה הראשית נקודת כניסה שמוגדרת כברירת מחדל משתני סביבה
gunicorn gunicorn -b :8080 main:app
numpy gunicorn -b :8080 main:app
fastapi
uvicorn		 uvicorn main:app --host 0.0.0.0 --port 8080
fastapi[standard] uvicorn main:app --host 0.0.0.0 --port 8080
uvicorn
gunicorn		 gunicorn -b :8080 main:app
gradio python main.py GRADIO_SERVER_NAME=0.0.0.0
GRADIO_SERVER_PORT=8080
streamlit streamlit run main.py --server.address 0.0.0.0 --server.port 8080
google-adk adk api_server --host 0.0.0.0 --port 8080

כדי למנוע כשלים בהטמעה, צריך להשתמש בגרסת Python נתמכת בקובצי המקור, ולציין שרת אינטרנט בקובץ requirements.txt.

אפשר גם לציין את נקודת הכניסה על ידי הרצת הפקודה הבאה לפריסת מקור:

  gcloud run deploy SERVICE --source .  --set-build-env-vars GOOGLE_ENTRYPOINT="ENTRYPOINT"

מחליפים את מה שכתוב בשדות הבאים:

  • ‫SERVICE: השם של השירות שרוצים לפרוס.
  • ‫ENTRYPOINT: נקודת הכניסה שרוצים להשתמש בה כברירת מחדל לקוד המקור.

אם אתם לא מצליחים לפרוס את קוד המקור ב-Cloud Run או שאתם מוצאים שגיאות ביומנים, כדאי לעיין במדריך לפתרון בעיות ב-Cloud Run.

נקודת כניסה לכל שאר הפריסות

ה-buildpack של Python משתמש ב-Gunicorn בתור שרת ברירת המחדל של WSGI HTTP בעומס העבודה. אפליקציות שפותחו באמצעות buildpack של Python מתחילות את התהליך gunicorn עם הגדרות ברירת המחדל, בדומה להרצה של הקוד:

gunicorn --bind :8080 main:app

התאמה אישית של נקודת הכניסה לאפליקציה

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

אתם יכולים ליצור קובץ Procfile עם הגדרות בהתאמה אישית בתיקיית השורש. דוגמה:

web: gunicorn --bind :$PORT --workers 1 --threads 8 --timeout 0 main:app

לחלופין, אתם יכולים להשתמש במשתנה הסביבה GOOGLE_ENTRYPOINT באמצעות הפקודה pack. דוגמה:

pack build sample-python \
  --builder gcr.io/buildpacks/builder
  --env "GOOGLE_ENTRYPOINT='gunicorn --bind :$PORT main:app'"

משתני סביבה

כדי להתאים אישית את הקונטיינר, ה-buildpack של Python תומך במשתני הסביבה הבאים

PIP_<key>

ראו מאמרי העזרה בנושא PIP.

דוגמה: ‏PIP_DEFAULT_TIMEOUT=60 מגדיר את --default-timeout=60 לפקודות pip.

פריסת אפליקציות Python באמצעות קובץ pyproject.toml

‫Python buildpacks תומכים בפרויקטים שמוגדרים באמצעות הקובץ pyproject.toml. התכונה הזו מאפשרת לכם לפרוס אפליקציות שאתם מנהלים באמצעות Poetry,‏ uv או pip, ישירות ב-Cloud Run ובפונקציות Cloud Run. התכונה הזו לא זמינה ב-App Engine.

ה-buildpack של Python משתמש בקובץ pyproject.toml רק אם לא קיים קובץ requirements.txt בתיקיית הבסיס. אם האפליקציה משתמשת גם בקובץ pyproject.toml וגם בקובץ requirements.txt, אז לקובץ requirements.txt יש עדיפות.

הגדרות buildpacks נתמכות

‫Python buildpacks תומך בהגדרות הבאות:

  • ‫pip buildpack: מתקין יחסי תלות ישירות מ-pyproject.toml אם הוא מזהה את כל התנאים הבאים:

    • קובץ pyproject.toml נמצא בספריית השורש ולא הגדרתם כלים עם עדיפות גבוהה כמו קובץ poetry.lock, קטע [tool.poetry] או קובץ uv.lock.

    • מגדירים את משתנה הסביבה GOOGLE_PYTHON_PACKAGE_MANAGER לערך pip.

  • ‫uv buildpack: תומך בפרויקטים של Python שמנוהלים באמצעות uv. חבילת ה-buildpack הזו מופעלת אם היא מזהה אחד מהתנאים הבאים:

    • קובץ uv.lock וקובץ pyproject.toml נמצאים בתיקיית הבסיס של הפרויקט.
    • קובץ pyproject.toml נמצא בשורש הפרויקט, והגדרתם את משתנה הסביבה GOOGLE_PYTHON_PACKAGE_MANAGER ל-uv.
    • קובץ pyproject.toml קיים ולא כללתם קובצי נעילה אחרים עם עדיפות גבוהה יותר, כמו poetry.lock, ‏ uv.lock או הגדרות כמו [tool.poetry], ולא הגדרתם את משתנה הסביבה GOOGLE_PYTHON_PACKAGE_MANAGER.

  • ‫Poetry buildpack: תומך בפרויקטים של Python שמנוהלים באמצעות Poetry. חבילת ה-buildpack הזו מופעלת אם היא מזהה אחד מהתנאים הבאים:

    • קובץ poetry.lock וקובץ pyproject.toml נמצאים בתיקיית הבסיס של הפרויקט.
    • קובץ pyproject.toml נמצא בתיקיית הבסיס של הפרויקט, ויש קטע [tool.poetry] בקובץ pyproject.toml.

קדימות של מנהל החבילות

ה-buildpacks של Python קובעים את מנהל החבילות שמוגדר כברירת מחדל על סמך ההגדרה לפי סדר העדיפויות הבא:

  1. הקדימות הכי גבוהה ניתנת לקובץ requirements.txt. רק אם הקובץ הזה קיים, ה-buildpack של Python משתמש במנהל החבילות שמוגדר כברירת מחדל כדי להתקין יחסי תלות בשלב הבנייה. אם קובץ requirements.txt לא קיים, תהליך הזיהוי עובר לשלב הבא.

  2. לאחר מכן, ה-buildpack בודק אם בקובץ pyproject.toml יש קובץ poetry.lock או קטע [tool.poetry]. אם נמצא, תהליך ה-build ממשיך להשתמש ב-Poetry כדי להתקין יחסי תלות.

  3. אם לא מזוהה הגדרה של Poetry, ה-buildpack מחפש קובץ uv.lock. אם נמצא, תהליך build ממשיך להשתמש ב-uv כדי להתקין תלות.

  4. אם קובצי הנעילה לא קיימים, ה-buildpack בודק את משתנה הסביבה GOOGLE_PYTHON_PACKAGE_MANAGER כדי למצוא הגדרה של pip או uv.

  5. ברירת מחדל. אם לא מגדירים משתנה סביבה ומשתמשים רק בקובץ pyproject.toml בלי uv או Poetry, ה-buildpack משתמש כברירת מחדל ב-uv לכל גרסאות Python הנתמכות.

נקודת כניסה עם קובץ pyproject.toml

כשפורסים אפליקציה עם קובץ pyproject.toml במקום קובץ requirements.txt, ה-buildpack של Python משתמש בשיטה אחרת כדי לקבוע את נקודת הכניסה. מידע על הגדרת נקודת כניסה לאפליקציה באמצעות קובץ requirements.txt זמין במאמר נקודת כניסה לאפליקציה.

ה-buildpack מחפש נקודת כניסה לפי סדר העדיפויות הבא:

  1. אם הקובץ Procfile קיים בתיקיית השורש, או אם הגדרתם את משתנה הסביבה GOOGLE_ENTRYPOINT, ההגדרות האלה תמיד יבטלו את נקודת הכניסה שנקבעה על ידי סקריפטים של pyproject.toml.

  2. ה-buildpack של Python משתמש בסקריפטים מותאמים אישית שאתם מגדירים בקטעים [tool.poetry.scripts] ו-[project.scripts]. אם מגדירים סקריפט שכולל את start, זהו נקודת הכניסה. לדוגמה, poetry run start או uv run start.

  3. אם לא מגדירים סקריפט start, אבל מגדירים סקריפט אחר, הסקריפט שהגדרתם הוא נקודת הכניסה שמוגדרת כברירת מחדל. לדוגמה, poetry run mycmd או uv run mycmd.

בניגוד ל-builds שמבוססים על requirements.txt, ה-buildpack של Python לא מתקין את gunicorn באופן אוטומטי בפרויקטים של pyproject.toml. כדי להשתמש ב-gunicorn או בכל שרת אחר, צריך להוסיף אותו באופן מפורש לתלות בקובץ pyproject.toml.

אם לא מגדירים סקריפטים מותאמים אישית בקובץ pyproject.toml, חבילות ה-buildpack מנסות לזהות מסגרות נפוצות, כמו gunicorn,‏ uvicorn או fastapi, מתוך התלות של pyproject.toml וקובעות נקודת כניסה כברירת מחדל.