"subprocess" --- サブプロセス管理
*********************************

**ソースコード:** Lib/subprocess.py

======================================================================

"subprocess" モジュールでは、新しいプロセスを生成し、その標準入力、標
準出力、標準エラー出力のパイプに接続して、終了コードを取得できます。
このモジュールは、次のような古いモジュールや関数を置き換えるためのもの
です。

   os.system
   os.spawn*

"subprocess" モジュールでこれらのモジュールや関数を置き換える方法は、
後の節で説明します。

参考: **PEP 324** -- subprocess モジュールを提案している PEP

利用可能な環境: not Android, not iOS, not WASI.

このモジュールは モバイルプラットフォーム と WebAssemblyプラットフォー
ム をサポートしません。


"subprocess" モジュールの使用
=============================

サブプロセスの起動には、"run()" 関数で対応できる用途であればこの関数を
使うことを推奨します。 より高度な用途では、下層の "Popen" インターフェ
ースを直接使用できます。

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

   *args* で指定されたコマンドを実行します。コマンドの完了を待って、
   "CompletedProcess" インスタンスを返します。

   上記の引数は、もっともよく使われるものだけ示しており、後述の よく使
   われる引数 で説明されています (そのためここではキーワード専用引数の
   表記に省略されています)。 関数の完全な使用法を説明しても大部分が
   "Popen" コンストラクターの内容と同じになります - この関数のほとんど
   の引数は "Popen" インターフェイスに渡されます。 (*timeout*、*input*
   、*check*、*capture_output* は除きます。 )

   *capture_output* が真なら、標準出力と標準エラー出力を捕捉します。
   この指定を使うと、内部の "Popen" オブジェクトは *stdout* と
   *stderr* の両方を "PIPE" に設定して自動的に作成されます。 *stdout*
   や *stderr* 引数は *capture_output* と同時には指定できません。 両方
   のストリームをまとめて捕捉するには、*capture_output* を使わず、
   *stdout* を "PIPE"、*stderr* を "STDOUT" に設定してください。

   *timeout* には秒数を指定でき、内部で "Popen.communicate()" に渡され
   ます。 タイムアウトすると子プロセスを強制終了させ、その終了を待ちま
   す。 子プロセスが終了した後に "TimeoutExpired" 例外を再送出します。
   多くのプラットフォームの API では最初のプロセス作成自体を中断できな
   いため、少なくともプロセス作成にかかる時間が経過するまでは、タイム
   アウト例外が発生する保証はありません。

   *input* 引数は "Popen.communicate()" に渡され、サブプロセスの標準入
   力に送られます。 指定する場合はバイト列にする必要がありますが、
   *encoding* または *errors* を指定するか *text* が真なら文字列にしま
   す。 この指定を使うと、内部の "Popen" オブジェクトは *stdin* を
   "PIPE" に設定して自動的に作成されるため、*stdin* 引数は併用できませ
   ん。

   *check* に真を指定した場合、プロセスが非ゼロの終了コードで終了する
   と "CalledProcessError" 例外が送出されます。 この例外の属性には、引
   数、終了コード、標準出力および標準エラー出力が捕捉できた場合に格納
   されます。

   *encoding* または *errors* を指定するか、*text* が真なら、標準入力
   、標準出力、標準エラー出力のファイルオブジェクトをテキストモードで
   開きます。 その際には、指定された *encoding* と *errors*、または
   "io.TextIOWrapper" のデフォルト値を使います。 *universal_newlines*
   引数は *text* と同じ意味で、後方互換性のために用意されています。 デ
   フォルトでは、ファイルオブジェクトをバイナリモードで開きます。

   *env* が "None" でない場合は、新しいプロセスの環境変数を定義するマ
   ッピングを指定します。 現在のプロセスの環境を継承するデフォルトの動
   作に代わり、このマッピングが使用されます。 "Popen" に直接渡されます
   。 "os.environ" と同様に、どのプラットフォームでも文字列から文字列
   へのマッピングを使用できます。 POSIX では "os.environb" と同様に、
   バイト列からバイト列へのマッピングも使用できます。

   例:

      >>> subprocess.run(["ls", "-l"])  # 出力を捕捉しない
      CompletedProcess(args=['ls', '-l'], returncode=0)

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

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

   Added in version 3.5.

   バージョン 3.6 で変更: *encoding* と *errors* が引数に追加されまし
   た。

   バージョン 3.7 で変更: *universal_newlines* 引数のよりわかりやすい
   名前として、*text* 引数が追加されました。*capture_output* 引数が追
   加されました。

   バージョン 3.12 で変更: "shell=True" のときのWindowsシェル検索順序
   を変更しました。カレントディレクトリと "%PATH%" は、 "%COMSPEC%" と
   "%SystemRoot%\System32\cmd.exe" に置き換えられました。これにより、
   "cmd.exe" という名前の悪意のあるプログラムをカレントディレクトリに
   ドロップしても、動作しなくなりました。

class subprocess.CompletedProcess

   "run()" の戻り値。プロセスが終了したことを表します。

   args

      プロセスを起動するときに使用された引数。1 個のリストか 1 個の文
      字列になります。

   returncode

      子プロセスの終了コード。一般に、終了ステータス 0 はプロセスが正
      常に終了したことを示します。

      負の値 "-N" は子プロセスがシグナル "N" により中止させられたこと
      を示します (POSIX のみ)。

   stdout

      子プロセスから捕捉した標準出力です。 通常はバイト列ですが、
      "run()" に "encoding" または "errors" を指定した場合や、
      "text=True" で呼び出した場合は文字列になります。 標準出力を捕捉
      していない場合は "None" です。

      プロセスが "stderr=subprocess.STDOUT" で実行された場合、標準出力
      と標準エラー出力が混合されたものがこの属性に格納され、"stderr"
      は "None" になります。

   stderr

      子プロセスから捕捉した標準エラー出力です。 通常はバイト列ですが
      、"run()" に "encoding" または "errors" を指定した場合や、
      "text=True" で呼び出した場合は文字列になります。 標準エラー出力
      を捕捉していない場合は "None" です。

   check_returncode()

      "returncode" が非ゼロの場合、"CalledProcessError" が送出されます
      。

   Added in version 3.5.

subprocess.DEVNULL

   "Popen" の *stdin*, *stdout*, *stderr* 引数に渡して、標準入出力を
   "os.devnull" から入出力するように指定するための特殊値です。

   Added in version 3.3.

