10.6. "tempfile" --- 一時的なファイルやディレクトリの生成
*********************************************************

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

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

このモジュールを使うと、一時的なファイルやディレクトリを生成できます。
このモジュールはサポートされている全てのプラットフォームで利用可能です
。

バージョン 2.3 の Python では、このモジュールに対してセキュリティを高
める為の見直しが行われました。現在では新たに 3 つの関数、
"NamedTemporaryFile()" 、 "mkstemp()" 、および "mkdtemp()" が提供され
ており、安全でない "mktemp()" を使いつづける必要をなくしました。このモ
ジュールで生成されるテンポラリファイルはもはやプロセス番号を含みません
; その代わり、6 桁のランダムな文字からなる文字列が使われます。

また、ユーザから呼び出し可能な関数は全て、テンポラリファイルの場所や名
前を直接操作できるようにするための追加の引数をとるようになりました。も
はや変数 *tempdir* および *template* を使う必要はありません。以前のバ
ージョンとの互換性を維持するために、引数の順番は多少変です; 明確さのた
めにキーワード引数を使うことをお勧めします。

このモジュールではユーザから呼び出し可能な以下の関数を定義しています:

tempfile.TemporaryFile([mode='w+b'[, bufsize=-1[, suffix=''[, prefix='tmp'[, dir=None]]]]])

   一時的な記憶領域として使うことができるファイルライク(file-like)オブ
   ジェクトを返します。ファイルは "mkstemp()" を使って生成されます。こ
   のファイルは閉じられると (オブジェクトがガーベジコレクションされた
   際に、暗黙のうちに閉じられる場合を含みます) すぐに消去されます。
   Unix環境では、ファイルが生成されるとすぐにそのファイルのディレクト
   リエントリは除去されてしまいます。一方、他のプラットフォームではこ
   の機能はサポートされていません; 従って、コードを書くときには、この
   関数で作成したテンポラリファイルをファイルシステム上で見ることがで
   きる、あるいはできないということをあてにすべきではありません。

   生成されたファイルを一旦閉じなくてもファイルを読み書きできるように
   するために、 *mode* パラメータは標準で "'w+b'" に設定されています。
   ファイルに記録するデータが何であるかに関わらず全てのプラットフォー
   ムで一貫性のある動作をさせるために、バイナリモードが使われています
   。 *bufsize* の値は標準で "-1" で、これはオペレーティングシステムに
   おける標準の値を使うことを意味しています。

   *dir* 、 *prefix* および *suffix* パラメータは "mkstemp()" に渡され
   ます。

   返されるオブジェクトは、POSIXプラットフォームでは本物のfileオブジェ
   クトです。それ以外のプラットフォームではファイルライクオブジェクト
   が返され、 "file" 属性に本物のfileオブジェクトがあります。このファ
   イルライクオブジェクトは、通常のファイルと同じように "with" 文で利
   用することができます。

tempfile.NamedTemporaryFile([mode='w+b'[, bufsize=-1[, suffix=''[, prefix='tmp'[, dir=None[, delete=True]]]]]])

   この関数はファイルがファイルシステム上で見ることができるよう保証さ
   れている点を除き、 "TemporaryFile()" と全く同じに働きます (Unixでは
   、ディレクトリエントリはunlinkされません)。 ファイル名は返されるフ
   ァイルライクオブジェクトの "name" メンバから取得することができます
   。 このファイル名を使ってテンポラリファイルをもう一度開くとことがで
   きるかどうかは、プラットフォームによって異なります (Unixでは可能で
   す; Windows NT以降では開けません)。 *delete* がtrue(デフォルト)の場
   合、ファイルは閉じられるとすぐに削除されます。

   返されるオブジェクトは、常にファイルライクオブジェクトです。このオ
   ブジェクトの "file" 属性が本物のfileオブジェクトになります。このフ
   ァイルライクオブジェクトは、通常のファイルと同じように "with" 文を
   利用することができます。

   バージョン 2.3 で追加.

   バージョン 2.6 で追加: *delete* 引数

