Модуль subprocess

Модуль subprocess отвечает за выполнение следующих действий: порождение новых процессов, соединение c потоками стандартного ввода, стандартного вывода, стандартного вывода сообщений об ошибках и получение кодов возврата от этих процессов.

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

subprocess.call(args, *, stdin=None, stdout=None, stderr=None, shell=False, timeout=None) — выполняет команду, описанную args. Ожидает завершения команды, а затем возвращает код возврата.

Аргументы, приведенные выше, являются лишь наиболее распространенными из них. Полная сигнатура функция в значительной степени такая же, как конструктор Popen. Аргумент timeout передается Popen.wait(). Если тайм-аут истекает, дочерний процесс будет убит, а затем будет поднято исключение TimeoutExpired.

subprocess.check_call(args, *, stdin=None, stdout=None, stderr=None, shell=False, timeout=None) — выполняет команду, описанную args. Ожидает завершения команды, а затем завершается, если код возврата 0, или поднимает исключение CalledProcessError, объект которого возвращает код завершения атрибутом returncode.

subprocess.check_output(args, *, input=None, stdin=None, stderr=None, shell=False, universal_newlines=False, timeout=None) — выполняет команду и возвращает её вывод. Поднимает исключение CalledProcessError, если код возврата ненулевой.

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

subprocess.DEVNULL — значение, которое может использоваться в качестве аргумента stdin, stdout или stderr. Означает, что будет использован специальный файл devnull.

subprocess.PIPE — значение, которое может использоваться в качестве аргумента stdin, stdout или stderr. Означает, что для дочернего процесса будет создан пайп.

subprocess.STDOUT — значение, которое может использоваться в качестве аргумента stderr. Означает, что поток ошибок будет перенаправлен в поток вывода.

Класс 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=()) — Выполняет программу в новом процессе. args – строка или последовательность аргументов программы. Обычно первым указывают исполняемую программу, а затем аргументы, но также ее можно указать в параметре executable.

Также Popen поддерживает менеджеры контекста:

Методы класса Popen:

Popen.poll() — если процесс завершил работу — вернёт код возврата, в ином случае None.

Popen.wait(timeout=None) — ожидает завершения работы процесса и возвращает код возврата. Если в течение timeout процесс не завершился, поднимется исключение TimeoutExpired (которое можно перехватить, после чего сделать ещё раз wait).

Popen.communicate(input=None, timeout=None) — взаимодействовует с процессом: посылает данные, содержащиеся в input в stdin процесса, ожидает завершения работы процесса, возвращает кортеж данных потока вывода и ошибок. При этом в Popen необходимо задать значение PIPE для stdin (если вы хотите посылать в stdin), stdout, stderr (если вы хотите прочитать вывод дочернего процесса).

Если в течение timeout процесс не завершился, поднимется исключение TimeoutExpired (которое можно перехватить, после чего сделать ещё раз communicate, либо убить дочерний процесс).

Функция run() модуля subprocess в Python.

Запустить команду/программу с аргументами из кода Python.

Синтаксис:

Параметры:

Аргументы функции, за исключением обязательного args — являются не обязательны и следовательно задаются только ключевыми словами.

• args — запускаемая программа с аргументами,
• stdin=None — поток данных, отправляемых в процесс,
• input=None — поток данных, отправляемых в процесс,
• stdout=None — поток вывода программы,
• stderr=None — поток ошибок программы,
• capture_output=False — захват вывода stdout и stderr ,
• shell=False — используйте True , если программа и ее аргументы представлены как одна строка,
• cwd=None — путь к рабочему каталогу запускаемой программы,
• timeout=None — максимально-допустимое время выполнения запущенной программы,
• check=False — вызывает исключение при завершении запущенной программы с ошибками,
• encoding=None — кодировка, если input — строка,
• errors=None — обработчик ошибок кодировки,
• text=None — текстовый режим для stdin , stdout и stderr ,
• env=None — переменные среды для нового процесса,
• universal_newlines=None — тоже, что и параметр text .

Ключевые аргументы этой функции это лишь наиболее распространенные параметры, правила использования которых описанными в разделе «Часто используемые аргументы».

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

• экземпляр CompletedProcess() с результатами работы.

Описание:

Функция run() модуля subprocess запускает команду/скрипт/программу с аргументами, ждет завершения команды, а затем возвращает экземпляр CompletedProcess() с результатами работы.