subprocess.PIPE

   "Popen" の *stdin*, *stdout*, *stderr* 引数に渡して、標準ストリーム
   に対するパイプを開くことを指定するための特殊値です。
   "Popen.communicate()" に非常に有用です。

subprocess.STDOUT

   "Popen" の *stderr* 引数に渡して、標準エラー出力が標準出力と同じハ
   ンドルに出力されるように指定するための特殊値です。

exception subprocess.SubprocessError

   このモジュールの他のすべての例外のための基底クラスです。

   Added in version 3.3.

exception subprocess.TimeoutExpired

   "SubprocessError" のサブクラスです。子プロセスの終了を待機している
   間にタイムアウトが発生した場合に送出されます。

   cmd

      子プロセスの生成に使用されるコマンド本文。

   timeout

      タイムアウト秒数。

   output

      "run()" にまたは "check_output()" によって捕捉された場合は、子プ
      ロセスの出力となり、それ以外の場合は "None" となります。
      "text=True" の設定に関係なく、出力が捕捉された場合は常に "bytes"
      となります。出力がない場合は "b''" の代わりに "None" のままにな
      ることがあります。

   stdout

      output の別名。"stderr" と対になります。

   stderr

      "run()" が捕捉した子プロセスの標準エラー出力です。 捕捉していな
      ければ "None" です。 標準エラー出力を捕捉した場合、"text=True"
      の設定にかかわらず常に "bytes" です。 出力がなければ "b''" の代
      わりに "None" のままになることがあります。

   Added in version 3.3.

   バージョン 3.5 で変更: 属性 *stdout* および *stderr* が追加されまし
   た。

exception subprocess.CalledProcessError

   "SubprocessError" のサブクラスです。"check_call()" または
   "check_output()" 、 "check=True" であるときの "run()" 、によって実
   行されたプロセスが非ゼロの終了ステータスを返した場合に送出されます
   。

   returncode

      子プロセスの終了ステータスを表す整数です。 シグナルによってプロ
      セスが終了した場合は、シグナル番号を負にした値になります。

   cmd

      子プロセスの生成に使用されるコマンド本文。

   output

      "run()" または "check_output()" によって捕捉された子プロセスの出
      力。捕捉されなかったら "None" になります。

   stdout

      output の別名。"stderr" と対になります。

   stderr

      "run()" によって捕捉された子プロセスの標準エラー出力。捕捉されな
      かったら "None" になります。

   バージョン 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*.

   *encoding* または *errors* を指定するか、*text*
   (*universal_newlines* とも呼びます) が真なら、ファイルオブジェクト
   *stdin*、*stdout*、*stderr* をテキストモードで開きます。 呼び出し時
   に指定した *encoding* と *errors*、または "io.TextIOWrapper" のデフ
   ォルト値を使います。

   *stdin* については、入力での行末文字 "'\n'" はデフォルトの行セパレ
   ーター "os.linesep" に変換されます。*stdout* と *stderr* については
   、出力での行末はすべて "'\n'" に変換されます。詳細は
   "io.TextIOWrapper" クラスのドキュメントでコンストラクターの引数
   *newline* が "None" である場合を参照してください。

   テキストモードを使わなければ、*stdin*、*stdout*、*stderr* はバイナ
   リストリームとして開かれます。 エンコーディングや行末の変換は行いま
   せん。

   バージョン 3.6 で変更: *encoding* と *errors* が引数に追加されまし
   た。

   バージョン 3.7 で変更: *universal_newlines* の別名として、*text* 引
   数が追加されました。

   注釈:

     ファイルオブジェクト "Popen.stdin"、"Popen.stdout"、
     "Popen.stderr" の "newlines" 属性は、"Popen.communicate()" メソッ
     ドでは更新されません。

   *shell* が "True" なら、指定されたコマンドはシェルによって実行され
   ます。あなたが Python を主として (ほとんどのシステムシェル以上の)
   強化された制御フローのために使用していて、さらにシェルパイプ、ファ
   イル名ワイルドカード、環境変数展開、"~" のユーザーホームディレクト
   リへの展開のような他のシェル機能への簡単なアクセスを望むなら、これ
   は有用かもしれません。しかしながら、Python 自身が多くのシェル的な機
   能の実装を提供していることに注意してください (特に "glob",
   "fnmatch", "os.walk()", "os.path.expandvars()",
   "os.path.expanduser()", "shutil")。

   バージョン 3.3 で変更: *universal_newlines* が "True" の場合、クラ
   スはエンコーディング "locale.getpreferredencoding()" の代わりに
   "locale.getpreferredencoding(False)" を使用します。この変更について
   の詳細は、 "io.TextIOWrapper" クラスを参照してください。

   注釈:

     "shell=True" を使う前に セキュリティで考慮すべき点 を読んでくださ
     い。

これらのオプションは、他のすべてのオプションとともに "Popen" コンスト
ラクターのドキュメントの中でより詳細に説明されています。


Popen コンストラクター
----------------------

