17.5. "subprocess" --- Gerenciamento de subprocessos
****************************************************

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

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

O módulo "subprocess" permite que você crie novos processos, conecte-
se aos seus canais de entrada/saída/erro e obtenha seus códigos de
retorno. Este módulo pretende substituir vários módulos e funções mais
antigos:

   os.system
   os.spawn*

Informações sobre como o módulo "subprocess" pode ser usado para
substituir esses módulos e funções podem ser encontradas nas seções a
seguir.

Ver também: **PEP 324** -- PEP propondo o módulo subprocess


17.5.1. Usando o módulo "subprocess"
====================================

A abordagem recomendada para invocar subprocessos é usar a função
"run()" para todos os casos de uso que ela pode manipular. Para casos
de uso mais avançados, a interface subjacente "Popen" pode ser usada
diretamente.

A função "run()" foi adicionada no Python 3.5; se você precisa manter
a compatibilidade com versões anteriores, veja a seção API de alto
nível mais antiga.

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

   Executa o comando descrito por *args*. Aguarda a conclusão do
   comando e retorna uma instância de "CompletedProcess".

   The arguments shown above are merely the most common ones,
   described below in Argumentos Usados Freqüentemente (hence the use
   of keyword-only notation in the abbreviated signature). The full
   function signature is largely the same as that of the "Popen"
   constructor - apart from *timeout*, *input* and *check*, all the
   arguments to this function are passed through to that interface.

   This does not capture stdout or stderr by default. To do so, pass
   "PIPE" for the *stdout* and/or *stderr* arguments.

   O argumento *timeout* é passado para "Popen.communicate()". Se o
   tempo limite expirar, o processo filho será encerrado e aguardado.
   A exceção "TimeoutExpired" será levantada novamente após o término
   do processo filho.

   The *input* argument is passed to "Popen.communicate()" and thus to
   the subprocess's stdin.  If used it must be a byte sequence, or a
   string if *encoding* or *errors* is specified or
   *universal_newlines* is true.  When used, the internal "Popen"
   object is automatically created with "stdin=PIPE", and the *stdin*
   argument may not be used as well.

   Se *check* for verdadeiro, e o processo sair com um código de saída
   diferente de zero, uma exceção "CalledProcessError" será levantada.
   Os atributos dessa exceção contêm os argumentos, o código de saída
   e stdout e stderr se eles foram capturados.

   If *encoding* or *errors* are specified, or *universal_newlines* is
   true, file objects for stdin, stdout and stderr are opened in text
   mode using the specified *encoding* and *errors* or the
   "io.TextIOWrapper" default. Otherwise, file objects are opened in
   binary mode.

   Se *env* não for "None", deve ser um mapeamento que define as
   variáveis de ambiente para o novo processo; eles são usados em vez
   do comportamento padrão de herdar o ambiente do processo atual. É
   passado diretamente para "Popen".

   Exemplos:

      >>> 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"], stdout=subprocess.PIPE)
      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')

   Novo na versão 3.5.

   Alterado na versão 3.6: Adicionado os parâmetros *encoding* e
   *errors*.

class subprocess.CompletedProcess

   O valor de retorno de "run()", representando um processo que foi
   concluído.

   args

      Os argumentos usados para iniciar o processo. Pode ser uma lista
      ou uma string.

   returncode

      Status de saída do processo filho. Normalmente, um status de
      saída 0 indica que foi executado com êxito.

      Um valor negativo "-N" indica que o filho foi terminado pelo
      sinal "N" (POSIX apenas).

   stdout

      Captured stdout from the child process. A bytes sequence, or a
      string if "run()" was called with an encoding or errors. "None"
      if stdout was not captured.

      Se você executou o processo com "stderr=subprocess.STDOUT",
      stdout e stderr serão combinados neste atributo, e "stderr" será
      "None".

   stderr

      Captured stderr from the child process. A bytes sequence, or a
      string if "run()" was called with an encoding or errors. "None"
      if stderr was not captured.

   check_returncode()

      Se "returncode" é diferente de zero, levantar um
      "CalledProcessError".

   Novo na versão 3.5.

