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

17.1.1.1. Часто используемые аргументы¶Frequently Used Arguments

Чтобы поддерживать широкий спектр сценариев использования, конструктор Popen (и удобные функции) принимает большое количество необязательных аргументов. Для большинства типичных случаев многие из этих аргументов можно безопасно оставить со значениями по умолчанию. Наиболее часто требуемые аргументы:

args обязателен для всех вызовов и должен быть строкой или последовательностью аргументов программы. Как правило, предпочтительнее передавать последовательность аргументов, так как это позволяет модулю позаботиться о любом необходимом экранировании и кавычках аргументов (например, для пробелов в именах файлов). Если передаётся одна строка, то либо shell должен быть True (см. ниже), либо строка должна просто указывать имя программы для запуска без указания каких-либо аргументов.

stdin, stdout и stderr задают дескрипторы файлов стандартного ввода, стандартного вывода и стандартного вывода ошибок выполняемой программы соответственно. Допустимые значения: PIPE, существующий файловый дескриптор (положительное целое число), существующий файловый объект и None. PIPE указывает, что должен быть создан новый канал к дочернему процессу. При настройках по умолчанию None перенаправление не происходит; дескрипторы файлов дочернего процесса наследуются от родительского. Кроме того, stderr может быть STDOUT, что означает, что данные stderr от дочернего процесса должны захватываться в тот же дескриптор, что и stdout.

Если stdout или stderr являются каналами, а universal_newlines имеет значение True, то все концы строк будут преобразованы в '\n', как описано для аргумента режима universal newlines 'U' в open().

Если shell равен True, указанная команда будет выполняться через оболочку. Это может быть полезно, если вы используете Python в основном из-за улучшенного управления потоком, которое он предлагает по сравнению с большинством системных оболочек, и при этом хотите удобного доступа к другим возможностям оболочки, таким как конвейеры, подстановка имен файлов, подстановка переменных окружения и раскрытие ~ в домашний каталог пользователя. Однако имейте в виду, что сам Python предлагает реализации многих функций, подобных оболочке (в частности, glob, fnmatch, os.walk(), os.path.expandvars(), os.path.expanduser() и shutil).

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

Выполнение shell-команд, включающих непроверенные входные данные из ненадёжного источника, делает программу уязвимой для shell-инъекций – серьёзной уязвимости безопасности, которая может привести к выполнению произвольных команд. По этой причине использование shell=True настоятельно не рекомендуется, если командная строка формируется из внешних данных:

>>> from subprocess import call
>>> filename = input("What file would you like to display?\n")
What file would you like to display?
non_existent; rm -rf / #
>>> call("cat " + filename, shell=True) # Ой-ой. Это плохо кончится...

shell=False отключает все функции, основанные на shell, но не подвержен этой уязвимости; см. примечание в документации конструктора Popen для полезных советов по настройке shell=False.

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

Эти опции, как и все остальные, подробно описаны в документации конструктора Popen.

17.1.1.2. Конструктор Popen¶Popen Constructor

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

class subprocess.Popen(args, bufsize=0, executable=None, stdin=None, stdout=None, stderr=None, preexec_fn=None, close_fds=False, shell=False, cwd=None, env=None, universal_newlines=False, startupinfo=None, creationflags=0)¶

Запускает дочернюю программу в новом процессе. В Unix класс использует поведение, подобное os.execvp(), для выполнения дочерней программы. В Windows класс использует функцию Windows CreateProcess(). Аргументы Popen описаны ниже.

args должен быть последовательностью аргументов программы или отдельной строкой. По умолчанию, если args является последовательностью, исполняемая программа – это первый элемент в args. Если args – строка, интерпретация зависит от платформы и описана ниже. Дополнительные отличия от поведения по умолчанию см. в аргументах shell и executable. Если не указано иное, рекомендуется передавать args как последовательность.

В Unix, если args является строкой, она интерпретируется как имя или путь к выполняемой программе. Однако это можно сделать только в том случае, если программе не передаются аргументы.