tempfile.SpooledTemporaryFile([max_size=0[, mode='w+b'[, bufsize=-1[, suffix=''[, prefix='tmp'[, dir=None]]]]]])

   この関数は、ファイルサイズが *max_size* を超えるか、 "fileno()" メ
   ソッドが呼ばれるまでの間メモリ上で処理される以外は、
   "TemporaryFile()" と同じです。 *max_size* を超えるか "fileno()" が
   呼ばれたとき、テンポラリファイルの内容がディスクに書き込まれ、その
   後の処理は "TemporaryFile()" で行われます。また、これの "truncate"
   メソッドは "size" 引数を受け付けません。

   この関数が返すファイルは、追加で1つのメソッド "rollover()" を持って
   います。このメソッドが呼ばれると、(サイズに関係なく)メモリからディ
   スクへのロールオーバーが実行されます。

   返されるオブジェクトはファイルライクオブジェクトで、その "_file" 属
   性は、 "rollover()" が呼ばれたかどうかによって、 "StringIO" オブジ
   ェクトか、本物のファイルオブジェクトになります。このファイルライク
   オブジェクトは、通常のファイルオブジェクトと同じように、 "with" 文
   で利用することができます。

   バージョン 2.6 で追加.

tempfile.mkstemp([suffix=''[, prefix='tmp'[, dir=None[, text=False]]]])

   可能な限り最も安全な手段でテンポラリファイルを生成します。使用する
   プラットフォームで "os.open()" の "os.O_EXCL" フラグが正しく実装さ
   れている限り、ファイルの生成で競合状態が起こることはありません。こ
   のファイルは、ファイルを生成したユーザのユーザ ID からのみ読み書き
   可能です。使用するプラットフォームにおいて、ファイルを実行可能かど
   うかを示す許可ビットが使われている場合、ファイルは誰からも実行不可
   なように設定されます。このファイルのファイル記述子は子プロセスに継
   承されません。

   "TemporaryFile()" と違って、 "mkstemp()" で生成されたファイルが用済
   みになったときにファイルを消去するのはユーザの責任です。

   *suffix* が指定された場合、ファイル名は指定されたsuffixで終わります
   。そうでない場合にはsuffixは付けられません。 "mkstemp()" はファイル
   名とsuffixの間にドットを追加しません; 必要なら、 *suffix* の先頭に
   つけてください。

   *prefix* が指定された場合、ファイル名は指定されたプレフィクス(接頭
   文字列) で始まります; そうでない場合、標準のプレフィクスが使われま
   す。

   *dir* が指定された場合、テンポラリファイルは指定されたディレクトリ
   下に作成されます; そうでない場合、標準のディレクトリが使われます。
   デフォルトのディレクトリは、プラットフォームごとに異なるリストから
   選ばれます。しかし、アプリケーションのユーザーは *TMPDIR*, *TEMP*,
   *TMP* 環境変数を設定することで、その場所を設定することができます。
   そのため、生成されたファイル名について、クォート無しで "os.popen()"
   を使って外部コマンドに渡せるかどうかなどの保証はありません。

   *text* が指定された場合、ファイルをバイナリモード (標準の設定) かテ
   キストモードで開くかを示します。使用するプラットフォームによっては
   この値を設定しても変化はありません。

   "mkstemp()" は開かれたファイルを扱うための OS レベル ("os.open()"
   が返すものと同じ) とファイルの絶対パス名が順番に並んだタプルを返し
   ます。

   バージョン 2.3 で追加.

tempfile.mkdtemp([suffix=''[, prefix='tmp'[, dir=None]]])

   可能な限り安全な方法でテンポラリディレクトリを作成します。ディレク
   トリの生成で競合状態は発生しません。ディレクトリを作成したユーザ ID
   だけが、このディレクトリに対して内容を読み出したり、書き込んだり、
   検索したりすることができます。

   "mkdtemp()" によって作られたディレクトリとその内容が用済みになった
   時にそれを消去するのはユーザの責任です。

   *prefix*, *suffix*, *dir* 引数は "mkstemp()" 関数のものと同じです。

   "mkdtemp()" は新たに生成されたディレクトリの絶対パス名を返します。

   バージョン 2.3 で追加.

