subprocess — Управление подпроцессами

Исходный код: Lib/subprocess.py

Модуль subprocess позволяет запускать новые процессы, подключаться к их каналам ввода/вывода/ошибок и получать их коды возврата. Этот модуль призван заменить несколько более старых модулей и функций:

os.system
os.spawn*

Информацию о том, как модуль subprocess можно использовать для замены этих модулей и функций, можно найти в следующих разделах.

См. также

PEP 324 — PEP с предложением добавить модуль subprocess

Доступность: недоступен в Emscripten и WASI.

Этот модуль не работает или недоступен на платформах WebAssembly wasm32-emscripten и wasm32-wasi. Дополнительную информацию см. в разделе Платформы WebAssembly.

Использование модуля subprocess

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

subprocess.run(args, *, stdin=None, input=None, stdout=None, stderr=None, capture_output=False, shell=False, cwd=None, timeout=None, check=False, encoding=None, errors=None, text=None, env=None, universal_newlines=None, **other_popen_kwargs)

Запускает команду, заданную аргументом args. Ожидает завершения команды, затем возвращает экземпляр CompletedProcess.

Показанные выше аргументы — лишь наиболее распространённые, описанные ниже в разделе Часто используемые аргументы (отсюда использование обозначения только именованных аргументов в сокращённой сигнатуре). Полная сигнатура функции в основном совпадает с сигнатурой конструктора Popen — большинство аргументов этой функции передаются в этот интерфейс. (timeout, input, check и capture_output не передаются.)

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

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

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

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

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

Если значение env не равно None, оно должно быть отображением, задающим переменные окружения для нового процесса; они используются вместо поведения по умолчанию, при котором наследуется окружение текущего процесса. Оно передаётся непосредственно в Popen. Это отображение может содержать пары str и str на любой платформе или bytes и bytes на платформах POSIX, подобно os.environ или os.environb.

Примеры:

>>> subprocess.run(["ls", "-l"])  # doesn't capture output
CompletedProcess(args=['ls', '-l'], returncode=0)

>>> subprocess.run("exit 1", shell=True, check=True)
Traceback (most recent call last):
  ...
subprocess.CalledProcessError: Command 'exit 1' returned non-zero exit status 1

>>> subprocess.run(["ls", "-l", "/dev/null"], capture_output=True)
CompletedProcess(args=['ls', '-l', '/dev/null'], returncode=0,
stdout=b'crw-rw-rw- 1 root root 1, 3 Jan 23 16:23 /dev/null\n', stderr=b'')

Добавлено в версии 3.5.

Изменено в версии 3.6: Добавлены параметры encoding и errors

Изменено в версии 3.7: Добавлен параметр text как более понятный псевдоним universal_newlines. Добавлен параметр capture_output.

Изменено в версии 3.12: Изменён порядок поиска оболочки в Windows для shell=True. Текущий каталог и %PATH% заменены на %COMSPEC% и %SystemRoot%\System32\cmd.exe. В результате размещение вредоносной программы с именем cmd.exe в текущем каталоге больше не работает.

class subprocess.CompletedProcess

Возвращаемое значение run(), представляющее завершившийся процесс.

args: Аргументы, использованные для запуска процесса. Это может быть список или строка.

returncode

Статус завершения дочернего процесса. Обычно статус завершения 0 означает, что процесс выполнился успешно.

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

stdout

Захваченный stdout дочернего процесса. Последовательность байтов или строка, если run() была вызвана с параметром encoding, errors или text=True. None, если stdout не был захвачен.

Если процесс был запущен с stderr=subprocess.STDOUT, stdout и stderr будут объединены в этом атрибуте, а stderr будет равен None.

stderr: Захваченный stderr дочернего процесса. Последовательность байтов или строка, если run() была вызвана с параметром encoding, errors или text=True. None, если stderr не был захвачен.

check_returncode(): Если returncode не равен нулю, вызывает исключение CalledProcessError.

Добавлено в версии 3.5.

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

Добавлено в версии 3.3.

subprocess.PIPE: Специальное значение, которое можно использовать в качестве аргумента stdin, stdout или stderr для Popen; указывает, что для стандартного потока следует открыть канал. Особенно полезно вместе с Popen.communicate().

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

