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

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

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

os.system
os.spawn*

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

См. также

PEP 324 — PEP, предлагающий модуль subprocess

Доступность: не поддерживается на Android, iOS и 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.

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

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

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

stderr: Захваченный stderr дочернего процесса. Последовательность байтов или строка, если run() был вызван с кодировкой, ошибками или 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.

END_OF_DOCUMENT_MARKER

exception subprocess.TimeoutExpired

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

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

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

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

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

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

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

Примечание

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

Если 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: Параметр executable принимает объект-путь в POSIX.

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

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

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

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

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

Если restore_signals равно True (по умолчанию), все сигналы, которые Python установил в SIG_IGN, восстанавливаются в SIG_DFL в дочернем процессе перед выполнением exec. В настоящее время это включает сигналы 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, оно должно быть отображением, определяющим переменные среды для нового процесса; они используются вместо поведения по умолчанию — наследования среды текущего процесса. Это отображение может быть от 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 и предоставляется для обратной совместимости. По умолчанию объекты файлов открываются в бинарном режиме.

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

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

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

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

Объекты Popen и другие функции этого модуля, использующие Popen, генерируют событие аудита аудита subprocess.Popen со значениями аргументов executable, args, cwd, и env. Значение для args может быть одной строкой или списком строк, в зависимости от платформы.

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

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

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

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

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

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

Объекты Popen

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

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

Popen.wait(timeout=None)

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

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

Примечание

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

Примечание

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

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

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

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

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

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

END_OF_DOCUMENT_MARKER

Windows Popen Помощники

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

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

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

Изменено в версии 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 должен быть true, если список не пуст.

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

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

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

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

END_OF_DOCUMENT_MARKER

Константы 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 для указания того, что курсор мыши «Работа в фоновом режиме» будет отображаться во время запуска процесса. Это поведение по умолчанию для процессов графического интерфейса.

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

subprocess.STARTF_FORCEOFFFEEDBACK: Параметр STARTUPINFO.dwFlags для указания того, что курсор мыши не будет изменён при запуске процесса.

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

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

subprocess.CREATE_NEW_PROCESS_GROUP

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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.

END_OF_DOCUMENT_MARKER

Замена устаревших функций модулем 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 закрывает все дескрипторы файлов по умолчанию, но вам нужно явно указать close_fds=True с Popen для обеспечения этого поведения на всех платформах или в прошлых версиях Python.

Функции вызова оболочки (legacy)

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

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

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

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

Конец строки \n удаляется из вывода. Код возврата команды можно интерпретировать как код возврата подпроцесса. Пример:

>>> 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 runtime):

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

См. также

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

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

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

Если вам когда-либо потребуется предотвратить использование vfork() Python, вы можете установить атрибут 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.

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

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

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

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

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

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

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

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

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

Исключения

Рекомендации по безопасности

Объекты Popen

Windows Popen Помощники

Константы Windows

Более старый API высокого уровня

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

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

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

Замена os.system()

Замена семейства функций os.spawn

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

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

Функции вызова оболочки (legacy)

Примечания

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

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

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

Замена семейства функций `os.spawn`

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

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

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