17.1. subprocess – Управление подпроцессами¶subprocess – Subprocess management

17.1.1. Использование модуля подпроцесс¶Using the subprocess Module

Этот модуль определяет один класс с именем Popen:

class subprocess.Popen(args, bufsize=0, executable=None, stdin=None, stdout=None, stderr=None, preexec_fn=None, close_fds=False, shell=False, cwd=None, env=None, universal_newlines=False, startupinfo=None, creationflags=0)¶

Аргументы:

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

В Unix с shell=False (по умолчанию): в этом случае класс Popen использует os.execvp() для выполнения дочерней программы. args обычно должен быть последовательностью. Если для 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, показанная выше), являются отдельными элементами списка.

В Unix с shell=True: если args – строка, она задает командную строку для выполнения через оболочку. Это означает, что строка должна быть отформатирована точно так же, как если бы она вводилась в приглашении оболочки. Это включает, например, кавычки или экранирование обратной косой чертой имен файлов с пробелами. Если args – последовательность, первый элемент задает командную строку, а любые дополнительные элементы будут рассматриваться как дополнительные аргументы для самой оболочки. Иными словами, Popen делает эквивалент:

Popen(['/bin/sh', '-c', args[0], args[1], ...])

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

Выполнение команд оболочки, содержащих непроверенные входные данные из ненадёжного источника, делает программу уязвимой для внедрения команд оболочки – серьёзной уязвимости безопасности, которая может привести к выполнению произвольных команд. По этой причине использование shell=True настоятельно не рекомендуется в тех случаях, когда командная строка формируется из внешних данных:

>>> from subprocess import call
>>> filename = input("What file would you like to display?\n")
What file would you like to display?
non_existent; rm -rf / #
>>> call("cat " + filename, shell=True) # Ой-ой. Это плохо кончится...

shell=False не подвержен этой уязвимости; приведённое выше примечание может помочь в настройке кода, использующего shell=False.

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

bufsize, если задан, имеет тот же смысл, что и соответствующий аргумент встроенной функции open(): 0 – без буферизации, 1 – построчная буферизация, любое другое положительное значение означает использование буфера (примерно) такого размера. Отрицательное bufsize означает использование системного значения по умолчанию, что обычно означает полную буферизацию. Значение по умолчанию для bufsize – 0 (без буферизации).

Примечание

Если возникают проблемы с производительностью, рекомендуется попробовать включить буферизацию, установив bufsize в -1 или достаточно большое положительное значение (например, 4096).

Аргумент executable задаёт программу для выполнения. Он требуется очень редко: обычно выполняемая программа определяется аргументом args. Если shell=True, аргумент executable указывает, какую оболочку использовать. В Unix оболочкой по умолчанию является /bin/sh. В Windows оболочка по умолчанию задаётся переменной окружения COMSPEC. Единственная причина, по которой может потребоваться указать shell=True в Windows – это если команда, которую требуется выполнить, встроена в оболочку, например dir, copy. Для запуска пакетного файла или консольного исполняемого файла shell=True не требуется.

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

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

Если close_fds равен true, все файловые дескрипторы, кроме 0, 1 и 2, будут закрыты перед выполнением дочернего процесса. (Только Unix). Или, в Windows, если close_fds равен true, то дочерний процесс не унаследует ни одного дескриптора. Обратите внимание: в Windows нельзя одновременно установить close_fds в true и перенаправлять стандартные дескрипторы с помощью stdin, stdout или stderr.

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

Если cwd не равен None, текущий каталог дочернего процесса будет изменён на cwd перед его выполнением. Обратите внимание, что этот каталог не учитывается при поиске исполняемого файла, поэтому нельзя указать путь к программе относительно cwd.

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

Примечание

Если задан, env должен предоставлять все переменные, необходимые для выполнения программы. В Windows для запуска компонента side-by-side указанный env обязан содержать допустимый SystemRoot.

Если universal_newlines равен True, файловые объекты stdout и stderr открываются как текстовые файлы, но строки могут завершаться любым из символов: '\n' (соглашение Unix), '\r' (соглашение старых Macintosh) или '\r\n' (соглашение Windows). Все эти внешние представления воспринимаются программой Python как '\n'.

Примечание

Эта возможность доступна только если Python собран с поддержкой универсальных символов новой строки (по умолчанию). Кроме того, атрибут newlines файловых объектов stdout, stdin и stderr не обновляется методом communicate().

Если задан, startupinfo будет объектом STARTUPINFO, который передаётся базовой функции CreateProcess. creationflags, если задан, может быть CREATE_NEW_CONSOLE. (Только Windows)

subprocess.PIPE¶

Специальное значение, которое может использоваться в качестве аргумента stdin, stdout или stderr для Popen и указывает, что должен быть открыт канал к стандартному потоку.

subprocess.STDOUT¶

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

17.1.2. Объекты Popen¶Popen Objects

Экземпляры класса Popen имеют следующие методы:

