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

Availability: not Emscripten, not WASI.

Ce module ne fonctionne pas ou n'est pas disponible sur les plateformes WebAssembly `wasm32-emscripten` et `wasm32-wasi`. Référez vous à Plateformes WebAssembly pour plus d'informations.

## Utiliser le module `subprocess`

L'approche recommandée pour invoquer un sous-processus est d'utiliser la fonction `run()` pour tous les cas d'utilisation qu'elle gère. Pour les cas d'utilisation plus avancés, l'interface inhérente `Popen` peut être utilisée directement.

subprocess.run(args, *, stdin=None, input=None, stdout=None, stderr=None, capture_output=False, shell=False, cwd=None, timeout=None, check=False, encoding=None, errors=None, text=None, env=None, universal_newlines=None, **other_popen_kwargs)

  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, check et capture_output, tous les arguments donnés à cette fonction passent à travers cette interface.

  If capture_output is true, stdout and stderr will be captured. When used, the internal `Popen` object is automatically created with stdout and stdin both set to `PIPE`. The stdout and stderr arguments may not be supplied at the same time as capture_output. If you wish to capture and combine both streams into one, set stdout to `PIPE` and stderr to `STDOUT`, instead of using capture_output.

  A timeout may be specified in seconds, it is internally passed on to `Popen.communicate()`. If the timeout expires, the child process will be killed and waited for. The `TimeoutExpired` exception will be re-raised after the child process has terminated. The initial process creation itself cannot be interrupted on many platform APIs so you are not guaranteed to see a timeout exception until at least after however long process creation takes.

  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 encoding or errors is specified or text is true. When used, the internal `Popen` object is automatically created with stdin set to `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.

  Si encoding ou errors sont spécifiés, ou text est vrai, les fichiers pour les entrées et sorties sont ouverts en mode texte en utilisant les paramètres encoding et errors spécifiés, ou les valeurs par défaut de `io.TextIOWrapper`. L'argument universal_newlines est équivalent à text et est fourni pour la rétrocompatibilité. Par défaut, les fichiers sont ouverts en mode binaire.

  If env is not `None`, it must be a mapping that defines the environment variables for the new process; these are used instead of the default behavior of inheriting the current process' environment. It is passed directly to `Popen`. This mapping can be str to str on any platform or bytes to bytes on POSIX platforms much like `os.environ` or `os.environb`.

  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"], capture_output=True)
      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', stderr=b'')

  Nouveau dans la version 3.5.

  Modifié dans la version 3.6: Ajout des paramètres encoding et errors

  Modifié dans la version 3.7: Ajout du paramètre text, qui agit comme un alias plus compréhensible de universal_newlines. Ajout du paramètre capture_output.

  Modifié dans la version 3.11.3: Changed Windows shell search order for `shell=True`. The current directory and `%PATH%` are replaced with `%COMSPEC%` and `%SystemRoot%\System32\cmd.exe`. As a result, dropping a malicious program named `cmd.exe` into a current directory no longer works.

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

    La sortie standard capturée du processus enfant. Une séquence de bytes, ou une chaîne de caractères si `run()` a été appelée avec encoding, errors ou text=True. Vaut `None` si la sortie standard n'était pas capturée.

    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

    La sortie d'erreur capturée du processus enfant. Une séquence de bytes, ou une chaîne de caractères si `run()` a été appelée avec encoding, errors ou text=True. Vaut `None` si la sortie d'erreur n'était pas capturée.

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

    Sortie du processus enfant si elle a été récupérée par `run()` ou `check_output()`. Sinon, `None`. La sortie est toujours de type `bytes` quand elle est récupérée, que le paramètre `text` soit mis à `True` ou non. Si la sortie est vide, cette dernière peut être `None` au lieu de `b''`.

  stdout

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

  stderr

    Stderr output of the child process if it was captured by `run()`. Otherwise, `None`. This is always `bytes` when stderr output was captured regardless of the `text=True` setting. It may remain `None` instead of `b''` when no stderr output was observed.

  Nouveau dans la version 3.3.

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

exception subprocess.CalledProcessError

  Subclass of `SubprocessError`, raised when a process run by `check_call()`, `check_output()`, or `run()` (with `check=True`) returns a non-zero exit status.

  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

### Arguments fréquemment utilisés

Pour gérer un large ensemble de cas, le 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 and stderr specify the executed program's standard input, standard output and standard error file handles, respectively. Valid values are `PIPE`, `DEVNULL`, an existing file descriptor (a positive integer), an existing file object with a valid file descriptor, and `None`. `PIPE` indicates that a new pipe to the child should be created. `DEVNULL` indicates that the special file `os.devnull` will be used. With the default settings of `None`, no redirection will occur; the child's file handles will be inherited from the parent. Additionally, stderr can be `STDOUT`, which indicates that the stderr data from the child process should be captured into the same file handle as for stdout.

> Si encoding ou errors sont spécifiés, ou si text (aussi appelé universal_newlines) est vrai, les fichiers stdin, stdout et stderr seront ouverts en mode texte en utilisant les encoding et errors spécifiés à l'appel, ou les valeurs par défaut de `io.TextIOWrapper`.

> Pour stdin, les caractères de fin de ligne `'\n'` de l'entrée seront convertis vers des séparateurs de ligne par défaut `os.linesep`. Pour stdout et stderr, toutes les fins de lignes des sorties seront converties vers `'\n'`. Pour plus d'informations, voir la documentation de la classe `io.TextIOWrapper` quand l'argument newline du constructeur est `None`.

> Si le mode texte n'est pas utilisé, stdin, stdout et stderr seront ouverts comme des flux binaires. Aucune conversion d'encodage ou de fins de ligne ne sera réalisée.

> Modifié dans la version 3.6: Added the encoding and errors parameters.

> Modifié dans la version 3.7: Ajout du paramètre text comme alias de universal_newlines.

> 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 d’accueil 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`.

