"subprocess" --- Subprocess management
**************************************

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

This module does not work or is not available on WebAssembly platforms
"wasm32-emscripten" and "wasm32-wasi". See Plateformes WebAssembly for
more information.


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 *stderr* 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'')

   Added in 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.12: 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".

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

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

   Added in 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

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

   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.

   Added in 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 "None", "PIPE", "DEVNULL", an
   existing file descriptor (a positive integer), and an existing
   *file object* with a valid file descriptor.  With the default
   settings of "None", no redirection will occur.  "PIPE" indicates
   that a new pipe to the child should be created.  "DEVNULL"
   indicates that the special file "os.devnull" will be used.
   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.

   An example of passing some arguments to an external program as a
   sequence is:

      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:

     It may not be obvious how to break a shell command into a
     sequence of arguments, especially in complex cases.
     "shlex.split()" can illustrate how to determine the correct
     tokenization for *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.12: 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 "None", "PIPE", "DEVNULL", an
   existing file descriptor (a positive integer), and an existing
   *file object* with a valid file descriptor.  With the default
   settings of "None", no redirection will occur.  "PIPE" indicates
   that a new pipe to the child should be created.  "DEVNULL"
   indicates that the special file "os.devnull" will be used.
   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

   Added in 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

   Added in 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

   Added in 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

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

   Added in version 3.6: Ajout d'*encoding* et *errors*.

   Added in 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".

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

   Added in 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()").

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

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

   Added in version 3.7.

subprocess.HIGH_PRIORITY_CLASS

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

   Added in 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*).

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

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

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

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

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

   Added in 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*.

   Added in 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.12: 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.12: 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'

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

   Added in version 3.7: *text* a été ajouté comme un alias plus
   lisible de *universal_newlines*.

   Modifié dans la version 3.12: 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.

Added in version 3.8: "_USE_POSIX_SPAWN"

Added in version 3.11: "_USE_VFORK"
