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

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

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

os.system
os.spawn*

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

См. также

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

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

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

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

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

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

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

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

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

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

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

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

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

Если значение env не равно None, оно должно быть отображением, задающим переменные окружения для нового процесса; они используются вместо поведения по умолчанию, при котором процесс наследует окружение текущего процесса. Оно передаётся напрямую в Popen. Это отображение может содержать строки в качестве ключей и значений на любой платформе или байты в качестве ключей и значений на 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.11.3: Изменён порядок поиска оболочки в Windows для shell=True. Текущий каталог и %PATH% заменены на %COMSPEC% и %SystemRoot%\System32\cmd.exe. В результате размещение вредоносной программы с именем cmd.exe в текущем каталоге больше не работает.

class subprocess.CompletedProcess

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

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

returncode

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

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

stdout

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

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

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

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

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

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

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

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

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

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

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

exception subprocess.TimeoutExpired

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

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

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

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

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

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

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

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

exception subprocess.CalledProcessError

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

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

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

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

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

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

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

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

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

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

Параметры stdin, stdout и stderr задают дескрипторы файлов стандартного ввода, стандартного вывода и стандартного потока ошибок выполняемой программы соответственно. Допустимые значения: PIPE, DEVNULL, существующий файловый дескриптор (положительное целое число), существующий файловый объект с допустимым файловым дескриптором и None. Значение PIPE указывает, что для дочернего процесса следует создать новый канал. Значение DEVNULL указывает, что будет использоваться специальный файл os.devnull. При настройках по умолчанию None перенаправление не выполняется; дескрипторы файлов дочернего процесса наследуются от родительского. Кроме того, параметр 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 является строкой, её интерпретация зависит от платформы и описана ниже. Дополнительные отличия от поведения по умолчанию описаны в аргументах shell и executable. Если не указано иное, рекомендуется передавать args как последовательность.

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

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

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

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

Popen(["/usr/bin/git", "commit", "-m", "Fixes a bug."])

В POSIX, если args является строкой, она интерпретируется как имя или путь выполняемой программы. Однако это возможно только в том случае, если программе не передаются аргументы.

Примечание

Разбить команду оболочки на последовательность аргументов может быть непросто, особенно в сложных случаях. shlex.split() поможет определить правильное разбиение на токены для args:

>>> import shlex, subprocess
>>> command_line = input()
/bin/vikings -input eggs.txt -output "spam spam.txt" -cmd "echo '$MONEY'"
>>> args = shlex.split(command_line)
>>> print(args)
['/bin/vikings', '-input', 'eggs.txt', '-output', 'spam spam.txt', '-cmd', "echo '$MONEY'"]
>>> p = subprocess.Popen(args) # Success!

Обратите особое внимание: параметры (например, -input) и аргументы (например, eggs.txt), разделённые пробелами в оболочке, должны быть отдельными элементами списка. Аргументы, которые при использовании в оболочке нужно заключать в кавычки или экранировать обратной косой чертой (например, имена файлов с пробелами или приведённая выше команда echo), представляют собой один элемент списка.

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

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

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

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

В POSIX с shell=True оболочка по умолчанию равна /bin/sh. Если args является строкой, она задаёт команду, выполняемую через оболочку. Это означает, что строка должна быть отформатирована точно так же, как при вводе в командной строке оболочки. Например, имена файлов с пробелами нужно заключать в кавычки или экранировать обратной косой чертой. Если args является последовательностью, первый элемент задаёт командную строку, а все последующие элементы будут считаться дополнительными аргументами самой оболочки. Иными словами, Popen выполняет эквивалент следующего:

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

В Windows с shell=True переменная окружения COMSPEC задаёт оболочку по умолчанию. Указывать shell=True в Windows нужно только в том случае, если выполняемая команда встроена в оболочку (например, dir или copy). Для запуска пакетного файла или консольного исполняемого файла shell=True не требуется.

Примечание

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

bufsize передаётся как соответствующий аргумент функции open() при создании файловых объектов каналов stdin/stdout/stderr:

0 означает отсутствие буферизации (чтение и запись выполняются одним системным вызовом, который может обработать меньше данных, чем запрошено)
1 означает построчную буферизацию (доступна только при text=True или universal_newlines=True)
любое другое положительное значение задаёт приблизительный размер буфера
отрицательное значение bufsize (по умолчанию) означает, что будет использоваться системное значение по умолчанию io.DEFAULT_BUFFER_SIZE.

Изменено в версии 3.3.1: Теперь для bufsize по умолчанию используется значение -1, включающее буферизацию, как ожидает большинство программ. В версиях до Python 3.2.4 и 3.3.1 ошибочно использовалось значение 0, которое отключало буферизацию и допускало неполное чтение. Это было непреднамеренно и не соответствовало поведению Python 2, которого ожидало большинство программ.

Аргумент executable задаёт программу на замену выполняемой программе. Он нужен крайне редко. Если задано shell=False, executable заменяет программу, указанную в args. Однако исходное значение args всё равно передаётся программе. Большинство программ воспринимают программу, заданную в args, как имя команды, которое может отличаться от фактически выполняемой программы. В POSIX имя из args становится отображаемым именем исполняемого файла в таких утилитах, как ps. Если задано shell=True, в POSIX аргумент executable задаёт оболочку на замену оболочке по умолчанию /bin/sh.

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

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

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

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

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

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

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

Примечание

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

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

