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