subprocess — Subprocess management

Вихідний код: Lib/subprocess.py

---

Модуль subprocess дозволяє створювати нові процеси, підключатися до їхніх каналів вводу/виводу/помилок і отримувати їхні коди повернення. Цей модуль призначений для заміни кількох старих модулів і функцій:

os.system
os.spawn*

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

Дивись також

PEP 324 – PEP пропонує модуль підпроцесу

Availability: not Android, not iOS, not WASI.

This module is not supported on mobile platforms or WebAssembly platforms.

Використання модуля 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 не є.)

If capture_output is true, stdout and stderr will be captured. When used, the internal Popen object is automatically created with stdout and stderr both set to PIPE. The stdout and stderr arguments may not be supplied at the same time as capture_output. If you wish to capture and combine both streams into one, set stdout to PIPE and stderr to STDOUT, instead of using capture_output.

A timeout may be specified in seconds, it is internally passed on to Popen.communicate(). If the timeout expires, the child process will be killed and waited for. The TimeoutExpired exception will be re-raised after the child process has terminated. The initial process creation itself cannot be interrupted on many platform APIs so you are not guaranteed to see a timeout exception until at least after however long process creation takes.

The input argument is passed to Popen.communicate() and thus to the subprocess’s stdin. If used it must be a byte sequence, or a string if encoding or errors is specified or text is true. When used, the internal Popen object is automatically created with stdin set to PIPE, and the stdin argument may not be used as well.

Якщо check має значення true, і процес завершується з ненульовим кодом виходу, буде викликано виняток CalledProcessError. Атрибути цього винятку містять аргументи, код виходу, а також stdout і stderr, якщо вони були захоплені.

Якщо вказано кодування або помилки, або текст має значення true, файлові об’єкти для stdin, stdout і stderr відкриваються в текстовому режимі з використанням указаного кодування та помилок або io.TextIOWrapper за замовчуванням. Аргумент universal_newlines еквівалентний text і надається для зворотної сумісності. За замовчуванням файлові об’єкти відкриваються у двійковому режимі.

If env is not None, it must be a mapping that defines the environment variables for the new process; these are used instead of the default behavior of inheriting the current process“ environment. It is passed directly to Popen. This mapping can be str to str on any platform or bytes to bytes on POSIX platforms much like os.environ or os.environb.

Приклади:

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

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

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

Added in version 3.5.

Змінено в версії 3.6: Додано параметри кодування та помилки

Змінено в версії 3.7: Додано параметр text як більш зрозумілий псевдонім universal_newlines. Додано параметр capture_output.

Змінено в версії 3.12: Changed Windows shell search order for shell=True. The current directory and %PATH% are replaced with %COMSPEC% and %SystemRoot%\System32\cmd.exe. As a result, dropping a malicious program named cmd.exe into a current directory no longer works.

class subprocess.CompletedProcess

Повернене значення від run(), що представляє процес, який завершився.

args

Аргументи, які використовуються для запуску процесу. Це може бути список або рядок.

returncode

Статус виходу дочірнього процесу. Як правило, статус виходу 0 вказує на успішне виконання.

Від’ємне значення -N вказує на те, що дочірній елемент було завершено сигналом N (лише POSIX).

stdout

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

Якщо ви запустили процес із stderr=subprocess.STDOUT, stdout і stderr буде об’єднано в цьому атрибуті, а stderr буде None.

stderr

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

check_returncode()

Якщо returncode не дорівнює нулю, викликається CalledProcessError.

Added in version 3.5.

subprocess.DEVNULL

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

Added in version 3.3.

subprocess.PIPE

Спеціальне значення, яке можна використовувати як аргумент stdin, stdout або stderr для Popen і вказує, що канал до стандартного потоку має бути відкритий. Найкорисніше з Popen.communicate().

subprocess.STDOUT

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

exception subprocess.SubprocessError

Базовий клас для всіх інших винятків із цього модуля.

Added in version 3.3.

exception subprocess.TimeoutExpired

Підклас SubprocessError, викликається, коли закінчується час очікування під час очікування дочірнього процесу.

cmd

Команда, яка була використана для створення дочірнього процесу.

timeout

Час очікування в секундах.

output