subprocess.DEVNULL

   Valor especial que pode ser usado como o argumento *stdin*,
   *stdout* ou *stderr* para "Popen" e indica que o arquivo especial
   "os.devnull" será usado.

   Novo na versão 3.3.

subprocess.PIPE

   Valor especial que pode ser usado como o argumento *stdin*,
   *stdout* ou *stderr* para "Popen" e indica que um encadeamento para
   o fluxo padrão deve ser aberto. Mais útil com
   "Popen.communicate()".

subprocess.STDOUT

   Valor especial que pode ser usado como o argumento *stderr* para
   "Popen" e indica que o erro padrão deve ir para o mesmo manipulador
   que a saída padrão.

exception subprocess.SubprocessError

   Classe base para todas as outras exceções deste módulo.

   Novo na versão 3.3.

exception subprocess.TimeoutExpired

   Subclasse de "SubprocessError", levantada quando um tempo limite
   expira enquanto espera por um processo filho.

   cmd

      Comando que foi usado para gerar o processo filho.

   timeout

      Tempo limite em segundos.

   output

      Saída do processo filho se ele foi capturado por "run()" ou
      "check_output()". Caso contrário, "None".

   stdout

      Apelido para a saída, para simetria com "stderr".

   stderr

      Saída Stderr do processo filho se ele foi capturado por "run()".
      Caso contrário, "None".

   Novo na versão 3.3.

   Alterado na versão 3.5: Atributos *stdout* e *stderr* adicionados

exception subprocess.CalledProcessError

   Subclasse de "SubprocessError", levantada quando um processo
   executado por "check_call()" ou "check_output()" retorna um status
   de saída diferente de zero.

   returncode

      Status de saída do processo filho. Se o processo foi encerrado
      devido a um sinal, este será o número do sinal negativo.

   cmd

      Comando que foi usado para gerar o processo filho.

   output

      Saída do processo filho se ele foi capturado por "run()" ou
      "check_output()". Caso contrário, "None".

   stdout

      Apelido para a saída, para simetria com "stderr".

   stderr

      Saída Stderr do processo filho se ele foi capturado por "run()".
      Caso contrário, "None".

   Alterado na versão 3.5: Atributos *stdout* e *stderr* adicionados


17.5.1.1. Argumentos Usados Freqüentemente
------------------------------------------