exception subprocess.SubprocessError: Базовый класс для всех остальных исключений этого модуля.

Добавлено в версии 3.3.

exception subprocess.TimeoutExpired

Подкласс SubprocessError, вызываемый по истечении времени ожидания дочернего процесса.

cmd: Команда, использованная для запуска дочернего процесса.

timeout: Время ожидания в секундах.

output: Вывод дочернего процесса, если он был захвачен с помощью run() или check_output(). В противном случае — None. Если какой-либо вывод был захвачен, это всегда bytes, независимо от настройки text=True. Если вывод не наблюдался, значение может остаться None, а не b''.

stdout: Псевдоним output, обеспечивающий симметрию с stderr.

stderr: Вывод stderr дочернего процесса, если он был захвачен с помощью run(). В противном случае — None. Если вывод stderr был захвачен, это всегда bytes, независимо от настройки text=True. Если вывод stderr не наблюдался, значение может остаться None, а не b''.

Добавлено в версии 3.3.

Изменено в версии 3.5: Добавлены атрибуты stdout и stderr

exception subprocess.CalledProcessError

Подкласс SubprocessError, вызываемый, если процесс, запущенный с помощью check_call(), check_output() или run() (с параметром check=True), завершается с ненулевым кодом возврата.

returncode: Статус завершения дочернего процесса. Если процесс завершился из-за сигнала, это будет отрицательное число сигнала.

cmd: Команда, использованная для запуска дочернего процесса.

output: Вывод дочернего процесса, если он был захвачен с помощью run() или check_output(). В противном случае — None.

stdout: Псевдоним output, обеспечивающий симметрию с stderr.

stderr: Вывод stderr дочернего процесса, если он был захвачен с помощью run(). В противном случае — None.

Изменено в версии 3.5: Добавлены атрибуты stdout и stderr

Часто используемые аргументы

Для поддержки широкого спектра сценариев использования конструктор Popen (и функции-обёртки) принимает большое количество необязательных аргументов. В большинстве типичных случаев многие из этих аргументов можно безопасно оставить со значениями по умолчанию. Чаще всего необходимы следующие аргументы:

args обязателен для всех вызовов и должен быть строкой или последовательностью аргументов программы. Как правило, предпочтительно передавать последовательность аргументов: это позволяет модулю самостоятельно выполнять необходимое экранирование и заключать аргументы в кавычки (например, чтобы разрешить пробелы в именах файлов). При передаче одной строки значение shell должно быть равно True (см. ниже); иначе строка должна содержать только имя запускаемой программы без указания аргументов.

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

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

Для stdin символы окончания строки '\n' во входных данных будут преобразованы в разделитель строк по умолчанию os.linesep. Для stdout и stderr все символы окончания строки в выводе будут преобразованы в '\n'. Дополнительную информацию см. в документации класса io.TextIOWrapper, если аргумент newline его конструктора равен None.

Если текстовый режим не используется, stdin, stdout и stderr будут открыты как двоичные потоки. Кодирование и преобразование окончаний строк не выполняются.

Изменено в версии 3.6: Добавлены параметры encoding и errors.

Изменено в версии 3.7: Добавлен параметр text как псевдоним universal_newlines.

Примечание

Метод Popen.communicate() не обновляет атрибут newlines файловых объектов Popen.stdin, Popen.stdout и Popen.stderr.

Если значение shell равно True, указанная команда будет выполнена через оболочку. Это может быть полезно, если Python используется главным образом ради более широких возможностей управления потоком выполнения по сравнению с большинством системных оболочек, но при этом нужен удобный доступ к другим функциям оболочки, таким как конвейеры, шаблоны имён файлов, подстановка переменных окружения и раскрытие ~ в домашний каталог пользователя. Однако учтите, что в Python реализованы многие возможности, похожие на функции оболочки (в частности, glob, fnmatch, os.walk(), os.path.expandvars(), os.path.expanduser() и shutil).

Изменено в версии 3.3: Если значение universal_newlines равно True, класс использует кодировку locale.getpreferredencoding(False) вместо locale.getpreferredencoding(). Подробнее об этом изменении см. в документации класса io.TextIOWrapper.