Popen.poll()¶

Проверяет, завершён ли дочерний процесс. Устанавливает и возвращает атрибут returncode.

Popen.wait()¶

Ожидает завершения дочернего процесса. Устанавливает и возвращает атрибут returncode.

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

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

Popen.communicate(input=None)¶

Взаимодействие с процессом: отправляет данные в stdin. Читает данные из stdout и stderr до достижения конца файла. Ожидает завершения процесса. Необязательный аргумент input должен быть байтовой строкой для отправки дочернему процессу, или None, если данные не должны отправляться.

communicate() возвращает кортеж (stdoutdata, stderrdata).

Обратите внимание: для отправки данных в stdin процесса объект Popen должен быть создан с stdin=PIPE. Аналогично, чтобы получить в результирующем кортеже что-либо, кроме None, нужно также указать stdout=PIPE и/или stderr=PIPE.

Примечание

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

Popen.send_signal(signal)¶

Отправляет сигнал signal дочернему процессу.

Примечание

В Windows на данный момент поддерживается только SIGTERM. Это псевдоним для terminate().

Popen.terminate()¶

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

Popen.kill()¶

Завершает дочерний процесс. В ОС POSIX функция отправляет дочернему процессу сигнал SIGKILL. В Windows kill() – это псевдоним для terminate().

Также доступны следующие атрибуты:

Popen.stdin¶

Если аргумент stdin был равен PIPE, то этот атрибут представляет собой файловый объект, который передаёт входные данные дочернему процессу. В противном случае он равен None.

Popen.stdout¶

Если аргумент stdout был равен PIPE, то этот атрибут представляет собой файловый объект, который возвращает выходные данные дочернего процесса. В противном случае он равен None.

Popen.stderr¶

Если аргумент stderr был равен PIPE, то этот атрибут представляет собой файловый объект, который возвращает сообщения об ошибках дочернего процесса. В противном случае он равен None.

Popen.pid¶

PID дочернего процесса.

Обратите внимание: если установить аргумент shell в значение True, то это будет идентификатор процесса запущенной оболочки.

Popen.returncode¶

Код возврата дочернего процесса, устанавливаемый методами poll() и wait() (а косвенно и communicate()). Значение None указывает, что процесс ещё не завершён.

Отрицательное значение -N означает, что дочерний процесс был завершён сигналом N (только в Unix).

17.1.3. Вспомогательные средства Popen для Windows¶Windows Popen Helpers

Класс STARTUPINFO и следующие константы доступны только в Windows.

class subprocess.STARTUPINFO¶

Частичная поддержка структуры Windows STARTUPINFO используется при создании Popen.

dwFlags¶

Битовое поле, определяющее, используются ли определённые члены STARTUPINFO при создании окна процессом.

si = subprocess.STARTUPINFO()
si.dwFlags = subprocess.STARTF_USESTDHANDLES | subprocess.STARTF_USESHOWWINDOW

hStdInput¶

Если dwFlags указывает STARTF_USESTDHANDLES, этот член является дескриптором стандартного ввода для процесса. Если STARTF_USESTDHANDLES не указан, по умолчанию для стандартного ввода используется буфер клавиатуры.

hStdOutput¶

Если dwFlags указывает STARTF_USESTDHANDLES, этот член является дескриптором стандартного вывода для процесса. В противном случае этот член игнорируется, и по умолчанию для стандартного вывода используется буфер окна консоли.

hStdError¶

Если dwFlags указывает STARTF_USESTDHANDLES, этот член является дескриптором стандартного вывода ошибок для процесса. В противном случае этот член игнорируется, и по умолчанию для стандартного вывода ошибок используется буфер окна консоли.

wShowWindow¶

Если dwFlags указывает STARTF_USESHOWWINDOW, этот член может принимать любое из значений, которые можно указать в параметре nCmdShow для функции ShowWindow, за исключением SW_SHOWDEFAULT. В противном случае этот член игнорируется.

Для этого атрибута предусмотрено значение SW_HIDE. Оно используется, когда Popen вызывается с параметром shell=True.

17.1.4. Замена старых функций модулем подпроцесс¶Replacing Older Functions with the subprocess Module

В этом разделе «a ==> b» означает, что b можно использовать как замену a.

В следующих примерах предполагается, что модуль подпроцесс импортирован с помощью «from subprocess import *».

output=`mycmd myarg`
==>
output = Popen(["mycmd", "myarg"], stdout=PIPE).communicate()[0]

output=`dmesg | grep hda`
==>
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]

sts = os.system("mycmd" + " myarg")
==>
p = Popen("mycmd" + " myarg", shell=True)
sts = os.waitpid(p.pid, 0)[1]

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)

pid = os.spawnlp(os.P_NOWAIT, "/bin/mycmd", "mycmd", "myarg")
==>
pid = Popen(["/bin/mycmd", "myarg"]).pid

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"})

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

(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)

17.1.5. Примечания¶Notes