17.5. "subprocess" — Gestion de sous-processus
**********************************************

**Code source :** Lib/subprocess.py

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

Le module "subprocess" vous permet de lancer de nouveaux processus,
les connecter à des tubes d'entrée/sortie/erreur, et d'obtenir leurs
codes de retour.  Ce module a l'intention de remplacer plusieurs
anciens modules et fonctions :

   os.system
   os.spawn*

De plus amples informations sur comment le module "subprocess" peut
être utilisé pour remplacer ces modules et fonctions peuvent être
trouvées dans les sections suivantes.

Voir aussi: **PEP 324** -- PEP proposant le module *subprocess*


17.5.1. Utiliser le module "subprocess"
=======================================

L'approche recommandée pour invoquer un sous-processus et d'utiliser
la fonction "run()" pour tous les cas d'utilisation qu'il gère. Pour
les cas d'utilisation plus avancés, l'interface inhérente "Popen" peut
être utilisée directement.

La fonction "run()" a été ajoutée avec Python 3.5 ; si vous avez
besoin d'une compatibilité avec des versions plus anciennes, référez-
vous à la section Ancienne interface (API) haut-niveau.

subprocess.run(args, *, stdin=None, input=None, stdout=None, stderr=None, shell=False, cwd=None, timeout=None, check=False, encoding=None, errors=None, env=None)

   Lance la commande décrite par *args*.  Attend que la commande se
   termine, puis renvoie une instance "CompletedProcess".

   Les arguments présentés ci-dessus sont simplement les plus
   utilisés, décrits ci-dessous dans la section Arguments fréquemment
   utilisés (d'où l'utilisation de la notation *keyword-only* dans la
   signature abrégée). La signature complète de la fonction est
   sensiblement la même que celle du constructeur de "Popen" - à
   l'exception de *timeout*, *input* et *check*, tous les arguments
   donnés à cette fonction passent à travers cette interface.

   Les sorties standard (*stdout*) et d'erreur (*stderr*) ne sont pas
   capturées par défaut. Pour les capturer, utilisez "PIPE" comme
   valeur des arguments *stdout* et/ou *stderr*.

   L'argument *timeout* est passé à "Popen.communicate()". Si le
   *timeout* expire, le processus enfant sera tué et attendu.  Une
   exception "TimeoutExpired" sera levée une fois que le processus
   enfant se sera terminé.

   L'argument *input* est passé à "Popen.communicate()" et donc à
   l'entrée standard (*stdin*) du sous-processus.  Si l'argument est
   utilisé, il doit contenir une séquence de *bytes*, ou une chaîne de
   caractères si *encoding* ou *errors* son spécifiés, ou si
   *universal_newlines* est vrai.  Quand utilisé, l'objet interne
   "Popen" est automatiquement créé avec "stdin=PIPE", et l'argument
   *stdin* ne doit donc pas être utilisé.

   Si *check* est vrai, et que le processus s'arrête avec un code de
   statut non nul, une exception "CalledProcessError" est levée.  Les
   attributs de cette exception contiennent les arguments, le code de
   statut, et les sorties standard et d'erreur si elles ont été
   capturées.

   Si *encoding* ou *errors* sont spécifiés, ou *universal_newlines*
   est vrai, les fichiers pour les entrées et sorties sont ouverts en
   mode texte en utilisant les paramètres *encoding* et *errors*
   spécifiés, ou les valeurs par défaut de "io.TextIOWrapper".
   Autrement, les fichiers sont ouverts en mode binaire.

   Si *env* n'est pas "None", il doit être un tableau associatif
   définissant les variables d'environnement du nouveau processus ;
   elles seront utilisées à la place du comportement par défaut qui
   est d'hériter de l'environnement du processus courant. Il est passé
   directement à "Popen".

   Exemples :

      >>> subprocess.run(["ls", "-l"])  # doesn't capture output
      CompletedProcess(args=['ls', '-l'], returncode=0)

      >>> subprocess.run("exit 1", shell=True, check=True)
      Traceback (most recent call last):
        ...
      subprocess.CalledProcessError: Command 'exit 1' returned non-zero exit status 1

      >>> subprocess.run(["ls", "-l", "/dev/null"], stdout=subprocess.PIPE)
      CompletedProcess(args=['ls', '-l', '/dev/null'], returncode=0,
      stdout=b'crw-rw-rw- 1 root root 1, 3 Jan 23 16:23 /dev/null\n')

   Nouveau dans la version 3.5.

   Modifié dans la version 3.6: Ajout des paramètres *encoding* et
   *errors*

class subprocess.CompletedProcess

   La valeur de retour de "run()", représentant un processus qui s'est
   terminé.

   args

      Les arguments utilisés pour lancer le processus. Cela peut être
      une liste ou une chaîne de caractères.

   returncode

      Le code de statut du processus fils.  Typiquement, un code de
      statut de 0 indique qu'il s'est exécuté avec succès.

      Une valeur négative "-N" indique que le processus enfant a été
      terminé par un signal "N" (seulement sur les systèmes *POSIX*).

   stdout

      La sortie standard capturée du processus enfant. Une séquence de
      *bytes*, ou une chaîne de caractères si "run()" a été appelée
      avec *encoding* ou *errors*. Vaut "None" si la sortie standard
      n'était pas capturée.

      Si vous avez lancé le processus avec "stderr=subprocess.STDOUT",
      les sorties standard et d'erreur seront combinées dans cet
      attribut, et "stderr" sera mis à "None".

   stderr

      La sortie d'erreur capturée du processus enfant. Une séquence de
      *bytes*, ou une chaîne de caractères si "run()" a été appelée
      avec *encoding* ou *errors*. Vaut "None" si la sortie d'erreur
      n'était pas capturée.

   check_returncode()

      Si "returncode" n'est pas nul, lève une "CalledProcessError".

   Nouveau dans la version 3.5.

subprocess.DEVNULL

   Valeur spéciale qui peut être utilisée pour les arguments *stdin*,
   *stdout* ou *stderr* de "Popen" et qui indique que le fichier
   spécial "os.devnull" sera utilisé.

   Nouveau dans la version 3.3.

subprocess.PIPE

   Valeur spéciale qui peut être utilisée pour les arguments *stdin*,
   *stdout* ou *stderr* de "Popen" et qui indique qu'un tube vers le
   flux standard doit être ouvert.  Surtout utile avec
   "Popen.communicate()".