### 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=None, startupinfo=None, creationflags=0, restore_signals=True, start_new_session=False, pass_fds=(), *, group=None, extra_groups=None, user=None, umask=-1, encoding=None, errors=None, text=None, pipesize=-1, process_group=None)

  Execute a child program in a new process. On POSIX, the class uses `os.execvpe()`-like behavior to execute the child program. On Windows, the class uses the Windows `CreateProcess()` function. The arguments to `Popen` are as follows.

  args peut être une séquence d'arguments du programme, une chaîne seule ou un objet chemin. 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 de caractères, 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.

  Avertissement

  For maximum reliability, use a fully qualified path for the executable. To search for an unqualified name on `PATH`, use `shutil.which()`. On all platforms, passing `sys.executable` is the recommended way to launch the current Python interpreter again, and use the `-m` command-line format to launch an installed module.

  Resolving the path of executable (or the first item of args) is platform dependent. For POSIX, see `os.execvpe()`, and note that when resolving or searching for the executable path, cwd overrides the current working directory and env can override the `PATH` environment variable. For Windows, see the documentation of the `lpApplicationName` and `lpCommandLine` parameters of WinAPI `CreateProcess`, and note that when resolving or searching for the executable path with `shell=False`, cwd does not override the current working directory and env cannot override the `PATH` environment variable. Using a full path avoids all of these variations.

  Exemple de passage d'arguments, sous forme de séquence, à un autre programme:

      Popen(["/usr/bin/git", "commit", "-m", "Fixes a bug."])

  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

  Transformer une commande shell en une séquence de commandes peut ne pas être évident. `shlex.split()` permet d'illustrer comment séquencer une commande correctement pour args:

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

  Modifié dans la version 3.6: Le paramètre args accepte un objet chemin si shell vaut `False` et une séquence contenant des objets fichier sur POSIX.

  Modifié dans la version 3.8: Le paramètre args accepte un objet chemin si shell vaut `False` et une séquence contenant des chaines d'octets et des objets chemins sur Windows.

  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` means unbuffered (read and write are one system call and can return short)

  - `1` means line buffered (only usable if `text=True` or `universal_newlines=True`)

  - 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 now defaults to -1 to enable buffering by default to match the behavior that most code expects. In versions prior to Python 3.2.4 and 3.3.1 it incorrectly defaulted to `0` which was unbuffered and allowed short reads. This was unintentional and did not match the behavior of Python 2 as most code expected.

  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.

  Modifié dans la version 3.6: le paramètre executable accepte un objet chemin sur les systèmes POSIX.

  Modifié dans la version 3.8: le paramètre executable accepte un objet bytes ou un objet chemin sur Windows.

  Modifié dans la version 3.11.3: Changed Windows shell search order for `shell=True`. The current directory and `%PATH%` are replaced with `%COMSPEC%` and `%SystemRoot%\System32\cmd.exe`. As a result, dropping a malicious program named `cmd.exe` into a current directory no longer works.

  stdin, stdout and stderr specify the executed program's standard input, standard output and standard error file handles, respectively. Valid values are `PIPE`, `DEVNULL`, an existing file descriptor (a positive integer), an existing file object with a valid file descriptor, and `None`. `PIPE` indicates that a new pipe to the child should be created. `DEVNULL` indicates that the special file `os.devnull` will be used. With the default settings of `None`, no redirection will occur; the child's file handles will be inherited from the parent. Additionally, stderr can be `STDOUT`, which indicates that the stderr data from the applications should be captured into the same file handle as for stdout.

  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

  The preexec_fn parameter is NOT SAFE to use in the presence of threads in your application. The child process could deadlock before exec is called.

  Note

  If you need to modify the environment for the child use the env parameter rather than doing it in a preexec_fn. The start_new_session and process_group parameters should take the place of code using preexec_fn to call `os.setsid()` or `os.setpgid()` in the child.

  Modifié dans la version 3.8: Le paramètre preexec_fn n'est plus pris en charge dans les sous-interpréteurs. L'utilisation de ce paramètre lève `RuntimeError`. Cette nouvelle restriction peut affecter les applications déployées avec mod_wsgi, uWSGI et d'autres environnements qui peuvent embarquer Python.

  If close_fds is true, all file descriptors except `0`, `1` and `2` will be closed before the child process is executed. Otherwise when close_fds is false, file descriptors obey their inheritable flag as described in Héritage de descripteurs de fichiers.

  Sur Windows, si close_fds est vrai, alors aucun descripteur n'est hérité par le processus enfant à moins d'être explicitement passé dans l'élément `handle_list` de `STARTUPINFO.lpAttributeList`, ou par redirection des descripteurs standards.

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

  Modifié dans la version 3.7: Sur Windows, la valeur par défaut de close_fds a été changée de `False` à `True` lors d'une redirection des descripteurs standards. Il est maintenant possible de donner la valeur `True` à close_fds lors d'une redirection de descripteurs standards.

  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)

  Modifié 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. cwd can be a string, bytes or path-like object. On POSIX, the function looks for executable (or for the first item in args) relative to cwd if the executable path is a relative path.

  Modifié dans la version 3.6: le paramètre cwd accepte un objet chemin sur les systèmes POSIX.

  Modifié dans la version 3.7: le paramètre cwd accepte un objet chemin sur Windows.

  Modifié dans la version 3.8: le paramètre cwd accepte une séquence d'octets sur Windows

  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.

  If start_new_session is true the `setsid()` system call will be made in the child process prior to the execution of the subprocess.

  Availability: POSIX

  Modifié dans la version 3.2: Ajout de start_new_session.

  If process_group is a non-negative integer, the `setpgid(0, value)` system call will be made in the child process prior to the execution of the subprocess.

  Availability: POSIX

  Modifié dans la version 3.11: process_group was added.

  If group is not `None`, the setregid() system call will be made in the child process prior to the execution of the subprocess. If the provided value is a string, it will be looked up via `grp.getgrnam()` and the value in `gr_gid` will be used. If the value is an integer, it will be passed verbatim. (POSIX only)

  Availability: POSIX

  Nouveau dans la version 3.9.

  If extra_groups is not `None`, the setgroups() system call will be made in the child process prior to the execution of the subprocess. Strings provided in extra_groups will be looked up via `grp.getgrnam()` and the values in `gr_gid` will be used. Integer values will be passed verbatim. (POSIX only)

  Availability: POSIX

  Nouveau dans la version 3.9.

  If user is not `None`, the setreuid() system call will be made in the child process prior to the execution of the subprocess. If the provided value is a string, it will be looked up via `pwd.getpwnam()` and the value in `pw_uid` will be used. If the value is an integer, it will be passed verbatim. (POSIX only)

  Availability: POSIX

  Nouveau dans la version 3.9.

  If umask is not negative, the umask() system call will be made in the child process prior to the execution of the subprocess.

  Availability: POSIX

  Nouveau dans la version 3.9.

  If env is not `None`, it must be a mapping that defines the environment variables for the new process; these are used instead of the default behavior of inheriting the current process' environment. This mapping can be str to str on any platform or bytes to bytes on POSIX platforms much like `os.environ` or `os.environb`.

  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 encoding or errors are specified, or text is true, the file objects stdin, stdout and stderr are opened in text mode with the specified encoding and errors, as described above in Arguments fréquemment utilisés. The universal_newlines argument is equivalent to text and is provided for backwards compatibility. By default, file objects are opened in binary mode.

  Nouveau dans la version 3.6: Ajout d'encoding et errors.

  Nouveau dans la version 3.7: text a été ajouté comme un alias plus lisible de universal_newlines.

  If given, startupinfo will be a `STARTUPINFO` object, which is passed to the underlying `CreateProcess` function.

  If given, creationflags, can be one or more of the following flags:

  - `CREATE_NEW_CONSOLE`

  - `CREATE_NEW_PROCESS_GROUP`

  - `ABOVE_NORMAL_PRIORITY_CLASS`

  - `BELOW_NORMAL_PRIORITY_CLASS`

  - `HIGH_PRIORITY_CLASS`

  - `IDLE_PRIORITY_CLASS`

  - `NORMAL_PRIORITY_CLASS`

  - `REALTIME_PRIORITY_CLASS`

  - `CREATE_NO_WINDOW`

  - `DETACHED_PROCESS`

  - `CREATE_DEFAULT_ERROR_MODE`

  - `CREATE_BREAKAWAY_FROM_JOB`

  pipesize can be used to change the size of the pipe when `PIPE` is used for stdin, stdout or stderr. The size of the pipe is only changed on platforms that support this (only Linux at this time of writing). Other platforms will ignore this parameter.

  Modifié dans la version 3.10: Added the pipesize parameter.

  Les objets Popen sont géré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())

  Lève un évènement d'audit `subprocess.Popen` avec comme arguments `executable`, `args`, `cwd` et `env`.

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

  Modifié dans la version 3.6: Le destructeur de Popen émet maintenant un avertissement `ResourceWarning` si le processus fils est toujours en cours d'exécution.

  Modifié dans la version 3.8: Popen peut utiliser `os.posix_spawn()` dans certains cas pour de meilleures performances. Sur le sous-système Linux de Windows et sur QEMU en mode utilisateur, le constructeur de Popen utilisant `os.posix_spawn()` ne lève plus d'exception sur les erreurs comme programme manquant, mais le processus enfant échoue avec un `returncode` différent de zéro.

### Exceptions

Les exceptions levées dans le processus fils, avant que le nouveau programme ait commencé à s'exécuter, seront ré-levées dans le parent.

The most common exception raised is `OSError`. This occurs, for example, when trying to execute a non-existent file. Applications should prepare for `OSError` exceptions. Note that, when `shell=True`, `OSError` will be raised by the child only if the selected shell itself was not found. To determine if the shell failed to find the requested application, it is necessary to check the return code or output from the subprocess.

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.

All of the functions and methods that accept a timeout parameter, such as `run()` and `Popen.communicate()` will raise `TimeoutExpired` if the timeout expires before the process exits.

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

## Considérations de sécurité

Unlike some other popen functions, this library will not implicitly choose to call a system shell. This means that all characters, including shell metacharacters, can safely be passed to child processes. If the shell is invoked explicitly, via `shell=True`, it is the application's responsibility to ensure that all whitespace and metacharacters are quoted appropriately to avoid shell injection vulnerabilities. On some platforms, it is possible to use `shlex.quote()` for this escaping.

On Windows, batch files (`*.bat` or `*.cmd`) may be launched by the operating system in a system shell regardless of the arguments passed to this library. This could result in arguments being parsed according to shell rules, but without any escaping added by Python. If you are intentionally launching a batch file with arguments from untrusted sources, consider passing `shell=True` to allow Python to escape special characters. See gh-114539 for additional discussion.

## 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 et renvoie l'attribut `returncode`, sinon, renvoie `None`.

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

  When the `timeout` parameter is not `None`, then (on POSIX) the function is implemented using a busy loop (non-blocking call and short sleeps). Use the `asyncio` module for an asynchronous wait: see `asyncio.create_subprocess_exec`.

  Modifié dans la version 3.3: Ajout de 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 and set the `returncode` attribute. 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. If streams were opened in text mode, input must be a string. Otherwise, it must be bytes.

  `communicate()` renvoie une paire `(stdout_data, stderr_data)`. Les données seront des chaînes de caractères si les flux sont ouverts en mode texte, et des objets bytes dans le cas contraire.

  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 n-uplet 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.

  Do nothing if the process completed.

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

Popen.terminate()

  Stop the child. On POSIX OSs the method sends `SIGTERM` to the child. On Windows the Win32 API function `TerminateProcess()` is called to stop the child.

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

The following attributes are also set by the class for you to access. Reassigning them to new values is unsupported:

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 encoding or errors arguments were specified or the text or 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 encoding or errors arguments were specified or the text or 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 encoding or errors arguments were specified or the text or 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

  The child return code. Initially `None`, `returncode` is set by a call to the `poll()`, `wait()`, or `communicate()` methods if they detect that the process has terminated.

  A `None` value indicates that the process hadn't yet terminated at the time of the last method call.

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

## Utilitaires Popen pour Windows

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

class subprocess.STARTUPINFO(*, dwFlags=0, hStdInput=None, hStdOutput=None, hStdError=None, wShowWindow=0, lpAttributeList=None)

  Une gestion partielle de la structure STARTUPINFO est utilisée lors de la création d'un objet `Popen`. Les attributs ci-dessous peuvent être passés en tant que paramètres keyword-only.

  Modifié dans la version 3.7: Ajout de la gestion des paramètres keyword-only.

  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 descripteur 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 descripteur 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 descripteur 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`.

  lpAttributeList

    Dictionnaire des attributs supplémentaires pour la création d'un processus comme donnés dans `STARTUPINFOEX`, lisez UpdateProcThreadAttribute (ressource en anglais).

    Attributs gérés :

    handle_list

      Séquence des descripteurs qui hérités du parent. close_fds doit être vrai si la séquence n'est pas vide.

      Les descripteurs doivent être temporairement héritables par `os.set_handle_inheritable()` quand ils sont passés au constructeur `Popen`, sinon `OSError` est levée avec l'erreur Windows `ERROR_INVALID_PARAMETER` (87).

      Avertissement

      Dans un processus avec plusieurs fils d'exécution, faites très attention à éviter la fuite de descripteurs qui sont marqués comme héritables quand vous combinez ceci avec des appels concurrents vers des fonctions de création d'autres processus qui héritent de tous les descripteurs (telle que `os.system()`).

    Nouveau dans la version 3.7.