Para suportar uma ampla variedade de casos de uso, o construtor
"Popen" (e as funções de conveniência) aceita muitos argumentos
opcionais. Para a maioria dos casos de uso típicos, muitos desses
argumentos podem ser seguramente deixados em seus valores padrão. Os
argumentos mais comumente necessários são:

   *args* é necessário para todas as chamadas e deve ser uma string ou
   uma sequência de argumentos do programa. Fornecer uma sequência de
   argumentos geralmente é preferível, pois permite que o módulo cuide
   de qualquer escapamento e citação de argumentos que forem
   necessários (por exemplo, para permitir espaços em nomes de
   arquivo). Se for passada uma única string, *shell* deve ser "True"
   (veja abaixo) ou então a string deve apenas nomear o programa a ser
   executado sem especificar nenhum argumento.

   *stdin*, *stdout* e *stderr* especificam o manipulador de arquivo
   de entrada padrão, a saída padrão e de erro padrão do programa
   executado, respectivamente. Os valores válidos são "PIPE",
   "DEVNULL", um descritor de arquivo existente (um inteiro positivo),
   um objeto arquivo existente e "None". "PIPE" indica que um novo
   encadeamento para o filho deve ser criado. "DEVNULL" indica que o
   arquivo especial "os.devnull" será usado. Com as configurações
   padrão de "None", nenhum redirecionamento ocorrerá; os
   manipuladores de arquivo do filho serão herdados do pai. Além
   disso, *stderr* pode ser "STDOUT", o que indica que os dados stderr
   do processo filho devem ser capturados no mesmo manipulador de
   arquivo que para *stdout*.

   If *encoding* or *errors* are specified, or *universal_newlines* is
   true, the file objects *stdin*, *stdout* and *stderr* will be
   opened in text mode using the *encoding* and *errors* specified in
   the call or the defaults for "io.TextIOWrapper".

   Para *stdin*, os caracteres de fim de linha "'\n'" na entrada serão
   convertidos para o separador de linha padrão "os.linesep". Para
   *stdout* e *stderr*, todas as terminações de linha na saída serão
   convertidas para "'\n'". Para obter mais informações, consulte a
   documentação da classe "io.TextIOWrapper" quando o argumento
   *newline* para seu construtor é "None".

   Se o modo de texto não for usado, *stdin*, *stdout* e *stderr*
   serão abertos como fluxos binários. Nenhuma codificação ou
   conversão de final de linha é executada.

   Novo na versão 3.6: Adicionado os parâmetros *encoding* e *errors*.

   Nota:

     O atributo newlines dos objetos arquivo "Popen.stdin",
     "Popen.stdout" e "Popen.stderr" não são atualizados pelo método
     "Popen.communicate()".

   Se *shell* for "True", o comando especificado será executado
   através do shell. Isso pode ser útil se você estiver usando Python
   principalmente para o fluxo de controle aprimorado que ele oferece
   sobre a maioria dos shells do sistema e ainda deseja acesso
   conveniente a outros recursos do shell, como canais de shell,
   caracteres curinga de nome de arquivo, expansão de variável de
   ambiente e expansão de "~" para o diretório inicial de um usuário.
   No entanto, observe que o próprio Python oferece implementações de
   muitos recursos semelhantes a shell (em particular, "glob",
   "fnmatch", "os.walk()", "os.path.expandvars()",
   "os.path.expanduser()" e "shutil").

   Alterado na versão 3.3: Quando *universal_newlines* é "True", a
   classe usa a codificação "locale.getpreferredencoding(False)" em
   vez de``locale.getpreferredencoding()``.  Veja a classe
   "io.TextIOWrapper" para mais informações sobre esta alteração.

   Nota:

     Leia a seção Security Considerations antes de usar "shell=True".

Essas opções, junto com todas as outras opções, são descritas em mais
detalhes na documentação do construtor "Popen".


17.5.1.2. Construtor Popen
--------------------------