Output of the child process if it was captured by run() or check_output(). Otherwise, None. This is always bytes when any output was captured regardless of the text=True setting. It may remain None instead of b'' when no output was observed.

stdout

Псевдонім для виведення, для симетрії з stderr.

stderr

Stderr output of the child process if it was captured by run(). Otherwise, None. This is always bytes when stderr output was captured regardless of the text=True setting. It may remain None instead of b'' when no stderr output was observed.

Added in version 3.3.

Змінено в версії 3.5: Додано атрибути stdout і stderr

exception subprocess.CalledProcessError

Підклас SubprocessError, який виникає, коли процес, запущений check_call(), check_output() або run() (із check=True), повертає не- нульовий статус виходу.

returncode

Статус виходу дочірнього процесу. Якщо процес завершився через сигнал, це буде негативне число сигналу.

cmd

Команда, яка була використана для створення дочірнього процесу.

output

Висновок дочірнього процесу, якщо він був захоплений run() або check_output(). В іншому випадку Жодного.

stdout

Псевдонім для виведення, для симетрії з stderr.

stderr

Висновок stderr дочірнього процесу, якщо він був захоплений run(). В іншому випадку Жодного.

Змінено в версії 3.5: Додано атрибути stdout і stderr

Часто використовувані аргументи

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

args є обов’язковим для всіх викликів і має бути рядком або послідовністю аргументів програми. Надання послідовності аргументів зазвичай є кращим, оскільки це дозволяє модулю подбати про будь-які необхідні екранування та цитування аргументів (наприклад, дозволити пробіли в іменах файлів). Якщо передається один рядок, або shell має бути True (див. нижче), або в іншому випадку рядок має просто назвати програму, яку потрібно виконати, без вказівки жодних аргументів.

stdin, stdout and stderr specify the executed program’s standard input, standard output and standard error file handles, respectively. Valid values are None, PIPE, DEVNULL, an existing file descriptor (a positive integer), and an existing file object with a valid file descriptor. With the default settings of None, no redirection will occur. PIPE indicates that a new pipe to the child should be created. DEVNULL indicates that the special file os.devnull will be used. Additionally, stderr can be STDOUT, which indicates that the stderr data from the child process should be captured into the same file handle as for stdout.

Якщо вказано кодування або помилки, або текст (також відомий як universal_newlines) має значення true, файлові об’єкти stdin, stdout і stderr буде відкрито в текстовому режимі за допомогою кодування і помилки, указані у виклику або за замовчуванням для io.TextIOWrapper.

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

Якщо текстовий режим не використовується, stdin, stdout і stderr будуть відкриті як бінарні потоки. Кодування або перетворення закінчення рядка не виконується.

Змінено в версії 3.6: Added the encoding and errors parameters.

Змінено в версії 3.7: Додано параметр text як псевдонім для universal_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 прочитайте розділ Security Considerations.

Ці параметри разом з усіма іншими опціями описані більш детально в документації конструктора Popen.

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

Створення основного процесу та керування ним у цьому модулі обробляється класом Popen. Він пропонує велику гнучкість, щоб розробники могли обробляти менш поширені випадки, які не охоплюються функціями зручності.

class subprocess.Popen(args, bufsize=-1, executable=None, stdin=None, stdout=None, stderr=None, preexec_fn=None, close_fds=True, shell=False, cwd=None, env=None, universal_newlines=None, startupinfo=None, creationflags=0, restore_signals=True, start_new_session=False, pass_fds=(), *, group=None, extra_groups=None, user=None, umask=-1, encoding=None, errors=None, text=None, pipesize=-1, process_group=None)

Виконати дочірню програму в новому процесі. У POSIX клас використовує os.execvpe()-подібну поведінку для виконання дочірньої програми. У Windows цей клас використовує функцію CreateProcess() Windows. Аргументи Popen такі.

args має бути послідовністю аргументів програми або одним рядком або path-like object. За замовчуванням програма для виконання є першим елементом у args, якщо args є послідовністю. Якщо args є рядком, інтерпретація залежить від платформи та описана нижче. Перегляньте аргументи shell і executable, щоб дізнатися про додаткові відмінності від поведінки за замовчуванням. Якщо не вказано інше, рекомендується передавати args як послідовність.

