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

Nouveau dans la version 3.4.

**Source code:** Lib/ensurepip

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

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


Interface en ligne de commande
==============================

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

Cette commande installe "pip" s'il n'est pas déjà présent. Sinon, elle
ne fait rien. Pour s'assurer que la version de "pip" est au moins
aussi récente que celle embarquée dans "ensurepip", passer l'option "
--upgrade" :

   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()

   Renvoie, sous forme de chaîne, la version de "pip" qui serait
   installée par "ensurepip".

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* indique s'il faut ou non effectuer la mise à jour d'une
   éventuelle version plus ancienne de "pip" déjà installée vers la
   version embarquée dans "ensurepip".

   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.