### Constantes Windows

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

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

subprocess.ABOVE_NORMAL_PRIORITY_CLASS

  Paramètre `creationflags` de `Popen` pour spécifier qu'un processus aura une priorité au-dessus de la moyenne.

  Nouveau dans la version 3.7.

subprocess.BELOW_NORMAL_PRIORITY_CLASS

  Paramètre `creationflags` de `Popen` pour spécifier qu'un processus aura une priorité au-dessous de la moyenne.

  Nouveau dans la version 3.7.

subprocess.HIGH_PRIORITY_CLASS

  Paramètre `creationflags` de `Popen` pour spécifier qu'un processus aura une priorité haute.

  Nouveau dans la version 3.7.

subprocess.IDLE_PRIORITY_CLASS

  Paramètre `creationflags` de `Popen` pour spécifier qu'un processus aura la priorité la plus basse (inactif ou idle).

  Nouveau dans la version 3.7.

subprocess.NORMAL_PRIORITY_CLASS

  Paramètre `creationflags` de `Popen` pour spécifier qu'un processus aura une priorité normale (le défaut).

  Nouveau dans la version 3.7.

subprocess.REALTIME_PRIORITY_CLASS

  Paramètre `creationflags` de `Popen` pour spécifier qu’un nouveau processus aura une priorité en temps réel. Vous ne devriez presque JAMAIS utiliser `REALTIME_PRIORITY_CLASS`, car cela interrompt les fils d’exécution système qui gèrent les entrées de la souris, du clavier et flush le cache de disque en arrière-plan. Cette classe peut convenir aux applications qui « parlent » directement au matériel ou qui effectuent de brèves tâches nécessitant des interruptions limitées.

  Nouveau dans la version 3.7.

