"subprocess" --- Gestión de subprocesos
***************************************

**Código fuente:** Lib/subprocess.py

======================================================================

El módulo "subprocess" permite lanzar nuevos procesos, conectarse a
sus pipes de entrada/salida/error y obtener sus códigos de resultado.
Este módulo está destinado a reemplazar múltiples módulos y funciones
previamente existentes:

   os.system
   os.spawn*

Se puede obtener información sobre cómo utilizar el módulo
"subprocess" para reemplazar estos módulos y funciones en las
siguientes secciones.

Ver también: **PEP 324** -- PEP de proposición del módulo *subprocess*


Uso del módulo "subprocess"
===========================

La opción recomendada para invocar subprocesos es utilizar la función
"run()" para todos los casos al alcance de ésta. Para usos más
avanzados, se puede utilizar la interfaz de más bajo nivel "Popen".

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)

   Ejecuta la orden descrita por *args*. Espera a que termine y
   retorna una instancia de "CompletedProcess".

   Los argumentos mostrados en la definición superior son sólo los más
   comunes; que se describen posteriormente en Argumentos
   frecuentemente empleados (de ahí el uso de la notación por clave en
   la signatura abreviada). La signatura completa de la función es a
   grandes rasgos la misma que la del constructor de "Popen"; la
   mayoría de los argumentos de esta función se pasan a esa interfaz
   (no es el caso de  *timeout*,  *input*, *check* ni
   *capture_output*).

   Si *capture_output* es verdadero, se capturarán stdout y stderr. En
   tal caso, el objeto "Popen" interno se crea automáticamente con
   "stdout=PIPE" y "stderr=PIPE". No se pueden proporcionar los
   argumentos *stdout* y *stderr* a la vez que  *capture_output*. Si
   se desea capturar y combinar los dos flujos, se ha de usar
   "stdout=PIPE" y "stderr=STDOUT" en lugar de  *capture_output*.

   El argumento *timeout* se pasa a "Popen.communicate()". Si vence el
   plazo de ejecución, se matará el proceso hijo y se le esperará. Se
   relanzará la excepción "TimeoutExpired" cuando finalice el proceso
   hijo.

   Se pasará el argumento *input* a "Popen.communicate()" y de ahí, a
   la entrada estándar del subproceso. Si se usa, debe ser una
   secuencia de bytes o una cadena de texto si se especifican
   *encoding* o *errors* o *text* en verdadero. Cuando se usa, el
   objeto "Popen" interno se crea automáticamente con "stdin=PIPE" y
   no se puede usar el argumento *stdin* a la vez.

   Si *check* es verdadero y el proceso retorna un resultado distinto
   de cero, se lanzará una excepción "CalledProcessError". Los
   atributos de dicha excepción contendrán los argumentos, el código
   retornado y tanto stdout como stderr si se capturaron.

   Si se especifican *encoding* o *errors* o *text* es verdadero, se
   abrirán los objetos fichero para stdin, stdout y stderr en modo
   texto, con los *encoding* y *errors* especificados o los valores
   predeterminados de "io.TextIOWrapper". El argumento
   *universal_newlines* equivale a *text* y se admite por
   compatibilidad hacia atrás. Los objetos fichero se abren en modo
   binario por defecto.

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

   Ejemplos:

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

   Nuevo en la versión 3.5.

   Distinto en la versión 3.6: Se añadieron los parámetros *encoding*
   y *errors*

   Distinto en la versión 3.7: Se añadió el parámetro *text* como
   alias más comprensible de *universal_newlines*. Se añadió el
   parámetro *capture_output*.

   Distinto en la versión 3.10.11: 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

   El valor retornado por "run()", que representa un proceso ya
   terminado.

   args

      Los argumentos utilizados para lanzar el proceso. Pueden ser una
      lista o una cadena.

   returncode

      Estado de salida del proceso hijo. Típicamente, un estado de
      salida 0 indica que la ejecución tuvo éxito.

      Un valor negativo "-N" indica que el hijo fue forzado a terminar
      con la señal "N" (solamente POSIX).

   stdout

      La salida estándar capturada del proceso hijo. Una secuencia de
      bytes, o una cadena si se llamó a "run()" con *encoding*,
      *errors*, o *text* establecidos a "True". "None" si no se
      capturó el error estándar.

      Si se ejecutó el proceso con "stderr=subprocess.STDOUT", stdout
      y stderr se combinarán en este atributo, y "stderr" será "None".

   stderr

      El error estándar capturado del proceso hijo. Una secuencia de
      bytes, o una cadena si se llamó a "run()" con *encoding*,
      *errors*, o *text* establecidos a "True". "None" si no se
      capturó el error estándar.

   check_returncode()

      Si "returncode" no es cero, lanza un "CalledProcessError".

   Nuevo en la versión 3.5.

subprocess.DEVNULL

   Valor especial que se puede usar como argumento *stdin*, *stdout* o
   *stderr* de "Popen" y que indica que se usará el fichero especial
   "os.devnull".

   Nuevo en la versión 3.3.

subprocess.PIPE

   Valor especial que se puede usar como argumento *stdin*, *stdout* o
   *stderr* de "Popen" y que indica que se abrirá un pipe al flujo
   indicado. Es útil para usarlo con "Popen.communicate()".

subprocess.STDOUT

   Valor especial que se puede usar de argumento *stderr* a "Popen" y
   que indica que el error estándar debería ir al mismo gestor que la
   salida estándar.

exception subprocess.SubprocessError

   Clase base para el resto de excepciones de este módulo.

   Nuevo en la versión 3.3.

