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.

Эти параметры, как и все остальные, более подробно описаны в документации конструктора 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=())¶

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

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

На POSIX, если 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 в виде строки, а не последовательности.

На POSIX с 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 означает буферизацию по строкам (работает только если universal_newlines=True, т.е. в текстовом режиме)
• любое другое положительное значение означает использование буфера примерно такого размера
• отрицательное значение 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, как имя команды, которое может отличаться от реально выполняемой программы. В POSIX имя args становится отображаемым именем исполняемого файла в утилитах вроде ps. Если shell=True, то в POSIX аргумент executable задаёт заменяющую оболочку вместо стандартной /bin/sh.

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

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

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

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

Примечание

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

Если close_fds равно true, все файловые дескрипторы, кроме 0, 1 и 2, будут закрыты перед выполнением дочернего процесса (только POSIX). Значение по умолчанию зависит от платформы: на POSIX всегда 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 (только POSIX).

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

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

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

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

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

Изменено в версии 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.4.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¶

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

subprocess.CREATE_NEW_PROCESS_GROUP¶

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

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

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

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

17.5.5.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.5.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.5.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.5.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, stdin=PIPE)
...
process.stdin.close()
if process.wait() != 0:
    print("There were some errors")

17.5.5.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.7.1. Преобразование последовательности аргументов в строку в Windows¶Converting an argument sequence to a string on Windows

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

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