Попередження

For maximum reliability, use a fully qualified path for the executable. To search for an unqualified name on PATH, use shutil.which(). On all platforms, passing sys.executable is the recommended way to launch the current Python interpreter again, and use the -m command-line format to launch an installed module.

Визначення шляху виконуваного файлу (або першого елемента 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), відокремлені пробілами в оболонці, розміщуються в окремих елементах списку, тоді як аргументи, які потребують лапок або екранування зворотної скісної риски, коли використовуються в shell (наприклад, імена файлів, що містять пробіли, або команда echo, показана вище) є одними елементами списку.

У Windows, якщо args є послідовністю, вона буде перетворена на рядок у спосіб, описаний у Перетворення послідовності аргументів на рядок у Windows. Це тому, що базовий CreateProcess() працює з рядками.

Змінено в версії 3.6: Параметр args приймає path-like object, якщо shell має значення False, і послідовність, що містить шляхові об’єкти на POSIX.

Змінено в версії 3.8: Параметр args приймає path-like object, якщо 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 прочитайте розділ Security Considerations.

bufsize буде надано як відповідний аргумент функції open() під час створення об’єктів файлу каналу stdin/stdout/stderr:

• 0 means unbuffered (read and write are one system call and can return short)

• 1 means line buffered (only usable if text=True or universal_newlines=True)

• будь-яке інше позитивне значення означає використання буфера приблизно такого розміру

• negative bufsize (за замовчуванням) означає, що буде використано системне значення io.DEFAULT_BUFFER_SIZE.

Змінено в версії 3.3.1: bufsize now defaults to -1 to enable buffering by default to match the behavior that most code expects. In versions prior to Python 3.2.4 and 3.3.1 it incorrectly defaulted to 0 which was unbuffered and allowed short reads. This was unintentional and did not match the behavior of Python 2 as most code expected.

Аргумент executable визначає програму заміни для виконання. Це дуже рідко потрібно. Коли shell=False, executable замінює програму для виконання, указану args. Однак оригінальні args усе ще передаються програмі. Більшість програм розглядають програму, визначену args, як назву команди, яка потім може відрізнятися від фактично виконаної програми. У POSIX ім’я args стає відображуваним ім’ям для виконуваного файлу в таких утилітах, як ps. Якщо shell=True, у POSIX виконуваний аргумент вказує на заміну оболонки для типового /bin/sh.

Змінено в версії 3.6: Параметр executable приймає path-like object на POSIX.

Змінено в версії 3.8: Параметр executable приймає байти та path-like object у Windows.

Змінено в версії 3.12: Changed Windows shell search order for shell=True. The current directory and %PATH% are replaced with %COMSPEC% and %SystemRoot%\System32\cmd.exe. As a result, dropping a malicious program named cmd.exe into a current directory no longer works.

stdin, stdout and stderr specify the executed program’s standard input, standard output and standard error file handles, respectively. Valid values are None, PIPE, DEVNULL, an existing file descriptor (a positive integer), and an existing file object with a valid file descriptor. With the default settings of None, no redirection will occur. PIPE indicates that a new pipe to the child should be created. DEVNULL indicates that the special file os.devnull will be used. Additionally, stderr can be STDOUT, which indicates that the stderr data from the applications should be captured into the same file handle as for stdout.

Якщо preexec_fn встановлено на об’єкт, який можна викликати, цей об’єкт буде викликано в дочірньому процесі безпосередньо перед виконанням дочірнього процесу. (лише POSIX)

Попередження

The preexec_fn parameter is NOT SAFE to use in the presence of threads in your application. The child process could deadlock before exec is called.

Примітка

If you need to modify the environment for the child use the env parameter rather than doing it in a preexec_fn. The start_new_session and process_group parameters should take the place of code using preexec_fn to call os.setsid() or os.setpgid() in the child.

Змінено в версії 3.8: Параметр preexec_fn більше не підтримується субінтерпретаторами. Використання параметра у субінтерпретаторі викликає RuntimeError. Нове обмеження може вплинути на програми, які розгортаються в mod_wsgi, uWSGI та інших вбудованих середовищах.

