Spec-Zone.ru › Python 3.8

Подпроцессы

Исходный код: Lib/asyncio/subprocess.py, Lib/asyncio/base_subprocess.py

В этом разделе описываются высокоуровневые асинхронные API asyncio для создания и управления подпроцессами.

Вот пример того, как asyncio может выполнить командную строку и получить ее результат:

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

будет выводить:

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

Поскольку все асинхронные функции asyncio subprocess являются асинхронными, и asyncio предоставляет множество инструментов для работы с такими функциями, легко выполнить и отследить несколько подпроцессов параллельно. На самом деле, очень просто изменить приведенный выше пример, чтобы запустить несколько команд одновременно:

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

asyncio.run(main())

См. также подраздел Примеры.

Создание подпроцессов

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

Создать подпроцесс.

Аргумент limit устанавливает предел буфера для StreamReader обёртки для Process.stdout и Process.stderr (если subprocess.PIPE передано в аргументы stdout и stderr).

Возвращает экземпляр Process.

См. документацию loop.subprocess_exec() для других параметров.

Устарело начиная с версии 3.8, будет удалено в версии 3.10: Параметр loop.

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

Выполнить командную строку cmd.

Аргумент limit устанавливает предел буфера для StreamReader обёртки для Process.stdout и Process.stderr (если subprocess.PIPE передано в аргументы stdout и stderr).

Возвращает экземпляр Process.

См. документацию loop.subprocess_shell() для других параметров.

Важно

Приложению необходимо гарантировать, что все пробелы и специальные символы должным образом заключены в кавычки, чтобы избежать уязвимостей внедрения команд. Функция shlex.quote() может использоваться для правильного экранирования пробелов и специальных символов оболочки в строках, которые будут использоваться для построения команд оболочки.

Устарело начиная с версии 3.8, будет удалено в версии 3.10: Параметр loop.

Примечание

Подпроцессы доступны для Windows, если используется ProactorEventLoop. Подробности см. в разделе Поддержка подпроцессов в Windows.

См. также

asyncio также имеет следующие низкоуровневые API для работы с подпроцессами: loop.subprocess_exec(), loop.subprocess_shell(), loop.connect_read_pipe(), loop.connect_write_pipe(), а также Транспортные средства подпроцессов и Протоколы подпроцессов.

Константы

asyncio.subprocess.PIPE

Может быть передано в параметры stdin, stdout или stderr.

Если PIPE передано в аргумент stdin, атрибут Process.stdin будет указывать на экземпляр StreamWriter.

Если PIPE передано в аргументы stdout или stderr, атрибуты Process.stdout и Process.stderr будут указывать на экземпляры StreamReader.

asyncio.subprocess.STDOUT

Специальное значение, которое может быть использовано в качестве аргумента stderr и указывает, что стандартная ошибка должна быть перенаправлена ​​в стандартный вывод.

asyncio.subprocess.DEVNULL

Специальное значение, которое может быть использовано в качестве аргумента stdin, stdout или stderr для функций создания процессов. Это указывает, что специальный файл os.devnull будет использоваться для соответствующего потока подпроцесса.

Взаимодействие с дочерними процессами

Обе функции create_subprocess_exec() и create_subprocess_shell() возвращают экземпляры класса Process. Process — это высокоуровневая обёртка, которая позволяет взаимодействовать с дочерними процессами и отслеживать их завершение.

class asyncio.subprocess.Process

Объект, который оборачивает процессы ОС, созданные функциями create_subprocess_exec() и create_subprocess_shell().

Этот класс разработан с похожим API на класс subprocess.Popen, но есть некоторые заметные различия:

  • в отличие от Popen, экземпляры Process не имеют эквивалента методу poll();
  • методы communicate() и wait() не имеют параметра timeout: используйте функцию wait_for();
  • метод Process.wait() является асинхронным, в то время как метод subprocess.Popen.wait() реализован как блокирующий цикл ожидания;
  • параметр universal_newlines не поддерживается.

Этот класс не потокобезопасен.

См. также раздел Дочерние процессы и потоки.

coroutine wait()

Ожидание завершения дочернего процесса.

Устанавливает и возвращает атрибут returncode.

Примечание