このモジュールの中で、根底のプロセス生成と管理は "Popen" クラスによっ
て扱われます。簡易関数によってカバーされないあまり一般的でないケースを
開発者が扱えるように、 "Popen" クラスは多くの柔軟性を提供しています。

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

   新しいプロセスで子のプログラムを実行します。POSIX においては、子の
   プログラムを実行するために、このクラスは "os.execvpe()" のような挙
   動を使用します。Windows においては、このクラスは Windows の
   "CreateProcess()" 関数を使用します。"Popen" への引数は以下の通りで
   す。

   *args* はプログラム引数のシーケンスか、単一の文字列または *path-
   like object* でなければなりません。デフォルトでは、*args* がシーケ
   ンスの場合に実行されるプログラムは *args* の最初の要素です。*args*
   が文字列の場合、解釈はプラットフォーム依存であり、下記に説明されま
   す。デフォルトの挙動からの追加の違いについては *shell* および
   *executable* 引数を参照してください。特に明記されない限り、*args*
   をシーケンスとして渡すことが推奨されます。

   警告:

     最も確実なのは、実行ファイルに完全なパスを指定することです。 パス
     の付いていない名前を "PATH" 上で検索するには "shutil.which()" を
     使ってください。 どのプラットフォームでも、現在の Python インター
     プリタをもう一度起動するには "sys.executable" を渡すことを推奨し
     ます。 インストール済みのモジュールを起動するには、コマンドライン
     の "-m" 形式を使ってください。*executable* (または *args* の最初
     の要素) のパス解決はプラットフォームに依存します。 POSIX について
     は "os.execvpe()" を参照してください。 実行ファイルのパスを解決ま
     たは検索するとき、*cwd* はカレント作業ディレクトリを変更し、*env*
     で環境変数 "PATH" を変更できます。 Windows については、WinAPI の
     "CreateProcess" の引数 "lpApplicationName" と "lpCommandLine" の
     ドキュメントを参照してください。 "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) # 成功!

     特に注意すべき点は、シェル内でスペースで区切られたオプション
     (*-input* など) と引数 (*eggs.txt* など) はリストの別々の要素にな
     るのに対し、シェル内で (上記のスペースを含むファイル名や *echo*
     コマンドのように) クォーティングやバックスラッシュエスケープが必
     要なものは単一のリスト要素であることです。

   Windows 上では、*args* がシーケンスなら Windows における引数シーケ
   ンスから文字列への変換 に記述された方法で文字列に変換されます。これ
   は根底の "CreateProcess()" が文字列上で動作するからです。

   バージョン 3.6 で変更: POSIX では、*shell* が "False" の場合に
   *args* 引数が *path-like object*、およびパス類似オブジェクトを含む
   シーケンスを受け付けるようになりました。

   バージョン 3.8 で変更: Windows では、*shell* が "False" の場合に
   *args* 引数が *path-like object*、およびバイト列やパス類似オブジェ
   クトを含むシーケンスを受け付けるようになりました。

   *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" 環境変数がデフォルトシ
   ェルを指定します。Windows で "shell=True" を指定する必要があるのは
   、実行したいコマンドがシェルに組み込みの場合だけです (例えば
   **dir** や **copy**)。バッチファイルやコンソールベースの実行ファイ
   ルを実行するために "shell=True" は必要ありません。

   注釈:

     "shell=True" を使う前に セキュリティで考慮すべき点 を読んでくださ
     い。

   *bufsize* は標準入力/標準出力/標準エラー出力パイプファイルオブジェ
   クトを生成するときに "open()" 関数の対応する引数に渡されます:

   * "0" はバッファリングなしを意味します (読み書きは 1 回のシステムコ
     ールで行われ、要求した量より少ないデータで戻ることがあります)。

   * "1" は行バッファリングを意味します ("text=True" または
     "universal_newlines=True" の場合にだけ使えます)。

   * それ以外の正の整数はバッファーのおよそのサイズになることを意味し
     ます。

   * 負のサイズ (デフォルト) は io.DEFAULT_BUFFER_SIZE のシステムデフ
     ォルトが使用されることを意味します。

   バージョン 3.3.1 で変更: *bufsize* のデフォルトが -1 になりました。
   これにより、多くのコードが期待する動作に合わせ、デフォルトでバッフ
   ァリングが有効になります。 Python 3.2.4 および 3.3.1 より前のバージ
   ョンでは、誤ってデフォルトが "0" になっており、バッファリングなしで
   要求した量より少ない読み出しが起こり得ました。 これは意図したもので
   はなく、多くのコードが期待する Python 2 の動作とも異なっていました
   。

   *executable* 引数は、実行する置換プログラムを指定します。これが必要
   になるのは極めて稀です。"shell=False" のときは、*executable* は
   *args* で指定されている実行プログラムを置換します。しかし、オリジナ
   ルの *args* は依然としてプログラムに渡されます。ほとんどのプログラ
   ムは、*args* で指定されたプログラムをコマンド名として扱います。そし
   て、それは実際に実行されたプログラムとは異なる可能性があります。
   POSIX において、**ps** のようなユーティリティの中では、*args* 名が
   実行ファイルの表示名になります。"shell=True" の場合、POSIX において
   *executable* 引数はデフォルトの "/bin/sh" に対する置換シェルを指定
   します。

   バージョン 3.6 で変更: *executable* 引数が POSIX で *path-like
   object* を受け付けるようになりました。

   バージョン 3.8 で変更: Windows で *executable* 引数がバイト列と
   *path-like object* を受け付けるようになりました。

   バージョン 3.12 で変更: "shell=True" のときのWindowsシェル検索順序
   を変更しました。カレントディレクトリと "%PATH%" は、 "%COMSPEC%" と
   "%SystemRoot%\System32\cmd.exe" に置き換えられました。これにより、
   "cmd.exe" という名前の悪意のあるプログラムをカレントディレクトリに
   ドロップしても、動作しなくなりました。

   *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* に呼び出し可能オブジェクトが指定されている場合、このオ
   ブジェクトは子プロセスが実行される直前 (fork されたあと、exec され
   る直前) に子プロセス内で呼ばれます。(POSIXのみ)

   警告:

     アプリケーション中に複数のスレッドが存在する状態で *preexec_fn*
     引数を使用するのは**安全ではありません**。exec が呼ばれる前に子プ
     ロセスがデッドロックを起こすことがあります。

   注釈:

     子プロセスの環境を変更する場合は、*preexec_fn* 内で行う代わりに
     *env* 引数を使ってください。 *preexec_fn* を使って子プロセスで
     "os.setsid()" や "os.setpgid()" を呼び出すコードは、
     *start_new_session* や *process_group* 引数で置き換えてください。

   バージョン 3.8 で変更: サブインタープリタでは *preexec_fn* 引数を使
   えなくなりました。 サブインタープリタでこの引数を使うと
   "RuntimeError" を送出します。 この新しい制限は、mod_wsgi、uWSGI、そ
   の他の埋め込み環境に配置されたアプリケーションに影響することがあり
   ます。

   *close_fds* が真なら、子プロセスの実行前に "0"、"1"、"2" を除くすべ
   てのファイル記述子を閉じます。 *close_fds* が偽なら、ファイル記述子
   は ファイル記述子の継承 で説明されている継承可能フラグに従います。

   Windows では *close_fds* が真の場合、"STARTUPINFO.lpAttributeList"
   の "handle_list" 要素で明示的に渡したハンドルと、標準ハンドルのリダ
   イレクトで渡したものを除き、子プロセスはハンドルを継承しません。

   バージョン 3.2 で変更: *close_fds* のデフォルトは、"False" から上記
   のものに変更されました。

   バージョン 3.7 で変更: Windows では、標準ハンドルをリダイレクトする
   ときの *close_fds* のデフォルトが "False" から "True" に変わりまし
   た。 標準ハンドルをリダイレクトするときも *close_fds* を "True" に
   設定できるようになりました。

   *pass_fds* はオプションで、親と子の間で開いたままにしておくファイル
   記述子のシーケンスを指定します。何らかの *pass_fds* を渡した場合、
   *close_fds* は強制的に "True" になります。(POSIXのみ)

   バージョン 3.2 で変更: *pass_fds* 引数が追加されました。

   *cwd* が "None" でなければ、子プロセスを実行する前に作業ディレクト
   リを *cwd* に変更します。 *cwd* には文字列、バイト列、*パス類似オブ
   ジェクト* を指定できます。 POSIX では、実行ファイルのパスが相対パス
   なら、*executable* (または *args* の最初の要素) を *cwd* からの相対
   パスとして検索します。

   バージョン 3.6 で変更: *cwd* 引数が POSIX で *path-like object* を
   受け付けるようになりました。

   バージョン 3.7 で変更: *cwd* 引数が Windows で *path-like object*
   を受け付けるようになりました。

   バージョン 3.8 で変更: *cwd* 引数が Windows で bytes オブジェクトを
   受け付けるようになりました。

   *restore_signals* が真の場合 (デフォルト)、Python が "SIG_IGN" に設
   定したすべてのシグナルの処理を、子プロセスで exec を実行する前に
   "SIG_DFL" に戻します。 現在の対象は "SIGPIPE"、"SIGXFZ"、"SIGXFSZ"
   です (POSIX のみ)。

   バージョン 3.2 で変更: *restore_signals* が追加されました。

   *start_new_session* が真なら、サブプロセスを実行する前に子プロセス
   内で "setsid()" システムコールを呼び出します。

   利用可能な環境: POSIX

   バージョン 3.2 で変更: *start_new_session* が追加されました。

   *process_group* が非負の整数なら、サブプロセスを実行する前に子プロ
   セス内で "setpgid(0, value)" システムコールを呼び出します。

   利用可能な環境: POSIX

   バージョン 3.11 で変更: *process_group* が追加されました。

   *group* が "None" でなければ、サブプロセスを実行する前に子プロセス
   内で "setregid()" システムコールを呼び出します。 指定した値が文字列
   なら "grp.getgrnam()" で検索し、"gr_gid" の値を使います。 整数なら
   そのまま渡します (POSIX のみ)。

   利用可能な環境: POSIX

   Added in version 3.9.

   *extra_groups* が "None" でなければ、サブプロセスを実行する前に子プ
   ロセス内で "setgroups()" システムコールを呼び出します。
   *extra_groups* に含まれる文字列は "grp.getgrnam()" で検索し、
   "gr_gid" の値を使います。 整数はそのまま渡します (POSIX のみ)。

   利用可能な環境: POSIX

   Added in version 3.9.

   *user* が "None" でなければ、サブプロセスを実行する前に子プロセス内
   で "setreuid()" システムコールを呼び出します。 指定した値が文字列な
   ら "pwd.getpwnam()" で検索し、"pw_uid" の値を使います。 整数ならそ
   のまま渡します (POSIX のみ)。

   注釈:

     *user* を指定しても、既存の補助グループへの所属は解除されません。
     セキュリティ上の目的で子プロセスの所属グループを減らすには、呼び
     出し側で "extra_groups=()" も渡す必要があります。

   利用可能な環境: POSIX

   Added in version 3.9.

   *umask* が負でなければ、サブプロセスを実行する前に子プロセス内で
   "umask()" システムコールを呼び出します。

   利用可能な環境: POSIX

   Added in version 3.9.

   *env* が "None" でない場合は、新しいプロセスの環境変数を定義するマ
   ッピングを指定します。 現在のプロセスの環境を継承するデフォルトの動
   作に代わり、このマッピングが使用されます。 "os.environ" と同様に、
   どのプラットフォームでも文字列から文字列へのマッピングを使用できま
   す。 POSIX では "os.environb" と同様に、バイト列からバイト列へのマ
   ッピングも使用できます。

   注釈:

     *env* を指定する場合、プログラムの実行に必要な環境変数をすべて含
     める必要があります。 Windows で side-by-side assembly を実行する
     には、*env* に有効な "%SystemRoot%" を **必ず** 含めてください。

   *encoding* または *errors* を指定するか *text* が真なら、前述の よ
   く使われる引数 のとおり、ファイルオブジェクト *stdin*、*stdout*、
   *stderr* は指定した *encoding* と *errors* を使うテキストモードで開
   かれます。 *universal_newlines* 引数は *text* と同じ意味で、後方互
   換性のために用意されています。 デフォルトでは、ファイルオブジェクト
   はバイナリモードで開かれます。

   Added in version 3.6: *encoding* と *errors* が追加されました。

   Added in version 3.7: *text* が、*universal_newlines* のより読みや
   すい別名として追加されました。

   *startupinfo* を指定する場合は "STARTUPINFO" オブジェクトにします。
   内部の "CreateProcess" 関数に渡されます。

   *creationflags* には、次のフラグを 1 つ以上指定できます:

   * "CREATE_NEW_CONSOLE"

   * "CREATE_NEW_PROCESS_GROUP"

   * "ABOVE_NORMAL_PRIORITY_CLASS"

   * "BELOW_NORMAL_PRIORITY_CLASS"

   * "HIGH_PRIORITY_CLASS"

   * "IDLE_PRIORITY_CLASS"

   * "NORMAL_PRIORITY_CLASS"

   * "REALTIME_PRIORITY_CLASS"

   * "CREATE_NO_WINDOW"

   * "DETACHED_PROCESS"

   * "CREATE_DEFAULT_ERROR_MODE"

   * "CREATE_BREAKAWAY_FROM_JOB"

   *stdin*、*stdout*、*stderr* に "PIPE" を使う場合、*pipesize* でパイ
   プのサイズを変更できます。 サイズが変更されるのは、この機能に対応す
   るプラットフォームだけです (執筆時点では Linux のみ)。 ほかのプラッ
   トフォームでは、この引数は無視されます。

   バージョン 3.10 で変更: *pipesize* 引数が追加されました。

   Popen オブジェクトは "with" 文によってコンテキストマネージャーとし
   てサポートされます: 終了時には標準ファイル記述子が閉じられ、プロセ
   スを待機します:

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

   "Popen" と、それを使うこのモジュールのほかの関数は、引数
   "executable"、"args"、"cwd"、"env" を持つ 監査イベント
   "subprocess.Popen" を発生させます。 プラットフォームによって、
   "args" の値は単一の文字列または文字列のリストになります。

   バージョン 3.2 で変更: コンテキストマネージャーサポートが追加されま
   した。

   バージョン 3.6 で変更: 子プロセスがまだ実行中の場合、"Popen" のデス
   トラクタが "ResourceWarning" 警告を出すようになりました。

   バージョン 3.8 で変更: "Popen" は、性能を向上させるため、一部の場合
   に "os.posix_spawn()" を使えるようになりました。 Windows Subsystem
   for Linux と QEMU User Emulation では、"os.posix_spawn()" を使う
   "Popen" コンストラクタは、プログラムが見つからないなどのエラーでも
   例外を送出しなくなりました。 代わりに、子プロセスが失敗し、
   "returncode" がゼロ以外の値になります。


