17.5. subprocess – Управление подпроцессами¶subprocess – Subprocess management

17.5.1. Использование модуля subprocess¶Using the subprocess Module

Рекомендуемый способ вызова подпроцессов – использовать функцию run() для всех случаев, с которыми она может справиться. Для более сложных случаев можно напрямую использовать нижележащий интерфейс Popen.

Функция run() была добавлена в Python 3.5; если требуется сохранить совместимость со старыми версиями, см. раздел Старого высокоуровневого API.

subprocess.run(args, *, stdin=None, input=None, stdout=None, stderr=None, shell=False, timeout=None, check=False)¶

Выполняет команду, описанную аргументом args. Ожидает завершения команды и возвращает экземпляр CompletedProcess.

Аргументы, показанные выше, – лишь наиболее распространённые; они описаны ниже в разделе Часто используемые аргументы (отсюда использование только именованных аргументов в сокращённой сигнатуре). Полная сигнатура функции в основном совпадает с сигнатурой конструктора Popen – за исключением timeout, input и check; все остальные аргументы этой функции передаются этому интерфейсу.

По умолчанию stdout и stderr не захватываются. Чтобы это сделать, передайте PIPE для аргументов stdout и/или stderr.

Аргумент timeout передаётся в Popen.communicate(). Если время ожидания истекает, дочерний процесс будет завершён, и он будет ожидаться. Исключение TimeoutExpired будет возбуждено повторно после завершения дочернего процесса.

Аргумент input передаётся в Popen.communicate(), а через него – в stdin подпроцесса. Если он используется, то должен представлять собой последовательность байтов или строку, если universal_newlines=True. При использовании внутренний объект Popen автоматически создаётся с stdin=PIPE, и аргумент stdin не может быть использован.

Если check истинно и процесс завершается с ненулевым кодом возврата, будет возбуждено исключение CalledProcessError. Атрибуты этого исключения содержат аргументы, код возврата, а также stdout и stderr, если они были захвачены.

Примеры:

>>> subprocess.run(["ls", "-l"])  # не захватывает вывод
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')

Новое в версии 3.5.

class subprocess.CompletedProcess¶

Возвращаемое значение run(), представляющее завершившийся процесс.

args¶

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

returncode¶

Статус выхода дочернего процесса. Обычно статус выхода 0 указывает на успешное завершение.

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

stdout¶

Захваченный stdout дочернего процесса. Последовательность байтов или строка, если run() был вызван с universal_newlines=True. None, если stdout не был захвачен.

Если процесс был запущен с stderr=subprocess.STDOUT, stdout и stderr будут объединены в этом атрибуте, а stderr будет равно None.

stderr¶

Захваченный stderr дочернего процесса. Последовательность байтов или строка, если run() был вызван с universal_newlines=True. None, если stderr не был захвачен.

check_returncode()¶

Если returncode ненулевой, возбуждается CalledProcessError.

Новое в версии 3.5.

subprocess.DEVNULL¶

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

Новое в версии 3.3.

subprocess.PIPE¶

Специальное значение, которое можно использовать в качестве аргумента stdin, stdout или stderr для Popen и указывает, что должен быть открыт канал (pipe) для стандартного потока. Наиболее полезен с Popen.communicate().

subprocess.STDOUT¶

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

exception subprocess.SubprocessError¶

Базовый класс для всех остальных исключений из этого модуля.

Новое в версии 3.3.

exception subprocess.TimeoutExpired¶

Подкласс SubprocessError, возбуждается при истечении тайм-аута во время ожидания дочернего процесса.

cmd¶

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

timeout¶

Тайм-аут в секундах.

output¶

Вывод дочернего процесса, если он был захвачен с помощью run() или check_output(). В противном случае None.

stdout¶

Псевдоним для output, для симметрии с stderr.

stderr¶

Вывод stderr дочернего процесса, если он был захвачен с помощью run(). В противном случае – None.