subprocess.CREATE_NO_WINDOW

  Paramètre `creationflags` de `Popen` pour spécifier qu'un processus ne créera pas une nouvelle fenêtre.

  Nouveau dans la version 3.7.

subprocess.DETACHED_PROCESS

  Paramètre `creationflags` de `Popen` pour spécifier qu'un nouveau processus n'héritera pas de la console du processus parent. Cette valeur ne peut pas être utilisée avec CREATE_NEW_CONSOLE.

  Nouveau dans la version 3.7.

subprocess.CREATE_DEFAULT_ERROR_MODE

  Paramètre `creationflags` de `Popen` pour spécifier qu'un nouveau processus n'hérite pas du mode de gestion des erreurs du processus appelant. À la place, le nouveau processus acquiert le mode d'erreur par défaut. Cette fonctionnalité est particulièrement utile pour les applications shell avec de multiples fils d'exécution qui s'exécutent avec les erreurs irréversibles désactivées.

  Nouveau dans la version 3.7.

subprocess.CREATE_BREAKAWAY_FROM_JOB

  Paramètre `creationflags` de `Popen` pour spécifier qu'un processus n'est pas associé au job.

  Nouveau dans la version 3.7.

## 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, cwd=None, timeout=None, **other_popen_kwargs)

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

  Le code ayant besoin de capturer stdout ou stderr doit plutôt utiliser :`run()` :

      run(...).returncode

  Pour supprimer stdout ou stderr, passez la valeur `DEVNULL`.

  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.

  Modifié dans la version 3.11.3: Changed Windows shell search order for `shell=True`. The current directory and `%PATH%` are replaced with `%COMSPEC%` and `%SystemRoot%\System32\cmd.exe`. As a result, dropping a malicious program named `cmd.exe` into a current directory no longer works.

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

  Run command with arguments. Wait for command to complete. If the return code was zero then return, otherwise raise `CalledProcessError`. The `CalledProcessError` object will have the return code in the `returncode` attribute. If `check_call()` was unable to start the process it will propagate the exception that was raised.

  Le code ayant besoin de capturer stdout ou stderr doit plutôt utiliser :`run()` :

      run(..., check=True)

  Pour supprimer stdout ou stderr, passez la valeur `DEVNULL`.

  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.

  Modifié dans la version 3.11.3: Changed Windows shell search order for `shell=True`. The current directory and `%PATH%` are replaced with `%COMSPEC%` and `%SystemRoot%\System32\cmd.exe`. As a result, dropping a malicious program named `cmd.exe` into a current directory no longer works.