例外
----

子プロセスで新しいプログラムの実行開始前に送出された例外は、親プロセス
で再送出されます。

The most common exception raised is "OSError".  This occurs, for
example, when trying to execute a non-existent file.  Applications
should prepare for "OSError" exceptions. Note that, when "shell=True",
"OSError" will be raised by the child only if the selected shell
itself was not found. To determine if the shell failed to find the
requested application, it is necessary to check the return code or
output from the subprocess.

不正な引数で "Popen" が呼ばれた場合は "ValueError" が発生します。

呼び出されたプロセスが非ゼロのリターンコードを返した場合
"check_call()" や "check_output()" は "CalledProcessError" を送出しま
す。

"run()" や "Popen.communicate()" など、*timeout* 引数を受け取るすべて
の関数とメソッドは、プロセスが終了する前にタイムアウトすると
"TimeoutExpired" を送出します。

このモジュールで定義されたすべての例外は "SubprocessError" を継承して
います。

Added in version 3.3: "SubprocessError" 基底クラスが追加されました。


セキュリティで考慮すべき点
==========================

ほかの一部の popen 関数と異なり、このライブラリは暗黙的にシステムのシ
ェルを呼び出しません。 そのため、シェルのメタ文字を含め、すべての文字
を安全に子プロセスへ渡せます。 "shell=True" で明示的にシェルを呼び出す
場合は、シェルインジェクション の脆弱性を避けるため、アプリケーション
側ですべての空白やメタ文字を適切にクォートする必要があります。 一部の
プラットフォーム では、このエスケープに "shlex.quote()" を使えます。