A criação e gerenciamento do processo subjacente neste módulo é
manipulado pela classe "Popen". Ela oferece muita flexibilidade para
que os desenvolvedores sejam capazes de lidar com os casos menos
comuns não cobertos pelas funções de conveniência.

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=False, startupinfo=None, creationflags=0, restore_signals=True, start_new_session=False, pass_fds=(), *, encoding=None, errors=None)

   Executa um programa filho em um novo processo. No POSIX, a classe
   usa o comportamento de "os.execvp()" para executar o programa
   filho. No Windows, a classe usa a função Windows "CreateProcess()".
   Os argumentos para "Popen" são os seguintes.

   *args* should be a sequence of program arguments or else a single
   string. By default, the program to execute is the first item in
   *args* if *args* is a sequence.  If *args* is a string, the
   interpretation is platform-dependent and described below.  See the
   *shell* and *executable* arguments for additional differences from
   the default behavior.  Unless otherwise stated, it is recommended
   to pass *args* as a sequence.

   No POSIX, se *args* for uma string, a string é interpretada como o
   nome ou caminho do programa a ser executado. No entanto, isso só
   pode ser feito se não forem passados argumentos para o programa.

   Nota:

     "shlex.split()" can be useful when determining the correct
     tokenization for *args*, especially in complex cases:

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

     Observe em particular que as opções (como *-input*) e argumentos
     (como *eggs.txt*) que são separados por espaços em branco no
     shell vão em elementos de lista separados, enquanto os argumentos
     que precisam de aspas ou escape de contrabarra quando usados no
     shell (como nomes de arquivos contendo espaços ou o comando
     *echo* mostrado acima) são um único elemento de lista.

   No Windows, se *args* for uma sequência, será convertido em uma
   string da maneira descrita em Converter uma sequência de argumentos
   em uma string no Windows. Isso ocorre porque o "CreateProcess()"
   subjacente opera em strings.

   The *shell* argument (which defaults to "False") specifies whether
   to use the shell as the program to execute.  If *shell* is "True",
   it is recommended to pass *args* as a string rather than as a
   sequence.

   On POSIX 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], ...])

   On Windows with "shell=True", the "COMSPEC" environment variable
   specifies the default shell.  The only time you need to specify
   "shell=True" on Windows is when the command you wish to execute is
   built into the shell (e.g. **dir** or **copy**).  You do not need
   "shell=True" to run a batch file or console-based executable.

   Nota:

     Leia a seção Security Considerations antes de usar "shell=True".

   *bufsize* will be supplied as the corresponding argument to the
   "open()" function when creating the stdin/stdout/stderr pipe file
   objects:

   * "0" means unbuffered (read and write are one system call and can
     return short)

   * "1" means line buffered (only usable if "universal_newlines=True"
     i.e., in a text mode)

   * any other positive value means use a buffer of approximately that
     size

   * negative bufsize (the default) means the system default of
     io.DEFAULT_BUFFER_SIZE will be used.

   Alterado na versão 3.3.1: *bufsize* now defaults to -1 to enable
   buffering by default to match the behavior that most code expects.
   In versions prior to Python 3.2.4 and 3.3.1 it incorrectly
   defaulted to "0" which was unbuffered and allowed short reads.
   This was unintentional and did not match the behavior of Python 2
   as most code expected.

   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
   POSIX, the *args* name becomes the display name for the executable
   in utilities such as **ps**.  If "shell=True", on POSIX 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", "DEVNULL", 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.  "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.

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

   Aviso:

     The *preexec_fn* parameter is not safe to use in the presence of
     threads in your application.  The child process could deadlock
     before exec is called. If you must use it, keep it trivial!
     Minimize the number of libraries you call into.

   Nota:

     If you need to modify the environment for the child use the *env*
     parameter rather than doing it in a *preexec_fn*. The
     *start_new_session* parameter can take the place of a previously
     common use of *preexec_fn* to call os.setsid() in the child.

   If *close_fds* is true, all file descriptors except "0", "1" and
   "2" will be closed before the child process is executed. (POSIX
   only). The default varies by platform:  Always true on POSIX.  On
   Windows it is true when *stdin*/*stdout*/*stderr* are "None", false
   otherwise. 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*.

   Alterado na versão 3.2: The default for *close_fds* was changed
   from "False" to what is described above.

   *pass_fds* is an optional sequence of file descriptors to keep open
   between the parent and child.  Providing any *pass_fds* forces
   *close_fds* to be "True".  (POSIX only)

   Novo na versão 3.2: O parâmetro *pass_fds* foi adicionado.

   If *cwd* is not "None", the function changes the working directory
   to *cwd* before executing the child.  *cwd* can be a "str" and
   *path-like* object.  In particular, the function looks for
   *executable* (or for the first item in *args*) relative to *cwd* if
   the executable path is a relative path.

   Alterado na versão 3.6: *cwd* parameter accepts a *path-like
   object*.

   If *restore_signals* is true (the default) all signals that Python
   has set to SIG_IGN are restored to SIG_DFL in the child process
   before the exec. Currently this includes the SIGPIPE, SIGXFZ and
   SIGXFSZ signals. (POSIX only)

   Alterado na versão 3.2: *restore_signals* foi adicionado.

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

   Alterado na versão 3.2: *start_new_session* foi adicionado.

   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.

   Nota:

     If specified, *env* must provide any variables required for the
     program to execute.  On Windows, in order to run a side-by-side
     assembly the specified *env* **must** include a valid
     "SystemRoot".

   If *encoding* or *errors* are specified, the file objects *stdin*,
   *stdout* and *stderr* are opened in text mode with the specified
   encoding and *errors*, as described above in Argumentos Usados
   Freqüentemente. If *universal_newlines* is "True", they are opened
   in text mode with default encoding. Otherwise, they are opened as
   binary streams.

   Novo na versão 3.6: *encoding* e *errors* foram adicionados.

   If given, *startupinfo* will be a "STARTUPINFO" object, which is
   passed to the underlying "CreateProcess" function. *creationflags*,
   if given, can be "CREATE_NEW_CONSOLE" or
   "CREATE_NEW_PROCESS_GROUP". (Windows only)

   Popen objects are supported as context managers via the "with"
   statement: on exit, standard file descriptors are closed, and the
   process is waited for.

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

   Alterado na versão 3.2: Adicionado suporte a gerenciador de
   contexto.

   Alterado na versão 3.6: O destruidor Popen agora emite um aviso
   "ResourceWarning" se o processo filho ainda estiver em execução.


