# Subprocessos

Código-fonte: Lib/asyncio/subprocess.py, Lib/asyncio/base_subprocess.py

Esta seção descreve APIs async/await asyncio de alto nível para criar e gerenciar subprocessos.

Aqui está um exemplo de como asyncio pode executar um comando shell e obter o seu resultado:

    import asyncio

    async def run(cmd):
        proc = await asyncio.create_subprocess_shell(
            cmd,
            stdout=asyncio.subprocess.PIPE,
            stderr=asyncio.subprocess.PIPE)

        stdout, stderr = await proc.communicate()

        print(f'[{cmd!r} exited with {proc.returncode}]')
        if stdout:
            print(f'[stdout]\n{stdout.decode()}')
        if stderr:
            print(f'[stderr]\n{stderr.decode()}')

    asyncio.run(run('ls /zzz'))

irá exibir:

    ['ls /zzz' exited with 1]
    [stderr]
    ls: /zzz: No such file or directory

Devido ao fato que todas as funções de subprocessos asyncio são assíncronas e asyncio fornece muitas ferramentas para trabalhar com tais funções, é fácil executar e monitorar múltiplos subprocessos em paralelo. É na verdade trivial modificar o exemplo acima para executar diversos comandos simultaneamente:

    async def main():
        await asyncio.gather(
            run('ls /zzz'),
            run('sleep 1; echo "hello"'))

    asyncio.run(main())

Veja também a subseção Exemplos.

## Criando subprocessos

async asyncio.create_subprocess_exec(program, *args, stdin=None, stdout=None, stderr=None, limit=None, **kwds)

  Cria um subprocesso.

  O argumento limit define o limite do buffer para os invólucros `StreamReader` para `stdout` e `stderr` (se `subprocess.PIPE` for passado para os argumentos stdout e stderr).

  Retorna uma instância de `Process`.

  Veja a documentação de `loop.subprocess_exec()` para outros parâmetros.

  Se o objeto do processo for coletado pelo coletor de lixo enquanto o processo ainda estiver em execução, o processo filho será finalizado.

  Alterado na versão 3.10: Removido o parâmetro loop.

async asyncio.create_subprocess_shell(cmd, stdin=None, stdout=None, stderr=None, limit=None, **kwds)

  Executa o comando cmd no shell.

  O argumento limit define o limite do buffer para os invólucros `StreamReader` para `stdout` e `stderr` (se `subprocess.PIPE` for passado para os argumentos stdout e stderr).

  Retorna uma instância de `Process`.

  Veja a documentação de `loop.subprocess_shell()` para outros parâmetros.

  Se o objeto do processo for coletado pelo coletor de lixo enquanto o processo ainda estiver em execução, o processo filho será finalizado.

  Importante

  É responsabilidade da aplicação garantir que todos os espaços em branco e caracteres especiais tenham aspas apropriadamente para evitar vulnerabilidades de injeção de shell. A função `shlex.quote()` pode ser usada para escapar espaços em branco e caracteres especiais de shell apropriadamente em strings que serão usadas para construir comandos shell.

  Alterado na versão 3.10: Removido o parâmetro loop.

Nota

Subprocessos estão disponíveis para Windows se uma `ProactorEventLoop` for usada. Veja Suporte para subprocesso para Windows para detalhes.

Ver também

asyncio também tem as seguintes APIs de baixo nível para trabalhar com subprocessos: `loop.subprocess_exec()`, `loop.subprocess_shell()`, `loop.connect_read_pipe()`, `loop.connect_write_pipe()`, assim como os Transportes de Subprocesso e Protocolos de Subprocesso.

## Constantes

asyncio.subprocess.PIPE

  Pode ser passado para os parâmetros stdin, stdout ou stderr.

  Se PIPE for passado para o argumento stdin, o atributo `Process.stdin` irá apontar para uma instância `StreamWriter`.

  Se PIPE for passado para os argumentos stdout ou stderr, os atributos `Process.stdout` e `Process.stderr` irão apontar para instâncias `StreamReader`.

asyncio.subprocess.STDOUT

  Valor especial que pode ser usado como o argumento stderr e indica que a saída de erro padrão deve ser redirecionada para a saída padrão.

asyncio.subprocess.DEVNULL

  Valor especial que pode ser usado como argumento stdin, stdout ou stderr para funções de criação de processos. Ele indica que o arquivo especial `os.devnull` será usado para o fluxo de subprocesso correspondente.

## Interagindo com subprocessos

Ambas as funções `create_subprocess_exec()` e `create_subprocess_shell()` retornam instâncias da classe Process. Process é um invólucro de alto nível que permite a comunicação com subprocessos e observar eles serem completados.