Примечание

Перед использованием shell=True прочитайте раздел Рекомендации по безопасности.

Эти параметры и все остальные параметры подробнее описаны в документации конструктора Popen.

Конструктор Popen

Создание и управление нижележащим процессом в этом модуле выполняет класс 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=(), *, group=None, extra_groups=None, user=None, umask=-1, encoding=None, errors=None, text=None, pipesize=-1, process_group=None)

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

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

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

Для максимальной надёжности используйте полный путь к исполняемому файлу. Чтобы найти имя без полного пути в PATH, используйте shutil.which(). На всех платформах для повторного запуска текущего интерпретатора Python рекомендуется передавать sys.executable, а для запуска установленного модуля использовать формат командной строки -m.

Разрешение пути к executable (или к первому элементу args) зависит от платформы. Для POSIX см. os.execvpe(); обратите внимание, что при разрешении или поиске пути к исполняемому файлу cwd переопределяет текущий рабочий каталог, а env может переопределить переменную окружения PATH. Для Windows см. документацию к параметрам lpApplicationName и lpCommandLine WinAPI CreateProcess; обратите внимание, что при разрешении или поиске пути к исполняемому файлу с помощью shell=False cwd не переопределяет текущий рабочий каталог, а env не может переопределить переменную окружения PATH. Использование полного пути позволяет избежать всех этих различий.

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

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) и аргументы (например, eggs.txt), разделённые в оболочке пробелами, должны быть отдельными элементами списка, тогда как аргументы, которые при использовании в оболочке требуют кавычек или экранирования обратной косой чертой (например, имена файлов с пробелами или показанная выше команда echo), должны быть одним элементом списка.

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

Изменено в версии 3.6: Параметр args принимает объект, подобный пути, если shell равен False, а также последовательность, содержащую объекты, подобные путям, в POSIX.

Изменено в версии 3.8: Параметр args принимает объект, подобный пути, если shell равен False, а также последовательность, содержащую байты и объекты, подобные путям, в Windows.

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

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

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

Изменено в версии 3.6: В POSIX параметр executable принимает объект, подобный пути.

Изменено в версии 3.8: В Windows параметр executable принимает байты и объект, подобный пути.

Изменено в версии 3.12: Изменён порядок поиска оболочки в Windows для shell=True. Текущий каталог и %PATH% заменяются на %COMSPEC% и %SystemRoot%\System32\cmd.exe. В результате размещение вредоносной программы с именем cmd.exe в текущем каталоге больше не работает.

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

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

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

Использовать параметр preexec_fn НЕБЕЗОПАСНО, если в приложении есть потоки. Дочерний процесс может зайти в тупик до вызова exec.

Примечание

Если нужно изменить окружение дочернего процесса, используйте параметр env, а не делайте это в preexec_fn. Параметры start_new_session и process_group предназначены для замены кода, использующего preexec_fn для вызова os.setsid() или os.setpgid() в дочернем процессе.

Изменено в версии 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 может быть строка, объект bytes или объект, подобный пути. В POSIX, если путь к исполняемому файлу относительный, функция ищет executable (или первый элемент args) относительно cwd.

Изменено в версии 3.6: В POSIX параметр cwd принимает объект, подобный пути.

Изменено в версии 3.7: В Windows параметр cwd принимает объект, подобный пути.

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

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

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

Если start_new_session имеет значение true, перед выполнением подпроцесса в дочернем процессе будет выполнен системный вызов setsid().

Доступность: POSIX

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

Если process_group — неотрицательное целое число, перед выполнением подпроцесса в дочернем процессе будет выполнен системный вызов setpgid(0, value).

Доступность: POSIX

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

Если group не равен None, перед выполнением подпроцесса в дочернем процессе будет выполнен системный вызов setregid(). Если задано строковое значение, оно будет найдено с помощью grp.getgrnam(), после чего будет использовано значение из gr_gid. Если задано целое число, оно будет передано без изменений. (Только POSIX.)

Доступность: POSIX

Добавлено в версии 3.9.