Полная сигнатура функции subprocess.run() в значительной степени совпадает с сигнатурой конструктора subprocess.Popen() , a большинство аргументов этой функции передаются в интерфейс последней кроме параметров timeout , input , check и capture_output .

Если аргумент capture_output () имеет значение True , то вывод stdout и stderr будут захвачены. При использовании, внутренний объект subprocess.Popen() автоматически создается с stdout=subprocess.PIPE и stderr=subprocess.PIPE . Аргументы stdout и stderr не могут быть предоставлены одновременно с capture_output . Если необходимо захватить и объединить оба потока в один, то используйте stdout=subprocess.PIPE и stderr=subprocess.STDOUT вместо capture_output=True .

Аргумент timeout передается в subprocess.Popen.communicate() . Если тайм-аут истекает, то дочерний процесс, в котором запущена программа будет принудительно остановлен и ожидание завершения процесса прекращается. Исключение subprocess.TimeoutExpired будет повторно вызвано после завершения дочернего процесса.

Аргумент input передается в subprocess.Popen.communicate() и следовательно в стандартный поток дочернего процесса. Если он используется, то это должна быть последовательность байтов или строка — если задана кодировка encoding и errors или аргумент text имеет значение True . При использовании аргумента input , внутренний объект subprocess.Popen автоматически создается с помощью значения аргумента stdin=subprocess.PIPE при этом сам аргумент stdin может не указываться.

Если аргумент check=True и процесс завершается с ненулевым кодом выхода, то будет вызвано исключение subprocess.CalledProcessError . Атрибуты этого исключения содержат аргументы запуска программы, код ее выхода, а так же stdout и stderr , если они были захвачены.

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

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

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

Примеры исполнения команд/программ из кода в Python.

Чтобы вызывать команды, в которых используются wildcard-выражения *tpl , нужно добавлять аргумент shell .

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

Если команда была выполнена с ошибкой или не отработала корректно, вывод команды попадет на стандартный поток ошибок.

Получить этот вывод можно так же, как и стандартный поток вывода:

Функция ping() проверяет доступность адреса address и возвращает stdout , если адрес доступен или stderr , если адрес недоступен.

Класс Process() модуля multiprocessing в Python.

Создание отдельного процесса, запуск задачи и получение результата выполнения.

Синтаксис:

Параметры:

Конструктор всегда следует вызывать с ключевыми аргументами.

• group=None — не используется модулем,
• target=None — вызываемый объект (функция),
• name=None — имя процесса,
• args=() — аргументы для target ,
• kwargs=<> — ключевые аргументы для target ,
• daemon=None — флаг для демонизации процесса.

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

Описание:

Класс Process() модуля multiprocessing запускает вызываемый объект target на исполнение, который будет выполняется в отдельном процессе/ядре процессора.

Есть два способа запустить какое либо действие:

• Передать вызываемый объект (функцию) target в конструктор.
• Переопределить метод Process.run() в подклассе.

Внимание! Никакие другие методы не должны переопределяться в подклассе (кроме конструктора). Другими словами, можно переопределять только методы __init__() и Process.run() этого класса.

Объект Process имеет эквиваленты всех методов объекта Thread() .

Аргумент group всегда должна быть None ; он существует исключительно для совместимости с классом threading.Thread() .

Аргумент target — это вызываемый объект, который будет вызываться методом Process.run() . По умолчанию это None , что означает, что ничего не вызывается. По умолчанию в вызываемый объект target не передаются его аргументы.

Аргумент name — это имя процесса, подробнее смотрите атрибут Process.name .

Аргумент args — это кортеж аргументов для целевого вызова target . Аргумент kwargs — это словарь ключевых аргументов для целевого вызова target .

Если предоставлен ключевой аргумент daemon , то он устанавливает флаг демона процесса значение True или False . Если daemon=None (по умолчанию), этот флаг будет унаследован от процесса создателя.

Если подкласс переопределяет конструктор класса multiprocessing.Process() , то необходимо вызывать конструктор базового класса Process.__init__() , прежде чем делать что-либо еще с процессом.

Обратите внимание, что методы Process.start() , Process.join() , Process.is_alive() , Process.terminate() и Process.exitcode должны вызываться только процессом, создавшим этот объект процесса.

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

Объекты Process представляют собой действия, которые выполняются в отдельном процессе.