exception subprocess.TimeoutExpired

   Subclase de "SubprocessError", se lanza cuando expira un plazo de
   ejecución esperando a un proceso hijo.

   cmd

      Orden que se utilizó para lanzar el proceso hijo.

   timeout

      Plazo de ejecución en segundos.

   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 de *output*, por simetría con "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.

   Nuevo en la versión 3.3.

   Distinto en la versión 3.5: Se añadieron los atributos *stdout* y
   *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

      Estado de salida del proceso hijo. Si el proceso terminó por
      causa de una señal, el estado será el número de la señal en
      negativo.

   cmd

      Orden que se utilizó para lanzar el proceso hijo.

   output

      Salida del proceso hijo si fue capturada por "run()" o
      "check_output()".  De otro modo, "None".

   stdout

      Alias de *output*, por simetría con "stderr".

   stderr

      Salida de *stderr* del proceso hijo si fue capturada por
      "run()". De otro modo, "None".

   Distinto en la versión 3.5: Se añadieron los atributos *stdout* y
   *stderr*


Argumentos frecuentemente empleados
-----------------------------------

Para permitir una gran variedad de usos, el constructor de "Popen" (y
las funciones asociadas) aceptan un gran número de argumentos
opcionales. Para los usos más habituales, se pueden dejar de forma
segura los valores por defecto. Los argumentos más frecuentemente
necesarios son:

   *args* se requiere en todas las llamadas; debe ser una cadena o una
   secuencia de argumentos al programa. En general, es mejor
   proporcionar una secuencia de argumentos porque permite que el
   módulo se ocupe de las secuencias de escape y los entrecomillados
   de los argumentos (por ejemplo, para permitir espacios en los
   nombres de fichero). Si se pasa una cadena simple, se ha de
   especificar *shell* como "True" (ver más adelante) o la cadena debe
   ser el nombre del programa a ejecutar sin especificar ningún
   argumento.

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

   Si se especifican *encoding* o *errors*, o *text* (o su alias
   *universal_newlines*) es verdadero, se abrirán en modo texto los
   objetos fichero *stdin*, *stdout* y *stderr* usando los *encoding*
   y *errors* especificados en la llamada o los valores
   predeterminados de "io.TextIOWrapper".

   Para *stdin*, los saltos del línea "'\n'" de la entrada serán
   convertidos al separador de línea predeterminado "os.linesep". Para
   *stdout* y *stderr*, todos los saltos de línea de la salida serán
   convertidos a "'\n'". Hay más información en la documentación de la
   clase "io.TextIOWrapper" para el caso en que el argumento
   *newline* de su constructor es "None".

   Si no se usa el modo texto, *stdin*, *stdout* y *stderr* se abrirán
   como flujos binarios. No se realizará ninguna codificación ni
   conversión de salto de línea.

   Nuevo en la versión 3.6: Se añadieron los parámetros *encoding* y
   *errors*.

   Nuevo en la versión 3.7: Se añadió el parámetro *text* como alias
   de *universal_newlines*.

   Nota:

     El atributo *newlines* de los objetos fichero "Popen.stdin",
     "Popen.stdout" y "Popen.stderr" no es actualizado por el método
     "Popen.communicate()".

   Si *shell* es "True", la orden especificada se ejecutará pasando
   por la shell. Esto tiene utilidad si se usa Python principalmente
   por el flujo de control mejorado sobre la mayoría de las shell de
   sistema, pero se desea también un acceso práctico a otras
   características de la shell, como pipes, nombres de fichero con
   comodines, expansión de variables de entorno o expansión de "~" al
   directorio *home* del usuario. Sin embargo, no se debe olvidar que
   el propio Python tiene implementaciones de muchas características
   tipo shell (en particular, "glob", "fnmatch", "os.walk()",
   "os.path.expandvars()", "os.path.expanduser()", y "shutil").

   Distinto en la versión 3.3: Cuando *universal_newlines* es "True",
   la clase usa la codificación "locale.getpreferredencoding(False)"
   en lugar de "locale.getpreferredencoding()".  Ver la clase
   "io.TextIOWrapper" para obtener más información sobre este cambio.

   Nota:

     Leer la sección Consideraciones sobre la seguridad antes de usar
     "shell=True".

Estas opciones y el resto se describen con más detalle en la
documentación del constructor de "Popen".


El constructor de Popen
-----------------------

