"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


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

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

   Os argumentos mostrados acima são meramente os mais comuns,
   descritos abaixo em Argumentos usados frequentemente (daí o uso de
   notação somente-nomeado na assinatura abreviada). A assinatura da
   função completa é basicamente a mesma do construtor "Popen" - a
   maioria dos argumentos para esta função são passados para aquela
   interface. (*timeout*, *input*, *check* e *capture_output* não
   são.)

   Se *capture_output* for verdadeiro, stdout e stderr serão
   capturados. Quando usado, o objeto interno "Popen" é
   automaticamente criado com "stdout=PIPE" e "stderr=PIPE". Os
   argumentos *stdout * e *stderr* não podem ser fornecidos ao mesmo
   tempo que *capture_output*. Se você deseja capturar e combinar os
   dois fluxos em um, use "stdout=PIPE" e "stderr=STDOUT" ao invés de
   *capture_output*.

   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.

   O argumento *input* é passado para "Popen.communicate()" e,
   portanto, para o stdin do subprocesso. Se usado, deve ser uma
   sequência de bytes ou uma string se *encoding* ou *errors* forem
   especificados ou *text* for verdadeiro. Quando usado, o objeto
   internal "Popen" é automaticamente criado com "stdin=PIPE", e o
   argumento *stdin* também não pode ser usado.

   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.

   Se *encoding* ou *errors* forem especificados, ou *text* for
   verdadeiro, os objetos de arquivo para stdin, stdout e stderr são
   abertos em modo de texto usando a *encoding* e *errors*
   especificados ou o "io.TextIOWrapper" padrão. O argumento
   *universal_newlines* é equivalente a *text* e é fornecido para
   compatibilidade com versões anteriores. Por padrão, os objetos
   arquivo são abertos no modo binário.

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

   Novo na versão 3.5.

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

   Alterado na versão 3.7: Adicionado o parâmetro *text*, como um
   apelido mais compreensível que *universal_newlines*. Adicionado o
   parâmetro *capture_output*.

   Alterado na versão 3.8.17: 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

   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

      Stdout capturado do processo filho. Uma sequência de bytes ou
      uma string se "run()" foi chamada com uma codificação, erros ou
      text=True. "None" se stdout não foi capturado.

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

   stderr

      Stderr capturado do processo filho. Uma sequência de bytes ou
      uma string se "run()" foi chamada com uma codificação, erros ou
      text=True. "None" se stderr não foi capturado.

   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


