17.1. "subprocess" — Gestion de sous-processus
**********************************************

Nouveau dans la version 2.4.

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*
   os.popen*
   popen2.*
   commands.*

Information about how this module can be used to replace the older
functions can be found in the subprocess-replacements section.

Voir aussi: POSIX users (Linux, BSD, etc.) are strongly encouraged
  to install and use the much more recent subprocess32 module instead
  of the version included with python 2.7.  It is a drop in
  replacement with better behavior in many situations.

  **PEP 324** – PEP proposant le module *subprocess*


17.1.1. Utiliser le module "subprocess"
=======================================

The recommended way to launch subprocesses is to use the following
convenience functions.  For more advanced use cases when these do not
meet your needs, use the underlying "Popen" interface.

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

   Run the command described by *args*.  Wait for command to complete,
   then return the "returncode" attribute.

   The arguments shown above are merely the most common ones,
   described below in Arguments fréquemment utilisés (hence the
   slightly odd notation in the abbreviated signature). The full
   function signature is the same as that of the "Popen" constructor -
   this functions passes all supplied arguments directly through to
   that interface.

   Exemples :

      >>> subprocess.call(["ls", "-l"])
      0

      >>> subprocess.call("exit 1", shell=True)
      1

   Avertissement: Using "shell=True" can be a security hazard.  See
     the warning under Arguments fréquemment utilisés for details.

   Note: Do not use "stdout=PIPE" or "stderr=PIPE" with this
     function as that can deadlock based on the child process output
     volume. Use "Popen" with the "communicate()" method when you need
     pipes.

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

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

   The arguments shown above are merely the most common ones,
   described below in Arguments fréquemment utilisés (hence the
   slightly odd notation in the abbreviated signature). The full
   function signature is the same as that of the "Popen" constructor -
   this functions passes all supplied arguments directly through to
   that interface.

   Exemples :

      >>> subprocess.check_call(["ls", "-l"])
      0

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

   Nouveau dans la version 2.5.

   Avertissement: Using "shell=True" can be a security hazard.  See
     the warning under Arguments fréquemment utilisés for details.

   Note: Do not use "stdout=PIPE" or "stderr=PIPE" with this
     function as that can deadlock based on the child process output
     volume. Use "Popen" with the "communicate()" method when you need
     pipes.

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

   Run command with arguments and return its output as a byte string.

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

   The arguments shown above are merely the most common ones,
   described below in Arguments fréquemment utilisés (hence the
   slightly odd notation in the abbreviated signature). The full
   function signature is largely the same as that of the "Popen"
   constructor, except that *stdout* is not permitted as it is used
   internally. All other supplied arguments are passed directly
   through to the "Popen" constructor.

   Exemples :

      >>> subprocess.check_output(["echo", "Hello World!"])
      'Hello World!\n'

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

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

   Avertissement: Using "shell=True" can be a security hazard.  See
     the warning under Arguments fréquemment utilisés for details.

   Note: Do not use "stderr=PIPE" with this function as that can
     deadlock based on the child process error volume.  Use "Popen"
     with the "communicate()" method when you need a stderr pipe.

subprocess.PIPE

   Special value that can be used as the *stdin*, *stdout* or *stderr*
   argument to "Popen" and indicates that a pipe to the standard
   stream should be opened.

subprocess.STDOUT

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

exception subprocess.CalledProcessError

   Exception raised when a process run by "check_call()" or
   "check_output()" returns a non-zero exit status.

   returncode

      Exit status of the child process.

   cmd

      La commande utilisée pour instancier le processus fils.

   output

      Output of the child process if this exception is raised by
      "check_output()".  Otherwise, "None".


17.1.1.1. Arguments fréquemment utilisés
----------------------------------------

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

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

   *stdin*, *stdout* and *stderr* specify the executed program’s
   standard input, standard output and standard error file handles,
   respectively.  Valid values are "PIPE", an existing file descriptor
   (a positive integer), an existing file object, and "None".  "PIPE"
   indicates that a new pipe to the child should be created.  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.

   When *stdout* or *stderr* are pipes and *universal_newlines* is
   "True" then all line endings will be converted to "'\n'" as
   described for the *universal newlines* "'U'" mode argument to
   "open()".

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

   Avertissement: Executing shell commands that incorporate
     unsanitized input from an untrusted source makes a program
     vulnerable to shell injection, a serious security flaw which can
     result in arbitrary command execution. For this reason, the use
     of "shell=True" is **strongly discouraged** in cases where the
     command string is constructed from external input:

        >>> from subprocess import call
        >>> filename = input("What file would you like to display?\n")
        What file would you like to display?
        non_existent; rm -rf / #
        >>> call("cat " + filename, shell=True) # Uh-oh. This will end badly...

     "shell=False" disables all shell based features, but does not
     suffer from this vulnerability; see the Note in the "Popen"
     constructor documentation for helpful hints in getting
     "shell=False" to work.When using "shell=True", "pipes.quote()"
     can be used to properly escape whitespace and shell
     metacharacters in strings that are going to be used to construct
     shell commands.

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