Если extra_groups не равен None, перед выполнением подпроцесса в дочернем процессе будет выполнен системный вызов setgroups(). Строковые значения из extra_groups будут найдены с помощью grp.getgrnam(), после чего будут использованы значения из gr_gid. Целые числа будут переданы без изменений. (Только POSIX.)

Доступность: POSIX

Добавлено в версии 3.9.

Если user не равен None, перед выполнением подпроцесса в дочернем процессе будет выполнен системный вызов setreuid(). Если задано строковое значение, оно будет найдено с помощью pwd.getpwnam(), после чего будет использовано значение из pw_uid. Если задано целое число, оно будет передано без изменений. (Только POSIX.)

Доступность: POSIX

Добавлено в версии 3.9.

Если umask неотрицателен, перед выполнением подпроцесса в дочернем процессе будет выполнен системный вызов umask().

Доступность: POSIX

Добавлено в версии 3.9.

Если env не равен None, он должен быть отображением, задающим переменные окружения нового процесса; эти переменные используются вместо поведения по умолчанию, при котором наследуется окружение текущего процесса. На любой платформе отображение может содержать строки в качестве ключей и значений, а на платформах POSIX — байты, как в os.environ или os.environb.

Примечание

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

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

Добавлено в версии 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

Параметр pipesize позволяет изменить размер канала, если для stdin, stdout или stderr используется PIPE. Размер канала изменяется только на платформах, поддерживающих эту возможность (на данный момент — только Linux). На других платформах этот параметр игнорируется.

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

Объекты 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(), больше не вызывает исключение при таких ошибках, как отсутствие программы; вместо этого дочерний процесс завершается с ненулевым значением returncode.

Исключения

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

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

Исключение ValueError будет вызвано, если Popen вызван с недопустимыми аргументами.

check_call() и check_output() вызовут CalledProcessError, если вызванный процесс вернёт ненулевой код возврата.

Все функции и методы, принимающие параметр timeout, например run() и Popen.communicate(), вызовут TimeoutExpired, если время ожидания истечёт до завершения процесса.

Все исключения, определённые в этом модуле, наследуются от SubprocessError.

Добавлено в версии 3.3: Добавлен базовый класс SubprocessError.

Меры безопасности

В отличие от некоторых других функций popen, эта библиотека не выбирает неявно системную оболочку для вызова. Это означает, что все символы, включая метасимволы оболочки, можно безопасно передавать дочерним процессам. Если оболочка вызывается явно с помощью shell=True, приложение должно обеспечить надлежащее экранирование всех пробелов и метасимволов, чтобы избежать уязвимостей, связанных с внедрением команд в оболочку. На некоторых платформах для такого экранирования можно использовать shlex.quote().

В Windows пакетные файлы (*.bat или *.cmd) могут запускаться операционной системой в системной оболочке независимо от аргументов, переданных этой библиотеке. В результате аргументы могут обрабатываться по правилам оболочки, но Python не добавит никакого экранирования. Если вы намеренно запускаете пакетный файл с аргументами из ненадёжных источников, рассмотрите возможность передачи shell=True, чтобы Python экранировал специальные символы. Дополнительное обсуждение см. в gh-114539.

Объекты Popen

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

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

Popen.wait(timeout=None)

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

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

Примечание

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

Примечание

Если параметр timeout не равен None, функция (в POSIX) реализована с помощью активного ожидания (неблокирующий вызов и короткие паузы). Для асинхронного ожидания используйте модуль asyncio: см. asyncio.create_subprocess_exec.

Изменено в версии 3.3: добавлен параметр timeout.

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

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

communicate() возвращает кортеж (stdout_data, stderr_data). Если потоки открыты в текстовом режиме, данные будут строками; в противном случае — объектами bytes.

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

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

Дочерний процесс не завершается при истечении времени ожидания, поэтому для надлежащей очистки корректно работающему приложению следует завершить дочерний процесс и закончить взаимодействие:

proc = subprocess.Popen(...)
try:
    outs, errs = proc.communicate(timeout=15)
except TimeoutExpired:
    proc.kill()
    outs, errs = proc.communicate()

Примечание

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

Изменено в версии 3.3: добавлен параметр timeout.

Popen.send_signal(signal)

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

Ничего не делает, если процесс завершён.