subprocess.STDOUT

   Valeur spéciale qui peut être utilisée pour l'argument *stderr* de
   "Popen" et qui indique que la sortie d'erreur doit être redirigée
   vers le même descripteur que la sortie standard.

exception subprocess.SubprocessError

   Classe de base à toutes les autres exceptions du module.

   Nouveau dans la version 3.3.

exception subprocess.TimeoutExpired

   Sous-classe de "SubprocessError", levée quand un *timeout* expire
   pendant l'attente d'un processus enfant.

   cmd

      La commande utilisée pour instancier le processus fils.

   timeout

      Le *timeout* en secondes.

   output

      La sortie du processus fils, si capturée par "run()" ou
      "check_output()".  Autrement, "None".

   stdout

      Alias pour *output*, afin d'avoir une symétrie avec "stderr".

   stderr

      La sortie d'erreur du processus fils, si capturée par "run()".
      Autrement, "None".

   Nouveau dans la version 3.3.

   Modifié dans la version 3.5: Ajout des attributs *stdout* et
   *stderr*

exception subprocess.CalledProcessError

   Sous-classe de "SubprocessError", levée quand un processus lancé
   par "check_call()" ou "check_output()" renvoie un code de statut
   non nul.

   returncode

      Code de statut du processus fils.  Si le processus a été arrêté
      par un signal, le code sera négatif et correspondra à l'opposé
      du numéro de signal.

   cmd

      La commande utilisée pour instancier le processus fils.

   output

      La sortie du processus fils, si capturée par "run()" ou
      "check_output()".  Autrement, "None".

   stdout

      Alias pour *output*, afin d'avoir une symétrie avec "stderr".

   stderr

      La sortie d'erreur du processus fils, si capturée par "run()".
      Autrement, "None".

   Modifié dans la version 3.5: Ajout des attributs *stdout* et
   *stderr*


17.5.1.1. Arguments fréquemment utilisés
----------------------------------------

Pour gérer un large ensemble de cas, le constructeur de "Popen" (et
les fonctions de convenance) acceptent de nombreux arguments
optionnels. Pour les cas d'utilisation les plus typiques, beaucoup de
ces arguments peuvent sans problème être laissés à leurs valeurs par
défaut. Les arguments les plus communément nécessaires sont :

   *args* est requis pour tous les appels et doit être une chaîne de
   caractères ou une séquence d'arguments du programme. Il est
   généralement préférable de fournir une séquence d'arguments,
   puisque cela permet au module de s'occuper des potentiels
   échappements ou guillemets autour des arguments (p. ex. pour
   permettre des espaces dans des noms de fichiers). Si l'argument est
   passé comme une simple chaîne, soit *shell* doit valoir "True"
   (voir ci-dessous) soit la chaîne doit simplement contenir le nom du
   programme à exécuter sans spécifier d'arguments supplémentaires.

   *stdin*, *stdout* et *stderr* spécifient respectivement les
   descripteurs d'entrée standard, de sortie standard et de sortie
   d'erreur du programme exécuté.  Les valeurs acceptées sont "PIPE",
   "DEVNULL", un descripteur de fichier existant (nombre entier
   positif), un objet de fichier, et "None".  "PIPE" indique qu'un
   nouveau tube vers le processus enfant sera créé.  "DEVNULL" indique
   que le fichier spécial "os.devnull" sera utilisé.  Avec les
   paramètres "None" par défaut, aucune redirection ne se produira,
   les descripteurs de fichiers du fils seront hérités du parent.
   Additionnellement, *stderr* peut valoir "STDOUT", qui indique que
   les données de la sortie d'erreur du processus fils doivent être
   capturées dans le même descripteur de fichier que la sortie
   standard.

   Si *encoding* ou *errors* sont spécifiés, ou si
   *universal_newlines* est vrai, les fichiers *stdin*, *stdout* et
   *stderr* seront ouverts en mode texte en utilisant les *encoding*
   et *errors* spécifiés à l'appel, ou les valeurs par défaut de
   "io.TextIOWrapper".

   Pour *stdin*, les caractères de fin de ligne "'\n'" de l'entrée
   seront convertis vers des séparateurs de ligne par défaut
   "os.linesep". Pour *stdout* et *stderr*, toutes les fins de lignes
   des sorties seront converties vers "'\n'".  Pour plus
   d'informations, voir la documentation de la classe
   "io.TextIOWrapper" quand l'argument *newline* du constructeur est
   "None".

   Si le mode texte n'est pas utilisé, *stdin*, *stdout* et *stderr*
   seront ouverts comme des flux binaires. Aucune conversion
   d'encodage ou de fins de ligne ne sera réalisée.

   Nouveau dans la version 3.6: Ajout des paramètres *encoding* et
   *errors*.

   Note:

     L'attribut *newlines* des objets "Popen.stdin", "Popen.stdout" et
     "Popen.stderr" ne sont pas mis à jour par la méthode
     "Popen.communicate()".

   Si *shell* vaut "True", la commande spécifiée sera exécutée à
   travers un *shell*.  Cela peut être utile si vous utilisez Python
   pour le contrôle de flot qu'il propose par rapport à beaucoup de
   *shells* système et voulez tout de même profiter des autres
   fonctionnalités des *shells* telles que les tubes (*pipes*), les
   motifs de fichiers, l'expansion des variables d'environnement, et
   l'expansion du "~" vers le répertoire d’accueil de l'utilisateur.
   Cependant, notez que Python lui-même propose l'implémentation de
   beaucoup de ces fonctionnalités (en particulier "glob", "fnmatch",
   "os.walk()", "os.path.expandvars()", "os.path.expanduser()" et
   "shutil").

   Modifié dans la version 3.3: Quand *universal_newlines* vaut
   "True", la classe utilise l'encodage
   "locale.getpreferredencoding(False)" plutôt que
   "locale.getpreferredencoding()".  Voir la classe "io.TextIOWrapper"
   pour plus d'informations sur ce changement.

   Note:

     Lire la section Security Considerations avant d'utiliser
     "shell=True".

Ces options, ainsi que toutes les autres, sont décrites plus en
détails dans la documentation du constructeur de "Popen".


17.5.1.2. Constructeur de *Popen*
---------------------------------