Примечание

shlex.split() может быть полезен при определении правильной токенизации для args, особенно в сложных случаях:

>>> import shlex, subprocess
>>> command_line = raw_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) # Успешно!

Обратите внимание, что опции (такие как -input) и аргументы (такие как eggs.txt), разделённые пробелами в оболочке, помещаются в отдельные элементы списка, в то время как аргументы, требующие кавычек или обратной косой черты в оболочке (например, имена файлов, содержащие пробелы, или команда echo, показанная выше), являются отдельными элементами списка.

На Windows, если args – последовательность, она будет преобразована в строку способом, описанным в разделе Преобразование последовательности аргументов в строку на Windows. Это связано с тем, что базовая функция CreateProcess() работает со строками.

Аргумент shell (по умолчанию False) определяет, нужно ли использовать оболочку в качестве исполняемой программы. Если shell равен True, рекомендуется передавать args в виде строки, а не последовательности.

В Unix с shell=True по умолчанию используется shell /bin/sh. Если args – строка, она задаёт команду для выполнения через shell. Это означает, что строка должна быть отформатирована точно так, как если бы она была введена в приглашении shell. Это включает, например, экранирование кавычками или обратным слешем имён файлов, содержащих пробелы. Если args – последовательность, первый элемент задаёт командную строку, а все остальные элементы рассматриваются как дополнительные аргументы для самого shell. То есть, Popen делает эквивалент следующего:

Popen(['/bin/sh', '-c', args[0], args[1], ...])

На Windows с shell=True переменная окружения COMSPEC задаёт оболочку по умолчанию. Указывать shell=True в Windows нужно только тогда, когда команда, которую требуется выполнить, встроена в оболочку (например, dir или copy). Для запуска пакетного файла или консольного исполняемого файла shell=True не требуется.

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

Передача shell=True может быть опасна с точки зрения безопасности в сочетании с ненадёжными входными данными. Подробнее см. предупреждение в разделе Часто используемые аргументы.

bufsize, если задан, имеет тот же смысл, что и соответствующий аргумент встроенной функции open(): 0 – без буферизации, 1 – построчная буферизация, любое другое положительное значение означает использование буфера (примерно) такого размера. Отрицательное bufsize означает использование системного значения по умолчанию, что обычно означает полную буферизацию. Значение по умолчанию для bufsize – 0 (без буферизации).

Примечание

Если возникают проблемы с производительностью, рекомендуется попробовать включить буферизацию, установив bufsize в -1 или достаточно большое положительное значение (например, 4096).

Аргумент executable задаёт заменяющую программу для выполнения. Он требуется крайне редко. Если shell=False, то executable заменяет программу, заданную args. Однако исходный args по-прежнему передаётся программе. Большинство программ рассматривают программу, указанную в args, как имя команды, которое может отличаться от фактически выполняемой программы. В Unix имя args становится отображаемым именем исполняемого файла в таких утилитах, как ps. Если shell=True, то в Unix аргумент executable задаёт замену shell для стандартного /bin/sh.

stdin, stdout и stderr задают дескрипторы файлов стандартного ввода, стандартного вывода и стандартного вывода ошибок выполняемой программы соответственно. Допустимые значения: PIPE, существующий файловый дескриптор (положительное целое число), существующий файловый объект и None. PIPE указывает, что должен быть создан новый канал к дочернему процессу. При настройках по умолчанию None перенаправление не происходит; дескрипторы файлов дочернего процесса наследуются от родительского. Кроме того, stderr может быть STDOUT, что означает, что данные stderr от дочернего процесса должны захватываться в тот же дескриптор, что и stdout.

Если preexec_fn задан как вызываемый объект, этот объект будет вызван в дочернем процессе непосредственно перед его выполнением. (Только Unix)