17.5.1.3. Exceções
------------------

Exceptions raised in the child process, before the new program has
started to execute, will be re-raised in the parent.  Additionally,
the exception object will have one extra attribute called
"child_traceback", which is a string containing traceback information
from the child's point of view.

A exceção mais comum levantada é "OSError". Isso ocorre, por exemplo,
ao tentar executar um arquivo inexistente. Os aplicativos devem se
preparar para exceções "OSError".

A exceção "ValueError" será levantada se "Popen" for chamado com
argumentos inválidos.

"check_call()" e "check_output()" levantarão "CalledProcessError" se o
processo chamado retornar um código de retorno diferente de zero.

Todas as funções e métodos que aceitam um parâmetro de *timeout*, como
"call()" e "Popen.communicate()" levantarão "TimeoutExpired" se o
tempo limite expirar antes de o processo terminar.

Todas as exceções definidas neste módulo herdam de "SubprocessError".

   Novo na versão 3.3: A classe base "SubprocessError" foi adicionada.


17.5.2. Considerações de Segurança
==================================

Unlike some other popen functions, this implementation will never
implicitly call a system shell.  This means that all characters,
including shell metacharacters, can safely be passed to child
processes. If the shell is invoked explicitly, via "shell=True", it is
the application's responsibility to ensure that all whitespace and
metacharacters are quoted appropriately to avoid shell injection
vulnerabilities.

When using "shell=True", the "shlex.quote()" function can be used to
properly escape whitespace and shell metacharacters in strings that
are going to be used to construct shell commands.


17.5.3. Objetos Popen
=====================

Instâncias da classe "Popen" têm os seguintes métodos:

Popen.poll()

   Check if child process has terminated.  Set and return "returncode"
   attribute. Otherwise, returns "None".

Popen.wait(timeout=None)

   Wait for child process to terminate.  Set and return "returncode"
   attribute.

   If the process does not terminate after *timeout* seconds, raise a
   "TimeoutExpired" exception.  It is safe to catch this exception and
   retry the wait.

   Nota:

     This will deadlock when using "stdout=PIPE" 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
     "Popen.communicate()" when using pipes to avoid that.

   Nota:

     The function is implemented using a busy loop (non-blocking call
     and short sleeps). Use the "asyncio" module for an asynchronous
     wait: see "asyncio.create_subprocess_exec".

   Alterado na versão 3.3: *timeout* foi adicionado.

   Obsoleto desde a versão 3.4: Do not use the *endtime* parameter.
   It is was unintentionally exposed in 3.3 but was left undocumented
   as it was intended to be private for internal use.  Use *timeout*
   instead.

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

   Interact with process: Send data to stdin.  Read data from stdout
   and stderr, until end-of-file is reached.  Wait for process to
   terminate.  The optional *input* argument should be data to be sent
   to the child process, or "None", if no data should be sent to the
   child.  If streams were opened in text mode, *input* must be a
   string.  Otherwise, it must be bytes.

   "communicate()" returns a tuple "(stdout_data, stderr_data)". The
   data will be strings if streams were opened in text mode;
   otherwise, bytes.

   Note that if you want to send data to the process's stdin, you need
   to create the Popen object with "stdin=PIPE".  Similarly, to get
   anything other than "None" in the result tuple, you need to give
   "stdout=PIPE" and/or "stderr=PIPE" too.

   If the process does not terminate after *timeout* seconds, a
   "TimeoutExpired" exception will be raised.  Catching this exception
   and retrying communication will not lose any output.

   The child process is not killed if the timeout expires, so in order
   to cleanup properly a well-behaved application should kill the
   child process and finish communication:

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

   Nota:

     The data read is buffered in memory, so do not use this method if
     the data size is large or unlimited.

   Alterado na versão 3.3: *timeout* foi adicionado.