La création et la gestion sous-jacentes des processus est gérée par la
classe "Popen". Elle offre beaucoup de flexibilité de façon à ce que
les développeurs soient capables de gérer les cas d'utilisation les
moins communs, non couverts par les fonctions de convenance.

class subprocess.Popen(args, bufsize=-1, executable=None, stdin=None, stdout=None, stderr=None, preexec_fn=None, close_fds=True, shell=False, cwd=None, env=None, universal_newlines=False, startupinfo=None, creationflags=0, restore_signals=True, start_new_session=False, pass_fds=(), *, encoding=None, errors=None)

   Exécute un programme fils dans un nouveau processus.  Sur les
   systèmes *POSIX*, la classe utilise un comportement similaire à
   "os.execvp()" pour exécuter le programme.  Sur Windows, la classe
   utilise la fonction Windows "CreateProcess()".  Les arguments de
   "Popen" sont les suivants.

   *args* doit être une séquence d'arguments du programme ou une
   chaîne seule. Par défaut, le programme à exécuter est le premier
   élément de *args* si *args* est une séquence.  Si *args* est une
   chaîne, l'interprétation dépend de la plateforme et est décrite
   plus bas.  Voir les arguments *shell* et *executable* pour d'autres
   différences avec le comportement par défaut.  Sans autre
   indication, il est recommandé de passer *args* comme une séquence.

   Sur les systèmes *POSIX*, si *args* est une chaîne, elle est
   interprétée comme le nom ou le chemin du programme à exécuter.
   Cependant, cela ne peut être fait que si le programme est passé
   sans arguments.

   Note:

     "shlex.split()" peut être utilisée pour déterminer le découpage
     correct de *args*, spécifiquement dans les cas complexes :

        >>> import shlex, subprocess
        >>> command_line = input()
        /bin/vikings -input eggs.txt -output "spam spam.txt" -cmd "echo '$MONEY'"
        >>> args = shlex.split(command_line)
        >>> print(args)
        ['/bin/vikings', '-input', 'eggs.txt', '-output', 'spam spam.txt', '-cmd', "echo '$MONEY'"]
        >>> p = subprocess.Popen(args) # Success!

     Notez en particulier que les options (comme *-input*) et
     arguments (comme *eggs.txt*) qui sont séparés par des espaces
     dans le *shell* iront dans des éléments séparés de la liste,
     alors que les arguments qui nécessitent des guillemets et
     échappements quand utilisés dans le *shell* (comme les noms de
     fichiers contenant des espaces ou la commande *echo* montrée plus
     haut) forment des éléments uniques.

   Sous Windows, si *args* est une séquence, elle sera convertie vers
   une chaîne de caractères de la manière décrite dans Convertir une
   séquence d'arguments vers une chaîne de caractères sous Windows.
   Cela fonctionne ainsi parce que la fonction "CreateProcess()" opère
   sur des chaînes.

   L'argument *shell* (qui vaut "False" par défaut) spécifie s'il faut
   utiliser un *shell* comme programme à exécuter.  Si *shell* vaut
   "True", il est recommandé de passer *args* comme une chaîne de
   caractères plutôt qu'une séquence.

   Sur les systèmes POSIX avec "shell=True", le *shell* par défaut est
   "/bin/sh".  Si *args* est une chaîne de caractères, la chaîne
   spécifie la commande à exécuter à travers le *shell*.  Cela
   signifie que la chaîne doit être formatée exactement comme elle le
   serait si elle était tapée dans l'invite de commandes du *shell*.
   Cela inclut, par exemple, les guillemets ou les *backslashs*
   échappant les noms de fichiers contenant des espaces.  Si *args*
   est une séquence, le premier élément spécifie la commande, et les
   éléments supplémentaires seront traités comme des arguments
   additionnels à passer au *shell* lui-même.  Pour ainsi dire,
   "Popen" réalise l'équivalent de :

      Popen(['/bin/sh', '-c', args[0], args[1], ...])

   Sous Windows avec "shell=True", la variable d'environnement
   "COMSPEC" spécifie le *shell* par défaut.  La seule raison pour
   laquelle vous devriez spécifier "shell=True" sous Windows est quand
   la commande que vous souhaitez exécuter est une *built-in* du
   *shell* (p. ex. **dir** ou **copy**).  Vous n'avez pas besoin de
   "shell=True" pour lancer un fichier batch ou un exécutable console.

   Note:

     Lire la section Security Considerations avant d'utiliser
     "shell=True".

   *bufsize* sera fourni comme l'argument correspondant à la fonction
   "open()", lors de la création des objets de fichiers pour les tubes
   *stdin*/*stdout*/*stderr* :

   * "0" indique de ne pas utiliser de tampon (les lectures et
     écritures sont des appels systèmes et peuvent renvoyer des
     données incomplètes) ;

   * "1" indique une mise en cache par ligne (utilisable seulement si
     "universal_newlines=True", c'est-à-dire en mode texte) ;

   * toutes les autres valeurs positives indiquent d'utiliser un
     tampon d'approximativement cette taille ;

   * un *bufsize* négatif (par défaut) indique au système d'utiliser
     la valeur par défaut *io.DEFAULT_BUFFER_SIZE*.

   Modifié dans la version 3.3.1: *bufsize* vaut maintenant "-1" par
   défaut, pour activer par défaut la mise en cache et correspondre au
   comportement attendu par la plupart des codes.  Dans les versions
   de Python antérieures à 3.2.4 et 3.3.1, par erreur, la valeur par
   défaut était "0" qui ne réalisait aucune mise en cache et
   autorisait les lectures incomplètes.  Cela n'était pas intentionnel
   et ne correspondait pas au comportement de Python 2 attendu par la
   plupart des codes.

   L'argument *executable* spécifie un programme de remplacement à
   exécuter.  Il est très rarement nécessaire.  Quand "shell=False",
   *executable* remplace le programme à exécuter spécifié par *args*.
   Cependant, les arguments originels d'*args` sont toujours passés au
   programme.  La plupart des programmes traitent le programme
   spécifié par *args* comme le nom de la commande, qui peut être
   différent du programme réellement exécuté.  Sur les systèmes POSIX,
   le nom tiré d'*args* devient le nom affiché pour l'exécutable dans
   des utilitaires tels que **ps**.  Si "shell=True", sur les systèmes
   POSIX, l'argument *executable* précise le *shell* à utiliser plutôt
   que "/bin/sh" par défaut.

   *stdin*, *stdout* et *stderr* spécifient respectivement les
   descripteurs d'entrée standard, de sortie standard et de sortie
   d'erreur du programme exécuté.  Les valeurs acceptées sont "PIPE",
   "DEVNULL", un descripteur de fichier existant (nombre entier
   positif), un *file object*, et "None".  "PIPE" indique qu'un
   nouveau tube vers le processus enfant sera créé.  "DEVNULL" indique
   que le fichier spécial "os.devnull" sera utilisé.  Avec les
   paramètres "None" par défaut, aucune redirection ne se produira,
   les descripteurs de fichiers du fils seront hérités du parent.
   Additionnellement, *stderr* peut valoir "STDOUT", qui indique que
   les données de la sortie d'erreur du processus fils doivent être
   capturées dans le même descripteur de fichier que la sortie
   standard.

   Si un objet appelable est passé à *preexec_fn*, cet objet sera
   appelé dans le processus enfant juste avant d'exécuter le
   programme.  (POSIX seulement)

   Avertissement:

     Le paramètre *preexec_fn* n'est pas sain à utiliser en présence
     d'autres fils d'exécution dans votre application.  Le processus
     fils pourrait être bloqué (*deadlock*) avant qu'*exec* ne soit
     appelée. Si vous devez utiliser ce paramètre, gardez son
     utilisation triviale !  Minimisez le nombre de bibliothèques que
     vous y appelez.

   Note:

     Si vous devez modifier l'environnement du fils, utilisez le
     paramètre *env* plutôt que faire cela dans une *preexec_fn*. Le
     paramètre *start_new_session* peut prendre la place de
     *preexec_fn* qui était autrefois communément utilisé pour appeler
     *os.setsid()* dans le fils.

   Si *close_fds* est vrai, tous les descripteurs de fichiers à
   l'exception de "0", "1" et "2" seront fermés avant que le processus
   fils ne soit exécuté.  (POSIX seulement).  La valeur par défaut
   varie selon les plateformes : il est toujours vrai sur les systèmes
   POSIX.  Sous Windows, il est vrai quand *stdin*/*stdout*/*stderr*
   sont "None", faux autrement. Sous Windows, si *close_fds* est vrai,
   aucun gestionnaire ne sera hérité par le processus fils.  Notez que
   sous Windows, vous ne pouvez pas mettre *close_fds* à *true* et en
   même temps rediriger les entrées/sorties standards avec les
   paramètres *stdin*/*stdout*/*stderr*.

   Modifié dans la version 3.2: La valeur par défaut de *close_fds*
   n'est plus "False", comme décrit ci-dessus.

   *pass_fds* est une séquence optionnelle de descripteurs de fichiers
   à garder ouverts entre le parent et l'enfant.  Fournir *pass_fds*
   force *close_fds* à valoir "True". (POSIX seulement)

   Nouveau dans la version 3.2: Ajout du paramètre *pass_fds*.

   Si *cwd* n'est pas "None", la fonction change de répertoire courant
   pour *cwd* avant d'exécuter le fils.  *cwd* peut être un objet
   "str" ou un *chemin-compatible*.  En particulier, la fonction
   recherche *executable* (ou le premier élément d'*args*)
   relativement à *cwd* si le chemin d'exécution est relatif.

   Modifié dans la version 3.6: le paramètre *cwd* accepte un *path-
   like object*.

   Si *restore_signals* est vrai (par défaut), tous les signaux que
   Python a mis à *SIG_IGN* sont restaurés à *SIG_DFL* dans le
   processus fils avant l'appel à *exec*.  Actuellement, cela inclut
   les signaux *SIGPIPE*, *SIGXFZ* et *SIGXFSZ*.  (POSIX seulement)

   Modifié dans la version 3.2: Ajout de *restore_signals*.

   Si *start_new_session* est vrai, l'appel système à *setsid()* sera
   réalisé dans le processus fils avant l'exécution du sous-processus.
   (POSIX seulement)

   Modifié dans la version 3.2: Ajout de *start_new_session*.

   Si *env* n'est pas "None", il doit être un tableau associatif
   définissant les variables d'environnement du nouveau processus ;
   elles seront utilisées à la place du comportement par défaut qui
   est d'hériter de l'environnement du processus courant.

   Note:

     Si spécifié, *env* doit fournir chaque variable requise pour
     l'exécution du programme.  Sous Windows, afin d'exécuter un side-
     by-side assembly, l'environnement *env* spécifié **doit**
     contenir une variable "SystemRoot" valide.

   Si *encoding* ou *errors* sont spécifiés, les fichiers *stdin*,
   *stdout* et *stderr* sont ouverts en mode texte, avec l'encodage et
   la valeur d'*errors* spécifiés, comme décrit ci-dessus dans
   Arguments fréquemment utilisés. Si *universal_newlines* vaut
   "True", ils sont ouverts en mode texte avec l'encodage par défaut.
   Autrement, ils sont ouverts comme des flux binaires.

   Nouveau dans la version 3.6: Ajout d'*encoding* et *errors*.

   Si fourni, *startupinfo* sera un objet "STARTUPINFO", qui sera
   passé à la fonction "CreateProcess" inhérente.  *creationflags*, si
   fourni, peut valoir "CREATE_NEW_CONSOLE" ou
   "CREATE_NEW_PROCESS_GROUP". (Windows seulement)

   Les objets *Popen* sont gérés comme gestionnaires de contexte avec
   l'instruction "with" : à la sortie, les descripteurs de fichiers
   standards sont fermés, et le processus est attendu

      with Popen(["ifconfig"], stdout=PIPE) as proc:
          log.write(proc.stdout.read())

   Modifié dans la version 3.2: Ajout de la gestion des gestionnaires
   de contexte.

   Modifié dans la version 3.6: Le destructeur de *Popen* émet
   maintenant un avertissement "ResourceWarning" si le processus fils
   est toujours en cours d'exécution.


17.5.1.3. Exceptions
--------------------

Les exceptions levées dans le processus fils, avant que le nouveau
programme n'ait commencé son exécution, seront relayées dans le
parent.  Additionnellement, l'objet de l'exception aura un attribut
supplémentaire appelé "child_traceback", une chaîne de caractères
contenant la trace de l'exception du point de vue du fils.

L'exception la plus communément levée est "OSError".  Elle survient,
par exemple, si vous essayez d'exécuter un fichier inexistant.  Les
applications doivent se préparer à traiter des exceptions "OSError".

Une "ValueError" sera levée si "Popen" est appelé avec des arguments
invalides.

"check_call()" et "check_output()" lèveront une "CalledProcessError"
si le processus appelé renvoie un code de retour non nul.

Toutes les fonctions et méthodes qui acceptent un paramètre *timeout*,
telles que "call()" et "Popen.communicate()" lèveront une
"TImeoutExpired" si le *timeout* expire avant la fin du processus.

Toutes les exceptions définies dans ce module héritent de
"SubprocessError".

   Nouveau dans la version 3.3: Ajout de la classe de base
   "SubprocessError".


17.5.2. Considérations de sécurité
==================================

Contrairement à quelques autres fonctions *popen*, cette
implémentation n'appellera jamais implicitement le *shell* du système.
Cela signifie que tous les caractères, incluant les métacaractères des
*shells*, peuvent être passés aux processus fils en toute sécurité. Si
le *shell* est invoqué explicitement, avec "shell=True", il est de la
responsabilité de l'application d'assurer que les espaces et
métacaractères sont échappés correctement pour éviter les
vulnérabilités de type shell injection.

Avec "shell=True", la fonction "shlex.quote()" peut être utilisée pour
échapper proprement les espaces et métacaractères dans les chaînes qui
seront utilisées pour construire les commandes *shell*.


17.5.3. Objets *Popen*
======================

Les instances de la classe "Popen" possèdent les méthodes suivantes :

Popen.poll()

   Vérifie que le processus enfant s'est terminé.  Modifie et renvoie
   l'attribut "returncode", sinon, renvoie "None".

Popen.wait(timeout=None)

   Attend qu'un processus enfant se termine.  Modifie l'attribut
   "returncode" et le renvoie.

   Si le processus ne se termine pas après le nombre de secondes
   spécifié par *timeout*, une exception "TimeoutExpired" est levée.
   Cela ne pose aucun problème d'attraper cette exception et de
   réessayer d'attendre.

   Note:

     Cela provoquera un blocage (*deadlock*) lors de l'utilisation de
     "stdout=PIPE" ou "stderr=PIPE" si le processus fils génère
     tellement de données sur le tube qu'il le bloque, en attente que
     le système d'exploitation permette au tampon du tube d'accepter
     plus de données.  Utilisez "Popen.communicate()" pour éviter ce
     problème lors de l'utilisation de tubes.

   Note:

     Cette fonction est implémentée avec une attente active (appels
     non bloquants et *sleep* courts). Utilisez le module "asyncio"
     pour une attente asynchrone : voir
     "asyncio.create_subprocess_exec".

   Modifié dans la version 3.3: Ajout de *timeout*.

   Obsolète depuis la version 3.4: N'utilisez pas le paramètre
   *endtime*.  Il a été par mégarde exposé dans la version 3.3 mais
   laissé non-documenté, et était destiné à rester privé pour un usage
   interne.  Utilisez plutôt *timeout*.

Popen.communicate(input=None, timeout=None)

   Interagit avec le processus : envoie des données sur l'entrée
   standard, lit en retour les données sur les sorties standard et
   d'erreur, et attend que le processus se termine.  L'argument
   optionnel *input* contient les données à envoyer au processus fils,
   ou "None" s'il n'y a aucune donnée à lui transmettre.  Si les flux
   sont ouverts en mode texte, *input* doit être une chaîne de
   caractère.  Autrement, ce doit être un objet *bytes*.

   "communicate()" renvoie un *tuple* "(stdout_data, stderr_data)".
   Les données seront des chaînes de caractères si les flux sont
   ouverts en mode texte, et des objets *bytes* dans le cas contraire.

   Notez que si vous souhaitez envoyer des données sur l'entrée
   standard du processus, vous devez créer l'objet *Popen* avec
   "stdin=PIPE".  Similairement, pour obtenir autre chose que "None"
   dans le *tuple* résultant, vous devez aussi préciser "stdout=PIPE"
   et/ou "stderr=PIPE".

   Si le processus ne se termine pas après *timeout* secondes, une
   exception "TimeoutExpired" est levée.  Attraper cette exception et
   retenter la communication ne fait perdre aucune donnée de sortie.

   Le processus enfant n'est pas tué si le *timeout* expire, donc afin
   de nettoyer proprement le tout, une application polie devrait tuer
   le processus fils et terminer la communication :

      proc = subprocess.Popen(...)
      try:
          outs, errs = proc.communicate(timeout=15)
      except TimeoutExpired:
          proc.kill()
          outs, errs = proc.communicate()

   Note:

     Les données lues sont mises en cache en mémoire, donc n'utilisez
     pas cette méthode si la taille des données est importante voire
     illimitée.

   Modifié dans la version 3.3: Ajout de *timeout*.

Popen.send_signal(signal)

   Envoie le signal *signal* au fils.

   Note:

     Sous Windows, *SIGTERM* est un alias pour "terminate()".
     *CTRL_C_EVENT* et *CTRL_BREAK_EVENT* peuvent être envoyés aux
     processus démarrés avec un paramètre *creationflags* incluant
     *CREATE_NEW_PROCESS_GROUP*.

Popen.terminate()

   Stoppe le processus fils. Sur les systèmes POSIX, la méthode envoie
   un signal *SIGTERM* au fils. Sous Windows, la fonction
   "TerminateProcess()" de l'API *Win32* est appelée pour arrêter le
   fils.

Popen.kill()

   Tue le processus fils. Sur les systèmes POSIX, la fonction envoie
   un signal *SIGKILL* au fils. Sous Windows, "kill()" est un alias
   pour "terminate()".

Les attributs suivants sont aussi disponibles :

Popen.args

   L'argument *args* tel que passé à "Popen" -- une séquence
   d'arguments du programme ou une simple chaîne de caractères.

   Nouveau dans la version 3.3.

Popen.stdin

   Si l'argument *stdin* valait "PIPE", cet attribut est un flux
   accessible en écriture comme renvoyé par "open()". Si les arguments
   *encoding* ou *errors* ont été spécifiés, ou si
   *universal_newlines* valait "True", le flux est textuel, il est
   autrement binaire. Si l'argument *stdin* ne valait pas "PIPE", cet
   attribut est "None".

Popen.stdout

   Si l'argument *stdout* valait "PIPE", cet attribut est un flux
   accessible en lecture comme renvoyé par "open()". Lire depuis le
   flux fournit la sortie du processus fils. Si les arguments
   *encoding* ou *errors* ont été spécifiés, ou si
   *universal_newlines* valait "True", le flux est textuel, il est
   autrement binaire. Si l'argument *stdout* ne valait pas "PIPE", cet
   attribut est "None".

Popen.stderr

   Si l'argument *stderr* valait "PIPE", cet attribut est un flux
   accessible en lecture comme renvoyé par "open()". Lire depuis le
   flux fournit la sortie d'erreur du processus fils. Si les arguments
   *encoding* ou *errors* ont été spécifiés, ou si
   *universal_newlines* valait "True", le flux est textuel, il est
   autrement binaire. Si l'argument *stderr* ne valait pas "PIPE", cet
   attribut est "None".

Avertissement:

  Utilisez "communicate()" plutôt que ".stdin.write", ".stdout.read"
  ou ".stderr.read" pour empêcher les *deadlocks* dus au remplissage
  des tampons des tubes de l'OS et bloquant le processus enfant.

Popen.pid

   L'identifiant de processus du processus enfant.

   Notez que si vous passez l'argument *shell* à "True", il s'agit
   alors de l'identifiant du *shell* instancié.

Popen.returncode

   Le code de retour de l'enfant, attribué par "poll()" et "wait()"
   (et indirectement par "communicate()").  Une valeur "None" indique
   que le processus ne s'est pas encore terminé.

   Une valeur négative "-N" indique que le processus enfant a été
   terminé par un signal "N" (seulement sur les systèmes *POSIX*).


17.5.4. Utilitaires *Popen* pour Windows
========================================

La classe "STARTUPINFO" et les constantes suivantes sont seulement
disponibles sous Windows.

class subprocess.STARTUPINFO

   Un support partiel de la structure STARTUPINFO de Windows est
   utilisé lors de la création d'un objet "Popen".

   dwFlags

      Un champ de bits déterminant si certains attributs "STARTUPINFO"
      sont utilisés quand le processus crée une fenêtre

         si = subprocess.STARTUPINFO()
         si.dwFlags = subprocess.STARTF_USESTDHANDLES | subprocess.STARTF_USESHOWWINDOW

   hStdInput

      Si "dwFlags" spécifie "STARTF_USESTDHANDLES", cet attribut est
      le descripteur d'entrée standard du processus. Si
      "STARTF_USESTDHANDLES" n'est pas spécifié, l'entrée standard par
      défaut est le tampon du clavier.

   hStdOutput

      Si "dwFlags" spécifie "STARTF_USESTDHANDLES", cet attribut est
      le descripteur de sortie standard du processus. Autrement,
      l'attribut est ignoré et la sortie standard par défaut est le
      tampon de la console.

   hStdError

      Si "dwFlags" spécifie "STARTF_USESTDHANDLES", cet attribut est
      le descripteur de sortie d'erreur du processus. Autrement,
      l'attribut est ignoré et la sortie d'erreur par défaut est le
      tampon de la console.

   wShowWindow

      Si "dwFlags" spécifie "STARTF_USESHOWWINDOW", cet attribut peut-
      être n'importe quel attribut valide pour le paramètre "nCmdShow"
      de la fonction ShowWindow, à l'exception de "SW_SHOWDEFAULT".
      Autrement, cet attribut est ignoré.

      "SW_HIDE" est fourni pour cet attribut. Il est utilisé quand
      "Popen" est appelée avec "shell=True".


17.5.4.1. Constantes
--------------------

Le module "subprocess" expose les constantes suivantes.

subprocess.STD_INPUT_HANDLE

   Le périphérique d'entrée standard. Initialement, il s'agit du
   tampon de la console d'entrée, "CONIN$".

subprocess.STD_OUTPUT_HANDLE

   Le périphérique de sortie standard. Initialement, il s'agit du
   tampon de l'écran de console actif, "CONOUT$".

subprocess.STD_ERROR_HANDLE

   Le périphérique de sortie d'erreur. Initialement, il s'agit du
   tampon de l'écran de console actif, "CONOUT$".

subprocess.SW_HIDE

   Cache la fenêtre. Une autre fenêtre sera activée.

subprocess.STARTF_USESTDHANDLES

   Spécifie que les attributs "STARTUPINFO.hStdInput",
   "STARTUPINFO.hStdOutput" et "STARTUPINFO.hStdError" contiennent des
   informations additionnelles.

subprocess.STARTF_USESHOWWINDOW

   Spécifie que l'attribut "STARTUPINFO.wShowWindow" contient des
   informations additionnelles.

subprocess.CREATE_NEW_CONSOLE

   Le nouveau processus instancie une nouvelle console, plutôt que
   d'hériter de celle de son père (par défaut).

subprocess.CREATE_NEW_PROCESS_GROUP

   Paramètre "creationflags" de "Popen" pour spécifier si un nouveau
   groupe de processus doit être créé. Cette option est nécessaire
   pour utiliser "os.kill()" sur le sous-processus.

   L'option est ignorée si "CREATE_NEW_CONSOLE" est spécifié.


17.5.5. Ancienne interface (*API*) haut-niveau
==============================================

Avant Python 3.5, ces trois fonctions représentaient l'API haut-niveau
de *subprocess*. Vous pouvez maintenant utiliser "run()" dans de
nombreux cas, mais beaucoup de codes existant font appel à ces trois
fonctions.

subprocess.call(args, *, stdin=None, stdout=None, stderr=None, shell=False, cwd=None, timeout=None)

   Lance la commande décrite par *args*, attend qu'elle se termine, et
   renvoie son attribut "returncode".

   C’est équivalent à :

      run(...).returncode

   (excepté que les paramètres *input* et *check* ne sont pas
   supportés)

   Les arguments montrés plus haut sont sûrement les plus communs. La
   signature complète de la fonction est en grande partie la même que
   le constructeur de "Popen" : cette fonction passe tous les
   arguments fournis autre que *timeout* directement à travers cette
   interface.

   Note:

     N'utilisez pas "stdout=PIPE" ou "stderr=PIPE" avec cette
     fonction.  Le processus enfant bloquera s'il génère assez de
     données pour remplir le tampon du tube de l'OS, puisque les tubes
     ne seront jamais lus.

   Modifié dans la version 3.3: Ajout de *timeout*.

subprocess.check_call(args, *, stdin=None, stdout=None, stderr=None, shell=False, cwd=None, timeout=None)

   Lance la commande avec les arguments et attend qu'elle se termine.
   Se termine normalement si le code de retour est zéro, et lève une
   "CalledProcessError" autrement. L'objet "CalledProcessError"
   contiendra le code de retour dans son attribut "returncode".

   C’est équivalent à :

      run(..., check=True)

   (excepté que le paramètre *input* n'est pas pris en charge)

   Les arguments montrés plus haut sont sûrement les plus communs. La
   signature complète de la fonction est en grande partie la même que
   le constructeur de "Popen" : cette fonction passe tous les
   arguments fournis autre que *timeout* directement à travers cette
   interface.

   Note:

     N'utilisez pas "stdout=PIPE" ou "stderr=PIPE" avec cette
     fonction.  Le processus enfant bloquera s'il génère assez de
     données pour remplir le tampon du tube de l'OS, puisque les tubes
     ne seront jamais lus.

   Modifié dans la version 3.3: Ajout de *timeout*.

subprocess.check_output(args, *, stdin=None, stderr=None, shell=False, cwd=None, encoding=None, errors=None, universal_newlines=False, timeout=None)

   Lance la commande avec les arguments et renvoie sa sortie.

   Si le code de retour est non-nul, la fonction lève une
   "CalledProcessError". L'objet "CalledProcessError" contiendra le
   code de retour dans son attribut "returncode", et la sortie du
   programme dans son attribut "output".

   C’est équivalent à :

      run(..., check=True, stdout=PIPE).stdout

   Les arguments montrés plus haut sont sûrement les plus communs. La
   signature complète de la fonction est en grande partie la même que
   "run()" : la plupart des arguments sont passés directement par
   cette interface.  Cependant, passer explicitement "input=None" pour
   hériter du gestionnaire d'entrée standard du parent n'est pas
   supporté.

   Par défaut, cette fonction renvoie les données encodées sous forme
   de *bytes*. Le réel encodage des données de sortie peut dépendre de
   la commande invoquée, donc le décodage du texte devra souvent être
   géré au niveau de l'application.

   Ce comportement peut être redéfini en mettant *universal_newlines*
   à "True" comme décrit ci-dessus dans Arguments fréquemment
   utilisés.

   Pour capturer aussi la sortie d'erreur dans le résultat, utilisez
   "stderr=subprocess.STDOUT" :

      >>> subprocess.check_output(
      ...     "ls non_existent_file; exit 0",
      ...     stderr=subprocess.STDOUT,
      ...     shell=True)
      'ls: non_existent_file: No such file or directory\n'

   Nouveau dans la version 3.1.

   Modifié dans la version 3.3: Ajout de *timeout*.

   Modifié dans la version 3.4: Ajout de la gestion de l'argument
   nommé *input*.

   Modifié dans la version 3.6: Ajout d'*encoding* et *errors*.
   Consultez "run()" pour plus d'informations.


17.5.6. Remplacer les fonctions plus anciennes par le module "subprocess"
=========================================================================

Dans cette section, « a devient b » signifie que b peut être utilisée
en remplacement de a.

Note:

  Toutes les fonctions « a » dans cette section échouent (plus ou
  moins) silencieusement si le programme à exécuter ne peut être
  trouvé ; les fonctions « b » de remplacement lèvent à la place une
  "OSError".De plus, les remplacements utilisant "check_output()"
  échoueront avec une "CalledProcessError" si l'opération requise
  produit un code de retour non-nul. La sortie est toujours disponible
  par l'attribut "output" de l'exception levée.

Dans les exemples suivants, nous supposons que les fonctions utilisées
ont déjà été importées depuis le module "subprocess".


17.5.6.1. Remplacement des *backquotes* des *shells /bin/sh*
------------------------------------------------------------

   output=`mycmd myarg`

devient :

   output = check_output(["mycmd", "myarg"])


17.5.6.2. Remplacer les *pipes* du *shell*
------------------------------------------

   output=`dmesg | grep hda`

devient :

   p1 = Popen(["dmesg"], stdout=PIPE)
   p2 = Popen(["grep", "hda"], stdin=p1.stdout, stdout=PIPE)
   p1.stdout.close()  # Allow p1 to receive a SIGPIPE if p2 exits.
   output = p2.communicate()[0]

L'appel à *p1.stdout.close()* après le démarrage de *p2* est important
pour que *p1* reçoive un *SIGPIPE* si *p2* se termine avant lui.

Alternativement, pour des entrées fiables, la gestion des tubes du
*shell* peut directement être utilisé :

   output=`dmesg | grep hda`

devient :

   output=check_output("dmesg | grep hda", shell=True)


17.5.6.3. Remplacer "os.system()"
---------------------------------

   sts = os.system("mycmd" + " myarg")
   # becomes
   sts = call("mycmd" + " myarg", shell=True)

Notes :

* Appeler le programme à travers un *shell* n'est habituellement pas
  requis.

Un exemple plus réaliste ressemblerait à cela :

   try:
       retcode = call("mycmd" + " myarg", shell=True)
       if retcode < 0:
           print("Child was terminated by signal", -retcode, file=sys.stderr)
       else:
           print("Child returned", retcode, file=sys.stderr)
   except OSError as e:
       print("Execution failed:", e, file=sys.stderr)


17.5.6.4. Remplacer les fonctions de la famille "os.spawn"
----------------------------------------------------------

Exemple avec *P_NOWAIT* :

   pid = os.spawnlp(os.P_NOWAIT, "/bin/mycmd", "mycmd", "myarg")
   ==>
   pid = Popen(["/bin/mycmd", "myarg"]).pid

Exemple avec *P_WAIT* :

   retcode = os.spawnlp(os.P_WAIT, "/bin/mycmd", "mycmd", "myarg")
   ==>
   retcode = call(["/bin/mycmd", "myarg"])

Exemple avec un tableau :

   os.spawnvp(os.P_NOWAIT, path, args)
   ==>
   Popen([path] + args[1:])

Exemple en passant un environnement :

   os.spawnlpe(os.P_NOWAIT, "/bin/mycmd", "mycmd", "myarg", env)
   ==>
   Popen(["/bin/mycmd", "myarg"], env={"PATH": "/usr/bin"})


17.5.6.5. Remplacer "os.popen()", "os.popen2()", "os.popen3()"
--------------------------------------------------------------

   (child_stdin, child_stdout) = os.popen2(cmd, mode, bufsize)
   ==>
   p = Popen(cmd, shell=True, bufsize=bufsize,
             stdin=PIPE, stdout=PIPE, close_fds=True)
   (child_stdin, child_stdout) = (p.stdin, p.stdout)

   (child_stdin,
    child_stdout,
    child_stderr) = os.popen3(cmd, mode, bufsize)
   ==>
   p = Popen(cmd, shell=True, bufsize=bufsize,
             stdin=PIPE, stdout=PIPE, stderr=PIPE, close_fds=True)
   (child_stdin,
    child_stdout,
    child_stderr) = (p.stdin, p.stdout, p.stderr)

   (child_stdin, child_stdout_and_stderr) = os.popen4(cmd, mode, bufsize)
   ==>
   p = Popen(cmd, shell=True, bufsize=bufsize,
             stdin=PIPE, stdout=PIPE, stderr=STDOUT, close_fds=True)
   (child_stdin, child_stdout_and_stderr) = (p.stdin, p.stdout)

La gestion du code de retour se traduit comme suit :

   pipe = os.popen(cmd, 'w')
   ...
   rc = pipe.close()
   if rc is not None and rc >> 8:
       print("There were some errors")
   ==>
   process = Popen(cmd, stdin=PIPE)
   ...
   process.stdin.close()
   if process.wait() != 0:
       print("There were some errors")


17.5.6.6. Remplacer les fonctions du module "popen2"
----------------------------------------------------

Note:

  Si l'argument *cmd* des fonctions de *popen2* est une chaîne de
  caractères, la commande est exécutée à travers */bin/sh*.  Si c'est
  une liste, la commande est directement exécutée.

   (child_stdout, child_stdin) = popen2.popen2("somestring", bufsize, mode)
   ==>
   p = Popen("somestring", shell=True, bufsize=bufsize,
             stdin=PIPE, stdout=PIPE, close_fds=True)
   (child_stdout, child_stdin) = (p.stdout, p.stdin)

   (child_stdout, child_stdin) = popen2.popen2(["mycmd", "myarg"], bufsize, mode)
   ==>
   p = Popen(["mycmd", "myarg"], bufsize=bufsize,
             stdin=PIPE, stdout=PIPE, close_fds=True)
   (child_stdout, child_stdin) = (p.stdout, p.stdin)

"popen2.Popen3" et "popen2.Popen4" fonctionnent basiquement comme
"subprocess.Popen", excepté que :

* "Popen" lève une exception si l'exécution échoue.

* L'argument *capturestderr* est remplacé par *stderr*.

* "stdin=PIPE" et "stdout=PIPE" doivent être spécifiés.

* *popen2* ferme tous les descripteurs de fichiers par défaut, mais
  vous devez spécifier "close_fds=True" avec "Popen" pour garantir ce
  comportement sur toutes les plateformes ou les anciennes versions de
  Python.


17.5.7. Remplacement des fonctions originales d'invocation du *shell*
=====================================================================

Ce module fournit aussi les fonctions suivantes héritées du module
"commands" de Python 2.x. Ces opérations invoquent implicitement le
*shell* du système et n'apportent aucune des garanties décrites ci-
dessus par rapport à la sécurité ou la cohérence de la gestion des
exceptions.

subprocess.getstatusoutput(cmd)

   Renvoie les valeurs "(exitcode, output)" de l'exécution de *cmd*
   dans un *shell*.

   Exécute la chaîne *cmd* dans un *shell* avec "Popen.check_output()"
   et renvoie un *tuple* de 2 éléments "(exitcode, output)".
   L'encodage local est utilisé, voir les notes de la section
   Arguments fréquemment utilisés pour plus de détails.

   Si la sortie se termine par un caractère de fin de ligne, ce
   dernier est supprimé. Le code de statut de la commande peut être
   interprété comme le code de retour de *subprocess*.  Par exemple :

      >>> subprocess.getstatusoutput('ls /bin/ls')
      (0, '/bin/ls')
      >>> subprocess.getstatusoutput('cat /bin/junk')
      (1, 'cat: /bin/junk: No such file or directory')
      >>> subprocess.getstatusoutput('/bin/junk')
      (127, 'sh: /bin/junk: not found')
      >>> subprocess.getstatusoutput('/bin/kill $$')
      (-15, '')

   Disponibilité : POSIX et Windows

   Modifié dans la version 3.3.4: Ajout de la gestion de Windows.The
   function now returns (exitcode, output) instead of (status, output)
   as it did in Python 3.3.3 and earlier.  exitcode has the same value
   as "returncode".

subprocess.getoutput(cmd)

   Renvoie la sortie (standard et d'erreur) de l'exécution de *cmd*
   dans un *shell*.

   Like "getstatusoutput()", except the exit code is ignored and the
   return value is a string containing the command's output.  Example:

      >>> subprocess.getoutput('ls /bin/ls')
      '/bin/ls'

   Disponibilité : POSIX et Windows

   Modifié dans la version 3.3.4: Ajout de la gestion de Windows


17.5.8. Notes
=============


17.5.8.1. Convertir une séquence d'arguments vers une chaîne de caractères sous Windows
---------------------------------------------------------------------------------------

Sous Windows, une séquence *args* est convertie vers une chaîne qui
peut être analysée avec les règles suivantes (qui correspondent aux
règles utilisées par l'environnement *MS C*) :

1. Les arguments sont délimités par des espacements, qui peuvent être
   des espaces ou des tabulations.

2. Une chaîne entourée de double guillemets est interprétée comme un
   argument seul, qu'elle contienne ou non des espacements.  Une
   chaîne entre guillemets peut être intégrée dans un argument.

3. Un guillemet double précédé d'un *backslash* est interprété comme
   un guillemet double littéral.

4. Les *backslashs* sont interprétés littéralement, à moins qu'ils
   précèdent immédiatement un guillemet double.

5. Si des *backslashs* précèdent directement un guillemet double,
   toute paire de *backslashs* est interprétée comme un *backslash*
   littéral.  Si le nombre de *backslashs* est impair, le dernier
   *backslash* échappe le prochain guillemet double comme décrit en
   règle 3.

Voir aussi:

  "shlex"
     Module qui fournit des fonctions pour analyser et échapper les
     lignes de commandes.
