17.5. subprocess — Gestion de sous-processus

Code source : Lib/subprocess.py

Le module subprocess vous permet de lancer de nouveaux processus, les connecter à des tubes d’entrée/sortie/erreur, et d’obtenir leurs codes de retour. Ce module a l’intention de remplacer plusieurs anciens modules et fonctions :

os.system
os.spawn*

De plus amples informations sur comment le module subprocess peut être utilisé pour remplacer ces modules et fonctions peuvent être trouvées dans les sections suivantes.

Voir aussi

PEP 324 – PEP proposant le module subprocess

17.5.1. Utiliser le module subprocess

L’approche recommandée pour invoquer un sous-processus et d’utiliser la fonction run() pour tous les cas d’utilisation qu’il supporte. Pour les cas d’utilisation plus avancés, l’interface inhérente Popen peut être utilisée directement.

La fonction run() a été ajoutée avec Python 3.5 ; si vous avez besoin d’une compatibilité avec des versions plus anciennes, référez-vous à la section Ancienne interface (API) haut-niveau.

subprocess.run(args, *, stdin=None, input=None, stdout=None, stderr=None, shell=False, timeout=None, check=False)

Lance la commande décrite par args. Attend que la commande se termine, puis renvoie une instance CompletedProcess.

Les arguments présentés ci-dessus sont simplement les plus utilisés, décrits ci-dessous dans la section Arguments fréquemment utilisés (d’où l’utilisation de la notation keyword-only dans la signature abrégée). La signature complète de la fonction est sensiblement la même que celle du constructeur de Popen - à l’exception de timeout, input et check, tous les arguments donnés à cette fonction passent à travers cette interface.

Les sorties standard (stdout) et d’erreur (stderr) ne sont pas capturées par défaut. Pour les capturer, utilisez PIPE comme valeur des arguments stdout et/ou stderr.

L’argument timeout est passé à Popen.communicate(). Si le timeout expire, le processus enfant sera tué et attendu. Une exception TimeoutExpired sera levée une fois que le processus enfant se sera terminé.

The input argument is passed to Popen.communicate() and thus to the subprocess’s stdin. If used it must be a byte sequence, or a string if universal_newlines=True. When used, the internal Popen object is automatically created with stdin=PIPE, and the stdin argument may not be used as well.

Si check est vrai, et que le processus s’arrête avec un code de statut non nul, une exception CalledProcessError est levée. Les attributs de cette exception contiennent les arguments, le code de statut, et les sorties standard et d’erreur si elles ont été capturées.

Exemples :

>>> subprocess.run(["ls", "-l"])  # doesn't capture output
CompletedProcess(args=['ls', '-l'], returncode=0)

>>> subprocess.run("exit 1", shell=True, check=True)
Traceback (most recent call last):
  ...
subprocess.CalledProcessError: Command 'exit 1' returned non-zero exit status 1

>>> subprocess.run(["ls", "-l", "/dev/null"], stdout=subprocess.PIPE)
CompletedProcess(args=['ls', '-l', '/dev/null'], returncode=0,
stdout=b'crw-rw-rw- 1 root root 1, 3 Jan 23 16:23 /dev/null\n')

Nouveau dans la version 3.5.

class subprocess.CompletedProcess

La valeur de retour de run(), représentant un processus qui s’est terminé.

args

Les arguments utilisés pour lancer le processus. Cela peut être une liste ou une chaîne de caractères.

returncode

Le code de statut du processus fils. Typiquement, un code de statut de 0 indique qu’il s’est exécuté avec succès.

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

stdout

Captured stdout from the child process. A bytes sequence, or a string if run() was called with universal_newlines=True. None if stdout was not captured.

Si vous avez lancé le processus avec stderr=subprocess.STDOUT, les sorties standard et d’erreur seront combinées dans cet attribut, et stderr sera mis à None.

stderr

Captured stderr from the child process. A bytes sequence, or a string if run() was called with universal_newlines=True. None if stderr was not captured.

check_returncode()

Si returncode n’est pas nul, lève une CalledProcessError.

Nouveau dans la version 3.5.

subprocess.DEVNULL

Valeur spéciale qui peut être utilisée pour les arguments stdin, stdout ou stderr de Popen et qui indique que le fichier spécial os.devnull sera utilisé.

Nouveau dans la version 3.3.

subprocess.PIPE

Valeur spéciale qui peut être utilisée pour les arguments stdin, stdout ou stderr de Popen et qui indique qu’un tube vers le flux standard doit être ouvert. Surtout utile avec Popen.communicate().

subprocess.STDOUT

Valeur spéciale qui peut être utilisée pour l’argument stderr de Popen et qui indique que la sortie d’erreur doit être redirigée vers le même gestionnaire que la sortie standard.

exception subprocess.SubprocessError

Classe de base à toutes les autres exceptions du module.

Nouveau dans la version 3.3.

exception subprocess.TimeoutExpired

Sous-classe de SubprocessError, levée quand un timeout expire pendant l’attente d’un processus enfant.

cmd

La commande utilisée pour instancier le processus fils.

timeout

Le timeout en secondes.

output

La sortie du processus fils, si capturée par run() ou check_output(). Autrement, None.