El proceso interno de creación y gestión de este módulo lo gestiona la
clase "Popen". Proporciona una gran flexibilidad para que los
desarrolladores sean capaces de gestionar los casos menos comunes que
quedan sin cubrir por las funciones auxiliares.

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)

   Ejecuta un programa hijo en un proceso nuevo. En POSIX, la clase
   usa  "os.execvp()" como comportamiento para lanzar el proceso hijo.
   En Windows, la clase usa la función "CreateProcess()" de Windows.
   Los argumentos de "Popen" son los siguientes.

   *args* debe ser o una secuencia de argumentos de programa o una
   cadena simple o un *objeto tipo ruta*. Por omisión, el programa a
   ejecutar es el primer elemento de *args* si *args* es una
   secuencia.  Si *args* es una cadena, la interpretación es
   dependiente de la plataforma, según se describe más abajo. Véase
   los argumentos *shell* y *executable* para más información sobre el
   comportamiento por defecto. Salvo que se indique, se recomienda
   pasar los *args* como una secuencia.

   Advertencia:

     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.La resolución de la ruta de *executable* (o el
     primer elemento de *args*) depende de la plataforma. Para POSIX,
     consulte "os.execvpe()", y tenga en cuenta que al resolver o
     buscar la ruta ejecutable, *cwd* anula el directorio de trabajo
     actual y *env* puede anular la variable de entorno "PATH". Para
     Windows, consulte la documentación de los parámetros
     "lpApplicationName" e "lpCommandLine" de WinAPI "CreateProcess",
     y tenga en cuenta que al resolver o buscar la ruta ejecutable con
     "shell = False", *cwd* no anula el directorio de trabajo actual y
     *env* no puede anular la variable de entorno "PATH". El uso de
     una ruta completa evita todas estas variaciones.

   Un ejemplo del paso de argumentos a un programa externo mediante
   una secuencia:

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

   En POSIX, si *args* es una cadena se interpreta como el nombre o la
   ruta del programa que ejecutar. Sin embargo, esto solamente
   funciona si no hay que pasar argumentos al programa.

   Nota:

     Puede que no resulte evidente cómo descomponer una orden de la
     shell en una secuencia de argumentos, especialmente en casos
     complejos. "shlex.split()" puede aclarar cómo determinar la
     descomposición en tokens de *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!

     Hay que destacar en particular que las opciones (como *-input*) y
     los argumentos (como *eggs.txt*) que van separados por espacio en
     blanco en la shell van en elementos de lista separados, mientras
     los argumentos que necesitan entrecomillado o escapado de
     espacios cuando se usan en la shell (como los nombres de ficheros
     con espacios o la orden *echo* anteriormente mostrada) son
     elementos simples de la lista.

   En Windows, si *args* es una secuencia, se convertirá a cadena del
   modo descrito en Cómo convertir una secuencia de argumentos a una
   cadena en Windows. Esto es así porque la función de bajo nivel
   "CreateProcess()" funciona sobre cadenas.

   Distinto en la versión 3.6: El parámetro *args* toma un *objeto
   tipo ruta* si *shell* es "False" y una secuencia de objetos tipo
   fichero en POSIX.

   Distinto en la versión 3.8: El parámetro *args* toma un *objeto
   tipo ruta* si *shell* es "False" y una secuencia de bytes y objetos
   tipo fichero en Windows.

   El argumento *shell* ("False``por defecto) especifica si usar la
   shell como programa a ejecutar. Si *shell* es ``True", se
   recomienda pasar *args* como cadena mejor que como secuencia.

   En POSIX con "shell=True", la shell predeterminada es "/bin/sh".
   Si *args* es una cadena, ésta especifica la orden a ejecutar por la
   shell. Esto significa que la cadena tiene que tener el formato que
   tendría si se tecleara en la línea de órdenes. Esto incluye, por
   ejemplo, el entrecomillado y las secuencias de escape necesarias
   para los nombres de fichero que contengan espacios. Si *args* es
   una secuencia, el primer elemento especifica la cadena de la orden
   y cualquier otro elemento será tratado como argumentos adicionales
   a la propia shell. De este modo, "Popen" hace el equivalente de:

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

   En Windows con "shell=True", la variable de entorno "COMSPEC"
   especifica la shell predeterminada. Solamente hace falta
   especificar "shell=True" en Windows cuando la orden que se desea
   ejecutar es interna a la shell (como. **dir** o **copy**).  No hace
   falta especificar "shell=True" para ejecutar un fichero por lotes o
   un ejecutable de consola.

   Nota:

     Leer la sección Consideraciones sobre la seguridad antes de usar
     "shell=True".

   Se proporcionará *bufsize* como el argumento correspondiente a la
   función "open()" cuando se creen los objetos fichero de los flujos
   stdin/stdout/stderr:

   * "0" significa sin búfer (*read* y *write* son una llamada al
     sistema y pueden retornar datos parciales)

   * "1" means line buffered (only usable if "text=True" or
     "universal_newlines=True")

   * cualquier otro valor positivo indica que hay que usar un búfer de
     aproximadamente dicho tamaño

   * *bufsize* negativo (el valor por defecto) indica que se use el
     valor predeterminado del sistema, *io.DEFAULT_BUFFER_SIZE*.

   Distinto en la versión 3.3.1: *bufsize* es ahora -1 por defecto
   para permitir que el buffering por defecto se comporte  como o que
   la mayoría del código espera. En versiones anteriores a Python
   3.2.4 o 3.3.1 tomaba un valor por defecto de "0", sin búfer, lo que
   permitía lecturas demasiado cortas. Esto no era intencionado y no
   se correspondía con el comportamiento de Python 2 como la mayoría
   de códigos esperan.

   El argumento *executable* especifica un programa de reemplazo que
   ejecutar. Esto es muy poco frecuente. Cuando "shell=False",
   *executable* reemplaza al programa especificado por *args*. Sin
   embargo, se pasan los *args* originales al programa. La mayoría de
   los programas tratan el programa especificado en los *args* como el
   nombre del programa, que puede ser diferente del programa realmente
   ejecutado. En POSIX, el nombre en *args* funciona como nombre
   visible en utilidades como  **ps**.  Si "shell=True", en POSIX el
   argumento *executable* especifica una shell de reemplazo de la
   predeterminada "/bin/sh".

   Distinto en la versión 3.6: El parámetro *executable* acepta un
   *objeto tipo ruta* en POSIX.

   Distinto en la versión 3.8: El parámetro *executable* acepta bytes
   y un *objeto tipo ruta* en POSIX.

   Distinto en la versión 3.10.11: Changed Windows shell search order
   for "shell=True". The current directory and "%PATH%" are replaced
   with "%COMSPEC%" and "%SystemRoot%\System32\cmd.exe". As a result,
   dropping a malicious program named "cmd.exe" into a current
   directory no longer works.

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

   Si se establece *preexec_fn* a un objeto invocable, se llamará a
   dicho objeto en el proceso hijo justo antes de que se ejecute el
   hijo. (solamente POSIX)

   Advertencia:

     No es seguro utilizar el parámetro *preexec_fn* en presencia de
     hilos de ejecución en la aplicación. El proceso hijo podría
     bloquearse antes de llamar a *exec*. ¡Si es imprescindible, que
     sea tan simple como sea posible!  Se ha de minimizar el número de
     librerías a las que se llama.

   Nota:

     Si es necesario modificar el entorno para el proceso hijo, se
     debe utilizar el parámetro *env* en lugar de hacerlo en una
     *preexec_fn*. El parámetro *start_new_session* puede tomar el
     lugar de un uso anteriormente común de *preexec_fn* para llamar a
     *os.setsid* en el proceso hijo.

   Distinto en la versión 3.8: Se ha abandonado el soporte de
   *preexec_fn* en subintérpretes. El uso de dicho parámetro en un
   subintérprete lanza "RuntimeError". La nueva restricción puede
   afectar a aplicaciones desplegadas en *mod_wsgi*, *uWSGI* y otros
   entornos incrustados.

   Si *close_fds* es verdadero, todos los descriptores de fichero
   salvo "0", "1" y "2" serán cerrados antes de ejecutar el proceso
   hijo. Por el contrario, cuando *close_fds* es falso, los
   descriptores de fichero obedecen su indicador de heredable según
   Herencia de los descriptores de archivos.

   En Windows, si *close_fds* es verdadero el proceso hijo no heredará
   ningún gestor de fichero salvo que se le pasen explícitamente en el
   elemento "handle_list" de "STARTUPINFO.lpAttributeList", o mediante
   redirección estándar.

   Distinto en la versión 3.2: El valor predeterminado de *close_fds*
   se cambió de "False" a lo antes descrito.

   Distinto en la versión 3.7: En Windows, el valor predeterminado de
   *close_fds* se cambió de "False" a "True" al redirigir los gestores
   estándar. Ahora es posible establecer *close_fds* a "True" cuando
   se redirigen los gestores estándar.

   *pass_fds* es una secuencia de descriptor de ficheros opcional que
   han de mantenerse abiertos entre el proceso padre e hijo. Si se
   proporciona un valor a *pass_fds* se fuerza *close_fds* a "True".
   (solamente POSIX)

   Distinto en la versión 3.2: Se añadió el parámetro *pass_fds*.

   Si *cwd* no es "None", la función cambia el directorio de trabajo a
   *cwd* antes de ejecutar el proceso hijo.  *cwd* puede ser una
   cadena, o un objeto bytes o *tipo ruta*. En POSIX, la función busca
   *executable* (o el primer elemento de *args*) relativo a *cwd* si
   la ruta del ejecutable es relativa.

   Distinto en la versión 3.6: El parámetro *cwd* acepta un *objeto
   tipo ruta* en POSIX.

   Distinto en la versión 3.7: El parámetro *cwd* acepta un *objeto
   tipo ruta* en Windows.

   Distinto en la versión 3.8: El parámetro *cwd* acepta un objeto
   bytes en Windows.

   Si *restore_signals* es verdadero (el valor por defecto) todas las
   señales que Python ha establecido a  SIG_IGN se restauran a SIG_DFL
   en el proceso hijo antes del *exec*. En la actualidad, esto incluye
   las señales SIGPIPE, SIGXFZ y SIGXFSZ (solamente POSIX).

   Distinto en la versión 3.2: Se añadió *restore_signals*.

   Si *start_new_session* es verdadero la llamada al sistema *setsid*
   se hará en el proceso hijo antes de la ejecución del subproceso
   (solamente POSIX).

   Distinto en la versión 3.2: Se añadió *start_new_session*.

   Si *group* no es "None", la llamada a sistema setregid() se hará en
   el proceso hijo antes de la ejecución del subproceso. Si el valor
   proveído es una cadena de caracteres, será buscado usando
   "grp.getgrnam()" y el valor en "gr_gid" será usado. Si el valor es
   un entero, será pasado literalmente. (solamente POSIX)

   Disponibilidad: POSIX

   Nuevo en la versión 3.9.

   Si *extra_groups* no es "None", la llamada a sistema setgroups() se
   hará en el proceso hijo antes de la ejecución del subproceso.
   Cadenas de caracteres proveídas en *extra_groups* serán buscadas
   usando "grp.getgrnam()" y los valores en "gr_gid" serán usados.
   Valor enteros serán pasados literalmente. (solamente POSIX)

   Disponibilidad: POSIX

   Nuevo en la versión 3.9.

   Si *user* no es "None", la llamada a sistema setreuid() se hará en
   el proceso hijo antes de la ejecución del subproceso. Si el valor
   proveído es una cadena de caracteres, será buscado usando
   "pwd.getpwnam()" y el valor en "pw_uid" será usado. Si el valor es
   un entero, será pasado literalmente. (solamente POSIX)

   Disponibilidad: POSIX

   Nuevo en la versión 3.9.

   Si *umask* no es negativo, la llamada a sistema umask() se hará en
   el proceso hijo antes de la ejecución del subproceso.

   Disponibilidad: POSIX

   Nuevo en la versión 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".

   Nota:

     Si se especifica, *env* debe proporcionar las variables
     necesarias para que el programa se ejecute. En Windows, para
     ejecutar una side-by-side assembly el *env* especificado **debe**
     incluir un "SystemRoot" válido.

   Si se especifica *encoding* o *errors*, o *text* verdadero, los
   objetos fichero *stdin*, *stdout* y *stderr* se abren en modo texto
   con la codificación y *errors* especificados, según se describió en
   Argumentos frecuentemente empleados. El argumento
   *universal_newlines* es equivalente a *text* y se admite por
   compatibilidad hacia atrás. Por omisión, los ficheros se abren en
   modo binario.

   Nuevo en la versión 3.6: Se añadieron *encoding* y *errors*.

   Nuevo en la versión 3.7: Se añadió *text* como alias más legible de
   *universal_newlines*.

   Si se proporciona, *startupinfo* será un objeto "STARTUPINFO", que
   se pasa a la función de más bajo nivel "CreateProcess".
   *creationflags*, si está presente, puede ser uno o más de los
   siguientes indicadores:

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

   *pipeize* se puede usar para cambiar el tamaño de la tubería cuando
   "PIPE" se usa para *stdin*, *stdout* o *stderr*. El tamaño de la
   tubería solo se cambia en plataformas que lo admiten (solo Linux en
   este momento de redacción). Otras plataformas ignorarán este
   parámetro.

   Nuevo en la versión 3.10: Se añadió el parámetro "pipesize".

   Se puede usar los objetos Popen como gestores de contexto mediante
   sentencia "with": a la salida, los descriptores de flujo se cierran
   y se espera a que acabe el proceso.

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

   Lanza un  evento de auditoría "subprocess.Popen" con argumentos
   "executable", "args", "cwd", "env".

   Distinto en la versión 3.2: Se añadió la funcionalidad de gestor de
   contexto.

   Distinto en la versión 3.6: El destructor de Popen ahora emite una
   advertencia "ResourceWarning" si el proceso hijo todavía se está
   ejecutando.

   Distinto en la versión 3.8: Popen puede usar "os.posix_spawn()" en
   algunos casos para obtener mejor rendimiento. En el Subsistema de
   Windows para Linux (WSL) y en la emulación del modo usuario de
   QEMU, el constructor de Popen que use "os.posix_spawn()" ya no
   lanzará una excepción cuando se den errores tales como que un
   programa no esté, sino que el proceso hijo fracasará con un
   "returncode" distinto de cero.


Excepciones
-----------

Las excepciones lanzadas en el proceso hijo, antes de que el nuevo
programa haya empezado a ejecutarse, se relanzarán en el padre.

La excepción más común que se lanza es "OSError". Esto ocurre, por
ejemplo, al intentar ejecutar un archivo inexistente. Las aplicaciones
deben prepararse para excepciones "OSError". Tenga en cuenta que,
cuando "shell = True", "OSError" será lanzado por el hijo solo si no
se encontró el shell seleccionado. Para determinar si el shell no pudo
encontrar la aplicación solicitada, es necesario verificar el código
de retorno o la salida del subproceso.

Se lanzará un "ValueError" si se llama a "Popen" con argumentos no
válidos.

"check_call()" y "check_output()" lanzarán un "CalledProcessError" si
el proceso invocado retorna un código de retorno distinto de cero.

Todas las funciones y métodos que admiten un parámetro *timeout*,
tales como "call()" y "Popen.communicate()" lanzarán "TimeoutExpired"
si se vence el plazo de ejecución antes de que finalice el proceso
hijo.

Todas las excepciones definidas en este módulo heredan de
"SubprocessError".

   Nuevo en la versión 3.3: Se añadió la clase base "SubprocessError".


Consideraciones sobre seguridad
===============================

Al contrario que otras funciones popen, esta implementación nunca
llamará implícitamente a la shell del sistema. Esto significa que
todos los caracteres, incluidos los metacaracteres de la shell, se
pueden pasar de manera segura a los procesos hijos. Si se invoca la
shell explícitamente, mediante "shell=True", es responsabilidad de la
aplicación asegurar que todo el espaciado y metacaracteres se
entrecomillan adecuadamente para evitar vulnerabilidades de inyección
de código. En algunas plataformas, es posible usar "shlex.quote()"
para este escape.


Objetos Popen
=============

Las instancias de la clase "Popen" cuentan con los siguientes métodos:

Popen.poll()

   Comprueba si el proceso hijo ha finalizado. Establece y retorna el
   atributo "returncode". De lo contrario, retorna "None".

Popen.wait(timeout=None)

   Espera a que termine el proceso hijo. Establece y retorna el
   atributo "returncode".

   Si el proceso no finaliza tras *timeout* segundos, lanza una
   excepción "TimeoutExpired". Se puede capturar esta excepción para
   reintentar la espera.

   Nota:

     Esto causará un bloqueo cuando se use "stdout=PIPE" o
     "stderr=PIPE" y el proceso hijo genere suficiente salida hacia un
     pipe como para bloquear esperando que el búfer del pipe del SO
     acepte más datos. Se debe usar "Popen.communicate()" cuando se
     usen pipes para evitar esto.

   Nota:

     Esta función se implementa mediante una espera activa (llamada no
     bloqueante y breves llamadas a *sleep*). Se debe usar el módulo
     "asyncio" para hacer una espera asíncrona: ver
     "asyncio.create_subprocess_exec".

   Distinto en la versión 3.3: Se añadió *timeout*.

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

   Interactúa con el proceso: Envía datos a stdin. Lee datos de stdout
   y stderr hasta encontrar un fin-de-fichero. Espera a que termine el
   proceso y escribe el atributo "returncode". El argumento opcional
   *input* debe contener los datos que hay que enviar al proceso hijo
   o "None" si no hay que enviar datos al proceso hijo. Si se abrieron
   los flujos en modo texto, *input* ha de ser una cadena de
   caracteres. En caso contrario, debe contener bytes.

   "communicate()" retorna una tupla "(stdout_data, stderr_data)". Los
   datos serán cadenas si se abrieron los flujos en modo texto, en
   caso contrario serán bytes.

   Adviértase que si se desea enviar datos al stdin del proceso, se ha
   de crear el objeto Popen con "stdin=PIPE". Análogamente, para
   obtener algo diferente de "None" en la tupla del resultado, hay que
   suministrar "stdout=PIPE" o "stderr=PIPE" también.

   Si el proceso no termina tras *timeout* segundos, se lanza una
   excepción "TimeoutExpired". Si se captura dicha excepción y se
   reintenta la comunicación, no se perderán datos de salida.

   No se matará el proceso si vence el plazo de ejecución, así que
   para hacer limpieza, una aplicación correcta debería matar el
   proceso y terminar la comunicación:

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

   Nota:

     Los datos leídos pasan por un búfer en memoria, así que no se ha
     de usar este método para un tamaño de datos grande o ilimitado.

   Distinto en la versión 3.3: Se añadió *timeout*.

Popen.send_signal(signal)

   Envía la señal *signal* al proceso hijo.

   No hace nada si el proceso ya ha terminado.

   Nota:

     En Windows, SIGTERM es un alias de "terminate()". Se puede enviar
     CTRL_C_EVENT y CTRL_BREAK_EVENT a los procesos creados con un
     parámetro *creationflags* que incluya *CREATE_NEW_PROCESS_GROUP*.

Popen.terminate()

   Detiene el proceso hijo. En sistemas operativos POSIX este método
   envía SIGTERM al proceso hijo. En Windows se llama a la función
   "TerminateProcess()" de la API de Win32 para detener el proceso
   hijo.

Popen.kill()

   Mata el proceso hijo. En sistemas operativos POSIX la función envía
   SIGKILL al proceso hijo. En Windows "kill()" es un alias de
   "terminate()".

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

Popen.args

   El argumento *args* según se pasó a "Popen": o una secuencia de
   argumentos del programa o una cadena sencilla.

   Nuevo en la versión 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".

Advertencia:

  Se ha de usar "communicate()" en lugar de ".stdin.write",
  ".stdout.read" o ".stderr.read" para evitar bloqueos por búfer de
  pipes del SO llenos que puedan bloquear el proceso hijo.

Popen.pid

   El ID de proceso del hijo.

   Adviértase que si se establece el argumento *shell* a "True", éste
   es el ID de proceso del la shell generada.

Popen.returncode

   El código de retorno del hijo, establecido por "poll()" y "wait()"
   (e indirectamente por "communicate()"). Un valor "None" indica que
   el proceso no ha terminado aún.

   Un valor negativo "-N" indica que el hijo fue forzado a terminar
   con la señal "N" (solamente POSIX).


Elementos auxiliares de Popen en Windows
========================================

La clase "STARTUPINFO" y las siguientes constantes sólo están
disponibles en Windows.

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

   Se utiliza un soporte parcial de la estructura STARTUPINFO de
   Windows para la creación de "Popen". Se pueden establecer los
   siguientes atributos pasándolos como argumentos sólo por clave.

   Distinto en la versión 3.7: Se añadió el soporte de argumentos sólo
   por clave.

   dwFlags

      Un campo bit que determina si se usan ciertos atributos de
      "STARTUPINFO" cuando el proceso crea una ventana.

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

   hStdInput

      Si "dwFlags" especifica "STARTF_USESTDHANDLES", este atributo es
      el gestor de entrada estándar del proceso. Si no se especifica
      "STARTF_USESTDHANDLES", el valor predeterminado de entrada
      estándar es el búfer de teclado.

   hStdOutput

      Si "dwFlags" especifica "STARTF_USESTDHANDLES", este atributo es
      el gestor de salida estándar del proceso. En caso contrario, se
      hace caso omiso del atributo y el valor predeterminado de salida
      estándar es el búfer de ventana.

   hStdError

      Si "dwFlags" especifica "STARTF_USESTDHANDLES", este atributo es
      el gestor de error estándar del proceso. En caso contrario, se
      hace caso omiso del atributo y el valor predeterminado de error
      estándar es el búfer de ventana.

   wShowWindow

      Si "dwFlags" especifica "STARTF_USESHOWWINDOW", este atributo
      puede ser cualquiera de los valores que pueden especificarse en
      el parámetro "nCmdShow" para la función ShowWindow, salvo
      "SW_SHOWDEFAULT". De otro modo, se hace caso omiso del atributo.

      Se proporciona "SW_HIDE" para este atributo. Se usa cuando se
      llama a "Popen" con "shell=True".

   lpAttributeList

      Un diccionario de atributos adicionales para la creación del
      proceso, según "STARTUPINFOEX", véase UpdateProcThreadAttribute.

      Atributos admitidos:

      **handle_list**
         Una secuencia de gestores que se heredará. *close_fds* debe
         ser verdadero si no viene vacío.

         Los gestores deben hacerse temporalmente heredables por
         "os.set_handle_inheritable()" cuando se pasan al constructor
         de "Popen" o de lo contrario, se lanzará "OSError" con el
         error de Windows "ERROR_INVALID_PARAMETER" (87).

         Advertencia:

           En un proceso multihilo, hay que evitar filtrar gestores no
           heredables cuando se combina esta característica con
           llamadas concurrentes a otras funciones de creación de
           procesos que heredan todos los gestores, como
           "os.system()". Esto también rige para la redirección de
           gestores estándar, que crea temporalmente gestores
           heredables.

      Nuevo en la versión 3.7.


Constantes de Windows
---------------------

El módulo "subprocess" expone las siguientes constantes.

subprocess.STD_INPUT_HANDLE

   El dispositivo de entrada estándar. Inicialmente, es el búfer de
   entrada de la consola, "CONIN$".

subprocess.STD_OUTPUT_HANDLE

   El dispositivo de salida estándar. Inicialmente, es el búfer de
   pantalla de la consola activa, "CONOUT$".

subprocess.STD_ERROR_HANDLE

   El dispositivo de error estándar. Inicialmente, es el búfer de
   pantalla de la consola activa, "CONOUT$".

subprocess.SW_HIDE

   Oculta la ventana. Se activará otra ventana.

subprocess.STARTF_USESTDHANDLES

   Especifica que los atributos "STARTUPINFO.hStdInput",
   "STARTUPINFO.hStdOutput", y "STARTUPINFO.hStdError" contienen
   información adicional.

subprocess.STARTF_USESHOWWINDOW

   Especifica que el atributo "STARTUPINFO.wShowWindow" contiene
   información adicional.

subprocess.CREATE_NEW_CONSOLE

   El nuevo proceso obtiene una nueva consola, en lugar de heredar la
   consola del padre (que es el comportamiento predeterminado).

subprocess.CREATE_NEW_PROCESS_GROUP

   Un parámetro "Popen" "creationflags" para especificar que se cree
   un nuevo grupo de procesos. Este indicador es necesario para usar
   "os.kill()" sobre el subproceso.

   Este indicador no se tiene en cuenta si se especifica
   "CREATE_NEW_CONSOLE".

subprocess.ABOVE_NORMAL_PRIORITY_CLASS

   Parámetro "Popen" "creationflags" para especificar que el nuevo
   proceso tendrá una prioridad superior a la media.

   Nuevo en la versión 3.7.

subprocess.BELOW_NORMAL_PRIORITY_CLASS

   Parámetro "Popen" "creationflags" para especificar que el nuevo
   proceso tendrá una prioridad inferior a la media.

   Nuevo en la versión 3.7.

subprocess.HIGH_PRIORITY_CLASS

   Parámetro "Popen" "creationflags" para especificar que el nuevo
   proceso tendrá una prioridad elevada.

   Nuevo en la versión 3.7.

subprocess.IDLE_PRIORITY_CLASS

   Parámetro "Popen" "creationflags" para especificar que el nuevo
   proceso tendrá una la mínima prioridad.

   Nuevo en la versión 3.7.

subprocess.NORMAL_PRIORITY_CLASS

   Parámetro "Popen" "creationflags" para especificar que el nuevo
   proceso tendrá una prioridad normal (éste es el valor
   predeterminado).

   Nuevo en la versión 3.7.

subprocess.REALTIME_PRIORITY_CLASS

   Parámetro "Popen" "creationflags" para especificar que el nuevo
   proceso tendrá una prioridad de tiempo real. Raramente se debería
   usar REALTIME_PRIORITY_CLASS, porque esto interrumpe los hilos que
   gestionan la entrada del ratón y del teclado, así como la gestión
   del volcado de búfer del disco. Esta clase es apropiada para
   aplicaciones que se comunican directamente con el hardware o que
   llevan a cabo tareas breves que no admitan interrupciones.

   Nuevo en la versión 3.7.

subprocess.CREATE_NO_WINDOW

   Parámetro "Popen" "creationflags" para especificar que el nuevo
   proceso no creará una ventana.

   Nuevo en la versión 3.7.

subprocess.DETACHED_PROCESS

   Parámetro "Popen" "creationflags" para especificar que el nuevo
   proceso no heredará la consola del padre. Este valor es
   incompatible con CREATE_NEW_CONSOLE.

   Nuevo en la versión 3.7.

subprocess.CREATE_DEFAULT_ERROR_MODE

   Parámetro "Popen" "creationflags" para especificar que el nuevo
   proceso no hereda el modo de error del proceso padre. En su lugar,
   el proceso parte del modo de error predeterminado. Esta
   característica es particularmente útil para aplicaciones de shell
   multihilo que se ejecutan con los errores 'duros' desactivados.

   Nuevo en la versión 3.7.

subprocess.CREATE_BREAKAWAY_FROM_JOB

   Parámetro "Popen" "creationflags" para especificar que el nuevo
   proceso no está asociado a la tarea.

   Nuevo en la versión 3.7.


Antigua API de alto nivel
=========================

Antes de Python 3.5, estas tres funciones conformaban la API de alto
nivel para subprocesos. Ahora se puede usar "run()" en muchos casos,
pero hay mucho código escrito con estas funciones.

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

   Ejecutar la orden descrita por *args*. Esperar que la orden se
   complete y retornar al atributo "returncode".

   El código que requiera capturar stdout o stderr debería usar
   "run()" en su lugar:

      run(...).returncode

   Para suprimir stdout o stderr se ha de proporcionar un valor de
   "DEVNULL".

   Se muestran algunos argumentos comunes. La signatura completa de la
   función es la misma que la del constructor de "Popen"; esta función
   pasa todos los argumentos proporcionados (salvo *timeout*)
   directamente a esa interfaz.

   Nota:

     No usar "stdout=PIPE" ni "stderr=PIPE" con esta función. El
     proceso hijo se bloqueará si genera suficiente salida a un pipe
     como para saturar el búfer del pipe del sistema operativo
     mientras no se lee de los pipes.

   Distinto en la versión 3.3: Se añadió *timeout*.

   Distinto en la versión 3.10.11: 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)

   Ejecuta la instrucción con argumentos. Espera a que la instrucción
   se complete. Si el código de retorno es cero retorna; en caso
   contrario, lanza "CalledProcessError". El objeto
   "CalledProcessError" tendrá el código de retorno en el atributo
   "returncode".Si "check_call()" no pudo iniciar el proceso,
   propagará la excepción que fue lanzada.

   El código que requiera capturar stdout o stderr debería usar
   "run()" en su lugar:

      run(..., check=True)

   Para suprimir stdout o stderr se ha de proporcionar un valor de
   "DEVNULL".

   Se muestran algunos argumentos comunes. La signatura completa de la
   función es la misma que la del constructor de "Popen"; esta función
   pasa todos los argumentos proporcionados (salvo *timeout*)
   directamente a esa interfaz.

   Nota:

     No usar "stdout=PIPE" ni "stderr=PIPE" con esta función. El
     proceso hijo se bloqueará si genera suficiente salida a un pipe
     como para saturar el búfer del pipe del sistema operativo
     mientras no se lee de los pipes.

   Distinto en la versión 3.3: Se añadió *timeout*.

   Distinto en la versión 3.10.11: 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)

   Ejecuta orden con argumentos y retorna su salida.

   Si el código de retorno fue diferente de cero lanza un
   "CalledProcessError". El objeto "CalledProcessError" tendrá el
   código de retorno en el atributo "returncode" y los datos de salida
   en el atributo "output".

   Esto equivale a:

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

   Los argumentos mostrados arriba son meramente algunos de los
   comunes. La signatura completa de la función es casi la misma que
   la de "run()" - la mayoría de los argumentos se pasa directamente a
   esa interfaz. Existe una diferencia con la interfaz de "run()"
   respecto al comportamiento: pasar "input=None" genera el mismo
   comportamiento que "input=b''" (o "input=''", dependiendo de otros
   argumentos) en vez de usar el flujo entrada estándar del padre.

   Por omisión, esta función retornará los datos como bytes
   codificados. La codificación real de los datos podría depender de
   la orden invocada, por lo que la decodificación a texto se deberá
   hacer al nivel de la aplicación.

   Este comportamiento se puede modificar estableciendo *text*,
   *encoding*, *errors*, o *universal_newlines* a "True", como se
   describe en Argumentos frecuentemente empleados y "run()".

   Para capturar también el error estándar del resultado se debe usar
   "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'

   Nuevo en la versión 3.1.

   Distinto en la versión 3.3: Se añadió *timeout*.

   Distinto en la versión 3.4: Se añadió soporte para el argumento por
   clave *input*.

   Distinto en la versión 3.6: Se añadieron *encoding* y *errors*.
   Ver "run()" para más detalles.

   Nuevo en la versión 3.7: Se añadió *text* como alias más legible de
   *universal_newlines*.

   Distinto en la versión 3.10.11: 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.