Если close_fds равен true, все файловые дескрипторы, кроме 0, 1 и 2, будут закрыты перед выполнением дочернего процесса. (Только Unix). Или, в Windows, если close_fds равен true, то дочерний процесс не унаследует ни одного дескриптора. Обратите внимание: в Windows нельзя одновременно установить close_fds в true и перенаправлять стандартные дескрипторы с помощью stdin, stdout или stderr.

Если cwd не равен None, текущий каталог дочернего процесса будет изменён на cwd перед его выполнением. Обратите внимание, что этот каталог не учитывается при поиске исполняемого файла, поэтому нельзя задать путь к программе относительно cwd.

Если env не равен None, он должен быть отображением (mapping), определяющим переменные окружения для нового процесса; они используются вместо наследования окружения текущего процесса, что является поведением по умолчанию.

Примечание

Если указано, env должен содержать все переменные, необходимые для выполнения программы. В Windows для запуска компоновки side-by-side указанный env обязан включать корректные SystemRoot.

Если universal_newlines равен True, файловые объекты stdout и stderr открываются как текстовые файлы в режиме универсальных новых строк. Строки могут завершаться любым из '\n' (соглашение Unix о конце строки), '\r' (соглашение старого Macintosh) или '\r\n' (соглашение Windows). Все эти внешние представления интерпретируются программой Python как '\n'.

Примечание

Эта функция доступна, только если Python собран с поддержкой универсальных новых строк (по умолчанию). Кроме того, атрибут newlines файловых объектов stdout, stdin и stderr не обновляется методом communicate().

Если задан, startupinfo будет объектом STARTUPINFO, который передаётся нижележащей функции CreateProcess. creationflags, если задан, может быть CREATE_NEW_CONSOLE или CREATE_NEW_PROCESS_GROUP (только Windows).

17.1.1.3. Исключения¶Exceptions

Исключения, возникающие в дочернем процессе до начала выполнения новой программы, будут повторно возбуждены в родительском процессе. Кроме того, объект исключения будет иметь дополнительный атрибут с именем child_traceback, который представляет собой строку, содержащую информацию о трассировке с точки зрения дочернего процесса.

Наиболее часто вызываемое исключение – OSError. Оно возникает, например, при попытке выполнить несуществующий файл. Приложения должны быть готовы к исключениям OSError.

ValueError будет вызван, если Popen вызвана с недопустимыми аргументами.

check_call() и check_output() вызовут CalledProcessError, если вызванный процесс вернёт ненулевой код возврата.

17.1.1.4. Безопасность¶Security

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

17.1.3.1. Константы¶Constants

Модуль subprocess предоставляет следующие константы.

subprocess.STD_INPUT_HANDLE¶

Устройство стандартного ввода. Изначально это буфер консольного ввода, CONIN$.

subprocess.STD_OUTPUT_HANDLE¶

Устройство стандартного вывода. Изначально это активный буфер консольного экрана, CONOUT$.

subprocess.STD_ERROR_HANDLE¶

Устройство стандартного вывода ошибок. Изначально это активный буфер консольного экрана, CONOUT$.

subprocess.SW_HIDE¶

Скрывает окно. Другое окно будет активировано.

subprocess.STARTF_USESTDHANDLES¶

Указывает, что атрибуты STARTUPINFO.hStdInput, STARTUPINFO.hStdOutput и STARTUPINFO.hStdError содержат дополнительную информацию.

subprocess.STARTF_USESHOWWINDOW¶

Указывает, что атрибут STARTUPINFO.wShowWindow содержит дополнительную информацию.

subprocess.CREATE_NEW_CONSOLE¶

Новый процесс получает новую консоль вместо наследования консоли родителя (по умолчанию).

Этот флаг всегда устанавливается, когда Popen создаётся с помощью shell=True.

subprocess.CREATE_NEW_PROCESS_GROUP¶

Параметр Popen creationflags, указывающий, что будет создана новая группа процессов. Этот флаг необходим для использования os.kill() в подпроцессе.