subprocess.check_output(args, *, stdin=None, stderr=None, shell=False, cwd=None, encoding=None, errors=None, universal_newlines=None, timeout=None, text=None, **other_popen_kwargs)

  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

  The arguments shown above are merely some common ones. The full function signature is largely the same as that of `run()` - most arguments are passed directly through to that interface. One API deviation from `run()` behavior exists: passing `input=None` will behave the same as `input=b''` (or `input=''`, depending on other arguments) rather than using the parent's standard input file handle.

  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 text, encoding, errors, ou universal_newlines à `True` comme décrit dans Arguments fréquemment utilisés et `run()`.

  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 de la gestion de l'argument nommé input.

  Modifié dans la version 3.6: Ajout d'encoding et errors. Consultez `run()` pour plus d'informations.

  Nouveau dans la version 3.7: text a été ajouté comme un alias plus lisible de universal_newlines.

  Modifié dans la version 3.11.3: Changed Windows shell search order for `shell=True`. The current directory and `%PATH%` are replaced with `%COMSPEC%` and `%SystemRoot%\System32\cmd.exe`. As a result, dropping a malicious program named `cmd.exe` into a current directory no longer works.

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

### Remplacement de la substitution de commandes de terminal /bin/sh

    output=$(mycmd myarg)

devient :

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