Windows では、このライブラリに渡す引数にかかわらず、バッチファイル
("*.bat" または "*.cmd") が OS によってシステムのシェル内で起動される
ことがあります。 その場合、Python によるエスケープが追加されないまま、
シェルの規則に従って引数が解析される可能性があります。 信頼できない情
報源からの引数を使って意図的にバッチファイルを起動する場合、Python に
特殊文字をエスケープさせるため、"shell=True" を渡すことを検討してくだ
さい。 詳しい議論は gh-114539 を参照してください。


Popen オブジェクト
==================

"Popen" クラスのインスタンスには、以下のようなメソッドがあります:

Popen.poll()

   子プロセスが終了しているかどうかを調べます。 "returncode" 属性を設
   定して返します。そうでなければ "None" を返します。

Popen.wait(timeout=None)

   子プロセスが終了するまで待ちます。"returncode" 属性を設定して返しま
   す。

   プロセスが *timeout* 秒後に終了してない場合、"TimeoutExpired" 例外
   を送出します。この例外を捕捉して wait を再試行するのは安全です。

   注釈:

     "stdout=PIPE" または "stderr=PIPE" を使っていると、子プロセスがパ
     イプに大量の出力を生成し、OS のパイプバッファがデータを受け入れら
     れるようになるまで待つ状態でブロックして、デッドロックすることが
     あります。 パイプを使う場合は、この問題を避けるため
     "Popen.communicate()" を使ってください。

   注釈:

     "timeout" が "None" でなく、プラットフォームが対応している場合は
     、イベント駆動の効率的な仕組みを使ってプロセスの終了を待ちます:

     * Linux 5.3 以降では "os.pidfd_open()" と "select.poll()" を使い
       ます。

     * macOS とその他の BSD 系 OS では "select.kqueue()"、
       "KQ_FILTER_PROC"、"KQ_NOTE_EXIT" を使います。

     * Windows では "WaitForSingleObject" を使います。

     これらの仕組みがどれも使えなければ、ビジーループ (非ブロッキング
     呼び出しと短いスリープ) に切り替えます。

   注釈:

     非同期に待機するには "asyncio" モジュールを使ってください。
     "asyncio.create_subprocess_exec" を参照してください。

   バージョン 3.3 で変更: *timeout* が追加されました

   バージョン 3.15 で変更: *timeout* が "None" でなければ、Linux 5.3
   以降と macOS / BSD で効率的なイベント駆動の実装を使います。

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

   プロセスと通信します。 標準入力にデータを送り、標準出力と標準エラー
   出力を EOF まで読み取ります。 プロセスの終了を待ち、"returncode" 属
   性を設定します。 省略可能な *input* 引数には子プロセスに送るデータ
   を指定し、送るデータがなければ "None" にします。 ストリームをテキス
   トモードで開いた場合、*input* は文字列でなければなりません。 それ以
   外の場合はバイト列でなければなりません。

   "communicate()" はタプル "(stdout_data, stderr_data)" を返します。
   ストリームをテキストモードで開いた場合、データは文字列です。 それ以
   外の場合はバイト列です。

   子プロセスの標準入力にデータを送りたい場合は、 Popen オブジェクトを
   "stdin=PIPE" と指定して作成しなければなりません。同じく、戻り値のタ
   プルから "None" ではない値を取得するためには、 "stdout=PIPE" かつ/
   または "stderr=PIPE" を指定しなければなりません。

   *timeout* 秒が経過してもプロセスが終了しなければ、"TimeoutExpired"
   例外を送出します。 この例外を捕捉して通信を再試行しても、出力は失わ
   れません。 タイムアウト後の "communicate()" 呼び出しに *input* を渡
   した場合の動作は未定義であり、将来はエラーになる可能性があります。

   タイムアウトが発生した場合子プロセスは kill されません。したがって
   、適切にクリーンアップを行うために、正常に動作するアプリケーション
   は子プロセスを kill して通信を終了すべきです:

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

   "communicate()" が "TimeoutExpired" を送出した後に "wait()" を呼び
   出さないでください。 もう一度 "communicate()" を呼び出し、パイプの
   処理を終えて "returncode" 属性を設定してください。

   注釈:

     受信したデータはメモリにバッファーされます。そのため、返されるデ
     ータが大きいかあるいは制限がないような場合はこのメソッドを使うべ
     きではありません。

   バージョン 3.3 で変更: *timeout* が追加されました