stdout

Alias pour output, afin d’avoir une symétrie avec stderr.

stderr

La sortie d’erreur du processus fils, si capturée par run(). Autrement, None.

Nouveau dans la version 3.3.

Modifié dans la version 3.5: Ajout des attributs stdout et stderr.

exception subprocess.CalledProcessError

Sous-classe de SubprocessError, levée quand un processus lancé par check_call() ou check_output() renvoie un code de statut non nul.

returncode

Code de statut du processus fils. Si le processus a été arrêté par un signal, le code sera négatif et correspondra à l’opposé du numéro de signal.

cmd

La commande utilisée pour instancier le processus fils.

output

La sortie du processus fils, si capturée par run() ou check_output(). Autrement, None.

stdout

Alias pour output, afin d’avoir une symétrie avec stderr.

stderr

La sortie d’erreur du processus fils, si capturée par run(). Autrement, None.

Modifié dans la version 3.5: Ajout des attributs stdout et stderr.

17.5.1.1. Arguments fréquemment utilisés

Pour supporter un large ensemble de cas, la constructeur de Popen (et les fonctions de convenance) acceptent de nombreux arguments optionnels. Pour les cas d’utilisation les plus typiques, beaucoup de ces arguments peuvent sans problème être laissés à leurs valeurs par défaut. Les arguments les plus communément nécessaires sont :

args est requis pour tous les appels et doit être une chaîne de caractères ou une séquence d’arguments du programme. Il est généralement préférable de fournir une séquence d’arguments, puisque cela permet au module de s’occuper des potentiels échappements ou guillemets autour des arguments (p. ex. pour permettre des espaces dans des noms de fichiers). Si l’argument est passé comme une simple chaîne, soit shell doit valoir True (voir ci-dessous) soit la chaîne doit simplement contenir le nom du programme à exécuter sans spécifier d’arguments supplémentaires.

stdin, stdout et stderr spécifient respectivement les gestionnaires d’entrée standard, de sortie standard et de sortie d’erreur du programme exécuté. Les valeurs acceptées sont PIPE, DEVNULL, un descripteur de fichier existant (nombre entier positif), un objet de fichier, et None. PIPE indique qu’un nouveau tube vers le processus enfant sera créé. DEVNULL indique que le fichier spécial os.devnull sera utilisé. Avec les paramètres None par défaut, aucune redirection ne se produira, les gestionnaires de fichiers du fils seront hérités du parent. Additionnellement, stderr peut valoir STDOUT, qui indique que les données de la sortie d’erreur du processus fils doivent être capturées dans le même gestionnaire de fichier que la sortie standard.

If universal_newlines is False the file objects stdin, stdout and stderr will be opened as binary streams, and no line ending conversion is done.

If universal_newlines is True, these file objects will be opened as text streams in universal newlines mode using the encoding returned by locale.getpreferredencoding(False). For stdin, line ending characters '\n' in the input will be converted to the default line separator os.linesep. For stdout and stderr, all line endings in the output will be converted to '\n'. For more information see the documentation of the io.TextIOWrapper class when the newline argument to its constructor is None.

Note

L’attribut newlines des objets Popen.stdin, Popen.stdout et Popen.stderr ne sont pas mis à jour par la méthode Popen.communicate().

Si shell vaut True, la commande spécifiée sera exécutée à travers un shell. Cela peut être utile si vous utilisez Python pour le contrôle de flot qu’il propose par rapport à beaucoup de shells système et voulez tout de même profiter des autres fonctionnalités des shells telles que les tubes (pipes), les motifs de fichiers, l’expansion des variables d’environnement, et l’expansion du ~ vers le répertoire principal de l’utilisateur. Cependant, notez que Python lui-même propose l’implémentation de beaucoup de ces fonctionnalités (en particulier glob, fnmatch, os.walk(), os.path.expandvars(), os.path.expanduser() et shutil).

Modifié dans la version 3.3: Quand universal_newlines vaut True, la classe utilise l’encodage locale.getpreferredencoding(False) plutôt que locale.getpreferredencoding(). Voir la classe io.TextIOWrapper pour plus d’informations sur ce changement.

Note

Lire la section Security Considerations avant d’utiliser shell=True.

Ces options, ainsi que toutes les autres, sont décrites plus en détails dans la documentation du constructeur de Popen.

17.5.1.2. Constructeur de Popen

La création et la gestion sous-jacentes des processus est gérée par la classe Popen. Elle offre beaucoup de flexibilité de façon à ce que les développeurs soient capables de gérer les cas d’utilisation les moins communs, non couverts par les fonctions de convenance.

class subprocess.Popen(args, bufsize=-1, executable=None, stdin=None, stdout=None, stderr=None, preexec_fn=None, close_fds=True, shell=False, cwd=None, env=None, universal_newlines=False, startupinfo=None, creationflags=0, restore_signals=True, start_new_session=False, pass_fds=())

Exécute un programme fils dans un nouveau processus. Sur les systèmes POSIX, la classe utilise un comportement similaire à os.execvp() pour exécuter le programme. Sur Windows, la classe utilise la fonction Windows CreateProcess(). Les arguments de Popen sont les suivants.