tempfile.mktemp([suffix=''[, prefix='tmp'[, dir=None]]])

   バージョン 2.3 で非推奨: 代わりに "mkstemp()" を使って下さい。

   テンポラリファイルの絶対パス名を返します。このパス名は少なくともこ
   の関数が呼び出された時点ではファイルシステム中に存在しなかったパス
   名です。 *prefix* 、 *prefix* 、 *suffix* 、および *dir* 引数は
   "mkstemp()" のものと同じです。

   警告: この関数を使うとプログラムのセキュリティホールになる可能性
     があり ます。この関数がファイル名を返した後、あなたがそのファイル
     名を使 って次に何かをしようとする段階に至る前に、誰か他の人間があ
     なたを 出し抜くことができてしまいます。 "mktemp()" の利用は、
     "NamedTemporaryFile()" に "delete=False" 引数を渡すことで、簡単に
     置き換えることができます:

        >>> f = NamedTemporaryFile(delete=False)
        >>> f
        <open file '<fdopen>', mode 'w+b' at 0x384698>
        >>> f.name
        '/var/folders/5q/5qTPn6xq2RaWqk+1Ytw3-U+++TI/-Tmp-/tmpG7V1Y0'
        >>> f.write("Hello World!\n")
        >>> f.close()
        >>> os.unlink(f.name)
        >>> os.path.exists(f.name)
        False

このモジュールは一時的な名前の作成法を指定するグローバル変数を使います
。それらの変数は上記のいずれかの関数を最初に呼び出した際に初期化されま
す。関数呼び出しを行うユーザはこれらの値を変更することができますが、推
奨されていません。その代わりに関数に適切な引数を使ってください。

tempfile.tempdir

   この値が "None" 以外に設定された場合、このモジュールで定義されてい
   る関数全ての *dir* 引数に対する標準の設定値となります。

   *tempdir* が設定されていないか "None" の場合、上記のいずれかの関数
   を呼び出した際は常に、Python は標準的なディレクトリ候補のリストを検
   索し、関数を呼び出しているユーザの権限でファイルを作成できる最初の
   ディレクトリ候補を *tempdir* に設定します。リストは以下のようになっ
   ています:

   1. 環境変数 "TMPDIR" で与えられているディレクトリ名。

   2. 環境変数 "TEMP" で与えられているディレクトリ名。

   3. 環境変数 "TMP" で与えられているディレクトリ名。

   4. プラットフォーム依存の場所:

      * RiscOS では環境変数 "Wimp$ScrapDir" で与えられているディレク
        ト リ名。

      * Windows ではディレクトリ "C:\TEMP" 、 "C:\TMP" 、 "\TEMP" 、
        お よび "\TMP" の順。

      * その他の全てのプラットフォームでは、 "/tmp" 、 "/var/tmp" 、
        お よび "/usr/tmp" の順。

   5. 最後の手段として、現在の作業ディレクトリ。

tempfile.gettempdir()

   現在選択されている、テンポラリファイルを作成するためのディレクトリ
   を返します。 "tempdir" が "None" でない場合、単にその内容を返します
   ; そうでない場合には上で記述されている検索が実行され、その結果が返
   されます。

   バージョン 2.3 で追加.

tempfile.template

   バージョン 2.0 で非推奨: 代わりに "gettempprefix()" を使ってくださ
   い。

   この値に "None" 以外の値を設定した場合、 "mktemp()" が返すファイル
   名のディレクトリ部を含まない先頭部分 (プレフィクス) を定義します。
   ファイル名を一意にするために、 6 つのランダムな文字および数字がこの
   プレフィクスの後に追加されます。デフォルトのプレフィックスは "tmp"
   です。

   このモジュールの古いバージョンでは、 "os.fork()" を呼び出した後に
   "template" を "None" に設定することが必要でした; この仕様はバージョ
   ン 1.5.2 からは必要なくなりました。

tempfile.gettempprefix()

   テンポラリファイルを生成する際に使われるファイル名の先頭部分を返し
   ます。この先頭部分にはディレクトリ部は含まれません。変数 *template*
   を直接読み出すよりもこの関数を使うことを勧めます。

   バージョン 1.5.2 で追加.
