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 forProcess.stdout
andProcess.stderr
(ifsubprocess.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 forProcess.stdout
andProcess.stderr
(ifsubprocess.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 deStreamWriter
.Si PIPE est passé au paramètre stdout ou stderr, l'attribut
Process.stdout
etProcess.stderr
pointeront vers des instances deStreamReader
.
- 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()
etcreate_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()
etwait()
n'ont pas de paramètre timeout : utilisez la fonctionwait_for()
;asyncio.subprocess.Process.wait()
est asynchrone, tandis que la méthodesubprocess.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
oustderr=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éthodecommunicate()
quand vous utilisez des tubes.
- coroutine communicate(input=None)¶
Interagit avec le processus :
envoie des données sur le stdin (si input n'est pas
None
) ;closes stdin;
lit les données sur stdout et stderr, jusqu'à ce que le EOF soit atteint ;
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
ouConnectionResetError
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 queNone
dans le n-uplet résultat, le processus doit être créé avec les argumentsstdout=PIPE
et/oustderr=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 forterminate()
.CTRL_C_EVENT
andCTRL_BREAK_EVENT
can be sent to processes started with a creationflags parameter which includesCREATE_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
) ouNone
si le processus a été créé avecstdin=None
.
- stdout¶
Flux de sortie standard (
StreamReader
) ouNone
si le processus a été créé avecstdout=None
.
- stderr¶
Flux d'erreur standard (
StreamReader
) ouNone
si le processus a été créé avecstderr=None
.
Avertissement
utilisez la méthode
communicate()
plutôt queprocess.stdin.write()
,wait process.stdout.read()
ouwait 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 signalN
(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.