[traduction] à relire : subprocess

branche bazaar : http://bzr.flibuste.net/libre/edition/pythonfr

ou

fichier intégral à me renvoyer avec les corrections (évitez les > de la
réponse)

n'hésitez pas non plus à faire des commentaires sur certains choix de
traduction...

\section{\module{subprocess} --- Subprocess management}

\declaremodule{standard}{subprocess}
\modulesynopsis{Subprocess management.}
\moduleauthor{Peter \AA strand}{astrand@lysator.liu.se}
\sectionauthor{Peter \AA strand}{astrand@lysator.liu.se}

\versionadded{2.4}

Le \module{subprocess} vous permet de créer des nouveaux procesus
(process) connectés à ses flux d'entrée/sortie/erreur, et d'obtenir
leurs codes de retour. L'objectif de ce module est de remplacer
quelques vieux modules et fonctions tels que :

% XXX Should add pointers to this module to at least the popen2
% and commands sections.

\begin{verbatim}
os.system
os.spawn*
os.popen*
popen2.*
commands.*
\end{verbatim}

Les informations à propos de la manière dont on peut utiliser
le mudule \module{subprocess} en remplacement des anciens modules
et fonctions peuvent être trouvées dans les sections suivantes.

\subsection{Utilisation du Module subprocess}

Ce module défini une classe \class{Popen} :

\begin{classdesc}{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}

Les arguments sont :

\var{args} doit être une chaine de caractères, ou une séquence
de paramètres. Le programme à lancer est normalement la première
valeur de la séquence de paramètres, mais peut aussi être
renseigné explicitement par le paramètre "executable".

Sous \UNIX{}, avec \var{shell=False} (par défaut): Dans ce cas, la
classe Popen utilise \method{os.execvp()} pour lancer le programme fils.
\var{args} doit normalement être une séquence. Une chaine sera traitée
comme une séquence avec une chaine comme seule valeur (le programme à
lancer).

Sous \UNIX{}, avec \var{shell=True}: Si args est une chaine, elle spécifie
la commande à lancer à travers le shell. Si \var{args} est une séquence,
la première valeur spécifie la commande, et toutes les autres valeurs
seront traitées comme des paramètres envoyés au shell.

Sous Windows: la \class{Popen} utilise CreateProcess() pour lancer
le programme fils, qui utilise des chaines. Si \var{args} est une
séquence, elle sera convertie en chaine en utilisant la méthode
\method{list2cmdline}. Notez s'il vous plait que toute les applications
MS Windows n'interpretent pas les lignes de commandes de la même
manière :
\method{list2cmdline} est conçue pour les application utilisant les
mêmes règles que les runtimes MS C.

\var{bufsize}, si renseigné, a la même signification que le paramètre
correspondant à la fonction standard open : \constant{0} signifie
pas de mise en tampon (unbuffered),
\constant{1} signifie mise en tampon par ligne (line buffered), toute
autre valeur positive signifie d'utiliser un tampon de cette taille
(aproximativement). Une valeur négative pour \var{bufsize} signifie
d'utiliser la valeur système par défaut, qui est généralement l'utilisation
d'un tampon complet. La valeur par défaut pour \var{bufsize} est \constant{0}
(pas de mise en tampon).

Le paramètre \var{executable} détermine le programme à lancer. Il est
rarement nécessaire : Généralement, le programme à lancer est
défini par le paramètre \var{args}. Si \var{shell=True}, le paramètre
\var{executable} détermine quel shell utiliser. Sous \UNIX{}, le shell
par défaut est /bin/sh. Sous Windows, le shell par défaut est spécifié
par la variable d'environnement COMSPEC.

\var{stdin}, \var{stdout} et \var{stderr} déterminent les
descripteur de fichier du programme, respectivement les flux d'entrée,
sortie et erreur standard.
Les valeurs valides sont un \code{PIPE}, un descripteur de fichier
existant (un entier positif), un objet fichier existant, et \code{None}.
\code{PIPE} indique qu'un nouveau pipe vers le fils devrait être créé.
Avec \code{None}, il n'y aura pas de redirection; les descripteurs
de fichiers du fils seront hérité du parent. Additionellement, \var{stderr}
peut être \code{STDOUT}, qui indique que les données de stderr seront
capturée par le même descripteur de fichier que celui de stdout.

Si \var{preexec_fn} est positionné à un object appelable (callable), cet
objet sera appelé dans le processus fils juste avant que le fils soit
lancé.

Si \var{close_fds} est vrai (true), tous les descrpiteurs à l'exception
de \constant{0} \constant{1} et \constant{2} seront fermés avant que
le processus fils soit lancé.

Si \var{shell} est \constant{True}, la commande spécifiée sera
lancée à travers le shell.