Примечание

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

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

Popen.kill(): Завершает дочерний процесс. В POSIX-совместимых операционных системах функция отправляет дочернему процессу сигнал SIGKILL. В Windows kill() является псевдонимом для terminate().

Класс также устанавливает следующие атрибуты для доступа к ним. Повторное присваивание им новых значений не поддерживается:

Popen.args: Аргумент args в том виде, в каком он был передан в Popen, — последовательность аргументов программы или одна строка.

Добавлено в версии 3.3.

Popen.stdin: Если аргумент stdin равен PIPE, этот атрибут представляет собой доступный для записи потоковый объект, возвращаемый функцией open(). Если указаны аргументы encoding или errors либо аргумент text или universal_newlines равен True, поток является текстовым; в противном случае это поток байтов. Если аргумент stdin не равен PIPE, этот атрибут равен None.

Popen.stdout: Если аргумент stdout равен PIPE, этот атрибут представляет собой доступный для чтения потоковый объект, возвращаемый функцией open(). Чтение из потока позволяет получить выходные данные дочернего процесса. Если указаны аргументы encoding или errors либо аргумент text или universal_newlines равен True, поток является текстовым; в противном случае это поток байтов. Если аргумент stdout не равен PIPE, этот атрибут равен None.

Popen.stderr: Если аргумент stderr равен PIPE, этот атрибут представляет собой доступный для чтения потоковый объект, возвращаемый функцией open(). Чтение из потока позволяет получить сообщения об ошибках дочернего процесса. Если указаны аргументы encoding или errors либо аргумент text или universal_newlines равен True, поток является текстовым; в противном случае это поток байтов. Если аргумент stderr не равен PIPE, этот атрибут равен None.

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

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

Popen.pid

Идентификатор процесса дочернего процесса.

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

Popen.returncode

Код возврата дочернего процесса. Изначально None; атрибут returncode устанавливается при вызове методов poll(), wait() или communicate(), если они обнаруживают, что процесс завершился.

Значение None означает, что на момент последнего вызова метода процесс ещё не завершился.

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

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

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

class subprocess.STARTUPINFO(*, dwFlags=0, hStdInput=None, hStdOutput=None, hStdError=None, wShowWindow=0, lpAttributeList=None)

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

Изменено в версии 3.7: добавлена поддержка аргументов только по имени.

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.

lpAttributeList

Словарь дополнительных атрибутов создания процесса, указанных в STARTUPINFOEX; см. UpdateProcThreadAttribute.

Поддерживаемые атрибуты:

handle_list

Последовательность дескрипторов, которые будут унаследованы. Если последовательность не пуста, значение close_fds должно быть истинным.

При передаче конструктору Popen дескрипторы необходимо временно сделать наследуемыми с помощью os.set_handle_inheritable(); в противном случае будет возбуждёно исключение OSError с кодом ошибки Windows ERROR_INVALID_PARAMETER (87).

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

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

Добавлено в версии 3.7.

Константы Windows

Модуль subprocess предоставляет следующие константы.

subprocess.STD_INPUT_HANDLE: Устройство стандартного ввода. Изначально это буфер ввода консоли, CONIN$.

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

subprocess.STD_ERROR_HANDLE: Устройство стандартного потока ошибок. Изначально это активный буфер экрана консоли, CONOUT$.

subprocess.SW_HIDE: Скрывает окно. Активируется другое окно.

subprocess.STARTF_USESTDHANDLES: Указывает, что атрибуты STARTUPINFO.hStdInput, STARTUPINFO.hStdOutput и STARTUPINFO.hStdError содержат дополнительные сведения.

subprocess.STARTF_USESHOWWINDOW: Указывает, что атрибут STARTUPINFO.wShowWindow содержит дополнительные сведения.

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

subprocess.CREATE_NEW_PROCESS_GROUP

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

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

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

Добавлено в версии 3.7.

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

Добавлено в версии 3.7.

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

Добавлено в версии 3.7.

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

Добавлено в версии 3.7.

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

Добавлено в версии 3.7.

