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, чтобы узнать о дополнительных отличиях от поведения по умолчанию. Если не указано иное, рекомендуется передавать аргументы в виде последовательности.
Пример передачи некоторых аргументов внешней программе в виде последовательности:
В POSIX, если args является строкой, строка интерпретируется как имя или путь выполняемой программы. Однако это можно сделать, только если не передать аргументы программе.
Примечание: Может быть неочевидно, как разбить команду оболочки на последовательность аргументов, особенно в сложных случаях. shlex.split ()
может проиллюстрировать, как определить правильную токенизацию для args:
Обратите внимание, в частности, что параметры (такие как -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 выполняет эквивалент:
В 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: при выходе стандартные файловые дескрипторы закрываются, и процесс ожидает.
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 (), больше не генерирует исключение при таких ошибках, как отсутствие программы, но дочерний процесс завершается с ошибкой с ненулевым кодом возврата.
Last updated