"ensurepip" --- Bootstrapping the "pip" installer
*************************************************

Ajouté 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.

This is an *optional module*. If it is missing from your copy of
CPython, look for documentation from your distributor (that is,
whoever provided Python to you). If you are the distributor, see
Requirements for optional modules.

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

Disponibilité: not Android, not iOS, not WASI.

This module is not supported on mobile platforms or WebAssembly
platforms.


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

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 <dir>

   Installs "pip" relative to the given root directory rather than the
   root of the currently active virtual environment (if any) or the
   default root for the current Python installation.

--user

   Installs "pip" into the user site packages directory rather than
   globally for the current Python installation (this option is not
   permitted inside an active virtual environment).

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

   If an alternate installation is requested, the "pipX" script will
   *not* be installed.

--default-pip

   If a "default pip" installation is requested, the "pip" script will
   be installed in addition to the two regular scripts.

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.