Argumentos usados frequentemente
--------------------------------

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

   Se *encoding* ou *errors* forem especificados, ou *text* (também
   conhecido como *universal_newlines*) for verdadeiro, os objetos de
   arquivo *stdin*, *stdout* e *stderr* serão abertos em modo de texto
   usando a *encoding* e *errors* especificados na chamada ou os
   valores padrão para "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: Adicionados os parâmetros *encoding* e
   *errors*.

   Novo na versão 3.7: Adicionado o parâmetro *text* como um apelido
   para *universal_newlines*.

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


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=None, startupinfo=None, creationflags=0, restore_signals=True, start_new_session=False, pass_fds=(), *, encoding=None, errors=None, text=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* deve ser uma sequência de argumentos do programa ou então
   uma única string ou *objeto caminho ou similar*. Por padrão, o
   programa a ser executado é o primeiro item em *args* se *args* for
   uma sequência. Se *args* for uma string, a interpretação depende da
   plataforma e é descrita abaixo. Consulte os argumentos *shell* e
   *executable* para obter diferenças adicionais em relação ao
   comportamento padrão. Salvo indicação em contrário, é recomendado
   passar *args* como uma sequência.

   Um exemplo de passagem de alguns argumentos para um programa
   externo como uma sequência é:

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

   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:

     Pode não ser óbvio como quebrar um comando shell em uma sequência
     de argumentos, especialmente em casos complexos. "shlex.split()"
     pode ilustrar como determinar a tokenização correta para *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!

     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.

   Alterado na versão 3.6: O parâmetro *args* aceita um *objeto
   caminho ou similar* se *shell* é "False" e uma sequência contendo
   objetos caminho ou similar no POSIX.

   Alterado na versão 3.8: *args* parameter accepts a *path-like
   object* if *shell* is "False" and a sequence containing bytes and
   path-like objects on Windows.

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

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

   Alterado na versão 3.8: *executable* parameter accepts a bytes and
   *path-like object* on Windows.

   Alterado na versão 3.8.17: 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*, 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.

   Alterado na versão 3.8: The *preexec_fn* parameter is no longer
   supported in subinterpreters. The use of the parameter in a
   subinterpreter raises "RuntimeError". The new restriction may
   affect applications that are deployed in mod_wsgi, uWSGI, and other
   embedded environments.

   If *close_fds* is true, all file descriptors except "0", "1" and
   "2" will be closed before the child process is executed.  Otherwise
   when *close_fds* is false, file descriptors obey their inheritable
   flag as described in Herança de descritores de arquivos.

   On Windows, if *close_fds* is true then no handles will be
   inherited by the child process unless explicitly passed in the
   "handle_list" element of "STARTUPINFO.lpAttributeList", or by
   standard handle redirection.

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

   Alterado na versão 3.7: On Windows the default for *close_fds* was
   changed from "False" to "True" when redirecting the standard
   handles. It's now possible to set *close_fds* to "True" when
   redirecting the standard handles.

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

   Alterado 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 string, bytes
   or *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* on POSIX.

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

   Alterado na versão 3.8: *cwd* parameter accepts a bytes object on
   Windows.

   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, or *text* is true, the
   file objects *stdin*, *stdout* and *stderr* are opened in text mode
   with the specified encoding and *errors*, as described above in
   Argumentos usados frequentemente. The *universal_newlines* argument
   is equivalent  to *text* and is provided for backwards
   compatibility. By default, file objects are opened in binary mode.

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

   Novo na versão 3.7: *text* foi adicionado como um atalho mais
   legível para *universal_newlines*.

   If given, *startupinfo* will be a "STARTUPINFO" object, which is
   passed to the underlying "CreateProcess" function. *creationflags*,
   if given, can be one or more of the following flags:

      * "CREATE_NEW_CONSOLE"

      * "CREATE_NEW_PROCESS_GROUP"

      * "ABOVE_NORMAL_PRIORITY_CLASS"

      * "BELOW_NORMAL_PRIORITY_CLASS"

      * "HIGH_PRIORITY_CLASS"

      * "IDLE_PRIORITY_CLASS"

      * "NORMAL_PRIORITY_CLASS"

      * "REALTIME_PRIORITY_CLASS"

      * "CREATE_NO_WINDOW"

      * "DETACHED_PROCESS"

      * "CREATE_DEFAULT_ERROR_MODE"

      * "CREATE_BREAKAWAY_FROM_JOB"

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

   Popen and the other functions in this module that use it raise an
   auditing event "subprocess.Popen" with arguments "executable",
   "args", "cwd", and "env". The value for "args" may be a single
   string or a list of strings, depending on platform.

   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.

   Alterado na versão 3.8: Popen can use "os.posix_spawn()" in some
   cases for better performance. On Windows Subsystem for Linux and
   QEMU User Emulation, Popen constructor using "os.posix_spawn()" no
   longer raise an exception on errors like missing program, but the
   child process fails with a non-zero "returncode".


Exceções
--------

Exceções levantadas no processo filho, antes que o novo programa
comece a ser executado, serão levantadas novamente no pai.

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.


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.


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.

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

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

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


Windows Popen Helpers
=====================

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

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

   Partial support of the Windows STARTUPINFO structure is used for
   "Popen" creation.  The following attributes can be set by passing
   them as keyword-only arguments.

   Alterado na versão 3.7: Keyword-only argument support was added.

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

   lpAttributeList

      A dictionary of additional attributes for process creation as
      given in "STARTUPINFOEX", see UpdateProcThreadAttribute.

      Atributos suportados:

      **handle_list**
         Sequence of handles that will be inherited. *close_fds* must
         be true if non-empty.

         The handles must be temporarily made inheritable by
         "os.set_handle_inheritable()" when passed to the "Popen"
         constructor, else "OSError" will be raised with Windows error
         "ERROR_INVALID_PARAMETER" (87).

         Aviso:

           In a multithreaded process, use caution to avoid leaking
           handles that are marked inheritable when combining this
           feature with concurrent calls to other process creation
           functions that inherit all handles such as "os.system()".
           This also applies to standard handle redirection, which
           temporarily creates inheritable handles.

      Novo na versão 3.7.


