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

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

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

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

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

Если universal_newlines равен False, файловые объекты stdin, stdout и stderr открываются как бинарные потоки, и преобразование концов строк не выполняется.

Если universal_newlines равен True, эти файловые объекты открываются как текстовые потоки в режиме universal newlines с использованием кодировки, возвращаемой locale.getpreferredencoding(False). Для stdin символы конца строки '\n' во входных данных преобразуются в разделитель строк по умолчанию os.linesep. Для stdout и stderr все концы строк в выводе преобразуются в '\n'. Дополнительную информацию см. в документации класса io.TextIOWrapper, когда аргумент newline его конструктора равен None.

Примечание

Атрибут newlines файловых объектов Popen.stdin, Popen.stdout и Popen.stderr не обновляется методом Popen.communicate().

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

Изменено в версии 3.3: Когда universal_newlines равен True, класс использует кодировку locale.getpreferredencoding(False) вместо locale.getpreferredencoding(). Подробнее об этом изменении см. в документации класса io.TextIOWrapper.

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

Выполнение команд оболочки, содержащих непроверенные входные данные из недоверенного источника, делает программу уязвимой к внедрению в оболочку – серьёзной уязвимости безопасности, которая может привести к выполнению произвольных команд. По этой причине использование 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 отключает все функции на основе оболочки, но не подвержен этой уязвимости; обратитесь к примечанию в документации конструктора Popen за полезными советами по настройке shell=False.

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

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

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

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

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=False, startupinfo=None, creationflags=0, restore_signals=True, start_new_session=False, pass_fds=())¶

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

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

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

Примечание

shlex.split() может быть полезен при определении правильной токенизации 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) # Успешно!

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

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

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

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

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

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

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

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

bufsize будет передан как соответствующий аргумент функции open() при создании файловых объектов каналов stdin/stdout/stderr: 0 означает отсутствие буферизации (чтение и запись – один системный вызов, может вернуть меньше данных), 1 означает построчную буферизацию, любое другое положительное значение означает использование буфера приблизительно этого размера. Отрицательное значение bufsize (по умолчанию) означает, что будет использоваться системное значение по умолчанию io.DEFAULT_BUFFER_SIZE.

Изменено в версии 3.3.1: bufsize теперь по умолчанию равен -1, чтобы включить буферизацию по умолчанию, как того ожидает большинство кода. В версиях до Python 3.2.4 и 3.3.1 по умолчанию ошибочно использовалось 0, что означало отсутствие буферизации и допускало короткие чтения. Это было непреднамеренно и не соответствовало поведению Python 2, как ожидал большинство кода.

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

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

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

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

Параметр preexec_fn небезопасно использовать при наличии потоков в приложении. Дочерний процесс может зависнуть до вызова exec. Если его всё же нужно использовать, пусть он будет тривиальным! Сведите к минимуму количество вызываемых библиотек.

Примечание

Если нужно изменить окружение для дочернего процесса, используйте параметр env вместо изменения в preexec_fn. Параметр start_new_session может заменить ранее распространённое использование preexec_fn для вызова os.setsid() в дочернем процессе.

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

Изменено в версии 3.2: Значение по умолчанию для close_fds было изменено с False на описанное выше.

pass_fds – это необязательная последовательность файловых дескрипторов, которые должны оставаться открытыми между родительским и дочерним процессами. Если задан любой pass_fds, то close_fds принудительно устанавливается в True. (Только Unix)

Новое в версии 3.2: Добавлен параметр pass_fds.

Если cwd не равен None, функция меняет рабочий каталог на cwd перед выполнением дочернего процесса. В частности, функция ищет executable (или первый элемент в args) относительно cwd, если путь к исполняемому файлу является относительным.

Если restore_signals имеет значение true (по умолчанию), все сигналы, которые Python установил в SIG_IGN, восстанавливаются до SIG_DFL в дочернем процессе перед exec. В настоящее время это включает сигналы SIGPIPE, SIGXFZ и SIGXFSZ. (Только Unix)

Изменено в версии 3.2: Добавлен restore_signals.

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

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

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

Примечание

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

Если universal_newlines равен True, файловые объекты stdin, stdout и stderr открываются как текстовые потоки в режиме универсальных новых строк, как описано выше в разделе Часто используемые аргументы; в противном случае они открываются как двоичные потоки.

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

Объекты Popen поддерживаются в качестве контекстных менеджеров с помощью оператора with: при выходе стандартные файловые дескрипторы закрываются, и выполняется ожидание завершения процесса.

with Popen(["ifconfig"], stdout=PIPE) as proc:
    log.write(proc.stdout.read())

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

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

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

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

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

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

Все функции и методы, принимающие параметр timeout, такие как call() и Popen.communicate(), возбудят TimeoutExpired, если время ожидания истечёт до выхода процесса.

Все исключения, определённые в этом модуле, наследуются от SubprocessError.

Новое в версии 3.3: Был добавлен базовый класс SubprocessError.

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

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

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

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

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¶

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

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

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

output=`mycmd myarg`
# becomes
output = check_output(["mycmd", "myarg"])

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

output=`dmesg | grep hda`
# becomes
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]

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

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

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

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

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)

17.5.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.5.4.5. Замена os.popen(), os.popen2(), os.popen3()¶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)

Обработка кода возврата выполняется следующим образом:

pipe = os.popen(cmd, 'w')
...
rc = pipe.close()
if rc is not None and rc >> 8:
    print("There were some errors")
==>
process = Popen(cmd, 'w', stdin=PIPE)
...
process.stdin.close()
if process.wait() != 0:
    print("There were some errors")

17.5.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)

(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 по умолчанию закрывает все файловые дескрипторы, но для гарантии такого поведения на всех платформах или в старых версиях Python необходимо указать close_fds=True вместе с Popen.

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

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

1. Аргументы разделяются пробельными символами, то есть пробелом или табуляцией.
2. Строка, заключённая в двойные кавычки, интерпретируется как один аргумент, независимо от пробельных символов внутри неё. Строка в кавычках может быть встроена в аргумент.
3. Двойная кавычка, перед которой стоит обратная косая черта, интерпретируется как литеральная двойная кавычка.
4. Обратные косые черты интерпретируются буквально, если только они не стоят непосредственно перед двойной кавычкой.
5. Если обратные косые черты стоят непосредственно перед двойной кавычкой, каждая пара обратных косых черт интерпретируется как литеральная обратная косая черта. Если количество обратных косых черт нечётное, последняя обратная косая черта экранирует следующую за ней двойную кавычку, как описано в правиле 3.