28.2. "ensurepip" --- Inicialização do instalador "pip"
*******************************************************

Novo na versão 3.4.

======================================================================

O pacote "ensurepip" fornece suporte a fazer bootstrapping (isto é,
inicializar) o instalador "pip" em uma instalação existente do Python
ou em um ambiente virtual. Essa abordagem de bootstrapping reflete o
fato de que "pip" é um projeto independente com seu próprio ciclo de
lançamento, e a última versão estável disponível é fornecida com
manutenção e lançamentos de recursos do interpretador de referência
CPython.

Na maioria dos casos, os usuários finais do Python não precisam chamar
esse módulo diretamente (como "pip" deve ser inicializado por padrão),
mas pode ser necessário se a instalação do "pip" foi ignorada ao
instalar o Python (ou ao criar um ambiente virtual) ou após
desinstalar explicitamente "pip".

Nota:

  Este módulo *não* acessa a Internet. Todos os componentes
  necessários para iniciar o "pip" estão incluídos como partes
  internas do pacote.

Ver também:

  Instalando Módulos Python
     O guia do usuário final para instalar pacotes Python

  **PEP 453**: Inicialização explícita de pip em instalações Python
     A justificativa e especificação originais para este módulo.


28.2.1. Interface de linha de comando
=====================================

A interface da linha de comandos é chamada usando a opção "-m" do
interpretador.

A invocação mais simples possível é:

   python -m ensurepip

Essa invocação instalará "pip" se ainda não estiver instalada, mas,
caso contrário, não fará nada. Para garantir que a versão instalada do
"pip" seja pelo menos tão recente quanto a que acompanha o pacote
"ensurepip", passe a opção "--upgrade":

   python -m ensurepip --upgrade

Por padrão, "pip" é instalado no ambiente virtual atual (se houver um
ativo) ou nos pacotes de sites do sistema (se não houver um ambiente
virtual ativo). O local da instalação pode ser controlado através de
duas opções adicionais de linha de comando:

* "--root <dir>": Instala "pip" em relação ao diretório raiz
  fornecido, em vez da raiz do ambiente virtual atualmente ativo (se
  houver) ou a raiz padrão da instalação atual do Python.

* "--user": Instala "pip" no diretório de pacotes do site do usuário
  em vez de globalmente para a instalação atual do Python (essa opção
  não é permitida dentro de um ambiente virtual ativo).

Por padrão, os scripts "pipX" e "pipX.Y" serão instalados (onde X.Y
representa a versão do Python usada para invocar "ensurepip"). Os
scripts instalados podem ser controlados através de duas opções
adicionais de linha de comando:

* "--altinstall": se uma instalação alternativa for solicitada, o
  script "pipX" *não* será instalado.

* "--default-pip": se uma instalação "pip padrão" for solicitada, o
  script "pip" será instalado junto com os dois scripts comuns.
     "pip" script will be installed in addition to the two regular
     scripts.

Fornecer as duas opções de seleção de script acionará uma exceção.

Alterado na versão 3.6.3: The exit status is non-zero if the command
fails.


28.2.2. API do módulo
=====================

"ensurepip" expõe duas funções para uso programático:

ensurepip.version()

   Retorna uma sequência que especifica a versão em pacote do pip que
   será instalado ao inicializar um ambiente.

ensurepip.bootstrap(root=None, upgrade=False, user=False, altinstall=False, default_pip=False, verbosity=0)

   Inicializa "pip" no ambiente atual ou designado.

   *root* especifica um diretório raiz alternativo para instalar em
   relação a. Se *root* for "None", a instalação utilizará o local de
   instalação padrão para o ambiente atual.

   *upgrade* indica se deve ou não atualizar uma instalação existente
   de uma versão anterior do "pip" para a versão empacotada.

   *user* indica se é necessário usar o esquema do usuário em vez de
   instalar globalmente.

   Por padrão, os scripts "pipX" e "pipX.Y" serão instalados (onde X.Y
   significa a versão atual do Python).

   Se *altinstall* estiver definido, o "pipX" *não* será instalado.

   Se *default_pip* estiver definido, o "pip" será instalado além dos
   dois scripts comuns.

   Definir *altinstall* e *default_pip* acionará "ValueError".

   *verbosity* controla o nível de saída para "sys.stdout" da operação
   de inicialização.

   Nota:

     O processo de inicialização tem efeitos colaterais em "sys.path"
     e "os.environ". Invocar a interface da linha de comandos em um
     subprocesso permite que esses efeitos colaterais sejam evitados.

   Nota:

     O processo de inicialização pode instalar módulos adicionais
     exigidos pelo "pip", mas outro software não deve assumir que
     essas dependências sempre estarão presentes por padrão (como as
     dependências podem ser removidas em uma versão futura do "pip").