args doit être une séquence d’arguments du programme ou une chaîne seule. Par défaut, le programme à exécuter est le premier élément de args si args est une séquence. Si args est une chaîne, l’interprétation dépend de la plateforme et est décrite plus bas. Voir les arguments shell et executable pour d’autres différences avec le comportement par défaut. Sans autre indication, il est recommandé de passer args comme une séquence.

Sur les systèmes POSIX, si args est une chaîne, elle est interprétée comme le nom ou le chemin du programme à exécuter. Cependant, cela ne peut être fait que si le programme est passé sans arguments.

Note

shlex.split() peut être utilisée pour déterminer le découpage correct de args, spécifiquement dans les cas complexes :

>>> import shlex, subprocess
>>> command_line = input()
/bin/vikings -input eggs.txt -output "spam spam.txt" -cmd "echo '$MONEY'"
>>> args = shlex.split(command_line)
>>> print(args)
['/bin/vikings', '-input', 'eggs.txt', '-output', 'spam spam.txt', '-cmd', "echo '$MONEY'"]
>>> p = subprocess.Popen(args) # Success!

Notez en particulier que les options (comme -input) et arguments (comme eggs.txt) qui sont séparés par des espaces dans le shell iront dans des éléments séparés de la liste, alors que les arguments qui nécessitent des guillemets et échappements quand utilisés dans le shell (comme les noms de fichiers contenant des espaces ou la commande echo montrée plus haut) forment des éléments uniques.

Sous Windows, si args est une séquence, elle sera convertie vers une chaîne de caractères de la manière décrite dans Convertir une séquence d’arguments vers une chaîne de caractères sous Windows. Cela fonctionne ainsi parce que la fonction CreateProcess() opère sur des chaînes.

L’argument shell (qui vaut False par défaut) spécifie s’il faut utiliser un shell comme programme à exécuter. Si shell vaut True, il est recommandé de passer args comme une chaîne de caractères plutôt qu’une séquence.

Sur les systèmes POSIX avec shell=True, le shell par défaut est /bin/sh. Si args est une chaîne de caractères, la chaîne spécifie la commande à exécuter à travers le shell. Cela signifie que la chaîne doit être formatée exactement comme elle le serait si elle était tapée dans l’invite de commandes du shell. Cela inclut, par exemple, les guillemets ou les backslashs échappant les noms de fichiers contenant des espaces. Si args est une séquence, le premier élément spécifie la commande, et les éléments supplémentaires seront traités comme des arguments additionnels à passer au shell lui-même. Pour ainsi dire, Popen réalise l’équivalent de :

Popen(['/bin/sh', '-c', args[0], args[1], ...])

Sous Windows avec shell=True, la variable d’environnement COMSPEC spécifie le shell par défaut. La seule raison pour laquelle vous devriez spécifier shell=True sous Windows est quand la commande que vous souhaitez exécuter est une built-in du shell (p. ex. dir ou copy). Vous n’avez pas besoin de shell=True pour lancer un fichier batch ou un exécutable console.

Note

Lire la section Security Considerations avant d’utiliser shell=True.

bufsize sera fourni comme l’argument correspondant à la fonction open(), lors de la création des objets de fichiers pour les tubes stdin/stdout/stderr.

  • 0 indique de ne pas utiliser de tampon (les lectures et écritures sont des appels systèmes et peuvent renvoyer des données incomplètes) ;
  • 1 indique une mise en cache par ligne (utilisable seulement si universal_newlines=True, c’est à dire en mode texte) ;
  • toutes les autres valeurs positives indiquent d’utiliser un tampon d’approximativement cette taille ;
  • un bufsize négatif (par défaut) indique au système d’utiliser la valeur par défaut io.DEFAULT_BUFFER_SIZE.

Modifié dans la version 3.3.1: bufsize vaut maintenant -1 par défaut, pour activer par défaut la mise en cache et correspondre au comportement attendu par la plupart des codes. Dans les versions de Python antérieures à 3.2.4 et 3.3.1, par erreur, la valeur par défaut était 0 qui ne réalisait aucune mise en cache et autorisait les lectures incomplètes. Cela n’était pas intentionnel et ne correspondait pas au comportement de Python 2 attendu par la plupart des codes.