If close_fds is true, all file descriptors except 0, 1 and 2 will be closed before the child process is executed. Otherwise when close_fds is false, file descriptors obey their inheritable flag as described in Успадкування файлових дескрипторів.

У Windows, якщо close_fds має значення true, дочірній процес не успадкує жодних дескрипторів, якщо вони явно не передані в елементі handle_list STARTUPINFO.lpAttributeList або за допомогою стандартного переспрямування дескриптора.

Змінено в версії 3.2: Типове значення для close_fds було змінено з False на описане вище.

Змінено в версії 3.7: У Windows типове значення для close_fds було змінено з False на True під час переспрямування стандартних дескрипторів. Тепер можна встановити close_fds на True під час перенаправлення стандартних дескрипторів.

pass_fds — це необов’язкова послідовність файлових дескрипторів, які залишаються відкритими між батьківським і дочірнім. Надання будь-якого pass_fds змушує close_fds мати значення True. (лише POSIX)

Змінено в версії 3.2: Додано параметр pass_fds.

Якщо cwd не є None, функція змінює робочий каталог на cwd перед виконанням дочірнього елемента. cwd може бути рядком, байтами або об’єктом path-like. У POSIX функція шукає виконуваний файл (або перший елемент у args) відносно cwd, якщо шлях до виконуваного файлу є відносним.

Змінено в версії 3.6: Параметр cwd приймає path-like object на POSIX.

Змінено в версії 3.7: Параметр cwd приймає path-like object у Windows.

Змінено в версії 3.8: Параметр cwd приймає об’єкт bytes у Windows.

Якщо restore_signals має значення true (за замовчуванням), усі сигнали, які Python встановив як SIG_IGN, відновлюються до SIG_DFL у дочірньому процесі перед виконанням. Наразі це включає сигнали SIGPIPE, SIGXFZ і SIGXFSZ. (лише POSIX)

Змінено в версії 3.2: Додано restore_signals.

If start_new_session is true the setsid() system call will be made in the child process prior to the execution of the subprocess.

Availability: POSIX

Змінено в версії 3.2: Додано start_new_session.

If process_group is a non-negative integer, the setpgid(0, value) system call will be made in the child process prior to the execution of the subprocess.

Availability: POSIX

Змінено в версії 3.11: process_group was added.

If group is not None, the setregid() system call will be made in the child process prior to the execution of the subprocess. If the provided value is a string, it will be looked up via grp.getgrnam() and the value in gr_gid will be used. If the value is an integer, it will be passed verbatim. (POSIX only)

Availability: POSIX

Added in version 3.9.

If extra_groups is not None, the setgroups() system call will be made in the child process prior to the execution of the subprocess. Strings provided in extra_groups will be looked up via grp.getgrnam() and the values in gr_gid will be used. Integer values will be passed verbatim. (POSIX only)

Availability: POSIX

Added in version 3.9.

If user is not None, the setreuid() system call will be made in the child process prior to the execution of the subprocess. If the provided value is a string, it will be looked up via pwd.getpwnam() and the value in pw_uid will be used. If the value is an integer, it will be passed verbatim. (POSIX only)

Availability: POSIX

Added in version 3.9.

Якщо umask не є негативним, системний виклик umask() буде здійснено в дочірньому процесі перед виконанням підпроцесу.

Availability: POSIX

Added in version 3.9.

If env is not None, it must be a mapping that defines the environment variables for the new process; these are used instead of the default behavior of inheriting the current process“ environment. This mapping can be str to str on any platform or bytes to bytes on POSIX platforms much like os.environ or os.environb.

Примітка

Якщо вказано, env має надавати будь-які змінні, необхідні для виконання програми. У Windows, щоб запустити паралельну збірку (side-by-side assembly), указаний env має містити дійсний SystemRoot.

If encoding or errors are specified, or text is true, the file objects stdin, stdout and stderr are opened in text mode with the specified encoding and errors, as described above in Часто використовувані аргументи. The universal_newlines argument is equivalent to text and is provided for backwards compatibility. By default, file objects are opened in binary mode.

Added in version 3.6: Додано кодування та помилки.

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

If given, startupinfo will be a STARTUPINFO object, which is passed to the underlying CreateProcess function.

If given, creationflags, can be one or more of the following flags:

• CREATE_NEW_CONSOLE

• CREATE_NEW_PROCESS_GROUP

• ВИЩЕ_ЗВИЧАЙНОГО_ПРІОРИТЕТНОГО_КЛАСУ

• 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: Added the pipesize parameter.

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

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

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

Змінено в версії 3.2: Додано підтримку менеджера контексту.

Змінено в версії 3.6: Деструктор Popen тепер видає попередження ResourceWarning, якщо дочірній процес все ще виконується.

Змінено в версії 3.8: Popen може використовувати os.posix_spawn() у деяких випадках для кращої продуктивності. У підсистемі Windows для Linux і емуляції користувача QEMU конструктор Popen, що використовує os.posix_spawn(), більше не створює виняток у разі помилки, як-от відсутня програма, але дочірній процес завершується помилкою з ненульовим returncode.

Винятки

Винятки, створені в дочірньому процесі, перш ніж нова програма почне виконуватися, будуть повторно викликані в батьківському.

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

Помилка ValueError буде викликана, якщо Popen викликається з недійсними аргументами.

check_call() і check_output() викличуть CalledProcessError, якщо викликаний процес повертає ненульовий код повернення.

All of the functions and methods that accept a timeout parameter, such as run() and Popen.communicate() will raise TimeoutExpired if the timeout expires before the process exits.

Усі винятки, визначені в цьому модулі, успадковуються від SubprocessError.

Added in version 3.3: Додано базовий клас SubprocessError.

Міркування безпеки

Unlike some other popen functions, this library will not implicitly choose to call a system shell. This means that all characters, including shell metacharacters, can safely be passed to child processes. If the shell is invoked explicitly, via shell=True, it is the application’s responsibility to ensure that all whitespace and metacharacters are quoted appropriately to avoid shell injection vulnerabilities. On some platforms, it is possible to use shlex.quote() for this escaping.

On Windows, batch files (*.bat or *.cmd) may be launched by the operating system in a system shell regardless of the arguments passed to this library. This could result in arguments being parsed according to shell rules, but without any escaping added by Python. If you are intentionally launching a batch file with arguments from untrusted sources, consider passing shell=True to allow Python to escape special characters. See gh-114539 for additional discussion.

Відкрити об’єкти

Екземпляри класу Popen мають такі методи:

Popen.poll()

Перевірте, чи завершився дочірній процес. Встановити та повернути атрибут returncode. В іншому випадку повертає None.

Popen.wait(timeout=None)

Дочекайтеся завершення дочірнього процесу. Встановити та повернути атрибут returncode.

Якщо процес не завершується після тайм-ауту секунд, викличте виняток TimeoutExpired. Можна безпечно перехопити цей виняток і повторити очікування.

Примітка

Це призведе до взаємоблокування під час використання stdout=PIPE або stderr=PIPE, і дочірній процес генерує достатню кількість виводу в канал, щоб блокувати очікування, поки буфер каналу ОС прийме більше даних. Використовуйте Popen.communicate() під час використання каналів, щоб уникнути цього.

Примітка

When the timeout parameter is not None, then (on POSIX) the function is implemented using a busy loop (non-blocking call and short sleeps). Use the asyncio module for an asynchronous wait: see asyncio.create_subprocess_exec.

Змінено в версії 3.3: Додано тайм-аут.

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

Взаємодія з процесом: надсилання даних на stdin. Читання даних із stdout і stderr, доки не буде досягнуто кінця файлу. Зачекайте, поки процес завершиться, і встановіть атрибут returncode. Додатковий аргумент input має бути даними, які надсилаються дочірньому процесу, або None, якщо дані не повинні надсилатися дочірньому процесу. Якщо потоки були відкриті в текстовому режимі, введення має бути рядком. В іншому випадку це повинні бути байти.

communicate() повертає кортеж (stdout_data, stderr_data). Дані будуть рядками, якщо потоки були відкриті в текстовому режимі; інакше, байти.

Зауважте, що якщо ви хочете надіслати дані на стандартний вхід процесу, вам потрібно створити об’єкт Popen за допомогою stdin=PIPE. Подібним чином, щоб отримати щось інше, окрім None у кортежі результатів, вам також потрібно вказати stdout=PIPE та/або stderr=PIPE.

