# `subprocess` — Subprocess management

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

The `subprocess` module allows you to spawn new processes, connect to their input/output/error pipes, and obtain their return codes. This module intends to replace several older modules and functions:

    os.system
    os.spawn*

Information about how the `subprocess` module can be used to replace these modules and functions can be found in the following sections.

Дивись також

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

Availability: not Android, not iOS, not WASI.

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

## Using the `subprocess` Module

Рекомендований підхід до виклику підпроцесів полягає у використанні функції `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)

  Примітка

  Specifying user will not drop existing supplementary group memberships! The caller must also pass `extra_groups=()` to reduce the group membership of the child process for security purposes.

  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`.

  Примітка

  If specified, env must provide any variables required for the program to execute. On Windows, in order to run a side-by-side assembly the specified env must include a valid `%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 `timeout` is not `None` and the platform supports it, an efficient event-driven mechanism is used to wait for process termination:

  - Linux >= 5.3 uses `os.pidfd_open()` + `select.poll()`

  - macOS and other BSD variants use `select.kqueue()` + `KQ_FILTER_PROC` + `KQ_NOTE_EXIT`

  - Windows uses `WaitForSingleObject`

  If none of these mechanisms are available, the function falls back to a busy loop (non-blocking call and short sleeps).

  Примітка

  Use the `asyncio` module for an asynchronous wait: see `asyncio.create_subprocess_exec`.

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

  Змінено в версії 3.15: if timeout is not `None`, use efficient event-driven implementation on Linux >= 5.3 and macOS / BSD.

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`.

  If the process does not terminate after timeout seconds, a `TimeoutExpired` exception will be raised. Catching this exception and retrying communication will not lose any output. Supplying input to a subsequent post-timeout `communicate()` call is in undefined behavior and may become an error in the future.

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

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

  After a call to `communicate()` raises `TimeoutExpired`, do not call `wait()`. Use an additional `communicate()` call to finish handling pipes and populate the `returncode` attribute.

  Примітка

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

  Змінено в версії 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).

  When `shell=True`, the return code reflects the exit status of the shell itself (e.g. `/bin/sh`), which may map signals to codes such as `128+N`. See the documentation of the shell (for example, the Bash manual’s Exit Status) for details.

## 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

The `subprocess` module exposes the following constants.

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.

## Replacing Older Functions with the `subprocess` Module

У цьому розділі «a стає b» означає, що b можна використовувати як заміну a.

Примітка

Усі функції «a» в цьому розділі виходять з ладу (більш-менш) тихо, якщо виконувану програму неможливо знайти; натомість заміни «b» викликають `OSError`.

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

In the following examples, we assume that the relevant functions have already been imported from the `subprocess` module.

### Заміна команди оболонки /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()`.

- The `os.system()` function ignores SIGINT and SIGQUIT signals while the command is running, but the caller must do this separately when using the `subprocess` module.

Більш реалістичний приклад виглядатиме так:

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

### Replacing `os.popen()`

Обробка коду повернення перекладається наступним чином:

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

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

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

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

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

  Execute the string cmd in a shell with `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.

## Примітки

### Timeout Behavior

When using the `timeout` parameter in functions like `run()`, `Popen.wait()`, or `Popen.communicate()`, users should be aware of the following behaviors:

1. Process Creation Delay: The initial process creation itself cannot be interrupted on many platform APIs. This means that even when specifying a timeout, you are not guaranteed to see a timeout exception until at least after however long process creation takes.

2. Extremely Small Timeout Values: Setting very small timeout values (such as a few milliseconds) may result in almost immediate `TimeoutExpired` exceptions because process creation and system scheduling inherently require time.

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

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

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

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

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

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

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

Дивись також

`shlex`

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

### Disable use of `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.

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

It is safe to set this to false on any Python version. It will have no effect on older or newer versions where unsupported. Do not assume the attribute is available to read. Despite the name, a true value does not indicate 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`