Sous-processus
**************

**Code source :** Lib/asyncio/subprocess.py,
Lib/asyncio/base_subprocess.py

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

Cette section décrit des API de haut niveau de *asyncio* pour créer et
gérer des sous-processus via "async"/"await".

Voici un exemple de comment *asyncio* peut lancer une commande shell
et obtenir son résultat :

   import asyncio

   async def run(cmd):
       proc = await asyncio.create_subprocess_shell(
           cmd,
           stdout=asyncio.subprocess.PIPE,
           stderr=asyncio.subprocess.PIPE)

       stdout, stderr = await proc.communicate()

       print(f'[{cmd!r} exited with {proc.returncode}]')
       if stdout:
           print(f'[stdout]\n{stdout.decode()}')
       if stderr:
           print(f'[stderr]\n{stderr.decode()}')

   asyncio.run(run('ls /zzz'))

affiche :

   ['ls /zzz' exited with 1]
   [stderr]
   ls: /zzz: No such file or directory

Puisque toutes les fonctions à sous-processus d'*asyncio* sont
synchrones et qu'*asyncio* fournit de nombreux outils pour travailler
avec de telles fonctions, il est facile d'exécuter et de surveiller de
nombreux processus  en parallèle. Il est en effet trivial de modifier
l'exemple ci-dessus pour exécuter plusieurs commandes simultanément :

   async def main():
       await asyncio.gather(
           run('ls /zzz'),
           run('sleep 1; echo "hello"'))

   asyncio.run(main())

Voir également la section Exemples.


Créer des sous-processus
========================

coroutine asyncio.create_subprocess_exec(program, *args, stdin=None, stdout=None, stderr=None, limit=None, **kwds)

   Crée un sous-processus.

   The *limit* argument sets the buffer limit for "StreamReader"
   wrappers for "Process.stdout" and "Process.stderr" (if
   "subprocess.PIPE" is passed to *stdout* and *stderr* arguments).

   Renvoie une instance de "Process".

   Voir la documentation de "loop.subprocess_exec()" pour d'autres
   paramètres.

   Modifié dans la version 3.10: suppression du paramètre *loop*.

coroutine asyncio.create_subprocess_shell(cmd, stdin=None, stdout=None, stderr=None, limit=None, **kwds)

   Exécute la commande *cmd* dans un *shell*.

   The *limit* argument sets the buffer limit for "StreamReader"
   wrappers for "Process.stdout" and "Process.stderr" (if
   "subprocess.PIPE" is passed to *stdout* and *stderr* arguments).

   Renvoie une instance de "Process".

   Voir la documentation de "loop.subprocess_shell()" pour d'autres
   paramètres.

   Important:

     Il est de la responsabilité de l'application de s'assurer que
     tous les espaces et les caractères spéciaux sont correctement mis
     entre guillemets pour éviter les vulnérabilités de type injection
     de code. La fonction "shlex.quote()" peut être utilisée pour
     l’échappement des espaces et caractères spéciaux dans les chaînes
     utilisées pour construire des commandes shell.

   Modifié dans la version 3.10: suppression du paramètre *loop*.

Note:

  les sous-processus sont disponibles pour Windows si un
  "ProactorEventLoop" est utilisé. Voir Support des sous-processus
  sous Windows pour plus de précisions.

Voir aussi:

  *asyncio* propose aussi les API de « bas niveau » suivantes pour
  travailler avec les sous-processus : "loop.subprocess_exec()",
  "loop.subprocess_shell()", "loop.connect_read_pipe()",
  "loop.connect_write_pipe()", ainsi que les Transports entre sous-
  processus et Protocoles liés aux sous-processus.


Constantes
==========

asyncio.subprocess.PIPE

   Peut être passé aux paramètres  *stdin*, *stdout* ou *stderr*.

   Si *PIPE* est passé au paramètre *stdin*, l'attribut
   "Process.stdin" ne pointera pas vers une instance de
   "StreamWriter".

   Si *PIPE* est passé au paramètre *stdout* ou *stderr*, l'attribut
   "Process.stdout" et "Process.stderr" pointeront vers des instances
   de "StreamReader".

asyncio.subprocess.STDOUT

   Une valeur spéciale qui peut être passée au paramètre *stderr* et
   qui indique que la sortie d'erreur doit être redirigée vers la
   sortie standard.

asyncio.subprocess.DEVNULL

   Une valeur spéciale qui peut être passée à l'argument *stdin*,
   *stdout* ou *stderr* des fonctions créant des processus. Elle
   implique l'utilisation du fichier "os.devnull" pour le flux
   correspondant du processus.


Interagir avec les sous-processus
=================================

Les fonctions "create_subprocess_exec()" et
"create_subprocess_shell()" renvoient des instances de la classe
*Process*. *Process* est une enveloppe de haut niveau qui permet de
communiquer avec les sous-processus et de surveiller leur achèvement.