Новое в версии 3.3.

Изменено в версии 3.5: добавлены атрибуты stdout и stderr

exception subprocess.CalledProcessError¶

Подкласс SubprocessError, вызываемый, когда процесс, запущенный через check_call() или check_output(), возвращает ненулевой код завершения.

returncode¶

Статус выхода дочернего процесса. Если процесс завершился из-за сигнала, это будет отрицательный номер сигнала.

cmd¶

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

output¶

Вывод дочернего процесса, если он был захвачен с помощью run() или check_output(). В противном случае None.

stdout¶

Псевдоним для output, для симметрии с stderr.

stderr¶

Вывод stderr дочернего процесса, если он был захвачен с помощью run(). В противном случае – None.

Изменено в версии 3.5: добавлены атрибуты stdout и stderr

17.5.2. Рекомендации по безопасности¶Security Considerations

В отличие от некоторых других функций popen, данная реализация никогда не вызывает системную оболочку неявно. Это означает, что все символы, включая метасимволы оболочки, можно безопасно передавать дочерним процессам. Если оболочка вызывается явно через shell=True, приложение должно само позаботиться о том, чтобы все пробелы и метасимволы были правильно экранированы во избежание уязвимостей внедрения команд оболочки.

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

17.5.3. Объекты Popen¶Popen Objects

Экземпляры класса Popen имеют следующие методы:

Popen.poll()¶

Проверяет, завершён ли дочерний процесс. Устанавливает и возвращает атрибут returncode.

Popen.wait(timeout=None)¶

Ожидает завершения дочернего процесса. Устанавливает и возвращает атрибут returncode.

Если процесс не завершается через тайм-аут секунд, возбуждается исключение TimeoutExpired. Это исключение можно безопасно перехватить и повторить ожидание.

Примечание

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

Примечание

Функция реализована с помощью busy-цикла (неблокирующий вызов и короткие паузы). Используйте модуль asyncio для асинхронного ожидания: см. asyncio.create_subprocess_exec.

Изменено в версии 3.3: добавлен timeout.

Устарело с версии 3.4: Не используйте параметр endtime. Он был случайно открыт в версии 3.3, но остался недокументированным, так как предполагался приватным для внутреннего использования. Вместо него используйте timeout.

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

Взаимодействует с процессом: отправляет данные в stdin. Читает данные из stdout и stderr, до достижения конца файла. Ожидает завершения процесса. Необязательный аргумент input должен содержать данные для отправки дочернему процессу или None, если данные не нужно отправлять. Тип input должен быть bytes или, если universal_newlines было True, строкой.

communicate() возвращает кортеж (stdout_data, stderr_data). Данные будут в формате bytes или, если universal_newlines было True, строк.

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

Если процесс не завершится за timeout секунд, будет вызвано исключение TimeoutExpired. Перехват этого исключения и повторное обращение к обмену данными не приведет к потере вывода.

Дочерний процесс не уничтожается по истечении тайм-аута, поэтому для корректной очистки хорошо написанное приложение должно уничтожить дочерний процесс и завершить обмен данными:

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

Примечание

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

Изменено в версии 3.3: добавлен timeout.

Popen.send_signal(signal)¶

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

Примечание

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

Popen.terminate()¶

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

Popen.kill()¶

Завершает дочерний процесс. В ОС POSIX функция отправляет SIGKILL дочернему процессу. В Windows kill() является псевдонимом для terminate().

Также доступны следующие атрибуты:

Popen.args¶

Аргумент args в том виде, в котором он был передан в Popen – последовательность аргументов программы или одна строка.

Новое в версии 3.3.

Popen.stdin¶

Если аргумент stdin был PIPE, этот атрибут представляет собой записываемый объект потока, возвращаемый open(). Если аргумент universal_newlines был True, поток является текстовым, в противном случае – байтовым потоком. Если аргумент stdin не был PIPE, этот атрибут равен None.

