subprocess.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=None, startupinfo=None, creationflags=0, restore_signals=True, start_new_session=False, pass_fds=(), *, encoding=None, errors=None, text=None )

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

args должен быть последовательностью аргументов программы или отдельной строкой или объектом, подобным пути (path-like object ). По умолчанию программа для выполнения является первым элементом в args, если args является последовательностью. Если args является строкой, интерпретация зависит от платформы и описана ниже. См. аргументы shell и executable, чтобы узнать о дополнительных отличиях от поведения по умолчанию. Если не указано иное, рекомендуется передавать аргументы в виде последовательности.

Пример передачи некоторых аргументов внешней программе в виде последовательности:

Popen(["/usr/bin/git", "commit", "-m", "Fixes a bug."])

В 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) # Success!

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

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

Изменено в версии 3.6: параметр args принимает объект, подобный пути (path-like object ), если оболочка имеет значение False, и последовательность, содержащую объекты, подобные пути (path-like object ), в POSIX.

Изменено в версии 3.8: параметр args принимает объект, подобный пути (path-like object ), если оболочка имеет значение False, и последовательность, содержащую байты и объекты, подобные пути (path-like object ), в Windows.

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

В 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 pipe:

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

Изменено в версии 3.6: параметр executable принимает объект, подобный пути (path-like object ), в POSIX.

Изменено в версии 3.8: параметр executable принимает байты и объект, подобный пути (path-like object ) в Windows.

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 () в дочернем элементе.

Изменено в версии 3.8: параметр preexec_fn больше не поддерживается в субинтерпретаторах. Использование параметра в субинтерпретаторе вызывает ошибку RuntimeError. Новое ограничение может повлиять на приложения, развернутые в mod_wsgi, uWSGI и других встроенных средах.

Если close_fds равно True, все файловые дескрипторы, кроме 0, 1 и 2, будут закрыты до выполнения дочернего процесса. В противном случае, когда close_fds имеет значение False, файловые дескрипторы подчиняются своему наследуемому флагу, как описано в разделе «Наследование файловых дескрипторов».

В Windows, если close_fds имеет значение True, то дескрипторы не будут унаследованы дочерним процессом, если они явно не переданы в элементе handle_list файла STARTUPINFO.lpAttributeList или стандартным перенаправлением дескрипторов.

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

Изменено в версии 3.7: в Windows значение по умолчанию для close_fds было изменено с False на True при перенаправлении стандартных дескрипторов. Теперь можно установить close_fds в True при перенаправлении стандартных дескрипторов.

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

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

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

Изменено в версии 3.6: параметр cwd принимает объект, подобный пути (path-like object ), в POSIX.

Изменено в версии 3.7: параметр cwd принимает в Windows объект, похожий на путь (path-like object ).

Изменено в версии 3.8: параметр cwd принимает байтовый объект в Windows.

Если 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 для запуска параллельной сборки указанный env должен включать действительный SystemRoot.

Если указаны encoding или errors, либо text имеет значение True, файловые объекты stdin, stdout и stderr открываются в текстовом режиме с указанной encoding и errors, как описано выше в разделе «Часто используемые аргументы». Аргумент universal_newlines эквивалентен тексту и предоставляется для обратной совместимости. По умолчанию файловые объекты открываются в двоичном режиме.

Новое в версии 3.6: добавлены encoding и errors.

Новое в версии 3.7: text был добавлен как более читаемый псевдоним для universal_newlines.

Если задано, startupinfo будет объектом STARTUPINFO, который передается базовой функции CreateProcess. creationflags, если задан, может быть одним или несколькими из следующих флагов:

• CREATE_NEW_CONSOLE

• CREATE_NEW_PROCESS_GROUP

• ABOVE_NORMAL_PRIORITY_CLASS

• BELOW_NORMAL_PRIORITY_CLASS

• HIGH_PRIORITY_CLASS

• IDLE_PRIORITY_CLASS

• NORMAL_PRIORITY_CLASS

• REALTIME_PRIORITY_CLASS

• CREATE_NO_WINDOW

• DETACHED_PROCESS

• CREATE_DEFAULT_ERROR_MODE

• CREATE_BREAKAWAY_FROM_JOB

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

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

Popen и другие функции в этом модуле, которые его используют, вызывают события аудита subprocess.Popen с аргументами executable, args, cwd и env. Значение args может быть одной строкой или списком строк, в зависимости от платформы.

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

Изменено в версии 3.6: деструктор Popen теперь выдает предупреждение ResourceWarning, если дочерний процесс все еще выполняется.

Изменено в версии 3.8: Popen может использовать os.posix_spawn () в некоторых случаях для повышения производительности. В подсистеме Windows для Linux и пользовательской эмуляции QEMU конструктор Popen, использующий os.posix_spawn (), больше не генерирует исключение при таких ошибках, как отсутствие программы, но дочерний процесс завершается с ошибкой с ненулевым кодом возврата.