Cómo reemplazar anteriores funciones con el módulo "subprocess"
===============================================================

En esta sección, "a se convierte en b" significa que b se puede usar
en lugar de.

Nota:

  Todas las funciones "a" de esta sección fracasan silenciosamente (o
  casi) si no se halla el programa ejecutado; las funciones de
  reemplazo "b" lanzan "OSError" en lugar de esto.Además, las
  funciones de reemplazo que usan "check_output()" fracasarán con un
  error "CalledProcessError" si la operación solicitada produce un
  código de retorno diferente de cero. La salida queda disponible en
  el atributo "output" de la excepción lanzada.

En los siguientes ejemplos, se asume que las funciones relevantes ya
han sido importadas del módulo "subprocess".


Cómo reemplazar la sustitución de órdenes de **/bin/sh**
--------------------------------------------------------

   output=$(mycmd myarg)

se convierte en:

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


Cómo remplazar los flujos de la shell
-------------------------------------

   output=$(dmesg | grep hda)

se convierte en:

   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]

La llamada a "p1.stdout.close()" tras lanzar *p2* es importante para
que *p1* reciba un SIGPIPE si *p2* retorna antes que *p1*.

Alternativamente, para entrada de confianza, se puede usar el propio
soporte de pipeline de la shell directamente:

   output=$(dmesg | grep hda)