Si \var{cwd} n'est pas \code{None}, le répertoire en court sera changé
en cwd avant que le fils ne soit lancé.

Si \var{env} n'est pas \code{None}, il défini les variables d'environnement
pour le nouveau processus.

Si \var{universal_newlines} est \constant{True}, les objets fichiers stdout
et stderr seront ouvert en tant que fichiers textes, mais les lignes
pourront être terminées par n'importe lequel des \code{\e \n'}, fin
de ligne conventionnelle sous Unix, \code{'\e r'}, la convention Macintosh,
ou \code{'\e r\e n'}, la convention sous Windows.
Toutes ces représentation externes sont vues par le programme Python
comme \code{'\e n'}.
\note{Cette fonctionnalité n'est présente que si Python est construit
avec le support universal newline (par défaut). De plus, l'attribut des
objets fichiers \member{stdout}, \member{stdin} et \member{stderr} n'est
pas mis à jour par la méthode communicate().}

Si renseignés, \var{startupinfo} et \var{creationflags} seront passés
à la fonction sous-jascente CreateProcess(). Ils peuvent déterminer
des choses comme l'apparence de la fenêtre principale et la priorité
pour le nouveau processus. (Seulement sous windows).
\end{classdesc}

\subsubsection{Fonctions pratiques}

Ce module défini également deux fonctions raccourcis :

\begin{funcdesc}{call}{*popenargs, **kwargs}
Lance la commande avec les paramètres. Attend que la commande soit
terminée, puis renvoi son attribut \member{returncode}.

Les paramètres sont les mêmes que pour le constructeur de Popen. Exemple :

\begin{verbatim}
retcode = call(["ls", "-l"])
\end{verbatim}
\end{funcdesc}

\begin{funcdesc}{check_call}{*popenargs, **kwargs}
Lance la commande avec les paramètres. Attend que la commande soit terminée.
Termine normalement si le code de retour est zéro, sinon lance l'exception
CalledProcessError. L'objet CalledProcessError contiendra le code de retour
dans l'attribut \member{errno}.

Les paramètres sont les mêmes que pour le constructeur Popen. Exemple :

\begin{verbatim}
check_call(["ls", "-l"])
\end{verbatim}
\end{funcdesc}

\subsubsection{Exceptions}

Les exceptions qui on été levées dans le processus fils, avant que le
nouveau programme ait commencé à s'éxécuter, seront levées à nouveau
chez le parent. De plus, l'object de l'exception contiendra un attribut
supplémentaire appelé \member{child_traceback}, qui est une chaine
contenant les informations de traceback du point de vue du fils.

L'exception levée la plus courante est \exception{OSError}. Cela arrive,
par exemple, si on essaye de lancer un fichier inexistant. Les applications
devraient être prête pour les exception \exception{OSError}.

\exception{ValueError} sera levée si \class{Popen} est appelé avec
des paramètres invalides.

check_call() va lever \exception{CalledProcessError}, qui est une
sous-classe de \exception{OSError}, si le processus renvoi un code
de retour différent de zéro.


\subsubsection{Sécurité}

À l'inverse de certains functions popen, cette implémentation ne va
jamais appeler /bin/sh implicitement. Cela signifie que tous les
caractères, y compris les méta-caractères du shell, peuvent
être passé au processus fils en toute sécurité.

\subsection{Popen Objects}

Les instances de \class{Popen} contiennent les méthodes suivantes :

\begin{methoddesc}{poll}{}
Vérifie si le processus fils est terminé. Renvoi l'attribut returncode
\end{methoddesc}

\begin{methoddesc}{wait}{}
Attend que le processus fils ce termine. Renvoi l'attribut returncode.
\end{methoddesc}

\begin{methoddesc}{communicate}{input=None}
Intéragi avec le processus: Envoi des données vers stdin. Lit les
données de stdout et stderr, jusqu'à ce que end-of-file soit atteind.
Attend que le processus se termine.
Le paramètre optionnel \var{input} devrait être une chaine à envoyer
au processus fils, ou \code{None}, si aucune donnée ne doit être
envoyée au fils.

communicate() renvoi un tuple (stdout, stderr).

\note{ Les données lues sont mise en tampon en mémoire, aussi n'utilisez pas
cette méthode si la taille des données est longue ou illimitée.}
\end{methoddesc}

Les attributs suivants sont également disponibles :

\begin{memberdesc}{stdin}
Si le paramètre \var{stdin} est un \code{PIPE}, cet attribut est un objet
fichier qui fourni une entrée vers le processus fils. Sinon, il est à
\code{None}.
\end{memberdesc}

\begin{memberdesc}{stdout}
Si le paramètre \var{stdout} est un \code{PIPE}, cet attribut est un objet
fichier qui fourni la sortie du processus fils. Sinon, il est à
\code{None}.
\end{memberdesc}