Popen.send_signal(signal)

   Envia o sinal *signal* para o filho.

   Nota:

     On Windows, SIGTERM is an alias for "terminate()". CTRL_C_EVENT
     and CTRL_BREAK_EVENT can be sent to processes started with a
     *creationflags* parameter which includes
     *CREATE_NEW_PROCESS_GROUP*.

Popen.terminate()

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

Popen.kill()

   Kills the child. On Posix OSs the function sends SIGKILL to the
   child. On Windows "kill()" is an alias for "terminate()".

Os seguintes atributos também estão disponíveis:

Popen.args

   O argumento *args* conforme foi passado para "Popen" - uma
   sequência de argumentos do programa ou então uma única string.

   Novo na versão 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 *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 *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 *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".

Aviso:

  Use "communicate()" rather than ".stdin.write", ".stdout.read" or
  ".stderr.read" to avoid deadlocks due to any of the other OS pipe
  buffers filling up and blocking the child process.

Popen.pid

   O ID de processo do processo filho.

   Observe que se você definir o argumento *shell* como "True", este é
   o ID do processo do shell gerado.

Popen.returncode

   The child return code, set by "poll()" and "wait()" (and indirectly
   by "communicate()").  A "None" value indicates that the process
   hasn't terminated yet.

   Um valor negativo "-N" indica que o filho foi terminado pelo sinal
   "N" (POSIX apenas).


17.5.4. Windows Popen Helpers
=============================

The "STARTUPINFO" class and following constants are only available on
Windows.

class subprocess.STARTUPINFO

   Partial support of the Windows STARTUPINFO structure is used for
   "Popen" creation.

   dwFlags

      A bit field that determines whether certain "STARTUPINFO"
      attributes are used when the process creates a window.

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

   hStdInput

      If "dwFlags" specifies "STARTF_USESTDHANDLES", this attribute is
      the standard input handle for the process. If
      "STARTF_USESTDHANDLES" is not specified, the default for
      standard input is the keyboard buffer.

   hStdOutput

      If "dwFlags" specifies "STARTF_USESTDHANDLES", this attribute is
      the standard output handle for the process. Otherwise, this
      attribute is ignored and the default for standard output is the
      console window's buffer.

   hStdError

      If "dwFlags" specifies "STARTF_USESTDHANDLES", this attribute is
      the standard error handle for the process. Otherwise, this
      attribute is ignored and the default for standard error is the
      console window's buffer.

   wShowWindow

      If "dwFlags" specifies "STARTF_USESHOWWINDOW", this attribute
      can be any of the values that can be specified in the "nCmdShow"
      parameter for the ShowWindow function, except for
      "SW_SHOWDEFAULT". Otherwise, this attribute is ignored.

      "SW_HIDE" is provided for this attribute. It is used when
      "Popen" is called with "shell=True".


17.5.4.1. Constantes
--------------------

The "subprocess" module exposes the following constants.

subprocess.STD_INPUT_HANDLE

   The standard input device. Initially, this is the console input
   buffer, "CONIN$".

subprocess.STD_OUTPUT_HANDLE

   The standard output device. Initially, this is the active console
   screen buffer, "CONOUT$".

subprocess.STD_ERROR_HANDLE

   The standard error device. Initially, this is the active console
   screen buffer, "CONOUT$".