class asyncio.subprocess.Process

  Um objeto que envolve processos do sistema operacional criados pelas funções `create_subprocess_exec()` e `create_subprocess_shell()`.

  Esta classe é projetada para ter uma API similar a classe `subprocess.Popen`, mas existem algumas diferenças notáveis:

  - ao contrário de Popen, instâncias de Process não têm um equivalente ao método `poll()`;

  - os métodos `communicate()` e `wait()` não têm um parâmetro timeout: utilize a função `wait_for()`;

  - o método `Process.wait()` é assíncrono, enquanto que o método `subprocess.Popen.wait()` é implementado como um laço bloqueante para indicar que está ocupado;

  - o parâmetro universal_newlines não é suportado.

  Esta classe não é segura para thread.

  Veja também a seção Subprocesso e Threads.

  async wait()

    Aguarda o processo filho encerrar.

    Define e retorna o atributo `returncode`.

    Nota

    Este método pode entrar em deadlock ao usar `stdout=PIPE` ou `stderr=PIPE` e o processo filho gera tantas saídas que ele bloqueia a espera pelo encadeamento de buffer do sistema operacional para aceitar mais dados. Use o método `communicate()` ao usar encadeamentos para evitar essa condição.

  async communicate(input=None)

    Interage com processo:

    1. envia dados para stdin (se input for diferente de `None`);

    2. fecha stdin;

    3. lê dados a partir de stdout e stderr, até que EOF (fim do arquivo) seja atingido;

    4. aguarda o processo encerrar.

    O argumento opcional input é a informação (objeto `bytes`) que será enviada para o processo filho.

    Retorna uma tupla `(stdout_data, stderr_data)`.

    Se qualquer exceção `BrokenPipeError` ou `ConnectionResetError` for levantada ao escrever input em stdin, a exceção é ignorada. Esta condição ocorre quando o processo encerra antes de todos os dados serem escritos em stdin.

    Se for desejado enviar dados para o stdin do processo, o mesmo precisa ser criado com `stdin=PIPE`. De forma similar, para obter qualquer coisa além de `None` na tupla resultante, o processo precisa ser criado com os argumentos `stdout=PIPE` e/ou `stderr=PIPE`.

    Perceba que, os dados lidos são armazenados em um buffer na memória, então não use este método se o tamanho dos dados é grande ou ilimitado.

    Alterado na versão 3.12: stdin é fechado quando `input=None` é também.

  send_signal(signal)

    Envia o sinal signal para o processo filho.

    Nota

    No Windows, `SIGTERM` é um apelido para `terminate()`. `CTRL_C_EVENT` e `CTRL_BREAK_EVENT` podem ser enviados para processos iniciados com um parâmetro creationflags, o qual inclui `CREATE_NEW_PROCESS_GROUP`.

  terminate()

    Interrompe o processo filho.

    Em sistemas POSIX este método envia `SIGTERM` para o processo filho.

    No Windows a função `TerminateProcess()` da API Win32 é chamada para interromper o processo filho.

  kill()

    Mata o processo filho.

    Em sistemas POSIX este método envia `SIGKILL` para o processo filho.

    No Windows, este método é um atalho para `terminate()`.

  stdin

    Fluxo de entrada padrão (`StreamWriter`) ou `None` se o processo foi criado com `stdin=None`.

  stdout

    Fluxo de saída padrão (`StreamReader`) ou `None` se o processo foi criado com `stdout=None`.

  stderr

    Erro de fluxo padrão (`StreamReader`) ou `None` se o processo foi criado com `stderr=None`.

  Aviso

  Use o método `communicate()` ao invés de `process.stdin.write()`, `await process.stdout.read()` ou `await process.stderr.read()`. Isso evita deadlocks devido a fluxos pausando a leitura ou escrita, e bloqueando o processo filho.

  pid

    Número de identificação do processo (PID).

    Perceba que para processos criados pela função `create_subprocess_shell()`, este atributo é o PID do console gerado.

  returncode

    Retorna o código do processo quando o mesmo terminar.

    Um valor `None` indica que o processo ainda não terminou.

    For processes created with `create_subprocess_exec()`, a negative value `-N` indicates that the child was terminated by signal `N` (POSIX only).

    For processes created with `create_subprocess_shell()`, the return code reflects the exit status of the shell itself (e.g. `/bin/sh`), which may map signals to codes such as `128+N`. See the documentation of the shell (for example, the Bash manual’s Exit Status) for details.

### Subprocesso e Threads

Laço de eventos padrão do asyncio suporta a execução de subprocessos a partir de diferentes threads por padrão.

No Windows, subprocessos são fornecidos pela classe `ProactorEventLoop` apenas (por padrão), a classe `SelectorEventLoop` não tem suporte a subprocesso.

Perceba que implementações alternativas do laço de eventos podem ter limitações próprias; por favor, verifique a sua documentação.

Ver também

A seção Concorrência e multithreading em asyncio.

### Exemplos

Um exemplo de uso da classe `Process` para controlar um subprocesso e a classe `StreamReader` para ler a partir da sua saída padrão.

O subprocesso é criado pela função `create_subprocess_exec()`:

    import asyncio
    import sys

    async def get_date():
        code = 'import datetime as dt; print(dt.datetime.now())'

        # Create the subprocess; redirect the standard output
        # into a pipe.
        proc = await asyncio.create_subprocess_exec(
            sys.executable, '-c', code,
            stdout=asyncio.subprocess.PIPE)

        # Read one line of output.
        data = await proc.stdout.readline()
        line = data.decode('ascii').rstrip()

        # Wait for the subprocess exit.
        await proc.wait()
        return line

    date = asyncio.run(get_date())
    print(f"Current date: {date}")

Veja também o mesmo exemplo escrito usando APIs de baixo nível.