\begin{memberdesc}{stderr}
Si le paramètre \var{stderr} est un \code{PIPE}, cet attribut est un objet
fichier qui fourni la sortie d'erreur du processus fils. Sinon, il est à
\code{None}.
\end{memberdesc}

\begin{memberdesc}{pid}
L'ID du processus fils.
\end{memberdesc}

\begin{memberdesc}{returncode}
Le code de retour du fils. Une valeur \code{None} indique que le processus
n'est pas encore terminé. Une valeur négative -N indique que le fils
s'est terminé avec par le signal N (\UNIX{} seulement).
\end{memberdesc}


\subsection{Remplacement des anciennes fonctions avec le Module subprocess}

Dans cette section, "a ==> b" signifie que b peut être utilisé en remplacement
de a.

\note{ Toutes les fonctions de cette section échouent (plus ou moins)
silencieusement si le programme lancé ne peut pas être trouvé; ce module lance
une
\exception{OSError} exception.}

Dans les exemples suivants, nous assumerons que le module subprocess est
importé avec "from subprocess import *".

\subsubsection{Remplacement du guillement inversé (backquote) du shell /bin/sh}

\begin{verbatim}
output=`mycmd myarg`
==>
output = Popen(["mycmd", "myarg"], stdout=PIPE).communicate()[0]
\end{verbatim}

\subsubsection{Remplacement du signe pipe du shell}

\begin{verbatim}
output=`dmesg | grep hda`
==>
p1 = Popen(["dmesg"], stdout=PIPE)
p2 = Popen(["grep", "hda"], stdin=p1.stdout, stdout=PIPE)
output = p2.communicate()[0]
\end{verbatim}

\subsubsection{Remplacement de os.system()}

\begin{verbatim}
sts = os.system("mycmd" + " myarg")
==>
p = Popen("mycmd" + " myarg", shell=True)
sts = os.waitpid(p.pid, 0)
\end{verbatim}

Notes :

\begin{itemize}
\item Appeler le programme à travers le shell n'est généralement pas nécessaire.
\item Il est plus facile de regarder l'attribut \member{returncode} plutôt que
le status d'exit.
\end{itemize}

Un exemple plus réaliste pourrait être ainsi :

\begin{verbatim}
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, e:
print >>sys.stderr, "Execution failed:", e
\end{verbatim}

\subsubsection{Remplacement os.spawn*}

P_NOWAIT exemple :

\begin{verbatim}
pid = os.spawnlp(os.P_NOWAIT, "/bin/mycmd", "mycmd", "myarg")
==>
pid = Popen(["/bin/mycmd", "myarg"]).pid
\end{verbatim}

P_WAIT exemple:

\begin{verbatim}
retcode = os.spawnlp(os.P_WAIT, "/bin/mycmd", "mycmd", "myarg")
==>
retcode = call(["/bin/mycmd", "myarg"])
\end{verbatim}

Vector exemple:

\begin{verbatim}
os.spawnvp(os.P_NOWAIT, path, args)
==>
Popen([path] + args[1:])
\end{verbatim}

Environnement exemple:

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

\subsubsection{Remplacement os.popen*}

\begin{verbatim}
pipe = os.popen(cmd, mode='r', bufsize)
==>
pipe = Popen(cmd, shell=True, bufsize=bufsize, stdout=PIPE).stdout
\end{verbatim}

\begin{verbatim}
pipe = os.popen(cmd, mode='w', bufsize)
==>
pipe = Popen(cmd, shell=True, bufsize=bufsize, stdin=PIPE).stdin
\end{verbatim}

\begin{verbatim}
(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)
\end{verbatim}

\begin{verbatim}
(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)
\end{verbatim}

\begin{verbatim}
(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)
\end{verbatim}

\subsubsection{Replacement de popen2.*}

\note{ Si le paramètre cmd des fonctions popen2 est une chaine, la commande
est exécutée à travers /bin/sh. Si c'est une liste, la commande est
directement exécutée.
}

\begin{verbatim}
(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)
\end{verbatim}

\begin{verbatim}
(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)
\end{verbatim}

The popen2.Popen3 and popen3.Popen4 basically works as subprocess.Popen,
except that:

popen2.Popen3 et popen3.Popen4 fonctionnement essentiellement comme
subprocess.Popen, à l'exception de :

\begin{itemize}
\item subprocess.Popen lance une exception si l'exécution échoue.

\item le paramètre \var{capturestderr} est remplacé par le paramètre \var{stderr}.

\item stdin=PIPE et stdout=PIPE doivent être spécifiés.

\item popen2 ferme tous les descripteurs de fichiers par défaut, mais vous devez
spécifier colde_fds=True avec subprocess.Popen.
\end{itemize}



--
William Dodé - http://flibuste.net