Nesta página, descrevemos como adicionar, visualizar e excluir pacotes e versões de pacotes do Python.
Antes de começar
Instale e initialize a Google Cloud CLI.
A Google Cloud CLI versão 354.0.0 ou mais recente é necessária para executar comandos para repositórios do Python. Verifique a versão com o comando:
gcloud version
Se o repositório de destino não existir, crie um novo repositório de pacotes do Python.
Verifique se o Python 3 está instalado. Para instruções de instalação, consulte o tutorial de configuração do Python do Google Cloud.
(Opcional) Configure padrões para comandos gcloud.
Se você estiver usando a autenticação de keyring com credenciais da gcloud, faça login na Google Cloud CLI com sua conta de usuário ou de serviço.
Funções exigidas
Para receber as permissões necessárias para gerenciar pacotes, peça ao administrador para conceder a você os seguintes papéis do IAM no repositório:
-
Visualizar pacotes ou arquivos em pacotes:
Leitor do Artifact Registry (
roles/artifactregistry.reader
) -
Faça o download ou instale os pacotes:
Leitor do Artifact Registry (
roles/artifactregistry.reader
) -
Adicione pacotes a um repositório:
Gravador do Artifact Registry (
roles/artifactregistry.writer
) -
Excluir pacotes:
Administrador de repositórios do Artifact Registry (
roles/artifactregistry.repoAdmin
)
Para mais informações sobre como conceder papéis, consulte Gerenciar acesso.
Também é possível conseguir as permissões necessárias por meio de papéis personalizados ou de outros papéis predefinidos.
Como adicionar pacotes
Modos de repositório:padrão
Ao criar um projeto em Python, os arquivos de distribuição são salvos em um subdiretório dist
no seu projeto. Em seguida, use o Twine para fazer upload de pacotes para um
repositório padrão.
Recomendamos as seguintes práticas para seus pacotes:
- Use nomes exclusivos para os pacotes privados, de modo que não correspondam aos nomes dos pacotes em pypi.org, especialmente se a configuração de pip incluir vários índices de pacotes.
- Use a especificação do identificador de versão na PEP 440 para os números de versão do pacote. Por padrão, o pip instala somente versões estáveis. Ele usa a especificação do identificador de versão para distinguir versões estáveis de versões de pré-lançamento e analisar requisitos para que a versão seja instalada.
Para adicionar um pacote:
Instale o Twine.
pip install twine
Mude para o diretório do projeto em Python.
Faça upload dos arquivos de distribuição para o repositório do subdiretório do projeto
dist
. Execute este comando:twine upload dist/*
Especifique um repositório específico com a sinalização
--repository-url
.twine upload --repository-url https://LOCATION-python.pkg.dev/PROJECT/REPOSITORY/ dist/*
Como visualizar pacotes e versões
Modos de repositório:padrão e remoto
Para visualizar pacotes e versões usando o console do Google Cloud
ou gcloud
:
Console
Abra a página Repositórios no console do Google Cloud.
Na lista de repositórios, clique no repositório apropriado.
A página Pacotes lista os pacotes no repositório.
Clique em um pacote para visualizar as versões dele.
gcloud
Para listar pacotes em um repositório, execute o seguinte comando:
gcloud artifacts packages list [--repository=REPOSITORY] [--location=LOCATION]
Por
- REPOSITORY é o nome do repositório. Se você tiver configurado um repositório padrão, você pode omitir essa sinalização para usar o padrão.
- LOCATION é um local regional ou multirregional. Use esta sinalização para ver repositórios em um local específico. Se você tiver configurado um local padrão, poderá omitir essa sinalização para usar o padrão.
Para ver as versões de um pacote, execute o seguinte comando:
gcloud artifacts versions list --package=PACKAGE \
[--repository=REPOSITORY] [--location=LOCATION]
Onde
- PACKAGE é o ID do pacote ou o identificador totalmente qualificado do pacote.
- REPOSITORY é o nome do repositório. Se você tiver configurado um repositório padrão, você pode omitir essa sinalização para usar o padrão.
- LOCATION é um local regional ou multirregional. Use esta sinalização para ver repositórios em um local específico. Se você tiver configurado um local padrão, poderá omitir essa sinalização para usar o padrão.
Para repositórios remotos, a lista retornada precisa incluir todas as dependências diretas e transitivas.
Como listar arquivos
Modos de repositório:padrão e remoto
É possível listar arquivos em um repositório, arquivos em todas as versões de um pacote especificado ou arquivos em uma versão específica de um pacote.
Para todos os comandos a seguir, defina um número máximo de arquivos a serem retornados
adicionando a sinalização --limit
ao comando.
Para listar todos os arquivos do projeto, do repositório e do local padrão quando os valores padrão estiverem configurados:
gcloud artifacts files list
Para listar arquivos em um projeto, repositório e local especificados, execute o comando:
gcloud artifacts files list \
--project=PROJECT \
--repository=REPOSITORY \
--location=LOCATION
Para listar os arquivos de todas as versões de um pacote específico:
gcloud artifacts files list \
--project=PROJECT \
--repository=REPOSITORY \
--location=LOCATION \
--package=PACKAGE
Para listar arquivos de uma versão específica do pacote:
gcloud artifacts files list \
--project=PROJECT \
--repository=REPOSITORY \
--location=LOCATION \
--package=PACKAGE \
--version=VERSION
Substitua os seguintes valores:
LOCATION
é o local regional ou multirregional do repositório.PROJECT
: seuID de projeto no Google Cloud. Caso o ID do projeto contenha dois pontos (:
), consulte Projetos com escopo de domínio.REPOSITORY
: o nome do repositório em que a imagem está armazenada.PACKAGE
: o nome do pacote.VERSION
: a versão do pacote.
Examples
Considere as seguintes informações do pacote:
- Projeto:
my-project
- Repositório:
my-repo
- Local do repositório:
us-central1
- Pacote:
my-app
O comando a seguir lista todos os arquivos no repositório my-repo
no
local us-central1
dentro do projeto padrão:
gcloud artifacts files list \
--location=us-central1 \
--repository=my-repo
O comando a seguir lista os arquivos na versão 1.0
do pacote.
gcloud artifacts files list \
--project=my-project \
--location=us-central1 \
--repository=my-repo \
--package=my-app \
--version=1.0
Como instalar pacotes
Modos de repositório:padrão, remoto e virtual
Use o comando pip
para instalar pacotes.
Para instalar a versão estável mais recente de um pacote, execute o comando:
pip install PACKAGE
Para repositórios padrão, faça o download de um pacote diretamente do repositório.
Para um repositório remoto, faça o download de uma cópia armazenada em cache do pacote e das dependências dele. Se não houver uma cópia em cache, o repositório remoto fará o download do pacote da origem upstream e o armazenará em cache antes de disponibilizá-lo para você. Você pode verificar se o repositório remoto recuperou os pacotes da origem upstream visualizando a lista de pacotes no repositório.
Para um repositório virtual, o Artifact Registry pesquisa repositórios upstream para o pacote solicitado.
- Os repositórios remotos upstream fazem o download e armazenam o pacote solicitado se não houver uma cópia em cache. Os repositórios virtuais só disponibilizam os pacotes solicitados, eles não os armazenam.
- Se você solicitar uma versão disponível em mais de um repositório upstream, o Artifact Registry escolherá um repositório upstream para usar com base nas configurações de prioridade definidas para o repositório virtual.
Por exemplo, considere um repositório virtual com as seguintes configurações de prioridade para repositórios upstream:
main-repo
: a prioridade foi definida como100
secondary-repo1
: a prioridade foi definida como80
.secondary-repo2
: a prioridade foi definida como80
.test-repo
: a prioridade foi definida como20
.
main-repo
tem o valor de prioridade mais alto. Portanto, o repositório virtual
sempre o pesquisa primeiro.
Tanto secondary-repo1
quanto secondary-repo2
têm prioridade definida como 80
. Se um
pacote solicitado não estiver disponível em main-repo
, o Artifact Registry
vai pesquisar esses repositórios em seguida. Como ambos têm o mesmo valor de prioridade,
o Artifact Registry pode disponibilizar um pacote de qualquer um dos repositórios
se a versão estiver disponível em ambos.
test-repo
tem o menor valor de prioridade e exibirá um artefato armazenado se
nenhum dos outros repositórios upstream o tiver.
Mais informações
Por padrão, o pip instala versões estáveis de um pacote e ignora as versões de pré-lançamento. A PEP 440 define a especificação do identificador da versão do Python que encaminha os usuários para analisar números de versão, incluindo versões de pré-lançamento.
Para incluir versões de pré-lançamento quando o pip procurar um pacote para instalar, use a sinalização --pre
ao seu comando.
pip install --pre PACKAGE
Para definir uma versão ou um intervalo de versões necessários, inclua um especificador de requisito. É possível incluir o requisito da versão diretamente no comando ou usar um arquivo de requisitos.
Por exemplo, este comando especifica que a versão mínima de my-package
é
a versão de desenvolvimento 1.0.dev0
.
pip install --pre my-package>=1.0.dev0
Versões estáveis são consideradas mais recentes que as de pré-lançamento. Portanto, se a versão 1.0
estiver no repositório, o pip escolherá a versão 1.0
em vez de uma versão de pré-lançamento.
Se você não especificar um repositório, a configuração do pip em pip.conf
determinará como o pip pesquisa o pacote.
- Se você tiver configurado o repositório do Artifact Registry com a configuração
index-url
e nenhum outro índice de pacote estiver configurado, o pip só procurará no repositório do Artifact Registry pelo pacote. - Se você estiver usando um repositório virtual, o Artifact Registry usará as prioridades configuradas na política upstream para escolher um pacote quando vários repositórios upstream tiverem a versão do pacote solicitada. Se dois repositórios com o pacote tiverem a mesma prioridade, o Artifact Registry o disponibilizará em qualquer um dos repositórios.
- Se você configurou o pip com a configuração
extra-index-url
ou configurou vários índices de pacote, o pip pesquisará pypi.org e quaisquer outros índices de pacote configurados e escolherá a versão mais recente do pacote.
É possível substituir as configurações index-url
ou extra-index-url
no arquivo requisitos. Você também
pode usar flags para essas configurações no comando pip. Por exemplo, este comando
substitui index-url
por um repositório do Artifact Registry.
pip install --index-url https://us-east1-python.pkg.dev/my-project/python-repo/simple/ my-package
Para mais informações sobre como instalar pacotes, consulte a documentação de empacotamento do Python (em inglês).
Como excluir pacotes e versões
Modos de repositório:padrão e remoto
É possível excluir um pacote e todas as versões dele ou uma versão específica.
- Depois de excluir um pacote, não é possível desfazer a ação.
- No caso de repositórios remotos, somente a cópia em cache do pacote é excluída. A origem upstream não é afetada. Se você excluir um pacote armazenado em cache, o Artifact Registry fará o download e o armazenará em cache novamente na próxima vez que o repositório receber uma solicitação para essa mesma versão do pacote.
Antes de excluir uma versão de pacote ou um pacote, verifique se você comunicou ou resolveu qualquer dependência importante nele.
Para excluir um pacote:
Console
Abra a página Repositórios no console do Google Cloud.
Na lista de repositórios, clique no repositório apropriado.
A página Pacotes lista os pacotes no repositório.
Selecione o pacote que você quer excluir.
Clique em EXCLUIR.
Na caixa de diálogo de confirmação, clique em Excluir.
gcloud
Execute este comando:
gcloud artifacts packages delete PACKAGE \
[--repository=REPOSITORY] [--location=LOCATION] [--async]
Por
- PACKAGE é o nome do pacote no repositório.
- REPOSITORY é o nome do repositório. Se você tiver configurado um repositório padrão, você pode omitir essa sinalização para usar o padrão.
- LOCATION é um local regional ou multirregional. Use esta sinalização para ver repositórios em um local específico. Se você tiver configurado um local padrão, poderá omitir essa sinalização para usar o padrão.
--async
Retorna imediatamente, sem aguardar a conclusão da operação em andamento.
Para excluir versões de um pacote:
Console
Abra a página Repositórios no console do Google Cloud.
Na lista de repositórios, clique no repositório apropriado.
A página Pacotes lista os pacotes no repositório.
Clique em um pacote para visualizar as versões dele.
Selecione as versões que você quer excluir.
Clique em EXCLUIR.
Na caixa de diálogo de confirmação, clique em Excluir.
gcloud
Execute este comando:
gcloud artifacts versions delete VERSION \
--package=PACKAGE \
[--repository=REPOSITORY] [--location=LOCATION] \
[--async]
Por
- PACKAGE é o nome do pacote no repositório.
- REPOSITORY é o nome do repositório. Se você tiver configurado um repositório padrão, você pode omitir essa sinalização para usar o padrão.
- LOCATION é um local regional ou multirregional. Use esta sinalização para ver repositórios em um local específico. Se você tiver configurado um local padrão, poderá omitir essa sinalização para usar o padrão.
--async
retorna imediatamente, sem aguardar a conclusão da operação em andamento.
A seguir
- Saiba mais sobre como gerenciar pacotes Java
- Saiba mais sobre como gerenciar pacotes do Node.js.
- Saiba mais sobre o gerenciamento de imagens de contêiner
- Fazer o download de arquivos individuais em um pacote