Якщо процес не завершиться після тайм-ауту секунд, буде викликано виняток TimeoutExpired. Перехоплення цього винятку та повторна спроба зв’язку не призведуть до втрати вихідних даних.

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

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

Примітка

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

Змінено в версії 3.3: Додано тайм-аут.

Popen.send_signal(signal)

Посилає сигнал сигнал дитині.

Нічого не робити, якщо процес завершено.

Примітка

On Windows, SIGTERM is an alias for terminate(). CTRL_C_EVENT and CTRL_BREAK_EVENT can be sent to processes started with a creationflags parameter which includes CREATE_NEW_PROCESS_GROUP.

Popen.terminate()

Stop the child. On POSIX OSs the method sends SIGTERM to the child. On Windows the Win32 API function TerminateProcess() is called to stop the child.

Popen.kill()

Вбиває дитину. В ОС POSIX функція надсилає SIGKILL дочірньому. У Windows kill() є псевдонімом для terminate().

The following attributes are also set by the class for you to access. Reassigning them to new values is unsupported:

Popen.args

Аргумент args, як його було передано до Popen – послідовність аргументів програми або один рядок.

Added in version 3.3.

Popen.stdin

If the stdin argument was PIPE, this attribute is a writeable stream object as returned by open(). If the encoding or errors arguments were specified or the text or universal_newlines argument was True, the stream is a text stream, otherwise it is a byte stream. If the stdin argument was not PIPE, this attribute is None.

Popen.stdout

If the stdout argument was PIPE, this attribute is a readable stream object as returned by open(). Reading from the stream provides output from the child process. If the encoding or errors arguments were specified or the text or universal_newlines argument was True, the stream is a text stream, otherwise it is a byte stream. If the stdout argument was not PIPE, this attribute is None.

Popen.stderr

If the stderr argument was PIPE, this attribute is a readable stream object as returned by open(). Reading from the stream provides error output from the child process. If the encoding or errors arguments were specified or the text or universal_newlines argument was True, the stream is a text stream, otherwise it is a byte stream. If the stderr argument was not PIPE, this attribute is None.

Попередження

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

Popen.pid

Ідентифікатор дочірнього процесу.

Зауважте, що якщо ви встановите для аргументу shell значення True, це буде ідентифікатор процесу створеної оболонки.

Popen.returncode

The child return code. Initially None, returncode is set by a call to the poll(), wait(), or communicate() methods if they detect that the process has terminated.

A None value indicates that the process hadn’t yet terminated at the time of the last method call.

Від’ємне значення -N вказує на те, що дочірній елемент було завершено сигналом N (лише POSIX).

Windows Open Helpers

Клас 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 має бути істинним, якщо воно не порожнє.

os.set_handle_inheritable() під час передачі в конструктор Popen дескрипторів має бути тимчасово успадкованим, інакше OSError буде викликано помилкою Windows ERROR_INVALID_PARAMETER (87).

Попередження

У багатопотоковому процесі будьте обережні, щоб уникнути витоку дескрипторів, позначених як успадковані, коли поєднуєте цю функцію з одночасними викликами інших функцій створення процесу, які успадковують усі дескриптори, наприклад os.system(). Це також стосується стандартного перенаправлення дескрипторів, яке тимчасово створює успадковані дескриптори.

Added in version 3.7.

Константи Windows

Модуль subprocess надає такі константи.

subprocess.STD_INPUT_HANDLE

Стандартний пристрій введення. Спочатку це буфер введення консолі, CONIN$.

subprocess.STD_OUTPUT_HANDLE

Стандартний пристрій виведення. Спочатку це активний буфер екрана консолі, CONOUT$.

subprocess.STD_ERROR_HANDLE

Пристрій стандартної помилки. Спочатку це активний буфер екрана консолі, CONOUT$.

subprocess.SW_HIDE

Приховує вікно. Буде активовано інше вікно.

subprocess.STARTF_USESTDHANDLES

Вказує, що атрибути STARTUPINFO.hStdInput, STARTUPINFO.hStdOutput і STARTUPINFO.hStdError містять додаткову інформацію.

subprocess.STARTF_USESHOWWINDOW

