Gestire i pacchetti Python

Questa pagina descrive come aggiungere, visualizzare ed eliminare pacchetti e versioni di pacchetti Python.

Prima di iniziare

  1. Installa e inizializza il Google Cloud CLI.

    Per eseguire comandi per i repository Python è necessaria la versione 354.0.0 o successive di Google Cloud CLI. Puoi controllare la versione con il comando:

    gcloud version

  2. Se il repository di destinazione non esiste, creando un nuovo repository di pacchetti Python.

  3. Verifica che Python 3 sia installato. Per istruzioni sull'installazione, consulta Tutorial di Google Cloud per la configurazione di Python.

  4. (Facoltativo) Configura i valori predefiniti per i comandi gcloud.

  5. Se utilizzi l'autenticazione tramite keyring con credenziali gcloud, accedi a Google Cloud CLI con il tuo account utente oppure l'account di servizio.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per gestire i pacchetti, chiedi all'amministratore di concederti seguenti ruoli IAM sul repository:

Per saperne di più sulla concessione dei ruoli, consulta Gestire l'accesso a progetti, cartelle e organizzazioni.

Potresti anche riuscire a ottenere le autorizzazioni richieste tramite la ruoli o altri ruoli predefiniti ruoli.

Aggiunta di pacchetti

Modalità repository: standard

Quando crei un progetto Python, i file di distribuzione vengono salvati in un percorso dist nel tuo progetto. Puoi quindi utilizzare Twine per caricare i pacchetti su un un repository standard.

Consigliamo le seguenti best practice per i pacchetti:

  • Utilizza nomi univoci per i pacchetti privati in modo che non corrispondano ai nomi dei pacchetti su pypi.org, in particolare se la configurazione di pip include più indici dei pacchetti.
  • Utilizza la specifica dell'identificatore di versione in PEP 440 per i numeri di versione del pacchetto. Per impostazione predefinita, pip installa solo le release stabili. Usa la specifica degli identificatori di versione per distinguere le versioni stabili dalle versioni pre-release e per analizzare eventuali requisiti per la versione da installare.