se convierte en:

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


Cómo reemplazar "os.system()"
-----------------------------

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

Notas:

* No suele hacer falta llamar al programa a través de la shell.

* El valor de retorno de "call()" se codifica de forma diferente al de
  "os.system()".

* La función "os.system()" ignora las señales SIGINT y SIGQUIT
  mientras se ejecuta el comando, pero el llamador debe hacerlo por
  separado cuando usa el módulo "subprocess".

Un ejemplo más creíble:

   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)


Cómo reemplazar la familia "os.spawn"
-------------------------------------

Ejemplo de P_NOWAIT:

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

Ejemplo de P_WAIT:

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

Ejemplo de vector:

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

Ejemplo de entorno:

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


Cómo reemplazar "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 gestión del código de retorno se traduce así:

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


Cómo reemplazar las funciones del módulo "popen2"
-------------------------------------------------

Nota:

  Si el argumento *cmd* de las funciones popen2 es una cadena, la
  orden se ejecuta a través de */bin/sh*. Si es una lista, la orden se
  ejecuta directamente.

   (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" y "popen2.Popen4" funcionan a grandes rasgos como
"subprocess.Popen", salvo:

* "Popen" lanza una excepción si falla la ejecución.

* El argumento *capturestderr* se sustituye por el argumento *stderr*.

* Se ha de especificar "stdin=PIPE" y "stdout=PIPE".

* popen2 cierra todos los descriptores de fichero por omisión, pero se
  ha de especificar "close_fds=True" con "Popen" para garantizar este
  comportamiento en todas las plataformas o en versiones anteriores de
  Python.


Funciones de llamada a la shell de retrocompatibilidad
======================================================

Este módulo también proporciona las siguientes funciones de
compatibilidad del módulo "commands" de las versiones 2.X. Estas
operaciones invocan implícitamente a la shell del sistema y no se les
aplican ninguna de las garantías descritas anteriormente respecto a
seguridad o consistencia en la gestión de excepciones.

subprocess.getstatusoutput(cmd)

   Retorna "(exitcode, output)" de ejecutar *cmd* en una shell.

   Ejecuta la cadena *cmd* en una shell con "Popen.check_output()" y
   retorna una tupla "(exitcode, output)". Se utiliza la codificación
   de localización activa; consultar las notas sobre Argumentos
   frecuentemente empleados para más información.

   Se elimina un salto de línea final de la salida. El código de
   salida de la orden se puede interpretar como el código de retorno
   del subproceso. Por ejemplo:

      >>> 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, '')

   Disponibilidad: POSIX y Windows.

   Distinto en la versión 3.3.4: Se añadió soporte de Windows.La
   función ahora retorna "(exitcode, output)" en lugar de "(status,
   output)" como en Python 3.3.3 y anteriores.  *exitcode* tiene el
   mismo valor que "returncode".