Popen.stdout¶

Если аргумент stdout был PIPE, этот атрибут представляет собой читаемый объект потока, возвращаемый open(). Чтение из потока предоставляет вывод дочернего процесса. Если аргумент universal_newlines был True, поток является текстовым, в противном случае – байтовым потоком. Если аргумент stdout не был PIPE, этот атрибут равен None.

Popen.stderr¶

Если аргумент stderr был PIPE, этот атрибут представляет собой читаемый объект потока, возвращаемый open(). Чтение из потока предоставляет вывод ошибок дочернего процесса. Если аргумент universal_newlines был True, поток является текстовым, в противном случае – байтовым потоком. Если аргумент stderr не был PIPE, этот атрибут равен None.

Popen.pid¶

PID дочернего процесса.

Обратите внимание: если аргумент shell установлен в True, это PID запущенной оболочки.

Popen.returncode¶

Код возврата дочернего процесса, устанавливаемый методами poll() и wait() (а косвенно – communicate()). Значение None указывает, что процесс ещё не завершён.

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

17.5.4. Вспомогательные классы Popen для Windows¶Windows Popen Helpers

Класс STARTUPINFO и следующие константы доступны только в Windows.

class subprocess.STARTUPINFO¶

Частичная поддержка структуры Windows STARTUPINFO используется для создания Popen.

dwFlags¶

Битовое поле, определяющее, используются ли определённые атрибуты STARTUPINFO при создании окна процессом.

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

hStdInput¶

Если dwFlags указывает STARTF_USESTDHANDLES, этот атрибут является дескриптором стандартного ввода процесса. Если STARTF_USESTDHANDLES не указан, по умолчанию для стандартного ввода используется буфер клавиатуры.

hStdOutput¶

Если dwFlags указывает STARTF_USESTDHANDLES, этот атрибут является дескриптором стандартного вывода процесса. В противном случае этот атрибут игнорируется, и по умолчанию для стандартного вывода используется буфер окна консоли.

hStdError¶

Если dwFlags указывает STARTF_USESTDHANDLES, этот атрибут является дескриптором стандартного вывода ошибок процесса. В противном случае этот атрибут игнорируется, и по умолчанию для стандартного вывода ошибок используется буфер окна консоли.

wShowWindow¶

Если в dwFlags указан STARTF_USESHOWWINDOW, этот атрибут может принимать любое значение, которое можно указать в параметре nCmdShow для функции ShowWindow, за исключением SW_SHOWDEFAULT. В противном случае этот атрибут игнорируется.

Для этого атрибута предоставляется SW_HIDE. Он используется, когда Popen вызывается с shell=True.

17.5.5. Старый высокоуровневый API¶Older high-level API

До Python 3.5 эти три функции представляли собой высокоуровневый API для subprocess. Теперь во многих случаях можно использовать run(), но значительная часть существующего кода по-прежнему вызывает эти функции.

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

Запускает команду, описанную параметром args. Ожидает завершения команды и затем возвращает атрибут returncode.

Это эквивалентно:

run(...).returncode

(за исключением того, что параметры input и check не поддерживаются)

Показанные выше аргументы – лишь самые распространённые. Полная сигнатура функции в основном совпадает с сигнатурой конструктора Popen – эта функция передаёт все переданные аргументы, кроме timeout, напрямую в этот интерфейс.

Примечание

Не используйте stdout=PIPE или stderr=PIPE с этой функцией. Дочерний процесс будет заблокирован, если он выдаст в канал достаточно данных, чтобы заполнить буфер канала ОС, поскольку каналы не читаются.

Изменено в версии 3.3: добавлен timeout.

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

Выполняет команду с аргументами. Ожидает завершения команды. Если код возврата равен нулю, возвращает результат, иначе вызывает CalledProcessError. Объект CalledProcessError будет содержать код возврата в атрибуте returncode.

Это эквивалентно:

run(..., check=True)