Process.run() :

Метод Process.run() представляет активность процесса.

Можно переопределить этот метод в своем подклассе. Стандартный метод Process.run() вызывает вызываемый объект, переданный конструктору в качестве целевого аргумента target , с позиционными и ключевыми аргументами, взятыми из аргументов args и kwargs соответственно.

Метод Thread.run() можно переопределить в пользовательском подклассе. Например:

Process.start() :

Метод Process.start() запускает экземпляр Process в отдельном процессе/ядре процессора.

Этот метод должен быть вызван не более одного раза для каждого объекта процесса. Он организует вызов метода Process.run() объекта в отдельном процессе/ядре процессора.

Дополнительно, смотрите описание этого метода у объекта Thread , примеры кода аналогичны.

Process.join([timeout]) :

Метод Process.join() ждет, пока не завершится процесс.

Если необязательный аргумент timeout=None (по умолчанию), то процесс, из которого вызван этот метод, блокируется до тех пор, пока не завершится процесс, у которого вызван этот метод. Проще говоря, если вызвать метод Process.join() для создаваемых процессов из основного процесса программы, то дальнейшее выполнение программы будет заблокировано, пока созданные процессы не завершаться.

Если тайм-аут timeout является положительным числом, то процесс блокируется не более чем на величину секунд, указанную в timeout . Обратите внимание, что метод возвращает None , если его процесс завершается или если время ожидания метода истекает. Проверьте код выхода процесса Process.exitcode , чтобы определить, завершился ли он.

К процессу можно присоединяться много раз.

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

Дополнительно, смотрите описание этого метода у объекта Thread , примеры кода аналогичны.

Process.name :

Атрибут Process.name это имя процесса и представляет собой строку, которая используется только для идентификации. У имени нет семантики.

Несколько процессов могут иметь одно и то же имя (можно присваивать).

Начальное имя задается конструктором класса. Если в конструктор не передан аргумент name , то имена порожденных процессов будет выглядеть как «Process-N1:N2. Nk», где каждый Nk является N-м потомком своего родителя.

Дополнительно, смотрите описание этого метода у объекта Thread , примеры кода аналогичны.

Process.is_alive() :

Метод Process.is_alive() проверяет, является ли процесс живым.

Грубо говоря, объект процесса является живым с момента вызова метода Process.start() и до завершения порожденного дочернего процесса.

Process.daemon :

Атрибут Process.daemon флаг демона процесса, логическое значение. Этот атрибут должен быть установлен перед вызовом метода Process.start() .

Начальное значение наследуется от процесса создателя.

Когда процесс завершается, он пытается завершить все свои демонические дочерние процессы.

Обратите внимание, что демоническому процессу не разрешается создавать дочерние процессы. Так как если демонический процесс будет прерван выходом из родительского процесса, то демонический процесс оставил бы свои дочерние процессы «сиротами«. Кроме того, это не демоны или службы Unix, это обычные процессы, которые будут завершены (но не присоединены), если завершились не-демонические процессы.

Process.pid :

Атрибут Process.pid возвращает идентификатор процесса. До того, как процесс будет порожден, это будет None .

Process.exitcode :

Атрибут Process.exitcode возвращает код выхода порожденного процесса. Значение будет None , если процесс еще не завершен.

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

Process.authkey :

Атрибут Process.authkey ключ аутентификации процесса, представляет из себя байтовую строку.

При инициализации модуля multiprocessing , основному процессу присваивается случайная строка с помощью os.urandom() .

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

Process.sentinel :

Атрибут Process.sentinel числовой дескриптор системного объекта, который станет «готовым» по завершении процесса.

Можно использовать это значение, если необходимо дождаться нескольких событий одновременно, используя multiprocessing.connection.wait() . Вообще это проще сделать вызвав метод Process.join() у каждого из создаваемых процессов, результатов которых надо дождаться.

В Windows это дескриптор ОС, который можно использовать с семейством вызовов API WaitForSingleObject и WaitForMultipleObjects . В Unix это файловый дескриптор, который можно использовать с примитивами из модуля select .

Process.terminate() :

Метод Process.terminate() завершает процесс. В Unix это делается с помощью сигнала SIGTERM , в Windows используется TerminateProcess() .

Обратите внимание, что обработчики выхода, предложения tru/finally и т. д. не будут выполняться.