class asyncio.subprocess.Process

   Objet qui encapsule les processus du système d'exploitation créés
   par les fonctions "create_subprocess_exec()" et
   "create_subprocess_shell()".

   Cette classe est conçue pour avoir une API similaire à la classe
   "subprocess.Popen", mais il existe quelques différences notables :

   * contrairement à *Popen*, les instances Process n'ont pas
     d'équivalent à la méthode "poll()" ;

   * les méthodes "communicate()" et "wait()" n'ont pas de paramètre
     *timeout* : utilisez la fonction "wait_for()" ;

   * "asyncio.subprocess.Process.wait()" est asynchrone, tandis que la
     méthode "subprocess.Popen.wait()" est implémentée comme une
     boucle bloquante ;

   * le paramètre *universal_newlines* n'est pas pris en charge.

   Cette classe n'est pas conçue pour un contexte multi-fils.

   Voir aussi la section sous-processus et fils d'exécution.

   coroutine wait()

      Attend que le sous processus s'arrête.

      Définit et renvoie l'attribut "returncode".

      Note:

        cette méthode peut générer un interblocage quand "stdout=PIPE"
        ou "stderr=PIPE" est utilisé et que le sous-processus génère
        tellement de sorties qu'il se bloque, dans l'attente que le
        tampon du tube côté OS accepte des données supplémentaires.
        Pour éviter cette situation, choisissez la méthode
        "communicate()" quand vous utilisez des tubes.

   coroutine communicate(input=None)

      Interagit avec le processus :

      1. envoie des données sur le *stdin* (si *input* n'est pas
         "None") ;

      2. lit les données sur *stdout* et *stderr*, jusqu'à ce que le
         EOF soit atteint ;

      3. attend que le processus s'arrête.

      Le paramètre optionnel *input* (objet de type "bytes")
      représente les données transmises au sous-processus.

      Renvoie un *n*-uplet "(stdout_data, stderr_data)".

      Si l'une des exceptions "BrokenPipeError" ou
      "ConnectionResetError" est levée lors de l'écriture de *input*
      dans *stdin*, l'exception est ignorée. Cette condition se
      produit lorsque le processus se termine avant que toutes les
      données ne soient écrites dans *stdin*.

      Si vous souhaitez envoyer des données au processus *stdin*, le
      processus doit être créé avec "stdin=PIPE". De même, pour
      obtenir autre chose que "None" dans le *n*-uplet résultat, le
      processus doit être créé avec les arguments "stdout=PIPE" et/ou
      "stderr=PIPE".

      Notez que 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.

   send_signal(signal)

      Envoie le signal *signal* au sous-processus.

      Note:

        On Windows, "SIGTERM" is an alias for "terminate()".
        "CTRL_C_EVENT" and "CTRL_BREAK_EVENT" can be sent to processes
        started with a *creationflags* parameter which includes
        "CREATE_NEW_PROCESS_GROUP".

   terminate()

      Arrête le sous-processus.

      On POSIX systems this method sends "SIGTERM" to the child
      process.

      On Windows the Win32 API function "TerminateProcess()" is called
      to stop the child process.

   kill()

      Arrête le sous-processus.

      Sur les systèmes POSIX, cette méthode envoie "signal.SIGTERM" au
      sous-processus.

      Sous Windows, cette méthode est un alias pour "terminate()".

   stdin

      Flux d'entrée standard ("StreamWriter") ou "None" si le
      processus a été créé avec "stdin=None".

   stdout

      Flux de sortie standard ("StreamReader") ou "None" si le
      processus a été créé avec "stdout=None".

   stderr

      Flux d'erreur standard ("StreamReader") ou "None" si le
      processus a été créé avec "stderr=None".

   Avertissement:

     utilisez la méthode "communicate()" plutôt que
     "process.stdin.write()", "wait process.stdout.read()" ou "wait
     process.stderr.read()". Cela évite les interblocages dus aux flux
     qui interrompent la lecture ou l'écriture et bloquent le
     processus enfant.

   pid

      Numéro d'identification du processus (PID, pour *Process
      Identification Number* en anglais).

      Notez que pour les processus créés par la fonction
      "create_subprocess_shell()", cet attribut est le PID du shell
      généré.

   returncode

      Code de retour du processus quand il se termine.

      Une valeur "None" indique que le processus n'est pas encore
      terminé.

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


Sous-processus et fils d'exécution
----------------------------------

La boucle d'événement asynchrone standard prend en charge l'exécution
de sous-processus à partir de différents fils d'exécution par défaut.

Sous Windows, les sous-processus sont fournis par "ProactorEventLoop"
uniquement (par défaut), "SelectorEventLoop" ne prend pas en charge
les sous-processus.

Sous UNIX, les *observateurs d'enfants (child watchers)* sont utilisés
pour l'attente de fin de sous-processus, voir Observateurs de
processus pour plus d'informations.

Modifié dans la version 3.8: UNIX est passé à l'utilisation de
"ThreadedChildWatcher" pour générer des sous-processus à partir de
différents threads sans aucune limitation.Instancier un sous-processus
avec un observateur enfant actuel *inactif* lève l'exception
"RuntimeError".

Notez que ces implémentations alternatives de la boucle d'événements
peuvent comporter leurs propres limitations. Veuillez vous référer à
leur documentation.

Voir aussi:

  la section Exécution concurrente et multi-fils d'exécution.


Exemples
--------

Un exemple utilisant la classe "Process" pour contrôler un sous-
processus et la classe "StreamReader" pour lire sa sortie standard.

Le sous-processus est créé par la fonction "create_subprocess_exec()"
:

   import asyncio
   import sys

   async def get_date():
       code = 'import datetime; print(datetime.datetime.now())'

       # Create the subprocess; redirect the standard output
       # into a pipe.
       proc = await asyncio.create_subprocess_exec(
           sys.executable, '-c', code,
           stdout=asyncio.subprocess.PIPE)

       # Read one line of output.
       data = await proc.stdout.readline()
       line = data.decode('ascii').rstrip()

       # Wait for the subprocess exit.
       await proc.wait()
       return line

   date = asyncio.run(get_date())
   print(f"Current date: {date}")

Voir également le même exemple, écrit en utilisant des API de bas
niveau.