17.1.1.2. Constructeur de *Popen*
---------------------------------

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

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

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

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

   On Unix, if *args* is a string, the string is interpreted as the
   name or path of the program to execute.  However, this can only be
   done if not passing arguments to the program.

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

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

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

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

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

   On Unix with "shell=True", the shell defaults to "/bin/sh".  If
   *args* is a string, the string specifies the command to execute
   through the shell.  This means that the string must be formatted
   exactly as it would be when typed at the shell prompt.  This
   includes, for example, quoting or backslash escaping filenames with
   spaces in them.  If *args* is a sequence, the first item specifies
   the command string, and any additional items will be treated as
   additional arguments to the shell itself.  That is to say, "Popen"
   does the equivalent of:

      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.

   Avertissement: Passing "shell=True" can be a security hazard if
     combined with untrusted input.  See the warning under Arguments
     fréquemment utilisés for details.

   *bufsize*, if given, has the same meaning as the corresponding
   argument to the built-in open() function: "0" means unbuffered, "1"
   means line buffered, any other positive value means use a buffer of
   (approximately) that size.  A negative *bufsize* means to use the
   system default, which usually means fully buffered.  The default
   value for *bufsize* is "0" (unbuffered).

   Note: If you experience performance issues, it is recommended
     that you try to enable buffering by setting *bufsize* to either
     -1 or a large enough positive value (such as 4096).

   The *executable* argument specifies a replacement program to
   execute.   It is very seldom needed.  When "shell=False",
   *executable* replaces the program to execute specified by *args*.
   However, the original *args* is still passed to the program.  Most
   programs treat the program specified by *args* as the command name,
   which can then be different from the program actually executed.  On
   Unix, the *args* name becomes the display name for the executable
   in utilities such as **ps**.  If "shell=True", on Unix the
   *executable* argument specifies a replacement shell for the default
   "/bin/sh".

   *stdin*, *stdout* and *stderr* specify the executed program’s
   standard input, standard output and standard error file handles,
   respectively.  Valid values are "PIPE", an existing file descriptor
   (a positive integer), an existing file object, and "None".  "PIPE"
   indicates that a new pipe to the child should be created.  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.

   If *preexec_fn* is set to a callable object, this object will be
   called in the child process just before the child is executed.
   (Unix only)

   If *close_fds* is true, all file descriptors except "0", "1" and
   "2" will be closed before the child process is executed. (Unix
   only). Or, on Windows, if *close_fds* is true then no handles will
   be inherited by the child process.  Note that on Windows, you
   cannot set *close_fds* to true and also redirect the standard
   handles by setting *stdin*, *stdout* or *stderr*.

   If *cwd* is not "None", the child’s current directory will be
   changed to *cwd* before it is executed.  Note that this directory
   is not considered when searching the executable, so you can’t
   specify the program’s path relative to *cwd*.

   If *env* is not "None", it must be a mapping that defines the
   environment variables for the new process; these are used instead
   of inheriting the current process” environment, which is the
   default behavior.

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

   If *universal_newlines* is "True", the file objects *stdout* and
   *stderr* are opened as text files in *universal newlines* mode.
   Lines may be terminated by any of "'\n'", the Unix end-of-line
   convention, "'\r'", the old Macintosh convention or "'\r\n'", the
   Windows convention. All of these external representations are seen
   as "'\n'" by the Python program.

   Note: This feature is only available if Python is built with
     universal newline support (the default).  Also, the newlines
     attribute of the file objects "stdout", "stdin" and "stderr" are
     not updated by the communicate() method.

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


17.1.1.3. Exceptions
--------------------

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

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

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

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


17.1.1.4. Security
------------------

Unlike some other popen functions, this implementation will never call
a system shell implicitly.  This means that all characters, including
shell metacharacters, can safely be passed to child processes.
Obviously, if the shell is invoked explicitly, then it is the
application’s responsibility to ensure that all whitespace and
metacharacters are quoted appropriately.


17.1.2. Objets *Popen*
======================

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

Popen.poll()

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

Popen.wait()

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

   Avertissement: This will deadlock when using "stdout=PIPE" and/or
     "stderr=PIPE" and the child process generates enough output to a
     pipe such that it blocks waiting for the OS pipe buffer to accept
     more data. Use "communicate()" to avoid that.

Popen.communicate(input=None)

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

   "communicate()" returns a tuple "(stdoutdata, stderrdata)".

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

   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.

Popen.send_signal(signal)

   Envoie le signal *signal* au fils.

   Note: Sous Windows, *SIGTERM* est un alias pour "terminate()".
     *CTRL_C_EVENT* et *CTRL_BREAK_EVENT* peuvent être envoyés aux
     processus démarrés avec un paramètre *creationflags* incluant
     *CREATE_NEW_PROCESS_GROUP*.

   Nouveau dans la version 2.6.

Popen.terminate()

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

   Nouveau dans la version 2.6.

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

   Nouveau dans la version 2.6.