subprocess.REALTIME_PRIORITY_CLASS: Параметр creationflags для Popen, указывающий, что новый процесс будет иметь приоритет реального времени. Почти никогда не используйте REALTIME_PRIORITY_CLASS, поскольку он прерывает системные потоки, управляющие вводом с мыши и клавиатуры, а также фоновой записью на диск. Этот класс может подходить приложениям, непосредственно взаимодействующим с оборудованием или выполняющим короткие задачи, которые не должны часто прерываться.

Добавлено в версии 3.7.

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

Добавлено в версии 3.7.

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

Добавлено в версии 3.7.

subprocess.CREATE_DEFAULT_ERROR_MODE: Параметр creationflags для Popen, указывающий, что новый процесс не будет наследовать режим обработки ошибок вызывающего процесса. Вместо этого новый процесс получит режим обработки ошибок по умолчанию. Эта возможность особенно полезна для многопоточных приложений-оболочек, работающих с отключённой обработкой критических ошибок.

Добавлено в версии 3.7.

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

Добавлено в версии 3.7.

Старый высокоуровневый API

До Python 3.5 эти три функции составляли высокоуровневый API для работы с подпроцессами. Во многих случаях теперь можно использовать run(), но многие существующие программы вызывают эти функции.

subprocess.call(args, *, stdin=None, stdout=None, stderr=None, shell=False, cwd=None, timeout=None, **other_popen_kwargs)

Запустить команду, описанную в args. Дождаться завершения команды, а затем вернуть атрибут returncode.

Для перехвата stdout или stderr следует использовать вместо этого run():

run(...).returncode

Чтобы игнорировать stdout или stderr, укажите значение DEVNULL.

Показанные выше аргументы — лишь некоторые из часто используемых. Полная сигнатура функции совпадает с сигнатурой конструктора Popen — эта функция передаёт все предоставленные аргументы, кроме timeout, непосредственно этому интерфейсу.

Примечание

Не используйте stdout=PIPE или stderr=PIPE с этой функцией. Дочерний процесс будет заблокирован, если он создаст достаточно данных для заполнения буфера канала ОС, поскольку данные из каналов не считываются.

Изменено в версии 3.3: Добавлен timeout.

Изменено в версии 3.12: Изменён порядок поиска команд оболочкой Windows для shell=True. Текущий каталог и %PATH% заменены на %COMSPEC% и %SystemRoot%\System32\cmd.exe. В результате размещение вредоносной программы с именем cmd.exe в текущем каталоге больше не работает.

subprocess.check_call(args, *, stdin=None, stdout=None, stderr=None, shell=False, cwd=None, timeout=None, **other_popen_kwargs)

Запустить команду с аргументами. Дождаться завершения команды. Если код возврата равен нулю, вернуть управление, иначе вызвать исключение CalledProcessError. Объект CalledProcessError будет содержать код возврата в атрибуте returncode. Если check_call() не удалось запустить процесс, функция передаст вызванное исключение.

Для перехвата stdout или stderr следует использовать вместо этого run():

run(..., check=True)

Чтобы игнорировать stdout или stderr, укажите значение DEVNULL.

Примечание

Изменено в версии 3.3: Добавлен timeout.

subprocess.check_output(args, *, stdin=None, stderr=None, shell=False, cwd=None, encoding=None, errors=None, universal_newlines=None, timeout=None, text=None, **other_popen_kwargs)

Запустить команду с аргументами и вернуть её вывод.

Если код возврата ненулевой, функция вызывает исключение CalledProcessError. Объект CalledProcessError будет содержать код возврата в атрибуте returncode, а вывод — в атрибуте output.

Это эквивалентно:

run(..., check=True, stdout=PIPE).stdout

Показанные выше аргументы — лишь некоторые из часто используемых. Полная сигнатура функции в основном совпадает с сигнатурой run() — большинство аргументов передаётся непосредственно этому интерфейсу. Есть одно отличие API от поведения run(): передача input=None будет вести себя так же, как input=b'' (или input='', в зависимости от других аргументов), а не использовать дескриптор стандартного ввода родительского процесса.

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

Это поведение можно изменить, задав для text, encoding, errors или universal_newlines значение True, как описано в разделах Часто используемые аргументы и run().