### 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, la gestion des tubes du shell peut directement être utilisé :

    output=$(dmesg | grep hda)

devient :

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

### Remplacer `os.system()`

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

Notes :

- Appeler le programme à travers un shell n'est habituellement pas requis.

- The `call()` return value is encoded differently to that of `os.system()`.

- The `os.system()` function ignores SIGINT and SIGQUIT signals while the command is running, but the caller must do this separately when using the `subprocess` module.

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)

### 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"})

### Remplacer `os.popen()`, `os.popen2()`, `os.popen3()`

    (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")

### Replacing functions from the `popen2` module

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.

## 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, *, encoding=None, errors=None)

  Renvoie les valeurs `(exitcode, output)` de l'exécution de cmd dans un shell.

  Execute the string cmd in a shell with `Popen.check_output()` and return a 2-tuple `(exitcode, output)`. encoding and errors are used to decode output; see the notes on Arguments fréquemment utilisés for more details.

  Si la sortie se termine par un caractère de fin de ligne, ce dernier est supprimé. Le code de statut de la commande peut être interprété comme le code de retour de subprocess. Par exemple :

      >>> subprocess.getstatusoutput('ls /bin/ls')
      (0, '/bin/ls')
      >>> subprocess.getstatusoutput('cat /bin/junk')
      (1, 'cat: /bin/junk: No such file or directory')
      >>> subprocess.getstatusoutput('/bin/junk')
      (127, 'sh: /bin/junk: not found')
      >>> subprocess.getstatusoutput('/bin/kill $$')
      (-15, '')

  Availability: Unix, Windows.

  Modifié dans la version 3.3.4: Ajout de la gestion de Windows.

  La fonction renvoie maintenant `(exitcode, output)` plutôt que `(status, output)` comme dans les versions de Python 3.3.3 ou antérieures. exitcode vaut la même valeur que `returncode`.

  Modifié dans la version 3.11: Added the encoding and errors parameters.

subprocess.getoutput(cmd, *, encoding=None, errors=None)

  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'

  Availability: Unix, Windows.

  Modifié dans la version 3.3.4: Ajout de la gestion de Windows

  Modifié dans la version 3.11: Added the encoding and errors parameters.

## Notes

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

### Disabling use of `vfork()` or `posix_spawn()`

On Linux, `subprocess` defaults to using the `vfork()` system call internally when it is safe to do so rather than `fork()`. This greatly improves performance.

If you ever encounter a presumed highly unusual situation where you need to prevent `vfork()` from being used by Python, you can set the `subprocess._USE_VFORK` attribute to a false value.

    subprocess._USE_VFORK = False  # See CPython issue gh-NNNNNN.

Setting this has no impact on use of `posix_spawn()` which could use `vfork()` internally within its libc implementation. There is a similar `subprocess._USE_POSIX_SPAWN` attribute if you need to prevent use of that.

    subprocess._USE_POSIX_SPAWN = False  # See CPython issue gh-NNNNNN.

It is safe to set these to false on any Python version. They will have no effect on older versions when unsupported. Do not assume the attributes are available to read. Despite their names, a true value does not indicate that the corresponding function will be used, only that it may be.

Please file issues any time you have to use these private knobs with a way to reproduce the issue you were seeing. Link to that issue from a comment in your code.

Nouveau dans la version 3.8: `_USE_POSIX_SPAWN`

Nouveau dans la version 3.11: `_USE_VFORK`