Константы и флаги OS Windows модуля subprocess в Python.

Содержание:

• Константы используемые в помощнике Windows subprocess.STARTUPINFO :
  • Константа subprocess.STD_INPUT_HANDLE
  • Константа subprocess.STD_OUTPUT_HANDLE
  • Константа subprocess.STD_ERROR_HANDLE
  • Константа subprocess.SW_HIDE
  • Константа subprocess.STARTF_USESTDHANDLES
  • Константа subprocess.STARTF_USESHOWWINDOW
  • Константа subprocess.CREATE_NEW_CONSOLE
• Флаги устанавливаемые в качестве параметра creationflags при создании subprocess.Popen() :
  • Флаг subprocess.CREATE_NEW_PROCESS_GROUP
  • Флаг subprocess.ABOVE_NORMAL_PRIORITY_CLASS
  • Флаг subprocess.BELOW_NORMAL_PRIORITY_CLASS
  • Флаг subprocess.HIGH_PRIORITY_CLASS
  • Флаг subprocess.IDLE_PRIORITY_CLASS
  • Флаг subprocess.NORMAL_PRIORITY_CLASS
  • Флаг subprocess.REALTIME_PRIORITY_CLASS
  • Флаг subprocess.CREATE_NO_WINDOW
  • Флаг subprocess.DETACHED_PROCESS
  • Флаг subprocess.CREATE_DEFAULT_ERROR_MODE
  • Флаг subprocess.CREATE_BREAKAWAY_FROM_JOB

Константы используемые в помощнике Windows subprocess.STARTUPINFO .

subprocess.STD_INPUT_HANDLE :

Стандартное устройство ввода. Первоначально это консольный буфер ввода, CONIN$ .

subprocess.STD_OUTPUT_HANDLE :

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

subprocess.STD_ERROR_HANDLE :

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

subprocess.SW_HIDE :

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

subprocess.STARTF_USESTDHANDLES :

subprocess.STARTF_USESHOWWINDOW :

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

subprocess.CREATE_NEW_CONSOLE :

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

Флаги устанавливаемые в качестве параметра creationflags при создании subprocess.Popen() .

subprocess.CREATE_NEW_PROCESS_GROUP :

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

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

subprocess.ABOVE_NORMAL_PRIORITY_CLASS :

Прямой параметр аргумента creationflags указывающий, что новый процесс будет иметь приоритет выше среднего.

subprocess.BELOW_NORMAL_PRIORITY_CLASS :

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

subprocess.HIGH_PRIORITY_CLASS :

Прямой параметр аргумента creationflags указывающий, что новый процесс будет иметь высокий приоритет.

subprocess.IDLE_PRIORITY_CLASS :

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

subprocess.NORMAL_PRIORITY_CLASS :

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

subprocess.REALTIME_PRIORITY_CLASS :

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

Флаг subprocess.REALTIME_PRIORITY_CLASS почти никогда не нужно использовать, потому что это прерывает системные потоки, которые управляют вводом с клавиатуры, вводом с клавиатуры и фоновым сбросом диска.

Этот флаг может быть подходящим для приложений, которые «общаются» непосредственно с оборудованием или выполняют короткие задачи, которые должны иметь ограниченные перерывы.

subprocess.CREATE_NO_WINDOW :

Прямой параметр аргумента creationflags указывающий, что новый процесс не будет создавать окно.

subprocess.DETACHED_PROCESS :

Прямой параметр аргумента creationflags указывающий, что новый процесс не наследует консоль своего родителя. Это значение нельзя использовать с subprocess.CREATE_NEW_CONSOLE .

subprocess.CREATE_DEFAULT_ERROR_MODE :

Прямой параметр аргумента creationflags указывающий, что новый процесс не наследует режим ошибки вызывающего процесса. Вместо этого новый процесс получает режим ошибки по умолчанию.

Этот флаг особенно полезен для многопоточных приложений оболочки, которые работают с отключенными серьезными ошибками.

subprocess.CREATE_BREAKAWAY_FROM_JOB :

Прямой параметр аргумента creationflags указывающий, что новый процесс не связан с заданием.

Объект Popen модуля subprocess в Python.

Содержание:

• Проверка на завершение процесса Popen.poll() ,
• Ожидание завершения процесса Popen.wait() ,
• Взаимодействие с процессом Popen.communicate() ,
• Послать сигнал процессу Popen.send_signal() ,
• Остановить процесс Popen.terminate() ,
• Убить процесс Popen.kill() ,
• Вернуть имя программы со всеми параметрами Popen.args() ,
• Передать данные процессу Popen.stdin() ,
• Извлечь генерируемые данные процессом Popen.stdout() ,
• Извлечь ошибки процесса Popen.stderr() ,
• Посмотреть pid процесса Popen.pid() ,
• Посмотреть код, с которым завершился процесс [ Popen.returncode() .

Методы объекта Popen .

Popen.poll() :

Метод Popen.poll() проверяет, завершен ли дочерний процесс. Возвращает атрибут кода возврата Popen.returncode . В противном случае возвращает None .

Popen.wait(timeout=None) :

Метод Popen.wait() ждет завершения дочернего процесса. Возвращает атрибут кода возврата Popen.returncode .

Если процесс не завершается по истечении времени ожидания timeout , то вызывается исключение TimeoutExpired . Можно перехватить это исключение и повторить ожидание.

Примечание:

• Метод Popen.wait() приведет к взаимоблокировке при использовании stdout=subprocess.PIPE или stderr=subprocess.PIPE если дочерний процесс генерирует достаточно данных для канала. Метод блокирует ожидание буфера канала ОС для приема большего количества данных. Используйте метод Popen.communicate() при использовании каналов, чтобы избежать этого.
• Метод реализован с использованием цикла занятости (неблокирующий вызов и короткие спящие режимы). Используйте модуль asyncio для асинхронного ожидания.

Popen.communicate(input=None, timeout=None) :

Метод Popen.communicate() взаимодействует с процессом, отправляя данные в stdin и читает данные из stdout и stderr , пока не будет достигнут конец файла. Необязательным входным аргументом должны быть данные input , которые будут отправлены дочернему процессу или None , если никакие данные отправлять не требуется.

Если потоки были открыты в текстовом режиме (аргументы encoding или errors , или text=True , также известный как universal_newlines ), то ввод должен быть строкой. В противном случае это должна быть, например байтовая строка.

Метод Popen.communicate() возвращает кортеж (stdout_data, stderr_data) . Данные будут строками, если потоки были открыты в текстовом режиме, в противном случае байты.

Обратите внимание, что если необходимо отправить данные в процесс, то нужно создать вызвать subprocess.Popen() с аргументом stdin=subprocess.PIPE . Точно так же, чтобы получить что-то кроме None в кортеже результата, то также нужно указать stdout=subprocess.PIPE и/или stderr=subprocess.PIPE .

Если процесс не завершится по истечении времени ожидания timeout , будет сгенерировано исключение TimeoutExpired . Перехват этого исключения и повторное соединение не потеряет никакого вывода.

Если истекает время ожидания timeout , то дочерний процесс не уничтожается, поэтому для правильной очистки, приложение с хорошим поведением должно завершить дочерний процесс и завершить соединение:

Примечание:

• Считываемые данные буферизируются в памяти, поэтому не используйте этот метод, если размер данных большой или неограниченный. В этом случае пишите данные в лог-файл, пример смотрите в разделе «Часто используемые параметры модуля subprocess «.

Popen.send_signal(signal) :

Метод Popen.send_signal() посылает сигнал signal дочернему процессу.

Примечание:

• В Windows SIGTERM является псевдонимом Popen.terminate() . CTRL_C_EVENT и CTRL_BREAK_EVENT можно отправлять процессам, запущенным с параметром creationflags , который включает CREATE_NEW_PROCESS_GROUP .

Popen.terminate() :

Метод Popen.terminate() останавливает дочерний процесс.

• В ОС Unix метод отправляет SIGTERM дочернему процессу.
• В Windows вызывается Win32 API-функция TerminateProcess() .

Popen.kill() :

Метод Popen.kill() убивает дочерний процесс.

• В ОС Unix функция отправляет SIGKILL ребенку.
• В Windows метод Popen.kill() является псевдонимом Popen.terminate() .

Атрибуты объекта Popen .

Popen.args :

Атрибут Popen.args() возвращает аргумент args в том виде, как он был передан в subprocess.Popen() . Представляет из себя список аргументов программы или отдельная строка.

Popen.stdin :

Если аргумент stdin=subprocess.PIPE , то атрибут Popen.stdin() является записываемым объектом потока, возвращаемым функцией open() .

Если были заданы аргументы encoding или errors , или text=True (также известный как universal_newlines), то Popen.stdin() является текстовым потоком, в противном случае это поток байтов.

Если аргумент stdin не был равен subprocess.PIPE , то этот атрибут будет возвращать None .

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

• Используйте метод Popen.communicate() вместо методов Popen.stdin.write() , чтобы избежать взаимных блокировок из-за того, что другие буферы конвейера ОС заполняют и блокируют дочерний процесс.

Popen.stdout :

Если аргумент stdout=subprocess.PIPE , то атрибут Popen.stdout() является читаемым объектом потока, возвращаемым функцией open() . Чтение из потока stdout обеспечивает вывод генерируемых данных от дочернего процесса.

Если были заданы аргументы encoding или errors , или text=True (также известный как universal_newlines), то Popen.stdout() является текстовым потоком, в противном случае это поток байтов.

Если аргумент stdout не был равен subprocess.PIPE , то этот атрибут будет возвращать None .

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

• Используйте метод Popen.communicate() вместо метода Popen.stdout.read() , чтобы избежать взаимных блокировок из-за того, что другие буферы конвейера ОС заполняют и блокируют дочерний процесс.

Popen.stderr :

Если аргумент stderr=subprocess.PIPE , то атрибут Popen.stderr() является читаемым объектом потока, возвращаемым open (). Чтение из потока stderr обеспечивает вывод ошибок от дочернего процесса.

Если были заданы аргументы encoding или errors , или text=True (также известный как universal_newlines), то Popen.stderr() является текстовым потоком, в противном случае это поток байтов.

Если аргумент stderr не был равен subprocess.PIPE , то этот атрибут будет возвращать None .

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

• Используйте метод Popen.communicate() вместо метода Popen.stderr.read() , чтобы избежать взаимных блокировок из-за того, что другие буферы конвейера ОС заполняют и блокируют дочерний процесс.

Popen.pid :

Атрибут Popen.pid() возвращает идентификатор ID процесса дочернего процесса.

Обратите внимание, что если аргумент shell=True , то это идентификатор процесса порожденный оболочкой.

Popen.returncode :

Атрибут Popen.returncode() это код возврата дочернего процесса, установленный Popen.poll() и Popen.wait() и косвенно — Popen.communicate() . Значение None указывает, что процесс еще не завершен.

Отрицательное значение -N указывает на то, что дочерний элемент был прерван сигналом N . Справедливо только для Unix.

Класс Popen() модуля subprocess в Python.

Выполнить команду/программу в новом процессе из кода Python.

Синтаксис:

Параметры:

• args — список или строка, запускаемая программа с аргументами,
• bufsize=-1 — буферизация,
• executable=None — замещающая программа для выполнения,
• stdin=None — поток данных, отправляемых в процесс,
• stdout=None — поток вывода программы,
• stderr=None — поток ошибок программы,
• preexec_fn=None — пользовательская функция, выполняемая до запуска программы,
• close_fds=True — управляет файловыми дескрипторами,
• shell=False — True , если программа и ее аргументы представлены как одна строка,
• cwd=None — путь к рабочему каталогу запускаемой программы,
• env=None — переменные среды для нового процесса,
• universal_newlines=None — тоже, что и параметр text ,
• startupinfo=None — объект subprocess.STARTUPINFO ,
• creationflags=None — один или несколько констант Windows,
• restore_signals=True — сигналы восстанавливаются до SIG_DFL ,
• start_new_session=False — управляет системным вызов setsid() ,
• pass_fds=() — последовательность файловых дескрипторов,
• encoding=None — кодировка, если text=True ,
• errors=None — обработчик ошибок кодировки,
• text=None — текстовый режим для stdin , stdout и stderr .

Возвращаемое значение:

Описание:

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

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

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

По умолчанию в Unix, если args является строкой, то она интерпретируется как имя исполняемой программы или путь к ней БЕЗ аргументов.

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

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

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

В Unix с аргументом shell=True оболочкой по умолчанию является /bin/sh , при этом параметр args должен быть строкой, которая определяет команду со всеми ее аргументами для выполнения через эту оболочку. Это означает, что команда должна быть отформатирована точно так же, как при вводе в командной строке. Форматирование включает кавычки или обратную косую черту, экранирующие имена файлов с пробелами в них. Подробнее в разделе «Часто используемые параметры модуля subprocess «.

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

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

Аргумент bufsize будет передаваться в качестве соответствующего аргумента функции open() при создании файловых объектов stdin , stdout и stderr :

• 0 означает небуферизованный, чтение и запись являются одним системным вызовом и могут возвращать short .
• 1 означает строку с буферизацией, используется только если universal_newlines=True , т. е. в текстовом режиме.
• Любое другое положительное значение означает использование буфера примерно такого размера.
• Отрицательный bufsize (по умолчанию) означает, что будет использоваться системное значение по умолчанию io.DEFAULT_BUFFER_SIZE .

Аргумент executable указывает замещающую программу для выполнения. Это нужно очень редко. Когда параметр shell=False , то executable заменяет программу для выполнения, заданную в args . Тем не менее, оригинальные args все еще передаются в программу. В Unix, имя args становится отображаемым именем исполняемого файла в таких утилитах, как ps .

Если в Unix параметр shell=True , то аргумент executable должен указывать оболочку для замены по умолчанию /bin/sh , при этом параметр args должен быть строкой, которая определяет команду со всеми ее аргументами для выполнения через новую оболочку.

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

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

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

• Параметр preexec_fn небезопасен для использования при наличии потоков в приложении. Дочерний процесс может заблокироваться до вызова exec . Если все таки preexec_fn используется, то функция должна быть крайне простой и с минимальным количеством вызываемых библиотек.
• В Python-3.8 и выше параметр preexec_fn больше не поддерживается в субинтерпретаторах. Использование параметра в субинтерпретаторе вызывает исключение RuntimeError .

Примечание.

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

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

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

В Python-3.7 и выше в Windows значение по умолчанию для close_fds было изменено с False на True при перенаправлении стандартных дескрипторов.

Аргумент pass_fds — это необязательная последовательность файловых дескрипторов, которые остаются открытыми между родителем и потомком. Предоставление любого pass_fds заставляет close_fds быть True . Доступно только Unix.

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

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

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

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

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

Аргумент universal_newlines эквивалентен параметру text и предназначен для обратной совместимости. По умолчанию файловые объекты открываются в бинарном режиме.

Если задан аргумент startupinfo , то это будет объектом subprocess.STARTUPINFO , который передается в базовую функцию CreateProcess .

Если задан сreationflags , то он может быть одним или несколькими из констант Windows.

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