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

**Source code:** 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'))

will print:

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

Because all asyncio subprocess functions are asynchronous and asyncio
provides many tools to work with such functions, it is easy to execute
and monitor multiple subprocesses in parallel.  It is indeed trivial
to modify the above example to run several commands simultaneously:

   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.

   Le paramètre *limit* définit la taille maximale du tampon pour les
   instances de "StreamReader" encapsulant "Process.stdout" et
   "Process.stderr" (Si "subprocess.PIPE" est passé aux paramètres
   *stdout* et *stderr*).

   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*.

   Le paramètre *limit* définit la taille maximale du tampon pour les
   instances de "StreamReader" encapsulant "Process.stdout" et
   "Process.stderr" (Si "subprocess.PIPE" est passé aux paramètres
   *stdout* et *stderr*).

   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 also has the following *low-level* APIs to work with
  subprocesses: "loop.subprocess_exec()", "loop.subprocess_shell()",
  "loop.connect_read_pipe()", "loop.connect_write_pipe()", as well as
  the Subprocess Transports and Subprocess Protocols.


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

Both "create_subprocess_exec()" and "create_subprocess_shell()"
functions return instances of the *Process* class.  *Process* is a
high-level wrapper that allows communicating with subprocesses and
watching for their completion.

class asyncio.subprocess.Process

   An object that wraps OS processes created by the
   "create_subprocess_exec()" and "create_subprocess_shell()"
   functions.

   This class is designed to have a similar API to the
   "subprocess.Popen" class, but there are some notable differences:

   * unlike Popen, Process instances do not have an equivalent to the
     "poll()" method;

   * the "communicate()" and "wait()" methods don't have a *timeout*
     parameter: use the "wait_for()" function;

   * the "Process.wait()" method is asynchronous, whereas
     "subprocess.Popen.wait()" method is implemented as a blocking
     busy loop;

   * 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 tuple "(stdout_data, stderr_data)".

      If either "BrokenPipeError" or "ConnectionResetError" exception
      is raised when writing *input* into *stdin*, the exception is
      ignored.  This condition occurs when the process exits before
      all data are written into *stdin*.

      If it is desired to send data to the process' *stdin*, the
      process needs to be created with "stdin=PIPE".  Similarly, to
      get anything other than "None" in the result tuple, the process
      has to be created with "stdout=PIPE" and/or "stderr=PIPE"
      arguments.

      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:

        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".

   terminate()

      Arrête le sous-processus.

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

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

   kill()

      Kill the child process.

      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

      Standard input stream ("StreamWriter") or "None" if the process
      was created with "stdin=None".

   stdout

      Standard output stream ("StreamReader") or "None" if the process
      was created with "stdout=None".

   stderr

      Standard error stream ("StreamReader") or "None" if the process
      was created with "stderr=None".

   Avertissement:

     Use the "communicate()" method rather than
     "process.stdin.write()", "await process.stdout.read()" or "await
     process.stderr.read()". This avoids deadlocks due to streams
     pausing reading or writing and blocking the child process.

   pid

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

      Note that for processes created by the
      "create_subprocess_shell()" function, this attribute is the PID
      of the spawned shell.

   returncode

      Code de retour du processus quand il se termine.

      A "None" value indicates that the process has not terminated
      yet.

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


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

Standard asyncio event loop supports running subprocesses from
different threads by default.

On Windows subprocesses are provided by "ProactorEventLoop" only
(default), "SelectorEventLoop" has no subprocess support.

On UNIX *child watchers* are used for subprocess finish waiting, see
Observateurs de processus for more info.

Modifié dans la version 3.8: UNIX switched to use
"ThreadedChildWatcher" for spawning subprocesses from different
threads without any 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.