Popen.send_signal(signal)

   *signal* シグナルを子プロセスに送ります。

   プロセスが終了していれば何もしません。

   注釈:

     Windows では、SIGTERM は "terminate()" の別名です。CTRL_C_EVENT
     と CTRL_BREAK_EVENT を、"CREATE_NEW_PROCESS_GROUP" を含む
     *creationflags* で始まった、プロセスに送れます。

Popen.terminate()

   子プロセスを終了させます。 POSIX OS では、子プロセスに "SIGTERM" を
   送ります。 Windows では Win32 API の "TerminateProcess()" 関数を呼
   び出して子プロセスを終了させます。

Popen.kill()

   子プロセスを kill します。POSIX OS では SIGKILL シグナルを子プロセ
   スに送ります。Windows では、"kill()" は "terminate()" の別名です。

このクラスは、利用者が参照できるように次の属性も設定します。 これらの
属性に新しい値を代入することはサポートされていません:

Popen.args

   "Popen" に渡された引数 *args* です -- プログラム引数のシーケンスま
   たは 1 個の文字列になります。

   Added in version 3.3.

Popen.stdin

   *stdin* 引数が "PIPE" なら、この属性は "open()" が返すような書き込
   み可能なストリームオブジェクトです。 *encoding* または *errors* 引
   数を指定するか、*text* または *universal_newlines* 引数が "True" な
   らテキストストリームになり、それ以外ではバイトストリームになります
   。 *stdin* 引数が "PIPE" でなければ、この属性は "None" です。

Popen.stdout

   *stdout* 引数が "PIPE" なら、この属性は "open()" が返すような読み取
   り可能なストリームオブジェクトです。 このストリームから子プロセスの
   出力を読み取れます。 *encoding* または *errors* 引数を指定するか、
   *text* または *universal_newlines* 引数が "True" ならテキストストリ
   ームになり、それ以外ではバイトストリームになります。 *stdout* 引数
   が "PIPE" でなければ、この属性は "None" です。

Popen.stderr

   *stderr* 引数が "PIPE" なら、この属性は "open()" が返すような読み取
   り可能なストリームオブジェクトです。 このストリームから子プロセスの
   エラー出力を読み取れます。 *encoding* または *errors* 引数を指定す
   るか、*text* または *universal_newlines* 引数が "True" ならテキスト
   ストリームになり、それ以外ではバイトストリームになります。 *stderr*
   引数が "PIPE" でなければ、この属性は "None" です。

警告:

  ".stdin.write", ".stdout.read", ".stderr.read" を利用すると、別のパ
  イプの OS パイプバッファーがいっぱいになってデッドロックが発生する恐
  れがあります。これを避けるためには "communicate()" を利用してくださ
  い。

Popen.pid

   子プロセスのプロセス ID が入ります。

   *shell* 引数を "True" に設定した場合は、生成されたシェルのプロセス
   ID になります。

Popen.returncode

   子プロセスの終了コードです。 初期値は "None" です。 "poll()"、
   "wait()"、"communicate()" の呼び出しでプロセスの終了を検出すると、
   "returncode" が設定されます。

   値が "None" なら、直前のメソッド呼び出しの時点ではプロセスがまだ終
   了していなかったことを示します。

   負の値 "-N" は子プロセスがシグナル "N" により中止させられたことを示
   します (POSIX のみ)。

   "shell=True" の場合、終了コードにはシェル自体 (例えば "/bin/sh") の
   終了ステータスが反映されます。 シェルはシグナルを "128+N" などのコ
   ードに対応付けることがあります。 詳しくはシェルのドキュメント (例え
   ば Bash マニュアルの Exit Status) を参照してください。


Windows Popen ヘルパー
======================

"STARTUPINFO" クラスと以下の定数は、Windows のみで利用できます。

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

   Windows の STARTUPINFO 構造体を部分的にサポートし、"Popen" の作成に
   使います。 次の属性は、キーワード専用引数として渡すことで設定できま
   す。

   バージョン 3.7 で変更: キーワード専用引数のサポートが追加されました
   。

   dwFlags

      特定の "STARTUPINFO" の属性が、プロセスがウィンドウを生成すると
      きに使われるかを決定するビットフィールドです:

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

   hStdInput

      "dwFlags" が "STARTF_USESTDHANDLES" を指定すれば、この属性がプロ
      セスの標準入力ハンドルです。 "STARTF_USESTDHANDLES" が指定されな
      ければ、標準入力のデフォルトはキーボードバッファーです。

   hStdOutput

      "dwFlags" が "STARTF_USESTDHANDLES" を指定すれば、この属性がプロ
      セスの標準出力ハンドルです。 そうでなければ、この属性は無視され
      、標準出力のデフォルトはコンソールウィンドウのバッファーです。

   hStdError

      "dwFlags" が "STARTF_USESTDHANDLES" を指定すれば、この属性がプロ
      セスの標準エラーハンドルです。 そうでなければ、この属性は無視さ
      れ、標準エラー出力のデフォルトはコンソールウィンドウのバッファー
      です。

   wShowWindow

      "dwFlags" が "STARTF_USESHOWWINDOW" を指定すれば、この属性は
      ShowWindow 関数の "nCmdShow" 引数で指定された値なら、
      "SW_SHOWDEFAULT" 以外の任意のものにできます。 それ以外の場合、こ
      の属性は無視されます。

      この属性には "SW_HIDE" が提供されています。これは、"Popen" が
      "shell=True" として呼び出されたときに使われます。

   lpAttributeList

      "STARTUPINFOEX" で指定する、プロセス作成用の追加属性の辞書です。
      UpdateProcThreadAttribute を参照してください。

      サポートする属性:

      **handle_list**
         継承するハンドルのシーケンスです。 空でなければ *close_fds*
         を真にする必要があります。

         これらのハンドルを "Popen" コンストラクタに渡すときは、
         "os.set_handle_inheritable()" で一時的に継承可能にしておく必
         要があります。 そうしないと、Windows エラー
         "ERROR_INVALID_PARAMETER" (87) を伴う "OSError" を送出します
         。

         警告:

           マルチスレッドのプロセスでは、この機能と並行して
           "os.system()" などのすべてのハンドルを継承するプロセス作成
           関数を呼び出すとき、継承可能にしたハンドルが漏れ出さないよ
           うに注意してください。 一時的に継承可能なハンドルを作成する
           標準ハンドルのリダイレクトでも同じ注意が必要です。

      Added in version 3.7.