subprocess.SW_HIDE

   Oculta a janela. Outra janela será ativada.

subprocess.STARTF_USESTDHANDLES

   Specifies that the "STARTUPINFO.hStdInput",
   "STARTUPINFO.hStdOutput", and "STARTUPINFO.hStdError" attributes
   contain additional information.

subprocess.STARTF_USESHOWWINDOW

   Specifies that the "STARTUPINFO.wShowWindow" attribute contains
   additional information.

subprocess.CREATE_NEW_CONSOLE

   The new process has a new console, instead of inheriting its
   parent's console (the default).

subprocess.CREATE_NEW_PROCESS_GROUP

   A "Popen" "creationflags" parameter to specify that a new process
   group will be created. This flag is necessary for using "os.kill()"
   on the subprocess.

   This flag is ignored if "CREATE_NEW_CONSOLE" is specified.


17.5.5. API de alto nível mais antiga
=====================================

Antes do Python 3.5, essas três funções constituíam a API de alto
nível para subprocesso. Agora você pode usar "run()" em muitos casos,
mas muitos códigos existentes chamam essas funções.

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

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

   This is equivalent to:

      run(...).returncode

   (except that the *input* and *check* parameters are not supported)

   The arguments shown above are merely the most common ones. The full
   function signature is largely the same as that of the "Popen"
   constructor - this function passes all supplied arguments other
   than *timeout* directly through to that interface.

   Nota:

     Do not use "stdout=PIPE" or "stderr=PIPE" with this function.
     The child process will block if it generates enough output to a
     pipe to fill up the OS pipe buffer as the pipes are not being
     read from.

   Alterado na versão 3.3: *timeout* foi adicionado.

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

   Run command with arguments.  Wait for command to complete. If the
   return code was zero then return, otherwise raise
   "CalledProcessError". The "CalledProcessError" object will have the
   return code in the "returncode" attribute.

   This is equivalent to:

      run(..., check=True)

   (except that the *input* parameter is not supported)

   The arguments shown above are merely the most common ones. The full
   function signature is largely the same as that of the "Popen"
   constructor - this function passes all supplied arguments other
   than *timeout* directly through to that interface.

   Nota:

     Do not use "stdout=PIPE" or "stderr=PIPE" with this function.
     The child process will block if it generates enough output to a
     pipe to fill up the OS pipe buffer as the pipes are not being
     read from.

   Alterado na versão 3.3: *timeout* foi adicionado.

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

   Executa o comando com argumentos e retorna sua saída.

   If the return code was non-zero it raises a "CalledProcessError".
   The "CalledProcessError" object will have the return code in the
   "returncode" attribute and any output in the "output" attribute.

   This is equivalent to:

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

   The arguments shown above are merely the most common ones. The full
   function signature is largely the same as that of "run()" - most
   arguments are passed directly through to that interface. However,
   explicitly passing "input=None" to inherit the parent's standard
   input file handle is not supported.

   By default, this function will return the data as encoded bytes.
   The actual encoding of the output data may depend on the command
   being invoked, so the decoding to text will often need to be
   handled at the application level.

   This behaviour may be overridden by setting *universal_newlines* to
   "True" as described above in Argumentos Usados Freqüentemente.

   To also capture standard error in the result, use
   "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'

   Novo na versão 3.1.

   Alterado na versão 3.3: *timeout* foi adicionado.

   Alterado na versão 3.4: Support for the *input* keyword argument
   was added.

   Alterado na versão 3.6: *encoding* and *errors* were added.  See
   "run()" for details.


17.5.6. Replacing Older Functions with the "subprocess" Module
==============================================================

In this section, "a becomes b" means that b can be used as a
replacement for a.

Nota:

  All "a" functions in this section fail (more or less) silently if
  the executed program cannot be found; the "b" replacements raise
  "OSError" instead.In addition, the replacements using
  "check_output()" will fail with a "CalledProcessError" if the
  requested operation produces a non-zero return code. The output is
  still available as the "output" attribute of the raised exception.

