ניהול חבילות Python

בדף הזה מוסבר איך מוסיפים, מציגים ומוחקים חבילות Python וגרסאות של חבילות.

לפני שמתחילים

  1. מתקינים ומפעילים את Google Cloud CLI.

    כדי להריץ פקודות למאגרי Python, צריך להשתמש ב-Google Cloud CLI בגרסה 354.0.0 ואילך. אפשר לבדוק את הגרסה באמצעות הפקודה:

    gcloud version

  2. אם מאגר היעד לא קיים, יוצרים מאגר חדש של חבילות Python.

  3. מוודאים ש-Python 3 מותקן. הוראות התקנה מופיעות בGoogle Cloud הדרכה להגדרת Python.

  4. (אופציונלי) הגדרת ברירות מחדל לפקודות gcloud.

  5. אם אתם משתמשים באימות באמצעות מחזיק מפתחות עם פרטי כניסה של gcloud, אתם צריכים להיכנס ל-Google Cloud CLI באמצעות חשבון המשתמש או חשבון השירות שלכם.

התפקידים הנדרשים

כדי לקבל את ההרשאות שדרושות לניהול חבילות, צריך לבקש מהאדמין להקצות לכם את תפקידי ה-IAM הבאים במאגר:

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

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

הוספת חבילות

מצבי מאגר: רגיל

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

אלה השיטות המומלצות לשימוש בחבילות:

  • חשוב להשתמש בשמות ייחודיים לחבילות פרטיות כדי שלא יהיו זהים לשמות של חבילות ב-pypi.org, במיוחד אם ההגדרה של pip כוללת כמה אינדקסים של חבילות.
  • מספרי הגרסאות של החבילות צריכים להיות בהתאם למפרט של מזהה הגרסה ב-PEP 440. כברירת מחדל, pip מתקין רק גרסאות יציבות. הוא משתמש במפרט של מזהה הגרסה כדי להבחין בין גרסאות יציבות לבין גרסאות טרום-השקה, וכדי לנתח את הדרישות להתקנת הגרסה.