L’argument executable spécifie un programme de remplacement à exécuter. Il est très rarement nécessaire. Quand shell=False, executable remplace le programme à exécuter spécifié par args. Cependant, les arguments originels d”args` sont toujours passés au programme. La plupart des programmes traitent le programme spécifié par *args comme le nom de la commande, qui peut être différent du programme réellement exécuté. Sur les systèmes POSIX, le nom tiré d”args devient le nom affiché pour l’exécutable dans des utilitaires tels que ps. Si shell=True, sur les systèmes POSIX, l’argument executable précise le shell à utiliser plutôt que /bin/sh par défaut.

stdin, stdout et stderr spécifient respectivement les gestionnaires d’entrée standard, de sortie standard et de sortie d’erreur du programme exécuté. Les valeurs acceptées sont PIPE, DEVNULL, un descripteur de fichier existant (nombre entier positif), un file object, et None. PIPE indique qu’un nouveau tube vers le processus enfant sera créé. DEVNULL indique que le fichier spécial os.devnull sera utilisé. Avec les paramètres None par défaut, aucune redirection ne se produira, les gestionnaires de fichiers du fils seront hérités du parent. Additionnellement, stderr peut valoir STDOUT, qui indique que les données de la sortie d’erreur du processus fils doivent être capturées dans le même gestionnaire de fichier que la sortie standard.

Si un objet appelable est passé à preexec_fn, cet objet sera appelé dans le processus enfant juste avant d’exécuter le programme. (POSIX seulement)

Avertissement

Le paramètre preexec_fn n’est pas sain à utiliser en présence d’autres fils d’exécution dans votre application. Le processus fils pourrait être bloqué (deadlock) avant qu”exec ne soit appelée. Si vous devez utiliser ce paramètre, gardez son utilisation triviale ! Minimisez le nombre de bibliothèques que vous y appelez.

Note

Si vous devez modifier l’environnement du fils, utilisez le paramètre env plutôt que faire cela dans une preexec_fn. Le paramètre start_new_session peut prendre la place de preexec_fn qui était autrefois communément utilisé pour appeler os.setsid() dans le fils.

Si close_fds est vrai, tous les descripteurs de fichiers à l’exception de 0, 1 et 2 seront fermés avant que le processus fils ne soit exécuté. (POSIX seulement). La valeur par défaut varie selon les plateformes : il est toujours vrai sur les systèmes POSIX. Sous Windows, il est vrai quand stdin/stdout/stderr sont None, faux autrement. Sous Windows, si close_fds est vrai, aucun gestionnaire ne sera hérité par le processus fils. Notez que sous Windows, vous ne pouvez pas mettre close_fds à true et en même temps rediriger les entrées/sorties standards avec les paramètres stdin/stdout/stderr.

Modifié dans la version 3.2: la valeur par défaut de close_fds n’est plus False, comme décrit ci-dessus.

pass_fds est une séquence optionnelle de descripteurs de fichiers à garder ouverts entre le parent et l’enfant. Fournir pass_fds force close_fds à valoir True. (POSIX seulement)

Nouveau dans la version 3.2: Ajout du paramètre pass_fds.

If cwd is not None, the function changes the working directory to cwd before executing the child. In particular, the function looks for executable (or for the first item in args) relative to cwd if the executable path is a relative path.

Si restore_signals est vrai (par défaut), tous les signaux que Python a mis à SIG_IGN sont restaurés à SIG_DFL dans le processus fils avant l’appel à exec. Actuellement, cela inclut les signaux SIGPIPE, SIGXFZ et SIGXFSZ. (POSIX seulement)

Modifié dans la version 3.2: Ajout de restore_signals.

Si start_new_session est vrai, l’appel système à setsid() sera réalisé dans le processus fils avant l’exécution du sous-processus. (POSIX seulement)

Modifié dans la version 3.2: Ajout de start_new_session.

Si env n’est pas None, il doit être un tableau associatif définissant les variables d’environnement du nouveau processus ; elles seront utilisées à la place du comportement par défaut qui est d’hériter de l’environnement du processus courant.

Note

Si spécifié, env doit fournir chaque variable requise pour l’exécution du programme. Sous Windows, afin d’exécuter un side-by-side assembly, l’environnement env spécifié doit contenir une variable SystemRoot valide.

If universal_newlines is True, the file objects stdin, stdout and stderr are opened as text streams in universal newlines mode, as described above in Arguments fréquemment utilisés, otherwise they are opened as binary streams.

Si fourni, startupinfo sera un objet STARTUPINFO, qui sera passé à la fonction CreateProcess inhérente. creationflags, si fourni, peut valoir CREATE_NEW_CONSOLE ou CREATE_NEW_PROCESS_GROUP. (Windows seulement)

Les objets Popen sont supportés comme gestionnaires de contexte avec l’instruction with : à la sortie, les descripteurs de fichiers standards sont fermés, et le processus est attendu :

with Popen(["ifconfig"], stdout=PIPE) as proc:
    log.write(proc.stdout.read())

Modifié dans la version 3.2: Ajout du support des gestionnaires de contexte.

17.5.1.3. Exceptions

Les exceptions levées dans le processus fils, avant que le nouveau programme n’ait commencé son exécution, seront relayées dans le parent. Additionnellement, l’objet de l’exception aura un attribut supplémentaire appelé child_traceback, une chaîne de caractères contenant la trace de l’exception du point de vue du fils.

L’exception la plus communément levée est OSError. Elle survient, par exemple, si vous essayez d’exécuter un fichier inexistant. Les applications doivent se préparer à traiter des exceptions OSError.

Une ValueError sera levée si Popen est appelé avec des arguments invalides.

check_call() et check_output() lèveront une CalledProcessError si le processus appelé renvoie un code de retour non nul.

Toutes les fonctions et méthodes qui acceptent un paramètre timeout, telles que call() et Popen.communicate() lèveront une TImeoutExpired si le timeout expire avant la fin du processus.

Toutes les exceptions définies dans ce module héritent de SubprocessError.

Nouveau dans la version 3.3: Ajout de la classe de base SubprocessError.

17.5.2. Considérations de sécurité

Contrairement à quelques autres fonctions popen, cette implémentation n’appellera jamais implicitement le shell du système. Cela signifie que tous les caractères, incluant les métacaractères des shells, peuvent être passés aux processus fils en toute sécurité. Si le shell est invoqué explicitement, avec shell=True, il est de la responsabilité de l’application d’assurer que les espaces et métacaractères sont échappés correctement pour éviter les vulnérabilités de type shell injection.

Avec shell=True, la fonction shlex.quote() peut être utilisée pour échapper proprement les espaces et métacaractères dans les chaînes qui seront utilisées pour construire les commandes shell.

17.5.3. Objets Popen

Les instances de la classe Popen possèdent les méthodes suivantes :

Popen.poll()

Vérifie que le processus enfant s’est terminé. Modifie l’attribut returncode et le renvoie.

Popen.wait(timeout=None)

Attend qu’un processus enfant se termine. Modifie l’attribut returncode et le renvoie.

Si le processus ne se termine pas après le nombre de secondes spécifié par timeout, une exception TimeoutExpired est levée. Cela ne pose aucun problème d’attraper cette exception et de réessayer d’attendre.

Note

Cela provoquera un blocage (deadlock) lors de l’utilisation de stdout=PIPE ou stderr=PIPE si le processus fils génère tellement de données sur le tube qu’il le bloque, en attente que le système d’exploitation permette au tampon du tube d’accepter plus de données. Utilisez Popen.communicate() pour éviter ce problème lors de l’utilisation de tubes.

Note

Cette fonction est implémentée avec une attente active (appels non bloquants et sleep courts). Utilisez le module asyncio pour une attente asynchrone : voir asyncio.create_subprocess_exec.

Modifié dans la version 3.3: Ajout de timeout.

Obsolète depuis la version 3.4: N’utilisez pas le paramètre endtime. Il a été par mégarde exposé dans la version 3.3 mais laissé non-documenté, et était destiné à rester privé pour un usage interne. Utilisez plutôt timeout.

Popen.communicate(input=None, timeout=None)

Interact with process: Send data to stdin. Read data from stdout and stderr, until end-of-file is reached. Wait for process to terminate. The optional input argument should be data to be sent to the child process, or None, if no data should be sent to the child. The type of input must be bytes or, if universal_newlines was True, a string.

communicate() returns a tuple (stdout_data, stderr_data). The data will be bytes or, if universal_newlines was True, strings.

Notez que si vous souhaitez envoyer des données sur l’entrée standard du processus, vous devez créer l’objet Popen avec stdin=PIPE. Similairement, pour obtenir autre chose que None dans le tuple résultant, vous devez aussi préciser stdout=PIPE et/ou stderr=PIPE.

Si le processus ne se termine pas après timeout secondes, une exception TimeoutExpired est levée. Attraper cette exception et retenter la communication ne fait perdre aucune donnée de sortie.

Le processus enfant n’est pas tué si le timeout expire, donc afin de nettoyer proprement le tout, une application polie devrait tuer le processus fils et terminer la communication :

proc = subprocess.Popen(...)
try:
    outs, errs = proc.communicate(timeout=15)
except TimeoutExpired:
    proc.kill()
    outs, errs = proc.communicate()

Note

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.3: Ajout de timeout.

Popen.send_signal(signal)

Envoie le signal signal au fils.

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.

Popen.terminate()

Stoppe le processus fils. Sur les systèmes POSIX, la méthode envoie un signal SIGTERM au fils. Sous Windows, la fonction TerminateProcess() de l’API Win32 est appelée pour arrêter le fils.

Popen.kill()

Tue le processus fils. Sur les systèmes POSIX, la fonction envoie un signal SIGKILL au fils. Sous Windows, kill() est un alias pour terminate().

Les attributs suivants sont aussi disponibles :

Popen.args

L’argument args tel que passé à Popen – une séquence d’arguments du programme ou une simple chaîne de caractères.

Nouveau dans la version 3.3.

Popen.stdin

If the stdin argument was PIPE, this attribute is a writeable stream object as returned by open(). If the universal_newlines argument was True, the stream is a text stream, otherwise it is a byte stream. If the stdin argument was not PIPE, this attribute is None.

Popen.stdout

If the stdout argument was PIPE, this attribute is a readable stream object as returned by open(). Reading from the stream provides output from the child process. If the universal_newlines argument was True, the stream is a text stream, otherwise it is a byte stream. If the stdout argument was not PIPE, this attribute is None.

Popen.stderr

If the stderr argument was PIPE, this attribute is a readable stream object as returned by open(). Reading from the stream provides error output from the child process. If the universal_newlines argument was True, the stream is a text stream, otherwise it is a byte stream. If the stderr argument was not PIPE, this attribute is None.

Avertissement

Utilisez communicate() plutôt que .stdin.write, .stdout.read ou .stderr.read pour empêcher les deadlocks dus au remplissage des tampons des tubes de l’OS et bloquant le processus enfant.

Popen.pid

L’identifiant de processus du processus enfant.

Notez que si vous passez l’argument shell à True, il s’agit alors de l’identifiant du shell instancié.

Popen.returncode

Le code de retour de l’enfant, attribué par poll() et wait() (et indirectement par communicate()). Une valeur None indique que le processus ne s’est pas encore terminé.

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

17.5.4. Utilitaires Popen pour Windows

La classe STARTUPINFO et les constantes suivantes sont seulement disponibles sous Windows.

class subprocess.STARTUPINFO

Un support partiel de la structure STARTUPINFO de Windows est utilisé lors de la création d’un objet Popen.

dwFlags

Un champ de bits déterminant si certains attributs STARTUPINFO sont utilisés quand le processus crée une fenêtre :

si = subprocess.STARTUPINFO()
si.dwFlags = subprocess.STARTF_USESTDHANDLES | subprocess.STARTF_USESHOWWINDOW
hStdInput

Si dwFlags spécifie STARTF_USESTDHANDLES, cet attribut est le gestionnaire d’entrée standard du processus. Si STARTF_USESTDHANDLES n’est pas spécifié, l’entrée standard par défaut est le tampon du clavier.

hStdOutput

Si dwFlags spécifie STARTF_USESTDHANDLES, cet attribut est le gestionnaire de sortie standard du processus. Autrement, l’attribut est ignoré et la sortie standard par défaut est le tampon de la console.

hStdError

Si dwFlags spécifie STARTF_USESTDHANDLES, cet attribut est le gestionnaire de sortie d’erreur du processus. Autrement, l’attribut est ignoré et la sortie d’erreur par défaut est le tampon de la console.

wShowWindow

Si dwFlags spécifie STARTF_USESHOWWINDOW, cet attribut peut-être n’importe quel attribut valide pour le paramètre nCmdShow de la fonction ShowWindow, à l’exception de SW_SHOWDEFAULT. Autrement, cet attribut est ignoré.

SW_HIDE est fourni pour cet attribut. Il est utilisé quand Popen est appelée avec shell=True.

17.5.4.1. Constantes

Le module subprocess expose les constantes suivantes.

subprocess.STD_INPUT_HANDLE

Le périphérique d’entrée standard. Initialement, il s’agit du tampon de la console d’entrée, CONIN$.

subprocess.STD_OUTPUT_HANDLE

Le périphérique de sortie standard. Initialement, il s’agit du tampon de l’écran de console actif, CONOUT$.

subprocess.STD_ERROR_HANDLE

Le périphérique de sortie d’erreur. Initialement, il s’agit du tampon de l’écran de console actif, CONOUT$.

subprocess.SW_HIDE

Cache la fenêtre. Une autre fenêtre sera activée.

subprocess.STARTF_USESTDHANDLES

Spécifie que les attributs STARTUPINFO.hStdInput, STARTUPINFO.hStdOutput et STARTUPINFO.hStdError contiennent des informations additionnelles.

subprocess.STARTF_USESHOWWINDOW

Spécifie que l’attribut STARTUPINFO.wShowWindow contient des informations additionnelles.

subprocess.CREATE_NEW_CONSOLE

Le nouveau processus instancie une nouvelle console, plutôt que d’hériter de celle de son père (par défaut).

subprocess.CREATE_NEW_PROCESS_GROUP

Un paramètre creationflags de Popen pour spécifier si un nouveau groupe de processus doit être créé. Cette option est nécessaire pour utiliser os.kill() sur le sous-processus.

L’option est ignorée si CREATE_NEW_CONSOLE est spécifié.

17.5.5. Ancienne interface (API) haut-niveau

Avant Python 3.5, ces trois fonctions représentaient l’API haut-niveau de subprocess. Vous pouvez maintenant utiliser run() dans de nombreux cas, mais beaucoup de codes existant font appel à ces trois fonctions.

subprocess.call(args, *, stdin=None, stdout=None, stderr=None, shell=False, timeout=None)

Lance la commande décrite par args, attend qu’elle se termine, et renvoie son attribut returncode.

C’est équivalent à :

run(...).returncode

(excepté que les paramètres input et check ne sont pas supportés)

Les arguments montrés plus haut sont sûrement les plus communs. La signature complète de la fonction est en grande partie la même que le constructeur de Popen : cette fonction passe tous les arguments fournis autre que timeout directement à travers cette interface.

Note

N’utilisez pas stdout=PIPE ou stderr=PIPE avec cette fonction. Le processus enfant bloquera s’il génère assez de données pour remplir le tampon du tube de l’OS, puisque les tubes ne seront jamais lus.

Modifié dans la version 3.3: Ajout de timeout.

subprocess.check_call(args, *, stdin=None, stdout=None, stderr=None, shell=False, timeout=None)

Lance la commande avec les arguments et attend qu’elle se termine. Se termine normalement si le code de retour est zéro, et lève une CalledProcessError autrement. L’objet CalledProcessError contiendra le code de retour dans son attribut returncode.

C’est équivalent à :

run(..., check=True)

(excepté que le paramètre input n’est pas pris en charge)

Les arguments montrés plus haut sont sûrement les plus communs. La signature complète de la fonction est en grande partie la même que le constructeur de Popen : cette fonction passe tous les arguments fournis autre que timeout directement à travers cette interface.

Note

N’utilisez pas stdout=PIPE ou stderr=PIPE avec cette fonction. Le processus enfant bloquera s’il génère assez de données pour remplir le tampon du tube de l’OS, puisque les tubes ne seront jamais lus.

Modifié dans la version 3.3: Ajout de timeout.

subprocess.check_output(args, *, stdin=None, stderr=None, shell=False, universal_newlines=False, timeout=None)

Lance la commande avec les arguments et renvoie sa sortie.

Si le code de retour est non-nul, la fonction lève une CalledProcessError. L’objet CalledProcessError contiendra le code de retour dans son attribut returncode, et la sortie du programme dans son attribut output.

C’est équivalent à :

run(..., check=True, stdout=PIPE).stdout

Les arguments montrés plus haut sont sûrement les plus communs. La signature complète de la fonction est en grande partie la même que run() : la plupart des arguments sont passés directement par cette interface. Cependant, passer explicitement input=None pour hériter du gestionnaire d’entrée standard du parent n’est pas supporté.

Par défaut, cette fonction renvoie les données encodées sous forme de bytes. Le réel encodage des données de sortie peut dépendre de la commande invoquée, donc le décodage du texte devra souvent être géré au niveau de l’application.

Ce comportement peut être redéfini en mettant universal_newlines à True comme décrit ci-dessus dans Arguments fréquemment utilisés.

Pour capturer aussi la sortie d’erreur dans le résultat, utilisez stderr=subprocess.STDOUT :

>>> subprocess.check_output(
...     "ls non_existent_file; exit 0",
...     stderr=subprocess.STDOUT,
...     shell=True)
'ls: non_existent_file: No such file or directory\n'

Nouveau dans la version 3.1.

Modifié dans la version 3.3: Ajout de timeout.

Modifié dans la version 3.4: Ajout du support de l’argument nommé input.

17.5.6. Remplacer les fonctions plus anciennes par le module subprocess

Dans cette section, « a devient b » signifie que b peut être utilisée en remplacement de a.

Note

Toutes les fonctions « a » dans cette section échouent (plus ou moins) silencieusement si le programme à exécuter ne peut être trouvé ; les fonctions « b » de remplacement lèvent à la place une OSError.

De plus, les remplacements utilisant check_output() échoueront avec une CalledProcessError si l’opération requise produit un code de retour non-nul. La sortie est toujours disponible par l’attribut output de l’exception levée.

Dans les exemples suivants, nous supposons que les fonctions utilisées ont déjà été importées depuis le module subprocess.

17.5.6.1. Remplacement des backquotes des shells /bin/sh

output=`mycmd myarg`

devient :

output = check_output(["mycmd", "myarg"])

17.5.6.2. Remplacer les pipes du shell

output=`dmesg | grep hda`

devient :

p1 = Popen(["dmesg"], stdout=PIPE)
p2 = Popen(["grep", "hda"], stdin=p1.stdout, stdout=PIPE)
p1.stdout.close()  # Allow p1 to receive a SIGPIPE if p2 exits.
output = p2.communicate()[0]

L’appel à p1.stdout.close() après le démarrage de p2 est important pour que p1 reçoive un SIGPIPE si p2 se termine avant lui.

Alternativement, pour des entrées fiables, le support des tubes du shell peut directement être utilisé :

output=`dmesg | grep hda`

devient :

output=check_output("dmesg | grep hda", shell=True)

17.5.6.3. Remplacer os.system()

sts = os.system("mycmd" + " myarg")
# becomes
sts = call("mycmd" + " myarg", shell=True)

Notes :

  • Appeler le programme à travers un shell n’est habituellement pas requis.

Un exemple plus réaliste ressemblerait à cela :

try:
    retcode = call("mycmd" + " myarg", shell=True)
    if retcode < 0:
        print("Child was terminated by signal", -retcode, file=sys.stderr)
    else:
        print("Child returned", retcode, file=sys.stderr)
except OSError as e:
    print("Execution failed:", e, file=sys.stderr)

17.5.6.4. Remplacer les fonctions de la famille os.spawn

Exemple avec P_NOWAIT :

pid = os.spawnlp(os.P_NOWAIT, "/bin/mycmd", "mycmd", "myarg")
==>
pid = Popen(["/bin/mycmd", "myarg"]).pid

Exemple avec P_WAIT :

retcode = os.spawnlp(os.P_WAIT, "/bin/mycmd", "mycmd", "myarg")
==>
retcode = call(["/bin/mycmd", "myarg"])

Exemple avec un tableau :

os.spawnvp(os.P_NOWAIT, path, args)
==>
Popen([path] + args[1:])

Exemple en passant un environnement :

os.spawnlpe(os.P_NOWAIT, "/bin/mycmd", "mycmd", "myarg", env)
==>
Popen(["/bin/mycmd", "myarg"], env={"PATH": "/usr/bin"})

17.5.6.5. Remplacer os.popen(), os.popen2(), os.popen3() etc.

(child_stdin, child_stdout) = os.popen2(cmd, mode, bufsize)
==>
p = Popen(cmd, shell=True, bufsize=bufsize,
          stdin=PIPE, stdout=PIPE, close_fds=True)
(child_stdin, child_stdout) = (p.stdin, p.stdout)

(child_stdin,
 child_stdout,
 child_stderr) = os.popen3(cmd, mode, bufsize)
==>
p = Popen(cmd, shell=True, bufsize=bufsize,
          stdin=PIPE, stdout=PIPE, stderr=PIPE, close_fds=True)
(child_stdin,
 child_stdout,
 child_stderr) = (p.stdin, p.stdout, p.stderr)

(child_stdin, child_stdout_and_stderr) = os.popen4(cmd, mode, bufsize)
==>
p = Popen(cmd, shell=True, bufsize=bufsize,
          stdin=PIPE, stdout=PIPE, stderr=STDOUT, close_fds=True)
(child_stdin, child_stdout_and_stderr) = (p.stdin, p.stdout)

La gestion du code de retour se traduit comme suit :

pipe = os.popen(cmd, 'w')
...
rc = pipe.close()
if rc is not None and rc >> 8:
    print("There were some errors")
==>
process = Popen(cmd, stdin=PIPE)
...
process.stdin.close()
if process.wait() != 0:
    print("There were some errors")

17.5.6.6. Remplacer les fonctions du module popen2

Note

Si l’argument cmd des fonctions de popen2 est une chaîne de caractères, la commande est exécutée à travers /bin/sh. Si c’est une liste, la commande est directement exécutée.

(child_stdout, child_stdin) = popen2.popen2("somestring", bufsize, mode)
==>
p = Popen("somestring", shell=True, bufsize=bufsize,
          stdin=PIPE, stdout=PIPE, close_fds=True)
(child_stdout, child_stdin) = (p.stdout, p.stdin)

(child_stdout, child_stdin) = popen2.popen2(["mycmd", "myarg"], bufsize, mode)
==>
p = Popen(["mycmd", "myarg"], bufsize=bufsize,
          stdin=PIPE, stdout=PIPE, close_fds=True)
(child_stdout, child_stdin) = (p.stdout, p.stdin)

popen2.Popen3 et popen2.Popen4 fonctionnent basiquement comme subprocess.Popen, excepté que :

  • Popen lève une exception si l’exécution échoue.
  • L’argument capturestderr est remplacé par stderr.
  • stdin=PIPE et stdout=PIPE doivent être spécifiés.
  • popen2 ferme tous les descripteurs de fichiers par défaut, mais vous devez spécifier close_fds=True avec Popen pour garantir ce comportement sur toutes les plateformes ou les anciennes versions de Python.

17.5.7. Remplacement des fonctions originales d’invocation du shell

Ce module fournit aussi les fonctions suivantes héritées du module commands de Python 2.x. Ces opérations invoquent implicitement le shell du système et n’apportent aucune des garanties décrites ci-dessus par rapport à la sécurité ou la cohérence de la gestion des exceptions.

subprocess.getstatusoutput(cmd)

Return (status, output) of executing cmd in a shell.

Execute the string cmd in a shell with Popen.check_output() and return a 2-tuple (status, output). Universal newlines mode is used; see the notes on Arguments fréquemment utilisés for more details.

A trailing newline is stripped from the output. The exit status for the command can be interpreted according to the rules for the C function wait(). Example:

>>> subprocess.getstatusoutput('ls /bin/ls')
(0, '/bin/ls')
>>> subprocess.getstatusoutput('cat /bin/junk')
(256, 'cat: /bin/junk: No such file or directory')
>>> subprocess.getstatusoutput('/bin/junk')
(256, 'sh: /bin/junk: not found')

Disponibilité : POSIX et Windows

Modifié dans la version 3.3.4: Ajout du support Windows.

subprocess.getoutput(cmd)

Renvoie la sortie (standard et d’erreur) de l’exécution de cmd dans un shell.

Comme getstatusoutput(), à l’exception que le code de statut est ignoré et que la valeur de retour est une chaîne contenant la sortie de la commande. Exemple :

>>> subprocess.getoutput('ls /bin/ls')
'/bin/ls'

Disponibilité : POSIX et Windows

Modifié dans la version 3.3.4: Ajout du support Windows.

17.5.8. Notes

17.5.8.1. Convertir une séquence d’arguments vers une chaîne de caractères sous Windows

Sous Windows, une séquence args est convertie vers une chaîne qui peut être analysée avec les règles suivantes (qui correspondent aux règles utilisées par l’environnement MS C) :

  1. Les arguments sont délimités par des espacements, qui peuvent être des espaces ou des tabulations.
  2. Une chaîne entourée de double guillemets est interprétée comme un argument seul, qu’elle contienne ou non des espacements. Une chaîne entre guillemets peut être intégrée dans un argument.
  3. Un guillemet double précédé d’un backslash est interprété comme un guillemet double littéral.
  4. Les backslashs sont interprétés littéralement, à moins qu’ils précèdent immédiatement un guillemet double.
  5. Si des backslashs précèdent directement un guillemet double, toute paire de backslashs est interprétée comme un backslash littéral. Si le nombre de backslashs est impair, le dernier backslash échappe le prochain guillemet double comme décrit en règle 3.

Voir aussi

shlex
Module qui fournit des fonctions pour analyser et échapper les lignes de commandes.