In the following examples, we assume that the relevant functions have
already been imported from the "subprocess" module.


17.5.6.1. Replacing /bin/sh shell backquote
-------------------------------------------

   output=`mycmd myarg`

torna-se:

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


17.5.6.2. Replacing shell pipeline
----------------------------------

   output=`dmesg | grep hda`

torna-se:

   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]

The p1.stdout.close() call after starting the p2 is important in order
for p1 to receive a SIGPIPE if p2 exits before p1.

Alternatively, for trusted input, the shell's own pipeline support may
still be used directly:

   output=`dmesg | grep hda`

torna-se:

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


17.5.6.3. Substituindo "os.system()"
------------------------------------

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

Notas:

* Calling the program through the shell is usually not required.

Um exemplo mais realista ficaria assim:

   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)


17.5.6.4. Replacing the "os.spawn" family
-----------------------------------------

Exemplo P_NOWAIT:

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

Exemplo P_WAIT:

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

Exemplo de vetor:

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

Exemplo de ambiente:

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


17.5.6.5. Replacing "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)

Return code handling translates as follows:

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


17.5.6.6. Replacing functions from the "popen2" module
------------------------------------------------------

Nota:

  If the cmd argument to popen2 functions is a string, the command is
  executed through /bin/sh.  If it is a list, the command is directly
  executed.

   (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" and "popen2.Popen4" basically work as
"subprocess.Popen", except that:

* "Popen" raises an exception if the execution fails.

* the *capturestderr* argument is replaced with the *stderr* argument.

* "stdin=PIPE" and "stdout=PIPE" must be specified.

* popen2 closes all file descriptors by default, but you have to
  specify "close_fds=True" with "Popen" to guarantee this behavior on
  all platforms or past Python versions.


17.5.7. Legacy Shell Invocation Functions
=========================================

This module also provides the following legacy functions from the 2.x
"commands" module. These operations implicitly invoke the system shell
and none of the guarantees described above regarding security and
exception handling consistency are valid for these functions.

subprocess.getstatusoutput(cmd)

   Return "(exitcode, output)" of executing *cmd* in a shell.

   Execute the string *cmd* in a shell with "Popen.check_output()" and
   return a 2-tuple "(exitcode, output)". The locale encoding is used;
   see the notes on Argumentos Usados Freqüentemente for more details.

   A trailing newline is stripped from the output. The exit code for
   the command can be interpreted as the return code of subprocess.
   Example:

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

   Availability: POSIX & Windows

   Alterado na versão 3.3.4: Suporte ao Windows foi adicionado.The
   function now returns (exitcode, output) instead of (status, output)
   as it did in Python 3.3.3 and earlier.  exitcode has the same value
   as "returncode".

subprocess.getoutput(cmd)

   Return output (stdout and stderr) of executing *cmd* in a shell.

   Like "getstatusoutput()", except the exit code is ignored and the
   return value is a string containing the command's output.  Example:

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

   Availability: POSIX & Windows

   Alterado na versão 3.3.4: Suporte para Windows adicionado.


17.5.8. Notas
=============


17.5.8.1. Converter uma sequência de argumentos em uma string no Windows
------------------------------------------------------------------------

On Windows, an *args* sequence is converted to a string that can be
parsed using the following rules (which correspond to the rules used
by the MS C runtime):

1. Arguments are delimited by white space, which is either a space or
   a tab.

2. A string surrounded by double quotation marks is interpreted as a
   single argument, regardless of white space contained within.  A
   quoted string can be embedded in an argument.

3. A double quotation mark preceded by a backslash is interpreted as a
   literal double quotation mark.

4. Backslashes are interpreted literally, unless they immediately
   precede a double quotation mark.

5. If backslashes immediately precede a double quotation mark, every
   pair of backslashes is interpreted as a literal backslash.  If the
   number of backslashes is odd, the last backslash escapes the next
   double quotation mark as described in rule 3.

Ver também:

  "shlex"
     Module which provides function to parse and escape command lines.
