"ensurepip" — Amorçage de l'installateur "pip"
**********************************************

Nouveau dans la version 3.4.

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

Le module "ensurepip" met en place l'installateur "pip" dans un
environnement Python, classique ou virtuel. Ce principe d'amorçage a
été choisi car "pip" est un projet séparé de Python avec son propre
cycle de versions. Il permet en particulier d'embarquer la version la
plus récente de "pip" dans les mises à jour de maintenance de
l'interpréteur CPython comme dans les nouvelles versions principales.

Dans la plupart des cas, il n'est pas nécessaire de recourir à ce
module. "pip" est le plus souvent déjà installé pour vous. Cependant,
"ensurepip" peut s'avérer utile si l'installation de "pip" a été
sautée au moment de l'installation de Python (ou en créant un
environnement virtuel), ou bien si "pip" a été désinstallé par
l'utilisateur.

Note:

  Ce module n'accède *pas* au réseau. Tout ce qu'il faut pour amorcer
  "pip" est compris dans le paquet.

Voir aussi:

  Installation de modules Python
     Guide de l'utilisateur final pour installer des paquets Python

  **PEP 453** : Amorçage explicite de pip dans les installations de
  Python
     Les motivations pour l'ajout de ce module et sa spécification
     d'origine


Command line interface
======================

On fait appel à l'interface en ligne de commande à l'aide de l'option
"-m" de l'interpréteur.

L'invocation la plus simple est :

   python -m ensurepip

This invocation will install "pip" if it is not already installed, but
otherwise does nothing. To ensure the installed version of "pip" is at
least as recent as the one bundled with "ensurepip", pass the "--
upgrade" option:

   python -m ensurepip --upgrade

"pip" est installé par défaut dans l'environnement virtuel courant,
s'il y en a un, ou bien dans le dossier "site-packages" du système.
L'emplacement d'installation se règle à travers deux options :

* "--root <dossier>" : installe "pip" sur un chemin relatif à la
  racine *dossier* au lieu de la racine de l'environnement virtuel ou
  la racine par défaut de l'installation de Python.

* "--user" : installe "pip" dans le dossier "site-packages" propre à
  l'utilisateur au lieu du dossier global de l'installation de Python.
  Cette option n'est pas valide dans un environnement virtuel.

Par défaut, les commandes "pipX" et "pipX.Y" sont créées (où X.Y est
la version de Python avec laquelle "ensurepip" est utilisé). Cela se
contrôle par deux options supplémentaires :

* "--altinstall" : dans ce mode d'« installation parallèle », seule la
  commande "pipX.Y" est ajoutée, et pas la commande "pipX".

* "--default-pip" : ce mode d'« installation de la version par défaut
  » crée la commande "pip" en plus de "pipX" et "pipX.Y".

Combiner ces deux options conduit à une exception.


API du module
=============

Le module "ensurepip" définit deux fonctions pour utilisation dans les
programmes :

ensurepip.version()

   Returns a string specifying the bundled version of pip that will be
   installed when bootstrapping an environment.

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

   Amorce "pip" dans l'environnement courant ou un environnement
   spécifique.

   Passer *root* permet de changer la racine du chemin d'installation.
   Si *root* vaut "None" (la valeur par défaut), l'installation se
   fait dans la racine par défaut pour l'environnement courant.

   *upgrade* indicates whether or not to upgrade an existing
   installation of an earlier version of "pip" to the bundled version.

   Si *user* vaut vrai, "pip" est mis dans des chemins qui le rendent
   disponible pour cet utilisateur uniquement, et non pour tous les
   utilisateurs de l'installation de Python.

   Par défaut, les commandes créées sont "pipX" et "pipX.Y" (où X.Y
   est la version de Python).

   Si *altinstall* vaut vrai, "pipX" n'est pas créée.

   Si *default_pip* vaut vrai, la commande "pip" est créée en plus des
   deux autres.

   Le fait de combiner *altinstall* et *default_pip* lève l'exception
   "ValueError".

   *verbosity* règle le niveau de verbosité des messages émis sur
   "sys.stdout" pendant l'amorçage.

   Cette fonction lève un événement d'audit "ensurepip.bootstrap" avec
   l'argument "root".

   Note:

     Le processus d'amorçage a des effets de bord sur "sys.path" et
     "os.environ". Pour les éviter, on peut appeler l'interface en
     ligne de commande dans un sous-processus.

   Note:

     L'amorçage peut installer des modules supplémentaires qui sont
     requis pour "pip". Les autres programmes ne doivent pas prendre
     pour acquise la présence de ces modules, car "pip" pourrait dans
     une version future se passer de ces dépendances.
