ציון יחסי תלות ב-Python

מציינים את יחסי התלות של האפליקציה בגרסאות 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"
    

• אורזים יחסי תלות מקומיים לצד הפונקציה.

  אין תמיכה בהגדרת תלות באמצעות התקן Pipfile/Pipfile.lock. הפרויקט לא אמור לכלול את הקבצים האלה.

  אם אתם משתמשים בקובץ requirements.txt כדי לנהל תלות,‏ Cloud Run מתקין בשבילכם את Functions Framework כשאתם יוצרים פונקציה. עם זאת, מומלץ לכלול את Functions Framework כתלות מפורשת כדי למנוע אי התאמות.

  כשמשתמשים בקובץ pyproject.toml, צריך לכלול את Functions Framework כתלות, כי Cloud Run לא מתקין אותו בשבילכם.

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

אם אתם מנהלים את יחסי התלות באמצעות 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".

מריצים את הפקודה gcloud run deploy כדי להגדיר את משתנה הסביבה של מנהל החבילות ל-pip:

gcloud run deploy SERVICE --source . \
  --set-build-env-vars=GOOGLE_PYTHON_PACKAGE_MANAGER=pip

מחליפים את SERVICE בשם של שירות Cloud Run.

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

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

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

מריצים את הפקודה gcloud run deploy כדי להגדיר את משתנה הסביבה של מנהל החבילות ל-uv:

gcloud run deploy SERVICE --source . \
  --set-build-env-vars=GOOGLE_PYTHON_PACKAGE_MANAGER=uv

מחליפים את SERVICE בשם של שירות Cloud Run.

אריזת יחסי תלות מקומיים

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

אפשר גם להשתמש בקובץ requirements.txt כדי לציין תלות נוספת שלא ארזתם לצד הפונקציה. לדוגמה, אפשר להשתמש במבנה הספרייה הבא:

myfunction/
├── main.py
└── localpackage/
    ├── __init__.py
    └── script.py

מייבאים את הקוד מ-localpackage באמצעות ההצהרה import הבאה:

# code in main.py
from localpackage import script

בגישה הזו לא מפעילים קובצי setup.py. אפשר לצרף את החבילות לקבצים האלה, אבל יכול להיות שהחבילה לא תפעל בצורה תקינה בפונקציות Cloud Run.

יחסי תלות שהועתקו

תלויות שהועתקו הן תלויות שהמקור שלהן נכלל ישירות בחבילת קוד המקור ונבנה מחדש לצד הקוד שלכם. משתמשים במשתנה הסביבה GOOGLE_VENDOR_PIP_DEPENDENCIES build כדי ליצור עותקים של יחסי התלות של pip ולהימנע מהתקנתם במהלך הפריסה.

יצירת תלות מועתקת

1. מוודאים ש-python3 מותקן במערכת הפיתוח.

2. מצהירים על יחסי התלות של האפליקציה בקובץ requirements.txt בתיקיית השורש של עץ הפיתוח.

3. מצהירים על Functions Framework כדרישה על ידי הוספת functions-framework בשורה נפרדת בקובץ requirements.txt.

4. מורידים את התלות של הפונקציה לספרייה המקומית. השלבים לביצוע הפעולה הזו משתנים בהתאם לסוג קובץ התלות: קובץ Python wheel ‏ (*.whl) או קובץ tar ‏ (*.tar.gz).

   1. אם התלות היא קובץ Python wheel ‏ (*.whl), מורידים אותו לספריית הבסיס של עץ הפיתוח באמצעות פקודת ה-pip הבאה:

      python3 -m pip download -r requirements.txt --only-binary=:all: \
         -d DIRECTORY \
         --python-version PYTHON_RUNTIME_VERSION \
         --platform manylinux2014_x86_64 \
         --implementation cp
      

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

      • ‫DIRECTORY: השם של הספרייה המקומית שאליה רוצים להוריד.
      • ‫PYTHON_RUNTIME_VERSION: גרסת Python שבה ייעשה שימוש לבדיקות תאימות. לדוגמה 314 ל-Python 3.14. ‫
        הגרסה הזו צריכה להתאים לאחת מסביבות זמן הריצה הנתמכות של Python.

      מבנה הספריות שמתקבל אמור להיראות כך:

      myfunction/
      ├── main.py
      └── requirements.txt
      └── DIRECTORY
         ├── dependency1.whl
         └── dependency2.whl
      

   2. אם התלות היא קובץ tar ‏ (*.tar.gz):

      1. אם יחסי התלות כתובים ב-Python, משתמשים ב-pip כדי להוריד אותם:

         python3 -m pip download -r requirements.txt \
            -d DIRECTORY
         

      2. אם יחסי התלות כוללים קוד שנכתב ב-C או ב-C++, צריך להוריד את הקוד ולהדר אותו בנפרד.