Чтобы также включить в результат стандартный поток ошибок, используйте stderr=subprocess.STDOUT:

>>> subprocess.check_output(
...     "ls non_existent_file; exit 0",
...     stderr=subprocess.STDOUT,
...     shell=True)
'ls: non_existent_file: No such file or directory\n'

Добавлено в версии 3.1.

Изменено в версии 3.3: Добавлен timeout.

Изменено в версии 3.4: Добавлена поддержка именованного аргумента input.

Изменено в версии 3.6: Добавлены encoding и errors. Подробности см. в разделе run().

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

Замена старых функций модулем subprocess

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

Примечание

Все функции «a» в этом разделе (в той или иной степени) не сообщают об ошибке, если исполняемую программу не удаётся найти; вместо этого функции-замены «b» вызывают исключение OSError.

Кроме того, замены с использованием check_output() вызывают исключение CalledProcessError, если в результате запрошенной операции возвращён ненулевой код. Вывод по-прежнему доступен в атрибуте output вызванного исключения.

В следующих примерах предполагается, что соответствующие функции уже импортированы из модуля subprocess.

Замена подстановки команд оболочки /bin/sh

output=$(mycmd myarg)

заменяется на:

output = check_output(["mycmd", "myarg"])

Замена конвейера оболочки

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]

Вызов p1.stdout.close() после запуска p2 важен для того, чтобы p1 получил SIGPIPE, если p2 завершится раньше p1.

В качестве альтернативы для доверенного ввода можно по-прежнему напрямую использовать встроенную поддержку конвейеров оболочкой:

output=$(dmesg | grep hda)

заменяется на:

output = check_output("dmesg | grep hda", shell=True)

Замена `os.system()`

sts = os.system("mycmd" + " myarg")
# becomes
retcode = call("mycmd" + " myarg", shell=True)

Примечания:

Обычно запускать программу через оболочку не требуется.
Возвращаемое значение call() кодируется иначе, чем значение os.system().
Функция os.system() игнорирует сигналы SIGINT и SIGQUIT во время выполнения команды, но при использовании модуля subprocess вызывающая сторона должна сделать это отдельно.

Более реалистичный пример будет выглядеть так:

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)

Замена семейства `os.spawn`

Пример с P_NOWAIT:

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

Пример с P_WAIT:

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

Замена `os.popen()`, `os.popen2()`, `os.popen3()`

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

Замена функций модуля `popen2`

Примечание

Если аргумент cmd функций popen2 — строка, команда выполняется через /bin/sh. Если это список, команда выполняется напрямую.

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

popen2.Popen3 и popen2.Popen4 в основном работают как subprocess.Popen, за исключением следующего:

Popen вызывает исключение при сбое выполнения.
Аргумент capturestderr заменён аргументом stderr.
stdin=PIPE и stdout=PIPE необходимо указывать.
popen2 по умолчанию закрывает все файловые дескрипторы, но для гарантии такого поведения на всех платформах или в старых версиях Python необходимо указать close_fds=True в Popen.

Устаревшие функции вызова оболочки

Этот модуль также предоставляет следующие устаревшие функции из модуля commands версии 2.x. Эти операции неявно запускают системную оболочку; описанные выше гарантии безопасности и единообразной обработки исключений к ним не применяются.

subprocess.getstatusoutput(cmd, *, encoding=None, errors=None)

Возвращает (exitcode, output) выполнения cmd в оболочке.

Выполняет строку cmd в оболочке с Popen.check_output() и возвращает кортеж из двух элементов (exitcode, output). Параметры encoding и errors используются для декодирования вывода; дополнительные сведения см. в примечаниях к разделу Часто используемые аргументы.

Завершающий символ новой строки удаляется из вывода. Код завершения команды можно интерпретировать как код возврата подпроцесса. Пример:

>>> subprocess.getstatusoutput('ls /bin/ls')
(0, '/bin/ls')
>>> subprocess.getstatusoutput('cat /bin/junk')
(1, 'cat: /bin/junk: No such file or directory')
>>> subprocess.getstatusoutput('/bin/junk')
(127, 'sh: /bin/junk: not found')
>>> subprocess.getstatusoutput('/bin/kill $$')
(-15, '')

