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

Источник: Lib/subprocess.py

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

os.system
os.spawn*

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

См.также

PEP 324 – PEP, предлагающий модуль подпроцесса

Availability: не WASI, не iOS.

Этот модуль не работает или недоступен на платформах WebAssembly или iOS. Дополнительные сведения о доступности WASM см. в разделе Платформы WebAssembly; о доступности iOS - в разделе iOS.

Использование `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.

Можно указать таймаут в секундах, он внутренне передается в Popen.communicate(). Если таймаут истечет, дочерний процесс будет завершен и будет ожидать завершения. Исключение TimeoutExpired будет повторно поднято после завершения дочернего процесса. Само создание начального процесса не может быть прервано во многих платформенных API, поэтому вы не гарантированно увидите исключение по таймауту, по крайней мере, после того, как создание процесса займет столько времени.

Аргумент input передается в Popen.communicate() и, таким образом, в stdin подпроцесса. Если он используется, то должен быть последовательностью байтов, или строкой, если указаны кодировка или ошибки, или text является истиной. При использовании автоматически создается внутренний объект 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'')

Added in version 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() был вызван с кодировкой, ошибками или text=True. None, если stdout не был перехвачен.

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

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

check_returncode()¶: Если значение returncode ненулевое, вызовите сообщение CalledProcessError.

Added in version 3.5.

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

Added in version 3.3.

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

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

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

Added in version 3.3.

exception subprocess.TimeoutExpired¶

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

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

timeout¶: Тайм-аут в секундах.

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

stdout¶: Псевдоним для вывода, для симметрии с stderr.

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

Added in version 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¶: Псевдоним для вывода, для симметрии с stderr.

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

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

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

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

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

stdin, stdout и stderr задают стандартный ввод, стандартный вывод и стандартную обработку файлов ошибок выполняемой программы, соответственно. Допустимые значения: None, PIPE, DEVNULL, существующий дескриптор файла (целое положительное число) и существующий file object с допустимым дескриптором файла. При настройках по умолчанию 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.

Примечание

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

Если shell равно True, указанная команда будет выполнена через оболочку. Это может быть полезно, если вы используете Python в первую очередь для расширенного потока управления, который он предлагает по сравнению с большинством системных оболочек, но при этом хотите иметь удобный доступ к другим функциям оболочки, таким как shell pipes, подстановочные знаки имен файлов, расширение переменных окружения и расширение ~ до домашнего каталога пользователя. Однако обратите внимание, что сам Python предлагает реализацию многих shell-подобных функций (в частности, 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 прочитайте раздел Security Considerations.

Эти и другие опции более подробно описаны в документации по конструктору 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 должна быть последовательность аргументов программы, иначе - одиночная строка или path-like object. По умолчанию программа для выполнения является первым элементом в args, если args - последовательность. Если args - строка, интерпретация зависит от платформы и описана ниже. Дополнительные отличия от поведения по умолчанию см. в аргументах shell и executable. Если не указано иное, рекомендуется передавать args в виде последовательности.

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

Для максимальной надежности используйте полный путь к исполняемому файлу. Для поиска неквалифицированного имени по PATH используйте shutil.which(). На всех платформах рекомендуется передавать sys.executable для повторного запуска текущего интерпретатора Python, а для запуска установленного модуля использовать формат командной строки -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 принимает значение path-like object, если shell - False, и последовательность, содержащую объекты типа path на POSIX.

Изменено в версии 3.8: Параметр args принимает значение path-like object, если shell - False, и последовательность, содержащую байты и объекты типа path в 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 прочитайте раздел Security Considerations.

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: Параметр executable принимает значение path-like object в POSIX.

Изменено в версии 3.8: Параметр executable принимает байт и path-like object в Windows.

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

stdin, stdout и stderr задают стандартный ввод, стандартный вывод и стандартную обработку файлов ошибок выполняемой программы, соответственно. Допустимые значения: None, PIPE, DEVNULL, существующий дескриптор файла (целое положительное число) и существующий file object с допустимым дескриптором файла. При настройках по умолчанию 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 может быть строкой, байтом или объектом path-like. На POSIX функция ищет executable (или первый элемент в args) относительно cwd, если путь к исполняемому файлу является относительным.

Изменено в версии 3.6: Параметр cwd принимает значение path-like object в POSIX.

Изменено в версии 3.7: Параметр cwd принимает значение path-like object в Windows.

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

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

Изменено в версии 3.2: Было добавлено restore_signals.

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

Availability: POSIX

Изменено в версии 3.2: Была добавлена функция start_new_session.

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

Availability: POSIX

Изменено в версии 3.11: Была добавлена process_group.

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

Availability: POSIX

Added in version 3.9.

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

Availability: POSIX

Added in version 3.9.

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

Availability: POSIX

Added in version 3.9.

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

Availability: POSIX

Added in version 3.9.

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

Примечание

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

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

Added in version 3.6: Были добавлены кодирование и ошибки.

Added in version 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 можно использовать для изменения размера трубы, когда PIPE используется для stdin, stdout или stderr. Размер трубы изменяется только на платформах, которые поддерживают этот параметр (на данный момент только Linux). Другие платформы будут игнорировать этот параметр.

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

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

with Popen(["ifconfig"], stdout=PIPE) as proc:
    log.write(proc.stdout.read())

Поднимает auditing event subprocess.Popen с аргументами executable, args, cwd, env.

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

Изменено в версии 3.6: Деструктор Popen теперь выдает предупреждение ResourceWarning, если дочерний процесс все еще запущен.

Изменено в версии 3.8: Popen может использовать os.posix_spawn() в некоторых случаях для повышения производительности. В Windows Subsystem for Linux и QEMU User Emulation конструктор Popen, использующий os.posix_spawn(), больше не вызывает исключение при ошибках типа отсутствия программы, но дочерний процесс завершается с ненулевым значением returncode.

Исключения¶

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

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

Если Popen вызывается с недопустимыми аргументами, то будет выдана ошибка ValueError.

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

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

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

Added in version 3.3: Был добавлен базовый класс SubprocessError.

Соображения безопасности¶

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

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

Объекты Попена¶

Экземпляры класса 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 должен быть строкой. В противном случае это должны быть байты.

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

Обратите внимание, что если вы хотите отправить данные на 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)¶

Посылает сигнал сигнал ребенку.

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

Примечание

В 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. – последовательность аргументов программы или одна строка.

Added in version 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).

Помощники Windows Popen¶

Класс 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.

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

список_ручек

Последовательность хэндлов, которые будут наследоваться. close_fds должно быть true, если оно непустое.

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

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

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

Added in version 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.STARTF_FORCEONFEEDBACK¶: Параметр STARTUPINFO.dwFlags, указывающий, что во время запуска процесса будет отображаться курсор мыши Working in Background. Это поведение по умолчанию для процессов с графическим интерфейсом.

Added in version 3.13.

subprocess.STARTF_FORCEOFFFEEDBACK¶: Параметр STARTUPINFO.dwFlags, указывающий, что курсор мыши не будет изменяться при запуске процесса.

Added in version 3.13.

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

subprocess.CREATE_NEW_PROCESS_GROUP¶

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

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

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

Added in version 3.7.

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

Added in version 3.7.

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

Added in version 3.7.

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

Added in version 3.7.

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

Added in version 3.7.

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

Added in version 3.7.

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

Added in version 3.7.

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

Added in version 3.7.

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

Added in version 3.7.

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

Added in version 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.

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

Примечание

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

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

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

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(). - большинство аргументов передаются непосредственно в этот интерфейс. Существует одно отклонение от поведения run() в API: при передаче 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'

Added in version 3.1.

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

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

Изменено в версии 3.6: Были добавлены кодирование и ошибки. Подробности см. в run().

Added in version 3.7: text был добавлен как более удобный для чтения псевдоним для universal_newlines.

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

Замена старых функций на `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()`¶

Обработка кода возврата происходит следующим образом:

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

Функции вызова Legacy Shell¶

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

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

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

Выполните строку cmd в оболочке с Popen.check_output() и верните 2-кортеж (exitcode, output). Для декодирования вывода используются кодировка и ошибки; подробнее см. примечания к Часто используемые аргументы.

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

>>> 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, '')

Availability: 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'

Availability: Unix, Windows.

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

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

Примечания¶

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

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

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

См.также

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

Запрет использования `vfork()` или `posix_spawn()`¶

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

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

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. Они не будут иметь никакого эффекта в старых версиях, если не поддерживаются. Не предполагайте, что атрибуты доступны для чтения. Несмотря на их названия, истинное значение не означает, что соответствующая функция будет использована, а только то, что она может быть использована.

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

Added in version 3.8: _USE_POSIX_SPAWN

Added in version 3.11: _USE_VFORK

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

Использование `subprocess` Модуль¶

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

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

Исключения¶

Соображения безопасности¶

Объекты Попена¶

Помощники Windows Popen¶

Константы Windows¶

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

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

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

Замена трубопровода оболочки¶

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

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

Замена `os.popen()`¶

Функции вызова Legacy Shell¶

Примечания¶

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

Запрет использования `vfork()` или `posix_spawn()`¶

Оглавление

Предыдущий раздел

Следующий раздел

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

Использование subprocess Модуль¶

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

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

Исключения¶

Соображения безопасности¶

Объекты Попена¶

Помощники Windows Popen¶

Константы Windows¶

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

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

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

Замена трубопровода оболочки¶

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

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

Замена os.popen()¶

Функции вызова Legacy Shell¶

Примечания¶

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

Запрет использования vfork() или posix_spawn()¶

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

Использование `subprocess` Модуль¶

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

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

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

Замена `os.popen()`¶

Запрет использования `vfork()` или `posix_spawn()`¶