Добавлено в версии 3.6: Добавлены encoding и errors.

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

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

Если задан параметр creationflags, он может содержать один или несколько следующих флагов:

CREATE_NEW_CONSOLE
CREATE_NEW_PROCESS_GROUP
ABOVE_NORMAL_PRIORITY_CLASS
BELOW_NORMAL_PRIORITY_CLASS
HIGH_PRIORITY_CLASS
IDLE_PRIORITY_CLASS
NORMAL_PRIORITY_CLASS
REALTIME_PRIORITY_CLASS
CREATE_NO_WINDOW
DETACHED_PROCESS
CREATE_DEFAULT_ERROR_MODE
CREATE_BREAKAWAY_FROM_JOB

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

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

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

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

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

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

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

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

Исключения

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

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

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

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

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

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

Примечание

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

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

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

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

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

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

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

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

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

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

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

Popen.pid

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

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

Popen.returncode

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

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

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

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

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

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

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

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

dwFlags

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

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

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

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

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

wShowWindow

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

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

lpAttributeList

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

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

handle_list

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

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

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

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

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

Константы Windows

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

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

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

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

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

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

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

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

subprocess.CREATE_NEW_PROCESS_GROUP

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Выполняет команду, описанную в args. Ожидает завершения команды, а затем возвращает атрибут returncode.

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

run(...).returncode

Чтобы подавить stdout или stderr, передайте значение DEVNULL.

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

Примечание

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

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

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

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

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

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

run(..., check=True)

Чтобы подавить stdout или stderr, передайте значение DEVNULL.

Примечание

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

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

Выполняет команду с аргументами и возвращает её вывод.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Примечание

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

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

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

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

output=$(mycmd myarg)

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

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

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

output=$(dmesg | grep hda)

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

p1 = Popen(["dmesg"], stdout=PIPE)
p2 = Popen(["grep", "hda"], stdin=p1.stdout, stdout=PIPE)
p1.stdout.close()  # Allow p1 to receive a SIGPIPE if p2 exits.
output = p2.communicate()[0]

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

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

output=$(dmesg | grep hda)

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

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

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

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

Примечания:

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

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

try:
    retcode = call("mycmd" + " myarg", shell=True)
    if retcode < 0:
        print("Child was terminated by signal", -retcode, file=sys.stderr)
    else:
        print("Child returned", retcode, file=sys.stderr)
except OSError as e:
    print("Execution failed:", e, file=sys.stderr)

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

Пример P_NOWAIT:

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

Пример P_WAIT:

retcode = os.spawnlp(os.P_WAIT, "/bin/mycmd", "mycmd", "myarg")
==>
retcode = call(["/bin/mycmd", "myarg"])

Пример с вектором:

os.spawnvp(os.P_NOWAIT, path, args)
==>
Popen([path] + args[1:])

Пример с окружением:

os.spawnlpe(os.P_NOWAIT, "/bin/mycmd", "mycmd", "myarg", env)
==>
Popen(["/bin/mycmd", "myarg"], env={"PATH": "/usr/bin"})

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

(child_stdin, child_stdout) = os.popen2(cmd, mode, bufsize)
==>
p = Popen(cmd, shell=True, bufsize=bufsize,
          stdin=PIPE, stdout=PIPE, close_fds=True)
(child_stdin, child_stdout) = (p.stdin, p.stdout)

(child_stdin,
 child_stdout,
 child_stderr) = os.popen3(cmd, mode, bufsize)
==>
p = Popen(cmd, shell=True, bufsize=bufsize,
          stdin=PIPE, stdout=PIPE, stderr=PIPE, close_fds=True)
(child_stdin,
 child_stdout,
 child_stderr) = (p.stdin, p.stdout, p.stderr)

(child_stdin, child_stdout_and_stderr) = os.popen4(cmd, mode, bufsize)
==>
p = Popen(cmd, shell=True, bufsize=bufsize,
          stdin=PIPE, stdout=PIPE, stderr=STDOUT, close_fds=True)
(child_stdin, child_stdout_and_stderr) = (p.stdin, p.stdout)

Обработка кода возврата выглядит так:

pipe = os.popen(cmd, 'w')
...
rc = pipe.close()
if rc is not None and rc >> 8:
    print("There were some errors")
==>
process = Popen(cmd, stdin=PIPE)
...
process.stdin.close()
if process.wait() != 0:
    print("There were some errors")

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

Примечание

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

(child_stdout, child_stdin) = popen2.popen2("somestring", bufsize, mode)
==>
p = Popen("somestring", shell=True, bufsize=bufsize,
          stdin=PIPE, stdout=PIPE, close_fds=True)
(child_stdout, child_stdin) = (p.stdout, p.stdin)

(child_stdout, child_stdin) = popen2.popen2(["mycmd", "myarg"], bufsize, mode)
==>
p = Popen(["mycmd", "myarg"], bufsize=bufsize,
          stdin=PIPE, stdout=PIPE, close_fds=True)
(child_stdout, child_stdin) = (p.stdout, p.stdin)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Примечания

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

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

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

См. также

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

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

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

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

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

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

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

Эти атрибуты можно безопасно установить в ложное значение в любой версии 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.11/library/subprocess.html

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

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

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

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

Исключения

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

Объекты Popen

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

Константы Windows

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

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

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

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

Замена os.system()

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

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

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

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

Примечания

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

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

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

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

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

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

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