Constantes do Windows
---------------------

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.

subprocess.ABOVE_NORMAL_PRIORITY_CLASS

   A "Popen" "creationflags" parameter to specify that a new process
   will have an above average priority.

   Novo na versão 3.7.

subprocess.BELOW_NORMAL_PRIORITY_CLASS

   A "Popen" "creationflags" parameter to specify that a new process
   will have a below average priority.

   Novo na versão 3.7.

subprocess.HIGH_PRIORITY_CLASS

   A "Popen" "creationflags" parameter to specify that a new process
   will have a high priority.

   Novo na versão 3.7.

subprocess.IDLE_PRIORITY_CLASS

   A "Popen" "creationflags" parameter to specify that a new process
   will have an idle (lowest) priority.

   Novo na versão 3.7.

subprocess.NORMAL_PRIORITY_CLASS

   A "Popen" "creationflags" parameter to specify that a new process
   will have an normal priority. (default)

   Novo na versão 3.7.

subprocess.REALTIME_PRIORITY_CLASS

   A "Popen" "creationflags" parameter to specify that a new process
   will have realtime priority. You should almost never use
   REALTIME_PRIORITY_CLASS, because this interrupts system threads
   that manage mouse input, keyboard input, and background disk
   flushing. This class can be appropriate for applications that
   "talk" directly to hardware or that perform brief tasks that should
   have limited interruptions.

   Novo na versão 3.7.

subprocess.CREATE_NO_WINDOW

   A "Popen" "creationflags" parameter to specify that a new process
   will not create a window.

   Novo na versão 3.7.

subprocess.DETACHED_PROCESS

   A "Popen" "creationflags" parameter to specify that a new process
   will not inherit its parent's console. This value cannot be used
   with CREATE_NEW_CONSOLE.

   Novo na versão 3.7.

subprocess.CREATE_DEFAULT_ERROR_MODE

   A "Popen" "creationflags" parameter to specify that a new process
   does not inherit the error mode of the calling process. Instead,
   the new process gets the default error mode. This feature is
   particularly useful for multithreaded shell applications that run
   with hard errors disabled.

   Novo na versão 3.7.

subprocess.CREATE_BREAKAWAY_FROM_JOB

   A "Popen" "creationflags" parameter to specify that a new process
   is not associated with the job.

   Novo na versão 3.7.


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, **other_popen_kwargs)

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

   Code needing to capture stdout or stderr should use "run()"
   instead:

      run(...).returncode

   To suppress stdout or stderr, supply a value of "DEVNULL".

   The arguments shown above are merely some common ones. The full
   function signature is 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.

   Alterado na versão 3.8.17: Changed Windows shell search order for
   "shell=True". The current directory and "%PATH%" are replaced with
   "%COMSPEC%" and "%SystemRoot%\System32\cmd.exe". As a result,
   dropping a malicious program named "cmd.exe" into a current
   directory no longer works.

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

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

   Code needing to capture stdout or stderr should use "run()"
   instead:

      run(..., check=True)

   To suppress stdout or stderr, supply a value of "DEVNULL".

   The arguments shown above are merely some common ones. The full
   function signature is 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.

   Alterado na versão 3.8.17: 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)

   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 some common ones. The full
   function signature is largely the same as that of "run()" - most
   arguments are passed directly through to that interface. One API
   deviation from "run()" behavior exists: passing "input=None" will
   behave the same as "input=b''" (or "input=''", depending on other
   arguments) rather than using the parent's standard input file
   handle.

   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 *text*, *encoding*,
   *errors*, or *universal_newlines* to "True" as described in
   Argumentos usados frequentemente and "run()".

   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.

   Novo na versão 3.7: *text* foi adicionado como um atalho mais
   legível para *universal_newlines*.

   Alterado na versão 3.8.17: 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.


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.


Replacing **/bin/sh** shell command substitution
------------------------------------------------

   output=$(mycmd myarg)

torna-se:

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


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)


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)


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


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


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.


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

   Disponibilidade: POSIX e 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'

   Disponibilidade: POSIX e Windows.

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


Notas
=====


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.