Les attributs suivants sont aussi disponibles :

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

   If the *stdin* argument was "PIPE", this attribute is a file object
   that provides input to the child process.  Otherwise, it is "None".

Popen.stdout

   If the *stdout* argument was "PIPE", this attribute is a file
   object that provides output from the child process.  Otherwise, it
   is "None".

Popen.stderr

   If the *stderr* argument was "PIPE", this attribute is a file
   object that provides error output from the child process.
   Otherwise, it is "None".

Popen.pid

   L’identifiant de processus du processus enfant.

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

Popen.returncode

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

   A negative value "-N" indicates that the child was terminated by
   signal "N" (Unix only).


17.1.3. Utilitaires *Popen* pour Windows
========================================

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

class subprocess.STARTUPINFO

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

   dwFlags

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

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

   hStdInput

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

   hStdOutput

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

   hStdError

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

   wShowWindow

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

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


17.1.3.1. Constantes
--------------------

Le module "subprocess" expose les constantes suivantes.

subprocess.STD_INPUT_HANDLE

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

subprocess.STD_OUTPUT_HANDLE

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

subprocess.STD_ERROR_HANDLE

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

subprocess.SW_HIDE

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

subprocess.STARTF_USESTDHANDLES

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

subprocess.STARTF_USESHOWWINDOW

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

subprocess.CREATE_NEW_CONSOLE

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

   This flag is always set when "Popen" is created with "shell=True".

subprocess.CREATE_NEW_PROCESS_GROUP

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

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


17.1.4. Remplacer les fonctions plus anciennes par le module "subprocess"
=========================================================================

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

Note: Toutes les fonctions « a » dans cette section échouent (plus
  ou moins) silencieusement si le programme à exécuter ne peut être
  trouvé ; les fonctions « b » de remplacement lèvent à la place une
  "OSError".De plus, les remplacements utilisant "check_output()"
  échoueront avec une "CalledProcessError" si l’opération requise
  produit un code de retour non-nul. La sortie est toujours disponible
  par l’attribut "output" de l’exception levée.

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


17.1.4.1. Remplacement des *backquotes* des *shells /bin/sh*
------------------------------------------------------------

   output=`mycmd myarg`

devient :

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


17.1.4.2. Remplacer les *pipes* du *shell*
------------------------------------------

   output=`dmesg | grep hda`

devient :

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

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

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

   output=`dmesg | grep hda`

devient :

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


17.1.4.3. Remplacer "os.system()"
---------------------------------

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

Notes :

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

Un exemple plus réaliste ressemblerait à cela :

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


17.1.4.4. Remplacer les fonctions de la famille "os.spawn"
----------------------------------------------------------

Exemple avec *P_NOWAIT* :

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

Exemple avec *P_WAIT* :

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

Exemple avec un tableau :

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

Exemple en passant un environnement :

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


17.1.4.5. Remplacer "os.popen()", "os.popen2()", "os.popen3()" etc.
-------------------------------------------------------------------

   pipe = os.popen("cmd", 'r', bufsize)
   ==>
   pipe = Popen("cmd", shell=True, bufsize=bufsize, stdout=PIPE).stdout

   pipe = os.popen("cmd", 'w', bufsize)
   ==>
   pipe = Popen("cmd", shell=True, bufsize=bufsize, stdin=PIPE).stdin

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

On Unix, os.popen2, os.popen3 and os.popen4 also accept a sequence as
the command to execute, in which case arguments will be passed
directly to the program without shell intervention.  This usage can be
replaced as follows:

   (child_stdin, child_stdout) = os.popen2(["/bin/ls", "-l"], mode,
                                           bufsize)
   ==>
   p = Popen(["/bin/ls", "-l"], bufsize=bufsize, stdin=PIPE, stdout=PIPE)
   (child_stdin, child_stdout) = (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", shell=True, stdin=PIPE)
   ...
   process.stdin.close()
   if process.wait() != 0:
       print "There were some errors"


17.1.4.6. Remplacer les fonctions du module "popen2"
----------------------------------------------------

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

On Unix, popen2 also accepts a sequence as the command to execute, in
which case arguments will be passed directly to the program without
shell intervention.  This usage can be replaced as follows:

   (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 closes all file descriptors by default, but you have to
  specify "close_fds=True" with "Popen".


17.1.5. Notes
=============


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

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

1. Les arguments sont délimités par des espacements, qui peuvent
   être des espaces ou des tabulations.

2. Une chaîne entourée de double guillemets est interprétée comme
   un argument seul, qu’elle contienne ou non des espacements.  Une
   chaîne entre guillemets peut être intégrée dans un argument.

3. Un guillemet double précédé d’un *backslash* est interprété
   comme un guillemet double littéral.

4. Les *backslashs* sont interprétés littéralement, à moins qu’ils
   précèdent immédiatement un guillemet double.

5. Si des *backslashs* précèdent directement un guillemet double,
   toute paire de *backslashs* est interprétée comme un *backslash*
   littéral.  Si le nombre de *backslashs* est impair, le dernier
   *backslash* échappe le prochain guillemet double comme décrit en
   règle 3.