(за исключением того, что параметр input не поддерживается)

Показанные выше аргументы – лишь самые распространённые. Полная сигнатура функции в основном совпадает с сигнатурой конструктора Popen – эта функция передаёт все переданные аргументы, кроме timeout, напрямую в этот интерфейс.

Примечание

Не используйте stdout=PIPE или stderr=PIPE с этой функцией. Дочерний процесс будет заблокирован, если он выдаст в канал достаточно данных, чтобы заполнить буфер канала ОС, поскольку каналы не читаются.

Изменено в версии 3.3: добавлен timeout.

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

Выполняет команду с аргументами и возвращает её вывод.

Если код возврата был ненулевым, возбуждается исключение CalledProcessError. Объект CalledProcessError будет содержать код возврата в атрибуте returncode, а вывод – в атрибуте output.

Это эквивалентно:

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

Показанные выше аргументы – лишь самые распространённые. Полная сигнатура функции в основном та же, что и у run() – большинство аргументов передаются напрямую в этот интерфейс. Однако явная передача input=None для наследования дескриптора стандартного ввода родительского процесса не поддерживается.

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

Это поведение можно переопределить, установив universal_newlines в True, как описано выше в разделе Часто используемые аргументы.

Чтобы также захватывать стандартный поток ошибок в результате, используйте 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'

Новое в версии 3.1.

Изменено в версии 3.3: добавлен timeout.

Изменено в версии 3.4: добавлена поддержка именованного аргумента input.

17.5.6. Замена старых функций модулем subprocess¶Replacing Older Functions with the subprocess Module

В этом разделе «a становится b» означает, что b можно использовать как замену для a.

В следующих примерах предполагается, что соответствующие функции уже импортированы из модуля subprocess.

output=`mycmd myarg`

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

output=`dmesg | grep hda`

p1 = Popen(["dmesg"], stdout=PIPE)
p2 = Popen(["grep", "hda"], stdin=p1.stdout, stdout=PIPE)
p1.stdout.close()  # Разрешить p1 получать SIGPIPE, если p2 завершается.
output = p2.communicate()[0]

output=`dmesg | grep hda`

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

sts = os.system("mycmd" + " myarg")
# становится
sts = call("mycmd" + " myarg", shell=True)

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)

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

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

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

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

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

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

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

17.5.7. Устаревшие функции вызова оболочки¶Legacy Shell Invocation Functions

Этот модуль также предоставляет следующие устаревшие функции из модуля commands версии 2.x. Эти операции неявно вызывают системную оболочку, и ни одно из описанных выше гарантий безопасности и согласованности обработки исключений не действует для этих функций.

subprocess.getstatusoutput(cmd)¶

Возвращает (status, output) выполнения cmd в оболочке.

Выполняет строку cmd в оболочке с Popen.check_output() и возвращает кортеж из двух элементов (status, output). Используется режим универсальных новых строк; см. примечания к Часто используемые аргументы для подробностей.

Конечный символ новой строки удаляется из вывода. Статус выхода команды можно интерпретировать в соответствии с правилами для функции C wait(). Пример:

>>> subprocess.getstatusoutput('ls /bin/ls')
(0, '/bin/ls')
>>> subprocess.getstatusoutput('cat /bin/junk')
(256, 'cat: /bin/junk: No such file or directory')
>>> subprocess.getstatusoutput('/bin/junk')
(256, 'sh: /bin/junk: not found')

Доступность: POSIX и Windows

Изменено в версии 3.3.4: Добавлена поддержка Windows

subprocess.getoutput(cmd)¶

Возвращает вывод (stdout и stderr) выполнения cmd в оболочке.

Как getstatusoutput(), за исключением того, что статус выхода игнорируется, а возвращаемое значение – строка, содержащая вывод команды. Пример:

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

Доступность: POSIX и Windows

Изменено в версии 3.3.4: Добавлена поддержка Windows

17.5.8. Примечания¶Notes