Доступность: Unix, Windows.

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

Теперь функция возвращает (exitcode, output) вместо (status, output), как это было в Python 3.3.3 и более ранних версиях. exitcode имеет то же значение, что и returncode.

Изменено в версии 3.11: Добавлены параметры encoding и errors.

subprocess.getoutput(cmd, *, encoding=None, errors=None)

Возвращает вывод (stdout и stderr) выполнения cmd в оболочке.

Работает как getstatusoutput(), но код завершения игнорируется, а возвращаемое значение — строка с выводом команды. Пример:

>>> subprocess.getoutput('ls /bin/ls')
'/bin/ls'

Доступность: Unix, Windows.

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

Изменено в версии 3.11: Добавлены параметры encoding и errors.

Примечания

Преобразование последовательности аргументов в строку в Windows

В Windows последовательность args преобразуется в строку, которую можно разобрать по следующим правилам (они соответствуют правилам среды выполнения MS C):

Аргументы разделяются пробельными символами — пробелами или табуляцией.
Строка, заключённая в двойные кавычки, интерпретируется как один аргумент независимо от содержащихся в ней пробельных символов. Строку в кавычках можно включить в аргумент.
Двойная кавычка, перед которой стоит обратная косая черта, интерпретируется как буквальная двойная кавычка.
Обратные косые черты интерпретируются буквально, если только непосредственно за ними не следует двойная кавычка.
Если перед двойной кавычкой непосредственно стоят обратные косые черты, каждая пара обратных косых черт интерпретируется как буквальная обратная косая черта. Если количество обратных косых черт нечётное, последняя обратная косая черта экранирует следующую двойную кавычку, как описано в правиле 3.

См. также

shlex: Модуль, предоставляющий функции для разбора и экранирования командных строк.

Отключение использования `vfork()` или `posix_spawn()`

В Linux модуль subprocess по умолчанию использует системный вызов vfork(), когда это безопасно, вместо fork(). Это значительно повышает производительность.

Если вы столкнулись с крайне необычной ситуацией, в которой необходимо запретить Python использовать vfork(), можно присвоить атрибуту subprocess._USE_VFORK ложное значение.

subprocess._USE_VFORK = False  # See CPython issue gh-NNNNNN.

Это не влияет на использование posix_spawn(), который может использовать vfork() внутри своей реализации libc. Если необходимо запретить и это, предусмотрен аналогичный атрибут subprocess._USE_POSIX_SPAWN.

subprocess._USE_POSIX_SPAWN = False  # See CPython issue gh-NNNNNN.

Безопасно задавать этим атрибутам значение false в любой версии Python. В старых версиях, где они не поддерживаются, это ни на что не повлияет. Не следует предполагать, что атрибуты доступны для чтения. Несмотря на свои имена, значение true не означает, что соответствующая функция будет использоваться, а лишь указывает на такую возможность.

Если вам приходится использовать эти закрытые параметры, сообщайте об ошибках и предоставляйте способ воспроизвести проблему. Добавьте ссылку на сообщение об ошибке в комментарий к своему коду.

Добавлено в версии 3.8: _USE_POSIX_SPAWN

Добавлено в версии 3.11: _USE_VFORK

© 2001–2024 Python Software Foundation
Licensed under the PSF License.
https://docs.python.org/3.12/library/subprocess.html

subprocess — Управление подпроцессами

Использование модуля subprocess

Часто используемые аргументы

Конструктор Popen

Исключения

Меры безопасности

Объекты Popen

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

Константы Windows

Старый высокоуровневый API

Замена старых функций модулем subprocess

Замена подстановки команд оболочки /bin/sh

Замена конвейера оболочки

Замена os.system()

Замена семейства os.spawn

Замена os.popen(), os.popen2(), os.popen3()

Замена функций модуля popen2

Устаревшие функции вызова оболочки

Примечания

Преобразование последовательности аргументов в строку в Windows

Отключение использования vfork() или posix_spawn()

Замена `os.system()`

Замена семейства `os.spawn`

Замена `os.popen()`, `os.popen2()`, `os.popen3()`

Замена функций модуля `popen2`

Отключение использования `vfork()` или `posix_spawn()`