Этот метод может привести к тупику при использовании stdout=PIPE или stderr=PIPE и если дочерний процесс генерирует слишком много вывода, который блокирует ожидание буфера канала ОС для принятия большего объёма данных. Используйте метод communicate() при использовании каналов для предотвращения этой ситуации.

coroutine communicate(input=None)

Взаимодействие с процессом:

  1. отправка данных в stdin (если input не None);
  2. чтение данных из stdout и stderr, пока не будет достигнут EOF;
  3. ожидание завершения процесса.

Необязательный аргумент input — это данные (bytes объект), которые будут отправлены дочернему процессу.

Возвращает кортеж (stdout_data, stderr_data).

Если при записи input в stdin возникает исключение BrokenPipeError или ConnectionResetError, исключение игнорируется. Эта ситуация происходит, когда процесс завершается до того, как все данные будут записаны в stdin.

Для отправки данных в stdin процесса, процесс должен быть создан с stdin=PIPE. Аналогично, для получения чего-либо, кроме None в кортеже результата, процесс должен быть создан с stdout=PIPE и/или stderr=PIPE аргументами.

Обратите внимание, что считанные данные буферизуются в памяти, поэтому не используйте этот метод, если размер данных велик или неограничен.

send_signal(signal)

Отправка сигнала signal дочернему процессу.

Примечание

В Windows, SIGTERM — это псевдоним для terminate(). CTRL_C_EVENT и CTRL_BREAK_EVENT могут быть отправлены в процессы, запущенные с параметром creationflags, включающим CREATE_NEW_PROCESS_GROUP.

terminate()

Остановка дочернего процесса.

На системах POSIX этот метод отправляет signal.SIGTERM дочернему процессу.

В Windows вызывается функция Win32 API TerminateProcess() для остановки дочернего процесса.

kill()

Уничтожение дочернего процесса.

На системах POSIX этот метод отправляет SIGKILL дочернему процессу.

В Windows этот метод является псевдонимом для terminate().

stdin

Поток стандартного ввода (StreamWriter) или None если процесс был создан с stdin=None.

stdout

Поток стандартного вывода (StreamReader) или None если процесс был создан с stdout=None.

stderr

Поток стандартной ошибки (StreamReader) или None если процесс был создан с stderr=None.

Предупреждение

Используйте метод communicate() вместо process.stdin.write(), await process.stdout.read() или await process.stderr.read. Это предотвращает тупики из-за потоков, приостанавливающих чтение или запись и блокирующих дочерний процесс.

pid

Идентификатор процесса (PID).

Обратите внимание, что для процессов, созданных функцией create_subprocess_shell(), этот атрибут является PID порождённой оболочки.

returncode

Код возврата процесса при его выходе.

Значение None указывает, что процесс ещё не завершен.

Отрицательное значение -N указывает, что дочерний процесс был завершен сигналом N (только POSIX).

Дочерние процессы и потоки

Стандартный цикл событий asyncio по умолчанию поддерживает запуск дочерних процессов из разных потоков.

В Windows дочерние процессы предоставляются только ProactorEventLoop (по умолчанию), SelectorEventLoop не поддерживает дочерние процессы.

В UNIX используются наблюдатели дочерних процессов для ожидания завершения дочерних процессов, см. Наблюдатели процессов для получения дополнительной информации.

Изменено в версии 3.8: UNIX переключился на использование ThreadedChildWatcher для запуска дочерних процессов из разных потоков без ограничений.

Запуск дочернего процесса с неактивным текущим наблюдателем дочернего процесса вызывает RuntimeError.

Обратите внимание, что альтернативные реализации цикла событий могут иметь собственные ограничения; см. их документацию.

См. также

Раздел Конкурентность и многопоточность в asyncio.

Примеры

Пример использования класса Process для управления дочерним процессом и класса StreamReader для чтения из его стандартного вывода.

Дочерний процесс создаётся функцией create_subprocess_exec():

import asyncio
import sys

async def get_date():
    code = 'import datetime; print(datetime.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}")

См. также аналогичный пример, написанный с использованием низкоуровневых API.

© 2001–2022 Python Software Foundation
Licensed under the PSF License.
https://docs.python.org/3.8/library/asyncio-subprocess.html

Spec-Zone.ru

Настройки Оффлайн Что нового Помощь О нас
Spec-Zone .ru
спецификации, руководства, описания, API