Windows の定数
--------------

"subprocess" モジュールは次の定数を公開しています。

subprocess.STD_INPUT_HANDLE

   標準入力デバイスです。この初期値は、コンソール入力バッファ、
   "CONIN$" です。

subprocess.STD_OUTPUT_HANDLE

   標準出力デバイスです。この初期値は、アクティブコンソールスクリーン
   、 "CONOUT$" です。

subprocess.STD_ERROR_HANDLE

   標準エラーデバイスです。この初期値は、アクティブコンソールスクリー
   ン、 "CONOUT$" です。

subprocess.SW_HIDE

   ウィンドウを隠します。別のウィンドウがアクティブになります。

subprocess.STARTF_USESTDHANDLES

   追加情報を保持する、"STARTUPINFO.hStdInput",
   "STARTUPINFO.hStdOutput", および "STARTUPINFO.hStdError" 属性を指定
   します。

subprocess.STARTF_USESHOWWINDOW

   追加情報を保持する、 "STARTUPINFO.wShowWindow" 属性を指定します。

subprocess.STARTF_FORCEONFEEDBACK

   プロセスの起動中に「バックグラウンドで作業中」のマウスカーソルを表
   示するよう指定する、"STARTUPINFO.dwFlags" の値です。 GUI プロセスで
   はこれがデフォルトの動作です。

   Added in version 3.13.

subprocess.STARTF_FORCEOFFFEEDBACK

   プロセスの起動時にマウスカーソルを変更しないよう指定する、
   "STARTUPINFO.dwFlags" の値です。

   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

   新しいプロセスの優先度を通常にするよう指定する、"Popen" の
   "creationflags" 引数の値です (デフォルト)。

   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 より前のバージョンでは、サブプロセスに対して以下の 3 つの関
数からなる高水準 API が用意されていました。現在多くの場合 "run()" の使
用で済みますが、既存の多くのコードではこれらの関数が使用されています。

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

   *args* で指定されたコマンドを実行します。コマンドの終了を待ち、
   "returncode" 属性を返します。

   標準出力や標準エラー出力を捕捉する必要があるコードでは、代わりに
   "run()" を使ってください。

      run(...).returncode

   標準出力や標準エラー出力を抑制するには、"DEVNULL" を指定してくださ
   い。

   上記の引数は、よく使われるものだけ示しています。関数の全使用法は
   "Popen" コンストラクターの内容と同じになります -  この関数は、この
   インターフェースに直接指定される *timeout* 以外は与えられた全引数を
   渡します。

   注釈:

     この関数を使用する際は "stdout=PIPE" および "stderr=PIPE" を使用
     しないでください。子プロセスが OS のパイプバッファーを埋めてしま
     うほどの出力データを生成した場合、パイプからは読み込まれないので
     、子プロセスがブロックされることがあります。

   バージョン 3.3 で変更: *timeout* が追加されました

   バージョン 3.12 で変更: "shell=True" のときのWindowsシェル検索順序
   を変更しました。カレントディレクトリと "%PATH%" は、 "%COMSPEC%" と
   "%SystemRoot%\System32\cmd.exe" に置き換えられました。これにより、
   "cmd.exe" という名前の悪意のあるプログラムをカレントディレクトリに
   ドロップしても、動作しなくなりました。

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

   引数を指定してコマンドを実行し、完了を待ちます。 終了コードがゼロな
   ら戻り、それ以外なら "CalledProcessError" を送出します。
   "CalledProcessError" オブジェクトの "returncode" 属性には終了コード
   が入ります。 "check_call()" がプロセスを起動できなかった場合は、発
   生した例外をそのまま伝播させます。

   標準出力や標準エラー出力を捕捉する必要があるコードでは、代わりに
   "run()" を使ってください。

      run(..., check=True)

   標準出力や標準エラー出力を抑制するには、"DEVNULL" を指定してくださ
   い。

   上記の引数は、よく使われるものだけ示しています。関数の全使用法は
   "Popen" コンストラクターの内容と同じになります -  この関数は、この
   インターフェースに直接指定される *timeout* 以外は与えられた全引数を
   渡します。

   注釈:

     この関数を使用する際は "stdout=PIPE" および "stderr=PIPE" を使用
     しないでください。子プロセスが OS のパイプバッファーを埋めてしま
     うほどの出力データを生成した場合、パイプからは読み込まれないので
     、子プロセスがブロックされることがあります。

   バージョン 3.3 で変更: *timeout* が追加されました

   バージョン 3.12 で変更: "shell=True" のときのWindowsシェル検索順序
   を変更しました。カレントディレクトリと "%PATH%" は、 "%COMSPEC%" と
   "%SystemRoot%\System32\cmd.exe" に置き換えられました。これにより、
   "cmd.exe" という名前の悪意のあるプログラムをカレントディレクトリに
   ドロップしても、動作しなくなりました。

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

   引数でコマンドを実行し、その出力を返します。

   コマンドのリターンコードが非ゼロならば "CalledProcessError" 例外が
   送出されます。"CalledProcessError" オブジェクトには、リターンコード
   が "returncode" 属性に、コマンドからの出力が "output" 属性に、それ
   ぞれ格納されています。

   これは次と等価です:

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

   上に示したのは、よく使われる引数の一部だけです。 完全な関数シグネチ
   ャは "run()" とほぼ同じで、ほとんどの引数はそのまま渡されます。
   "run()" の動作と異なる点が 1 つあります。 "input=None" を渡すと、親
   プロセスの標準入力のファイルハンドルを使わず、"input=b''" (他の引数
   によっては "input=''") と同じ動作になります。

   デフォルトで、この関数はデータをエンコードされたバイトとして返しま
   す。出力されたデータの実際のエンコードは起動されているコマンドに依
   存するため、テキストへのデコードは通常アプリケーションレベルで扱う
   必要があります。

   This behaviour may be overridden by setting *text*, *encoding*,
   *errors*, or *universal_newlines* to "True" as described in よく使
   われる引数 and "run()".

   標準エラー出力も結果に含めるには、"stderr=subprocess.STDOUT" を使い
   ます:

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

   Added in version 3.1.

   バージョン 3.3 で変更: *timeout* が追加されました

   バージョン 3.4 で変更: キーワード引数 *input* が追加されました。

   バージョン 3.6 で変更: *encoding* と *errors* が追加されました。 詳
   しくは "run()" を参照してください。

   Added in version 3.7: *text* が、*universal_newlines* のより読みや
   すい別名として追加されました。

   バージョン 3.12 で変更: "shell=True" のときのWindowsシェル検索順序
   を変更しました。カレントディレクトリと "%PATH%" は、 "%COMSPEC%" と
   "%SystemRoot%\System32\cmd.exe" に置き換えられました。これにより、
   "cmd.exe" という名前の悪意のあるプログラムをカレントディレクトリに
   ドロップしても、動作しなくなりました。