Вказує, що атрибут STARTUPINFO.wShowWindow містить додаткову інформацію.

subprocess.STARTF_FORCEONFEEDBACK

A STARTUPINFO.dwFlags parameter to specify that the Working in Background mouse cursor will be displayed while a process is launching. This is the default behavior for GUI processes.

Added in version 3.13.

subprocess.STARTF_FORCEOFFFEEDBACK

A STARTUPINFO.dwFlags parameter to specify that the mouse cursor will not be changed when launching a process.

Added in version 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, щоб вказати, що новий процес матиме пріоритет вище середнього.

Added in version 3.7.

subprocess.BELOW_NORMAL_PRIORITY_CLASS

Параметр Popen creationflags, щоб вказати, що новий процес матиме пріоритет нижче середнього.

Added in version 3.7.

subprocess.HIGH_PRIORITY_CLASS

Параметр Popen creationflags, щоб вказати, що новий процес матиме високий пріоритет.

Added in version 3.7.

subprocess.IDLE_PRIORITY_CLASS

Параметр Popen creationflags, щоб вказати, що новий процес матиме неактивний (найнижчий) пріоритет.

Added in version 3.7.

subprocess.NORMAL_PRIORITY_CLASS

A Popen creationflags parameter to specify that a new process will have a normal priority. (default)

Added in version 3.7.

subprocess.REALTIME_PRIORITY_CLASS

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

Added in version 3.7.

subprocess.CREATE_NO_WINDOW

Параметр Popen creationflags, щоб вказати, що новий процес не створюватиме вікно.

Added in version 3.7.

subprocess.DETACHED_PROCESS

Параметр Popen creationflags, щоб вказати, що новий процес не успадковуватиме батьківську консоль. Це значення не можна використовувати з CREATE_NEW_CONSOLE.

Added in version 3.7.

subprocess.CREATE_DEFAULT_ERROR_MODE

Параметр Popen creationflags, щоб вказати, що новий процес не успадковує режим помилки процесу, що викликає. Натомість новий процес отримує стандартний режим помилки. Ця функція особливо корисна для багатопоточних програм оболонки, які працюють із вимкненими серйозними помилками.

Added in version 3.7.

subprocess.CREATE_BREAKAWAY_FROM_JOB

Параметр Popen creationflags, щоб вказати, що новий процес не пов’язаний із завданням.

Added in version 3.7.

Старіший API високого рівня

До Python 3.5 ці три функції містили API високого рівня для підпроцесу. Тепер ви можете використовувати run() у багатьох випадках, але багато існуючого коду викликають ці функції.

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

Виконайте команду, описану args. Зачекайте, поки команда завершиться, а потім поверніть атрибут returncode.

Код, який потребує захоплення stdout або stderr, повинен використовувати замість цього run():

run(...).returncode

Щоб придушити stdout або stderr, укажіть значення DEVNULL.

Аргументи, наведені вище, є лише поширеними. Повний підпис функції такий самий, як і у конструктора Popen - ця функція передає всі надані аргументи, окрім timeout, безпосередньо до цього інтерфейсу.

Примітка

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

Змінено в версії 3.3: Додано тайм-аут.

Змінено в версії 3.12: Changed Windows shell search order for shell=True. The current directory and %PATH% are replaced with %COMSPEC% and %SystemRoot%\System32\cmd.exe. As a result, dropping a malicious program named cmd.exe into a current directory no longer works.

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

Виконати команду з аргументами. Дочекайтеся виконання команди. Якщо код повернення дорівнює нулю, тоді повертається, інакше викликається CalledProcessError. Об’єкт CalledProcessError матиме код повернення в атрибуті returncode. Якщо check_call() не вдалося запустити процес, він поширить викликану виняткову ситуацію.

Код, який потребує захоплення stdout або stderr, повинен використовувати замість цього run():

run(..., check=True)

Щоб придушити stdout або stderr, укажіть значення DEVNULL.

Аргументи, наведені вище, є лише поширеними. Повний підпис функції такий самий, як і у конструктора Popen - ця функція передає всі надані аргументи, окрім timeout, безпосередньо до цього інтерфейсу.

Примітка

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

Змінено в версії 3.3: Додано тайм-аут.