5. פורסים את הפונקציה ואת יחסי התלות שהועתקו:

   gcloud functions deploy FUNCTION_NAME \
     --runtime PYTHON_RUNTIME_NAME \
     --set-build-env-vars GOOGLE_VENDOR_PIP_DEPENDENCIES=DIRECTORY
   

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

   • ‫FUNCTION_NAME: שם הפונקציה שפורסתם.
   • ‫PYTHON_RUNTIME_NAME: השם של אחת מסביבות הריצה הנתמכות של Python להרצת הפונקציה שנפרסה – לדוגמה, python311. גרסת זמן הריצה של Python צריכה להיות זהה לגרסה שבה השתמשתם בסביבת הפיתוח המקומית.
   • ‫DIRECTORY: השם של הספרייה שמכילה את התלויות שהעתקתם.

מידע נוסף על השימוש ב-Buildpack זמין במאמר פיתוח פונקציה באמצעות Buildpack.

שימוש בתלות פרטית

אפשר להשתמש ביחסי תלות פרטיים מ-Artifact Registry או ממאגרים אחרים.

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

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

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

אם אתם צריכים כמה מאגרים בשביל ה-build, אתם יכולים להשתמש במאגר וירטואלי ב-Artifact Registry כדי לשלוט בבטחה בסדר שבו pip מחפש במאגרים.

יחסי תלות פרטיים ממאגרים אחרים

‫Buildpacks מתקין יחסי תלות בסביבת Cloud Build שלא מספקת גישה למפתחות SSH. מעתיקים את החבילות שמתארחות במאגרים שנדרש בהם אימות מבוסס-SSH ומעלים את החבילות עם הקוד של הפרויקט.

משתמשים בפקודה pip install עם הדגל -t DIRECTORY כדי להעתיק תלויות פרטיות לספרייה מקומית לפני פריסת האפליקציה, באופן הבא:

1. מעתיקים את התלות לספרייה מקומית:

   pip install -t DIRECTORY DEPENDENCY

2. מוסיפים קובץ ריק בשם __init__.py לספרייה DIRECTORY כדי להפוך אותה למודול.
3. כדי להשתמש בתלות, מייבאים אותה מהמודול הזה:

   import DIRECTORY.DEPENDENCY

חבילות שהותקנו מראש

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

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

anyio==4.5.2
blinker==1.8.2
click==8.1.8
cloudevents==1.11.0
deprecation==2.1.0
exceptiongroup==1.3.0
Flask==3.0.3
functions-framework==3.9.1
gunicorn==23.0.0
h11==0.16.0
idna==3.10
importlib_metadata==8.5.0
itsdangerous==2.2.0
Jinja2==3.1.6
MarkupSafe==2.1.5
packaging==25.0
sniffio==1.3.1
# Install starlette 0.44.0 for Python 3.8
starlette==0.44.0; python_version == '3.8'
# Install starlette 0.49.1 for Python versions greater than 3.8
starlette==0.49.1; python_version > '3.8'
typing_extensions==4.13.2
uvicorn==0.33.0
uvicorn-worker==0.2.0
watchdog==4.0.2
Werkzeug==3.0.6
zipp==3.20.2

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

• ‫pip (הגרסה האחרונה)
• ‫setuptools (הגרסה האחרונה)
• wheel (בהתאם לדרישות המוצר)

סביבת זמן הריצה של Python כוללת גם מספר חבילות מערכת בסביבת ההפעלה.