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

Novo na versão 3.4.

**Código-fonte:** Lib/ensurepip

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

O pacote "ensurepip" fornece suporte a fazer bootstrapping, ou seja,
inicializar o instalador do "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
invocar 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.

Disponibilidade: não Emscripten, não WASI.

Este módulo não funciona ou não está disponível em plataformas
WebAssembly "wasm32-emscripten" e "wasm32-wasi". Veja Plataformas
WebAssembly para mais informações.


Interface de linha de comando
=============================

A interface da linha de comando é 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 disponível do "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.

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


API do módulo
=============

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

ensurepip.version()

   Retorna uma string que especifica a versão disponível 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 disponível.

   *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.

   Levanta um evento de auditoria "ensurepip.bootstrap" com o
   argumento "root".

   Nota:

     O processo de inicialização tem efeitos colaterais em "sys.path"
     e "os.environ". Invocar a interface da linha de comando 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 presumir 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").
