# 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

async 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 `stdout` and `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.

  If the process object is garbage collected while the process is still running, the child process will be killed.

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

async 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 `stdout` and `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.

  If the process object is garbage collected while the process is still running, the child process will be killed.

  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.

  If PIPE is passed to stdin argument, the `Process.stdin` attribute will point to a `StreamWriter` instance.

  If PIPE is passed to stdout or stderr arguments, the `Process.stdout` and `Process.stderr` attributes will point to `StreamReader` instances.

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

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

  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.

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

  async communicate(input=None)

    Interagit avec le processus :

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

    2. closes stdin;

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

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

    Modifié dans la version 3.12: stdin gets closed when `input=None` too.

  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.

    On POSIX systems this method sends `SIGKILL` to the child process.

    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

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

    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.

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

    For processes created with `create_subprocess_exec()`, a negative value `-N` indicates that the child was terminated by signal `N` (POSIX only).

    For processes created with `create_subprocess_shell()`, the return code reflects the exit status of the shell itself (e.g. `/bin/sh`), which may map signals to codes such as `128+N`. See the documentation of the shell (for example, the Bash manual's Exit Status) for details.

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

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 as dt; print(dt.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.