Gestire i pacchetti Python

Questa pagina descrive l'aggiunta, la visualizzazione e l'eliminazione di pacchetti Python e versioni dei pacchetti.

Prima di iniziare

1. Installa e inizializza Google Cloud CLI.

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

   gcloud version
   

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

3. Verifica che Python 3 sia installato. Per le istruzioni di installazione, consulta ilGoogle Cloud tutorial per la configurazione di Python.

4. (Facoltativo) Configura le impostazioni predefinite per i comandi gcloud.

5. Se utilizzi l'autenticazione del portachiavi con le credenziali gcloud, accedi a Google Cloud CLI con il tuo account utente o account di servizio.

Ruoli obbligatori

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

• Visualizza pacchetti o file nei pacchetti: Lettore Artifact Registry (roles/artifactregistry.reader)
• Scarica o installa pacchetti: Artifact Registry Reader (roles/artifactregistry.reader)
• Aggiungi pacchetti a un repository: Scrittore Artifact Registry (roles/artifactregistry.writer)
• Elimina pacchetti: Amministratore repository Artifact Registry (roles/artifactregistry.repoAdmin)

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

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

Aggiunta di pacchetti

Modalità repository: standard

Quando crei un progetto Python, i file di distribuzione vengono salvati in una sottodirectory dist del progetto. Puoi quindi utilizzare Twine per caricare i pacchetti in un repository standard.

Consigliamo le seguenti best practice per i tuoi pacchetti:

• Utilizza nomi univoci per i tuoi pacchetti privati in modo che non corrispondano ai nomi dei pacchetti su pypi.org, in particolare se la configurazione di pip include più indici di 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 versioni stabili. Utilizza la specifica dell'identificatore 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 dalla sottodirectory dist del progetto. Esegui questo comando:

   twine upload dist/*
   

   Puoi specificare un repository particolare 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, remoto

Per visualizzare i pacchetti e le relative versioni utilizzando la Google Cloud console o gcloud:

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

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

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

Elenco dei file

Modalità repository: standard, remoto

Puoi elencare i file in un repository, i file in tutte le versioni di un pacchetto specificato o i file 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 nella posizione predefiniti quando sono configurati i valori predefiniti:

gcloud artifacts files list

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

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

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

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

Per elencare i file per una versione specifica del pacchetto:

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

Sostituisci i seguenti valori:

• LOCATION: la posizione regionale o multiregionale del repository.
• PROJECT: il tuo Google Cloud ID progetto. Se l'ID progetto contiene due punti (:), consulta Progetti basati sul dominio.
• REPOSITORY: il nome del repository in cui è archiviata l'immagine.
• 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
• Pacchetto: my-app

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

gcloud artifacts files list \
    --location=us-west1 \
    --repository=my-repo

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

Installazione dei pacchetti

Modalità repository: standard, remoto, virtuale

Utilizza il comando pip per installare i pacchetti.

Per installare l'ultima release stabile 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 relative dipendenze. Se non esiste una copia memorizzata nella cache, il repository remoto scarica il pacchetto dalla sorgente upstream e lo memorizza nella cache prima di fornirtelo. Puoi verificare che il repository remoto abbia recuperato i pacchetti dalla sorgente upstream visualizzando l'elenco dei pacchetti nel repository.

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

• I repository remoti upstream scaricano e memorizzano nella cache il pacchetto richiesto se non esiste una copia memorizzata nella cache. I repository virtuali forniscono 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 un pacchetto richiesto non è disponibile in main-repo, Artifact Registry esegue la ricerca in questi repository. Poiché hanno lo stesso valore di priorità, Artifact Registry può scegliere di pubblicare un pacchetto da uno dei due repository se la versione è disponibile in entrambi.

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

Informazioni aggiuntive

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

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

pip install --pre PACKAGE

Per specificare una versione o un intervallo di versioni richiesti, includi uno specificatore dei requisiti. Puoi includere il requisito di versione direttamente nel comando o utilizzare un file dei requisiti.

Ad esempio, questo comando specifica che la versione minima di my-package è la 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 nel repository è presente la versione 1.0, pip sceglierà la versione 1.0 rispetto a una versione di pre-release.

Se non specifichi un repository, la configurazione di pip in pip.conf determina la modalità di ricerca del pacchetto.

• Se hai configurato il repository Artifact Registry con l'impostazione index-url e non sono configurati altri indici di pacchetti, pip cerca il pacchetto solo nel repository Artifact Registry.
• Se utilizzi un repository virtuale, Artifact Registry utilizza le priorità configurate nelle norme 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 pubblica da uno dei due repository.
• Se hai configurato pip con l'impostazione extra-index-url o se hai configurato più indici di pacchetti, pip cerca pypi.org e qualsiasi altro indice di pacchetti configurato e sceglie l'ultima versione del pacchetto.

Puoi ignorare le impostazioni index-url o extra-index-url nel file dei requisiti. Puoi anche utilizzare i flag per queste impostazioni nel comando pip. Ad esempio, questo comando sostituisce 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 saperne di più sull'installazione dei pacchetti, consulta la documentazione sul packaging di Python.

Eliminazione di pacchetti e versioni

Modalità repository: standard, remoto

Puoi eliminare un pacchetto e tutte le relative versioni oppure eliminare 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. L'origine a monte non è interessata. Se elimini un pacchetto memorizzato nella cache, Artifact Registry lo scaricherà e memorizzerà nuovamente nella cache la volta successiva che il repository riceve una richiesta per la stessa versione del pacchetto.

Prima di eliminare un pacchetto o una versione del pacchetto, verifica di aver comunicato o risolto eventuali dipendenze importanti.

Per eliminare un pacchetto:

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

Per eliminare le versioni di un pacchetto:

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

Passaggi successivi

• Scopri di più sulla gestione dei pacchetti Java
• Scopri di più sulla gestione dei pacchetti Node.js
• Scopri di più sulla gestione delle immagini container
• Scaricare singoli file all'interno di un pacchetto