Змінено в версії 3.12: Changed Windows shell search order for shell=True. The current directory and %PATH% are replaced with %COMSPEC% and %SystemRoot%\System32\cmd.exe. As a result, dropping a malicious program named cmd.exe into a current directory no longer works.

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'

Added in version 3.1.

Змінено в версії 3.3: Додано тайм-аут.

Змінено в версії 3.4: Додано підтримку аргументу ключового слова input.

Змінено в версії 3.6: Додано кодування та помилки. Перегляньте run() для деталей.

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

Змінено в версії 3.12: Changed Windows shell search order for shell=True. The current directory and %PATH% are replaced with %COMSPEC% and %SystemRoot%\System32\cmd.exe. As a result, dropping a malicious program named cmd.exe into a current directory no longer works.

Заміна старих функцій модулем 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")

Replacing functions from the popen2 module

Примітка

Якщо аргумент 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.

Застарілі функції виклику оболонки

Цей модуль також надає такі застарілі функції з модуля команд 2.x. Ці операції неявно викликають системну оболонку, і жодна з описаних вище гарантій безпеки та узгодженості обробки винятків не діє для цих функцій.

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

Повернення (код виходу, вихід) виконання cmd в оболонці.

Execute the string cmd in a shell with Popen.check_output() and return a 2-tuple (exitcode, output). encoding and errors are used to decode output; see the notes on Часто використовувані аргументи for more details.

Кінцевий символ нового рядка видаляється з результату. Код виходу для команди можна інтерпретувати як код повернення підпроцесу. Приклад:

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

Availability: Unix, Windows.

Змінено в версії 3.3.4: Додано підтримку Windows.

Тепер функція повертає (код виходу, вихід) замість (статус, вихід), як це було в Python 3.3.3 і попередніх версіях. код виходу має те саме значення, що й returncode.

Змінено в версії 3.11: Added the encoding and errors parameters.

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

Вихідні дані (stdout і stderr) виконання cmd в оболонці.

Як getstatusoutput(), за винятком того, що код виходу ігнорується, а значення, що повертається, є рядком, що містить вихідні дані команди. Приклад:

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

Availability: Unix, Windows.

Змінено в версії 3.3.4: Додано підтримку Windows

Змінено в версії 3.11: Added the encoding and errors parameters.

Примітки

Перетворення послідовності аргументів на рядок у Windows

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

1. Аргументи розділені пробілом, який є пробілом або табуляцією.

2. Рядок, взятий у подвійні лапки, інтерпретується як один аргумент, незалежно від пробілу, що міститься в ньому. Рядок у лапках можна вставити в аргумент.

3. Подвійні лапки, перед якими стоїть зворотна скісна риска, інтерпретуються як буквальні подвійні лапки.

4. Зворотні косі риски інтерпретуються буквально, якщо вони не стоять безпосередньо перед подвійними лапками.

5. Якщо зворотні похилі риски безпосередньо передують подвійним лапкам, кожна пара зворотних похилих рисок інтерпретується як буквальна зворотна похила риска. Якщо кількість зворотних скісних рисок непарна, остання зворотна скісна риска виходить із наступних подвійних лапок, як описано в правилі 3.

Дивись також

shlex

Модуль, який забезпечує функцію аналізу та екранування командних рядків.

Disabling use of vfork() or posix_spawn()

On Linux, subprocess defaults to using the vfork() system call internally when it is safe to do so rather than fork(). This greatly improves performance.

If you ever encounter a presumed highly unusual situation where you need to prevent vfork() from being used by Python, you can set the subprocess._USE_VFORK attribute to a false value.

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

Setting this has no impact on use of posix_spawn() which could use vfork() internally within its libc implementation. There is a similar subprocess._USE_POSIX_SPAWN attribute if you need to prevent use of that.

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

It is safe to set these to false on any Python version. They will have no effect on older versions when unsupported. Do not assume the attributes are available to read. Despite their names, a true value does not indicate that the corresponding function will be used, only that it may be.

Please file issues any time you have to use these private knobs with a way to reproduce the issue you were seeing. Link to that issue from a comment in your code.

Added in version 3.8: _USE_POSIX_SPAWN

Added in version 3.11: _USE_VFORK