"subprocess" モジュールで古い関数を置き換える
=============================================

この節では、 "a becomes b" と書かれているものは a の代替として b が使
えるということを表します。

注釈:

  この節で紹介されている "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()  # p2 が終了したときに p1 が SIGPIPE を受け取れるようにする。
   output = p2.communicate()[0]

"p2" の開始後に "p1.stdout.close()" を呼び出すことが重要です。 これに
より、"p2" が "p1" より先に終了したとき、"p1" が "SIGPIPE" を受け取れ
るようになります。

あるいは、信頼された入力に対しては、シェル自身のパイプラインサポートを
直接使用することもできます:

   output=$(dmesg | grep hda)

これは以下のようになります:

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


"os.system()" を置き換える
--------------------------

   sts = os.system("mycmd" + " myarg")
   # 次のように置き換える。
   retcode = call("mycmd" + " myarg", shell=True)

注釈:

* このプログラムは普通シェル経由で呼び出す必要はありません。

* "call()" の戻り値と "os.system()" の戻り値では、終了ステータスの表し
  方が異なります。

* "os.system()" はコマンドの実行中に SIGINT と SIGQUIT シグナルを無視
  しますが、"subprocess" モジュールでは呼び出し側が別途これを行う必要
  があります。

より現実的な例ではこうなるでしょう:

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


"os.spawn" 関数群を置き換える
-----------------------------

P_NOWAIT の例:

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

P_WAIT の例:

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

シーケンスを使った例:

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

環境変数を使った例:

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


"os.popen()" を置き換える
-------------------------

終了コードハンドリングは以下のように解釈します:

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


レガシーなシェル呼び出し関数
============================

このモジュールでは、以下のような 2.x "commands" モジュールからのレガシ
ー関数も提供しています。これらの操作は、暗黙的にシステムシェルを起動し
ます。また、セキュリティに関して上述した保証や例外処理一貫性は、これら
の関数では有効ではありません。

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

   シェル中の *cmd* を実行して "(exitcode, output)" を返します。

   "check_output()" を使って文字列 *cmd* をシェルで実行し、2 要素のタ
   プル "(exitcode, output)" を返します。 出力のデコードには
   *encoding* と *errors* を使います。 詳しくは よく使われる引数 の注
   釈を参照してください。

   出力の末尾の改行は取り除かれます。 コマンドの終了コードは、
   subprocess の終了コードとして解釈できます。 例を示します。

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

   利用可能な環境: Unix, Windows.

   バージョン 3.3.4 で変更: Windows のサポートが追加されました。Python
   3.3.3 以前の (status, output) に代わり、(exitcode, output) を返すよ
   うになりました。 exitcode は "returncode" と同じ値です。

   バージョン 3.11 で変更: *encoding* と *errors* が引数に追加されまし
   た。

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

   シェル中の *cmd* を実行して出力 (stdout と stderr) を返します。

   "getstatusoutput()" に似ていますが、終了コードは無視され、コマンド
   の出力のみを返します。例えば:

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

   利用可能な環境: Unix, Windows.

   バージョン 3.3.4 で変更: Windowsで利用可能になりました

   バージョン 3.11 で変更: *encoding* と *errors* が引数に追加されまし
   た。


注釈
====


タイムアウトの動作
------------------

"run()"、"Popen.wait()"、"Popen.communicate()" などで "timeout" 引数を
使う場合は、次の動作に注意してください:

1. **プロセス作成による遅延**: 多くのプラットフォームの API では、最初
   のプロセス作成自体を中断できません。 そのため、タイムアウトを指定し
   ても、少なくともプロセス作成にかかる時間が経過するまではタイムアウ
   ト例外が発生する保証はありません。

2. **非常に短いタイムアウト**: プロセス作成やシステムのスケジューリン
   グには時間がかかるため、数ミリ秒などの非常に短いタイムアウトを設定
   すると、ほぼ直ちに "TimeoutExpired" 例外が発生することがあります。


Windows における引数シーケンスから文字列への変換
------------------------------------------------

Windows では、 *args* シーケンスは以下の (MS C ランタイムで使われる規
則に対応する) 規則を使って解析できる文字列に変換されます:

1. 引数は、スペースかタブのどちらかの空白で分けられます。

2. ダブルクオーテーションマークで囲まれた文字列は、空白が含まれていた
   としても 1 つの引数として解釈されます。クオートされた文字列は引数に
   埋め込めます。

3. バックスラッシュに続くダブルクオーテーションマークは、リテラルのダ
   ブルクオーテーションマークと解釈されます。

4. バックスラッシュは、ダブルクオーテーションが続かない限り、リテラル
   として解釈されます。

5. 複数のバックスラッシュにダブルクオーテーションマークが続くなら、バ
   ックスラッシュ 2 つで 1 つのバックスラッシュ文字と解釈されます。バ
   ックスラッシュの数が奇数なら、最後のバックスラッシュは規則 3 に従っ
   て続くダブルクオーテーションマークをエスケープします。

参考:

  "shlex"
     コマンドラインを解析したりエスケープしたりする関数を提供するモジ
     ュール。


"posix_spawn()" の使用を無効にする
----------------------------------

Linux では "subprocess" はデフォルトで、安全に使える場合に "fork()" の
代わりに "vfork()" システムコールを内部で使います。 これによって性能が
大幅に向上します。

   subprocess._USE_POSIX_SPAWN = False  # CPython の issue gh-NNNNNN を参照。

どの Python バージョンでも、この値を偽に設定して問題ありません。 対応
していない古いバージョンや新しいバージョンでは、効果がありません。 こ
の属性が存在して読み出せるとは仮定しないでください。 名前とは異なり、
値が真でも対応する関数を使うとは限らず、使う可能性があることだけを示し
ます。

これらの非公開の設定を使う必要がある場合は、その都度、問題を再現する方
法を添えて issue を報告してください。 コード内のコメントから、その
issue にリンクしてください。

Added in version 3.8: "_USE_POSIX_SPAWN"