subprocess.getoutput(cmd)

   Retorna la salida (stdout y stderr) de ejecutar *cmd* en una shell.

   Como "getstatusoutput()", salvo que se ignora el código de salida y
   el valor retornado es una cadena que contiene la salida del
   comando. Por ejemplo:

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

   Disponibilidad: POSIX y Windows.

   Distinto en la versión 3.3.4: Se añadió soporte de Windows


Notas
=====


Cómo convertir una secuencia de argumentos a una cadena en Windows
------------------------------------------------------------------

En Windows, para convertir una secuencia *args* en una cadena que
puede ser analizada con las siguientes reglas (correspondientes a las
reglas que usa la biblioteca de ejecución de MS C):

1. Los argumentos se separan por espacio en blanco, que debe ser un
   espacio o un tabulador.

2. Una cadena entre comillas dobles se interpreta como un argumento
   simple, sin importar los espacios en blanco que contenga. Se puede
   incrustar una cadena entre comillas en un argumento.

3. Una comilla doble precedida de una barra invertida se interpreta
   literalmente como una comilla doble.

4. Las barras invertidas se interpretan literalmente, salvo que
   precedan a una comilla doble.

5. Si las barras invertidas preceden inmediatamente a una doble
   comilla, cada par de barras invertidas se interpreta como una barra
   invertida literal. Si el número de barras invertidas es impar, la
   última barra invertida escapa la siguiente comilla doble según se
   describe en la regla 3.

Ver también:

  "shlex"
     Módulo que proporciona una función para analizar y escapar líneas
     de órdenes.