כדי להוסיף חבילה:

  1. מתקינים את Twine.

    pip install twine

  2. עוברים לספריית פרויקט Python.

  3. מעלים את קובצי ההפצה למאגר מהספרייה dist שנמצאת מתחת לספריית הפרויקט. מריצים את הפקודה הבאה:

    twine upload dist/*

    אפשר לציין מאגר מסוים באמצעות הדגל --repository-url.

    twine upload --repository-url https://LOCATION-python.pkg.dev/PROJECT/REPOSITORY/ dist/*

צפייה בחבילות ובגרסאות

מצבי מאגר: רגיל, מרוחק

כדי לראות את החבילות ואת גרסאות החבילות באמצעות Google Cloud המסוף או gcloud:

המסוף

  1. פותחים את הדף Repositories במסוף Google Cloud .

    פתיחת הדף Repositories

  2. ברשימת המאגרים, לוחצים על המאגר המתאים.

    בדף Packages (חבילות) מופיעה רשימת החבילות במאגר.

  3. לוחצים על חבילה כדי לראות את הגרסאות שלה.

gcloud

כדי להציג את רשימת החבילות במאגר, מריצים את הפקודה הבאה:

gcloud artifacts packages list [--repository=REPOSITORY] [--location=LOCATION]

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

  • ‫REPOSITORY הוא שם המאגר. אם הגדרתם מאגר ברירת מחדל, אתם יכולים להשמיט את הדגל הזה כדי להשתמש בברירת המחדל.
  • ‫ LOCATION הוא המיקום האזורי או המיקום במספר אזורים של המאגר. ‫ אם הגדרתם מיקום ברירת מחדל, תוכלו להשמיט את הדגל הזה כדי להשתמש בברירת המחדל.

כדי לראות את הגרסאות של חבילה, מריצים את הפקודה הבאה:

gcloud artifacts versions list --package=PACKAGE \
    [--repository=REPOSITORY] [--location=LOCATION]

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

  • ‫PACKAGE הוא המזהה של החבילה או המזהה המלא של החבילה.
  • ‫REPOSITORY הוא שם המאגר. אם הגדרתם מאגר ברירת מחדל, אתם יכולים להשמיט את הדגל הזה כדי להשתמש בברירת המחדל.
  • ‫ LOCATION הוא המיקום האזורי או המיקום במספר אזורים של המאגר. ‫ אפשר להשתמש בדגל הזה כדי להציג מאגרי מידע במיקום ספציפי. אם הגדרתם מיקום ברירת מחדל, אתם יכולים להשמיט את הדגל הזה כדי להשתמש בברירת המחדל.

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

מרכיב רשימת קבצים

מצבי מאגר: רגיל, מרוחק

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

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

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

gcloud artifacts files list

כדי לראות את רשימת הקבצים בפרויקט, במאגר ובמיקום שצוינו, מריצים את הפקודה:

gcloud artifacts files list \
    --project=PROJECT \
    --repository=REPOSITORY \
    --location=LOCATION

כדי להציג רשימה של קבצים לכל הגרסאות של חבילה מסוימת:

gcloud artifacts files list \
    --project=PROJECT \
    --repository=REPOSITORY \
    --location=LOCATION \
    --package=PACKAGE

כדי להציג רשימה של קבצים בגרסה ספציפית של חבילה:

gcloud artifacts files list \
    --project=PROJECT \
    --repository=REPOSITORY \
    --location=LOCATION \
    --package=PACKAGE \
    --version=VERSION

מחליפים את הערכים הבאים:

  • ‫LOCATION: המיקום האזורי או הרב-אזורי של המאגר.
  • ‫PROJECT: Google Cloud מזהה הפרויקט. אם מזהה הפרויקט מכיל נקודתיים (:), כדאי לעיין במאמר בנושא פרויקטים בהיקף הדומיין.
  • ‫REPOSITORY: השם של המאגר שבו התמונה מאוחסנת.
  • ‫PACKAGE: שם החבילה.
  • ‫VERSION: הגרסה של החבילה.

דוגמאות

כדאי לעיין בפרטי החבילה הבאים:

  • פרויקט: my-project
  • מאגר: my-repo
  • מיקום המאגר: us-west1
  • חבילה: my-app

הפקודה הבאה מציגה רשימה של כל הקבצים במאגר my-repo במיקום us-west1 בתוך פרויקט ברירת המחדל:

‫
gcloud artifacts files list \
    --location=us-west1 \
    --repository=my-repo
הפקודה הבאה מציגה רשימה של קבצים בגרסה 1.0 של החבילה.

gcloud artifacts files list \
    --project=my-project \
    --location=us-west1 \
    --repository=my-repo \
    --package=my-app \
    --version=1.0

התקנת חבילות

מצבי מאגר: רגיל, מרוחק, וירטואלי

משתמשים בפקודה pip כדי להתקין חבילות.

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

pip install PACKAGE

במאגרי מידע רגילים, מורידים חבילה ישירות ממאגר המידע.

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

במאגר וירטואלי, מערכת Artifact Registry מחפשת את החבילה המבוקשת במאגרים במעלה הזרם.

  • מאגרי מידע מרוחקים במעלה הזרם יורידו את החבילה המבוקשת וישמרו אותה במטמון אם לא קיים עותק במטמון. מאגרים וירטואליים מציגים רק חבילות מבוקשות, ולא מאחסנים אותן.
  • אם מבקשים גרסה שזמינה ביותר ממאגר אחד במעלה הזרם, Artifact Registry בוחר מאגר במעלה הזרם לשימוש על סמך הגדרות העדיפות שהוגדרו למאגר הווירטואלי.

לדוגמה, נניח שיש מאגר וירטואלי עם הגדרות העדיפות הבאות למאגרי upstream:

  • ‫main-repo: העדיפות מוגדרת ל-100
  • secondary-repo1: העדיפות מוגדרת ל-80.
  • secondary-repo2: העדיפות מוגדרת ל-80.
  • test-repo: העדיפות מוגדרת ל-20.

ל-main-repo יש את ערך העדיפות הגבוה ביותר, ולכן המאגר הווירטואלי תמיד מחפש בו קודם.

העדיפות של secondary-repo1 ושל secondary-repo2 מוגדרת כ80. אם חבילה מבוקשת לא זמינה ב-main-repo, ‏ Artifact Registry מחפש אותה במאגרים האלה. מכיוון שלשני המאגרים יש אותו ערך עדיפות, אם הגרסה זמינה בשניהם, Artifact Registry יכול לבחור להציג חבילה מכל אחד מהם.

ל-test-repo יש את ערך העדיפות הנמוך ביותר, והוא יציג פריט מאוחסן אם הוא לא נמצא באף אחד ממאגרי המידע האחרים במעלה הזרם.

מידע נוסף

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

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

pip install --pre PACKAGE

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

לדוגמה, הפקודה הזו מציינת שהגרסה המינימלית של my-package היא גרסת הפיתוח 1.0.dev0.

pip install --pre my-package>=1.0.dev0

גרסאות יציבות נחשבות חדשות יותר מגרסאות טרום-הפצה, ולכן אם גרסה 1.0 נמצאת במאגר, pip יבחר בגרסה 1.0 ולא בגרסת טרום-הפצה.

אם לא מציינים מאגר, הגדרת ה-pip ב-pip.conf קובעת איך pip מחפש את החבילה.

  • אם הגדרתם את מאגר Artifact Registry באמצעות ההגדרה index-url ולא הגדרתם אינדקסים אחרים של חבילות, pip יחפש את החבילה רק במאגר Artifact Registry.
  • אם אתם משתמשים במאגר וירטואלי, מערכת Artifact Registry משתמשת בעדיפויות שהוגדרו במדיניות של מאגרים במעלה הזרם כדי לבחור חבילה, אם בכמה מאגרים במעלה הזרם יש את גרסת החבילה המבוקשת. אם לשני מאגרי מידע עם החבילה יש אותה עדיפות, Artifact Registry יציג אותה מכל אחד מהמאגרים.
  • אם הגדרתם את pip עם ההגדרה extra-index-url או אם הגדרתם כמה אינדקסים של חבילות, pip יחפש ב-pypi.org ובכל אינדקס אחר של חבילות שהגדרתם, ויבחר את הגרסה האחרונה של החבילה.

אפשר לבטל את ההגדרות של index-url או extra-index-url בקובץ הדרישות. אפשר גם להשתמש בדגלים להגדרות האלה בפקודת pip. לדוגמה, הפקודה הזו מחליפה את index-url במאגר Artifact Registry.

pip install --index-url https://us-east1-python.pkg.dev/my-project/python-repo/simple/ my-package

מידע נוסף על התקנת חבילות זמין במאמרי העזרה בנושא Python Packaging.

מחיקת חבילות וגרסאות

מצבי מאגר: רגיל, מרוחק

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

  • אחרי שמוחקים חבילה, אי אפשר לבטל את הפעולה.
  • עבור מאגרי מידע מרוחקים, רק העותק שבמטמון של החבילה נמחק. אין השפעה על מקור הנתונים במעלה הזרם. אם מוחקים חבילה ששמורה במטמון, Artifact Registry יוריד אותה וישמור אותה במטמון שוב בפעם הבאה שהמאגר יקבל בקשה לאותה גרסת חבילה.

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

כדי למחוק חבילה:

המסוף

  1. פותחים את הדף Repositories במסוף Google Cloud .

    פתיחת הדף Repositories

  2. ברשימת המאגרים, לוחצים על המאגר המתאים.

    בדף Packages (חבילות) מופיעה רשימת החבילות במאגר.

  3. בוחרים את החבילה שרוצים למחוק.

  4. לוחצים על מחיקה.

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

gcloud

מריצים את הפקודה הבאה:

gcloud artifacts packages delete PACKAGE \
    [--repository=REPOSITORY] [--location=LOCATION] [--async]

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

  • ‫PACKAGE הוא שם החבילה במאגר.
  • ‫REPOSITORY הוא שם המאגר. אם הגדרתם מאגר ברירת מחדל, תוכלו להשמיט את הדגל הזה כדי להשתמש בברירת המחדל.
  • ‫ LOCATION הוא המיקום האזורי או המיקום במספר אזורים של המאגר. ‫ אפשר להשתמש בדגל הזה כדי להציג מאגרי מידע במיקום ספציפי. אם הגדרתם מיקום ברירת מחדל, אתם יכולים להשמיט את הדגל הזה כדי להשתמש בברירת המחדל.

הדגל --async גורם לפקודה לחזור באופן מיידי, בלי להמתין שהפעולה תסתיים.

כדי למחוק גרסאות של חבילה:

המסוף

  1. פותחים את הדף Repositories במסוף Google Cloud .

    פתיחת הדף Repositories

  2. ברשימת המאגרים, לוחצים על המאגר המתאים.

    בדף Packages (חבילות) מופיעה רשימת החבילות במאגר.

  3. לוחצים על חבילה כדי לראות את הגרסאות שלה.

  4. בוחרים את הגרסאות שרוצים למחוק.

  5. לוחצים על מחיקה.

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

gcloud

מריצים את הפקודה הבאה:

gcloud artifacts versions delete VERSION \
    --package=PACKAGE \
    [--repository=REPOSITORY] [--location=LOCATION] \
    [--async]

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

  • ‫VERSION הוא שם הגרסה שרוצים למחוק.
  • ‫PACKAGE הוא שם החבילה במאגר.
  • ‫REPOSITORY הוא שם המאגר. אם הגדרתם מאגר ברירת מחדל, תוכלו להשמיט את הדגל הזה כדי להשתמש בברירת המחדל.
  • ‫ LOCATION הוא המיקום האזורי או המיקום במספר אזורים של המאגר. ‫ אפשר להשתמש בדגל הזה כדי להציג מאגרי מידע במיקום ספציפי. אם הגדרתם מיקום ברירת מחדל, אתם יכולים להשמיט את הדגל הזה כדי להשתמש בברירת המחדל.

הדגל --async גורם לפקודה לחזור באופן מיידי, בלי להמתין שהפעולה תסתיים.

המאמרים הבאים