Этот флаг игнорируется, если указан CREATE_NEW_CONSOLE.

17.1.4.1. Замена обратных кавычек оболочки /bin/sh¶Replacing /bin/sh shell backquote

output=`mycmd myarg`

становится:

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

17.1.4.2. Замена конвейера оболочки¶Replacing shell pipeline

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]

Вызов p1.stdout.close() после запуска p2 важен для того, чтобы p1 получил SIGPIPE, если p2 завершится раньше p1.

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

output=`dmesg | grep hda`

становится:

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

17.1.4.3. Замена os.system()¶Replacing os.system()

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

Примечания:

• Вызов программы через оболочку обычно не требуется.

Более реалистичный пример выглядит так:

try:
    retcode = call("mycmd" + " myarg", shell=True)
    if retcode < 0:
        print >>sys.stderr, "Child was terminated by signal", -retcode
    else:
        print >>sys.stderr, "Child returned", retcode
except OSError as e:
    print >>sys.stderr, "Execution failed:", e

17.1.4.4. Замена семейства os.spawn¶Replacing the os.spawn family

Пример P_NOWAIT:

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

Пример P_WAIT:

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

17.1.4.5. Замена os.popen(), os.popen2(), os.popen3()¶Replacing os.popen(), os.popen2(), os.popen3()

pipe = os.popen("cmd", 'r', bufsize)
==>
pipe = Popen("cmd", shell=True, bufsize=bufsize, stdout=PIPE).stdout

pipe = os.popen("cmd", 'w', bufsize)
==>
pipe = Popen("cmd", shell=True, bufsize=bufsize, stdin=PIPE).stdin

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

В Unix os.popen2, os.popen3 и os.popen4 также принимают последовательность в качестве команды для выполнения; в этом случае аргументы будут переданы непосредственно программе без участия оболочки. Это использование можно заменить следующим образом:

(child_stdin, child_stdout) = os.popen2(["/bin/ls", "-l"], mode,
                                        bufsize)
==>
p = Popen(["/bin/ls", "-l"], bufsize=bufsize, stdin=PIPE, stdout=PIPE)
(child_stdin, child_stdout) = (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", shell=True, stdin=PIPE)
...
process.stdin.close()
if process.wait() != 0:
    print "There were some errors"

17.1.4.6. Замена функций из модуля popen2¶Replacing functions from the popen2 module

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

В Unix popen2 также принимает последовательность в качестве команды для выполнения; в этом случае аргументы будут переданы непосредственно программе без участия оболочки. Это использование можно заменить следующим образом:

(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 и popen2.Popen4 в основном работают как subprocess.Popen, за исключением того, что:

• Popen вызывает исключение, если выполнение завершается неудачей.

• аргумент capturestderr заменён аргументом stderr.

• stdin=PIPE и stdout=PIPE должны быть указаны.

• popen2 по умолчанию закрывает все файловые дескрипторы, но необходимо указать close_fds=True вместе с Popen.

17.1.5.1. Преобразование последовательности аргументов в строку в Windows¶Converting an argument sequence to a string on Windows

В Windows последовательность args преобразуется в строку, которая может быть разобрана с помощью следующих правил (которые соответствуют правилам, используемым в MS C runtime):

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

2. Строка, заключённая в двойные кавычки, интерпретируется как один аргумент, независимо от пробельных символов внутри неё. Строка в кавычках может быть встроена в аргумент.

3. Двойная кавычка, перед которой стоит обратная косая черта, интерпретируется как литеральная двойная кавычка.

4. Обратные косые черты интерпретируются буквально, если только они не стоят непосредственно перед двойной кавычкой.

5. Если обратные косые черты стоят непосредственно перед двойной кавычкой, каждая пара обратных косых черт интерпретируется как литеральная обратная косая черта. Если количество обратных косых черт нечётное, последняя обратная косая черта экранирует следующую за ней двойную кавычку, как описано в правиле 3.