Per aggiungere un pacchetto:

  1. Installa Twine.

    pip install twine

  2. Passa alla directory del progetto Python.

  3. Carica i file di distribuzione nel repository dal progetto dist nella sottodirectory. Esegui questo comando:

    twine upload dist/*

    Puoi specificare un determinato repository con il flag --repository-url.

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

Visualizzazione di pacchetti e versioni

Modalità repository: standard, remota

Visualizzazione di pacchetti e versioni dei pacchetti utilizzando la console Google Cloud o gcloud:

Console

  1. Apri la pagina Repository nella console Google Cloud.

    Apri la pagina Repository

  2. Nell'elenco dei repository, fai clic sul repository appropriato.

    La pagina Pacchetti elenca i pacchetti presenti nel repository.

  3. Fai clic su un pacchetto per visualizzare le sue versioni.

gcloud

Per elencare i pacchetti contenuti in un repository, esegui questo comando:

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

Dove

  • REPOSITORY è il nome del repository. Se hai configurato un repository predefinito, puoi omettere questo flag per utilizzare quello predefinito.
  • LOCATION è un una o più regioni località. Utilizza questo flag per visualizzare i repository in una posizione specifica. Se configurato una località predefinita, puoi omettere questo flag per utilizzare per impostazione predefinita.

Per visualizzare le versioni di un pacchetto, esegui il comando seguente:

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

Dove

  • PACKAGE è l'ID del pacchetto o dell'identificatore completo per il pacchetto.
  • REPOSITORY è il nome del repository. Se hai configurato un repository predefinito, puoi omettere questo flag per utilizzare quello predefinito.
  • LOCATION è un una o più regioni località. Utilizza questo flag per visualizzare i repository in una posizione specifica. Se hai configurato una posizione predefinita, puoi omettere questo flag per utilizzare la posizione predefinita.

Per i repository remoti, l'elenco restituito deve includere tutti i repository diretti e e le dipendenze transitive.

File della scheda

Modalità del repository: standard, remoto

Puoi elencare i file in un repository, in tutte le versioni di un pacchetto specificato o in una versione specifica di un pacchetto.

Per tutti i comandi seguenti, puoi impostare un numero massimo di file da restituire aggiungendo il flag --limit al comando.

Per elencare tutti i file nel progetto, nel repository e posizione quando sono configurati i valori predefiniti:

gcloud artifacts files list

Per elencare i file in un progetto, un repository e una posizione specifici, esegui il comando:

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

Per elencare i file di tutte le versioni di un pacchetto specifico:

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

Per elencare i file di una versione specifica del pacchetto:

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

Sostituisci i seguenti valori:

  • LOCATION: il una o più regioni località del repository.
  • PROJECT: il tuo ID progetto Google Cloud. Se l'ID progetto contiene i due punti (":"), vedi Progetti con ambito dominio.
  • REPOSITORY: il nome del repository in cui è stata creata l'immagine viene archiviato.
  • PACKAGE: il nome del pacchetto.
  • VERSION: la versione del pacchetto.

Esempi

Considera le seguenti informazioni sul pacchetto:

  • Progetto: my-project
  • Repository: my-repo
  • Posizione del repository: us-west1
  • Pacco: my-app

Il comando seguente elenca tutti i file del repository my-repo nella località us-west1 all'interno del progetto predefinito:

gcloud artifacts files list \
    --location=us-west1 \
    --repository=my-repo
Il seguente comando elenca i file nella versione 1.0 del pacchetto.

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

Installazione dei pacchetti

Modalità del repository: standard, remoto, virtuale

Utilizza il comando pip per installare i pacchetti.

Per installare la release stabile più recente di un pacchetto, esegui il comando:

pip install PACKAGE

Per i repository standard, scarichi un pacchetto direttamente dal repository.

Per un repository remoto, scarichi una copia memorizzata nella cache del pacchetto e delle sue dipendenze. Se non esiste una copia memorizzata nella cache, il repository remoto scarica il pacchetto dall'origine upstream e lo memorizza nella cache prima di fornirtelo. Puoi verificare che il repository remoto abbia recuperato i pacchetti dall'origine upstream visualizzando l'elenco dei pacchetti nel repository.

Per un repository virtuale, Artifact Registry cerca nei repository upstream per il pacchetto richiesto.

  • I repository remoti upstream scaricheranno e memorizzeranno nella cache il pacchetto richiesto se non esiste una copia memorizzata nella cache. I repository virtuali pubblicano solo i pacchetti richiesti, non li archiviano.
  • Se richiedi una versione disponibile in più di un repository upstream, Artifact Registry sceglie un repository upstream da utilizzare in base alle impostazioni di priorità configurate per il repository virtuale.

Ad esempio, considera un repository virtuale con le seguenti impostazioni di priorità per i repository upstream:

  • main-repo: priorità impostata su 100
  • secondary-repo1: priorità impostata su 80.
  • secondary-repo2: priorità impostata su 80.
  • test-repo: priorità impostata su 20.

main-repo ha il valore di priorità più alto, quindi il repository virtuale lo cerca sempre per primo.

Sia secondary-repo1 che secondary-repo2 hanno la priorità impostata su 80. Se il pacchetto richiesto non è disponibile in main-repo, Artifact Registry a cercare successivamente questi repository. Poiché entrambi hanno lo stesso valore di priorità, Artifact Registry può scegliere di gestire un pacchetto da entrambi i repository se la versione è disponibile in entrambi.

test-repo ha il valore di priorità più basso e pubblicherà un artefatto archiviato se ma nessuno degli altri repository upstream lo contiene.

Informazioni aggiuntive

Per impostazione predefinita, pip installa le versioni stabili di un pacchetto e ignora le versioni pre-release. PEP 440 definisce la specifica dell'identificatore della versione di Python che consente agli utenti di pip di analizzare i numeri di versione, incluse le versioni pre-release.

Per includere versioni di pre-release quando pip cerca un pacchetto da installare, il flag --pre al tuo comando.

pip install --pre PACKAGE

Per specificare una versione o un intervallo di versioni richiesto, includi un di controllo dei requisiti. Puoi includere il requisito della versione direttamente nel comando o utilizzare un file dei requisiti.

Ad esempio, questo comando specifica che la versione minima di my-package è versione di sviluppo 1.0.dev0.

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

Le release stabili sono considerate più recenti delle pre-release, quindi se la versione 1.0 è nel repository, pip sceglierà la versione 1.0 rispetto a una pre-release.

Se non specifichi un repository, la tua configurazione pip in pip.conf determina il modo in cui pip cerca il pacchetto.

  • Se hai configurato il repository Artifact Registry con l'impostazione index-url e non sono configurati altri indici dei pacchetti, pip cerca il pacchetto solo nel repository Artifact Registry.
  • Se utilizzi un repository virtuale, Artifact Registry utilizza il metodo priorità configurate nel criterio upstream per scegliere un pacchetto quando più repository upstream hanno la versione del pacchetto richiesta. Se due repository con il pacchetto hanno la stessa priorità, Artifact Registry lo serve da entrambi i repository.
  • Se hai configurato pip con l'impostazione extra-index-url o se hai configurato più indici di pacchetti, ricerche pip pypi.org e tutti gli altri account indicizza i pacchetti e sceglie la versione più recente del pacchetto.

Puoi sostituire le impostazioni index-url o extra-index-url nel file requirements. Puoi anche utilizzare i flag per queste impostazioni nel comando pip. Ad esempio, questo comando esegue l'override di index-url con un repository Artifact Registry.

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

Per ulteriori informazioni sull'installazione di pacchetti, consulta la documentazione relativa al pacchetto Python.

Eliminazione di pacchetti e versioni

Modalità repository: standard, remota

Puoi eliminare un pacchetto e tutte le sue versioni oppure una versione specifica.

  • Una volta eliminato un pacchetto, non puoi annullare l'azione.
  • Per i repository remoti, viene eliminata solo la copia memorizzata nella cache del pacchetto. La l'origine upstream non è interessata. Se elimini un pacchetto memorizzato nella cache, Artifact Registry lo scaricherà e lo memorizzerà di nuovo nella cache la prossima volta che il repository riceverà una richiesta per la stessa versione del pacchetto.

Prima di eliminare un pacchetto o una versione del pacchetto, verifica di avere che abbia comunicato o gestito eventuali dipendenze importanti.

Per eliminare un pacchetto:

Console

  1. Apri la pagina Repository nella console Google Cloud.

    Apri la pagina Repository

  2. Nell'elenco dei repository, fai clic sul repository appropriato.

    La pagina Pacchetti elenca i pacchetti nel repository.

  3. Seleziona il pacchetto da eliminare.

  4. Fai clic su ELIMINA.

  5. Nella finestra di dialogo di conferma, fai clic su ELIMINA.

gcloud

Esegui questo comando:

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

Dove

  • PACKAGE è il nome del pacchetto nel repository.
  • REPOSITORY è il nome del repository. Se hai configurato un repository predefinito, puoi omettere questo flag per utilizzare quello predefinito.
  • LOCATION è un una o più regioni località. Utilizza questo flag per visualizzare i repository in una posizione specifica. Se configurato una località predefinita, puoi omettere questo flag per utilizzare per impostazione predefinita.
  • --async Torna immediatamente senza attendere il completamento dell'operazione in corso.

Per eliminare le versioni di un pacchetto:

Console

  1. Apri la pagina Repository nella console Google Cloud.

    Apri la pagina Repository

  2. Nell'elenco dei repository, fai clic sul repository appropriato.

    La pagina Pacchetti elenca i pacchetti presenti nel repository.

  3. Fai clic su un pacchetto per visualizzarne le versioni.

  4. Seleziona le versioni da eliminare.

  5. Fai clic su ELIMINA.

  6. Nella finestra di dialogo di conferma, fai clic su ELIMINA.

gcloud

Esegui questo comando:

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

Dove

  • PACKAGE è il nome del pacchetto nel repository.
  • REPOSITORY è il nome del repository. Se hai configurato default, puoi omettere questo flag per utilizzare il repository predefinito.
  • LOCATION è un una o più regioni località. Utilizza questo flag per visualizzare i repository in una posizione specifica. Se hai configurato una posizione predefinita, puoi omettere questo flag per utilizzare la posizione predefinita.
  • --async restituisce immediatamente il valore, senza attendere il completamento dell'operazione in corso.

Passaggi successivi