\section{\module{tempfile} --- 一時的なファイルやディレクトリの生成}
\sectionauthor{Zack Weinberg}{zack@codesourcery.com}

\declaremodule{standard}{tempfile}
\modulesynopsis{一時的なファイルやディレクトリを生成。}

\indexii{temporary}{file name}
\indexii{temporary}{file}

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

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

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

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

\begin{funcdesc}{TemporaryFile}{\optional{mode=\code{'w+b'}\optional{,
                                bufsize=\code{-1}\optional{,
                                suffix\optional{, prefix\optional{, dir}}}}}}
一時的な記憶領域として使うことができるファイル (またはファイル類似の) 
オブジェクトを返します。ファイルは \function{mkstemp} を使って
生成されます。このファイルは閉じられると (オブジェクトが
ガーベジコレクションされた際に、暗黙のうちに閉じられる場合を含みます)
すぐに消去されます。\UNIX 環境では、ファイルが生成されるとすぐに
そのファイルのディレクトリエントリは除去されてしまいます。一方、他の
プラットフォームではこの機能はサポートされていません; 従って、
コードを書くときには、この関数で作成した一時ファイルをファイルシステム上で見る
ことができる、あるいはできないということをあてにすべきではありません。

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

\var{dir}、\var{prefix} および \var{suffix} パラメタは \function{mkstemp()}
に渡されます。
\end{funcdesc}

\begin{funcdesc}{NamedTemporaryFile}{\optional{mode=\code{'w+b'}\optional{,
                                     bufsize=\code{-1}\optional{,
                                     suffix\optional{, prefix\optional{,
                                     dir}}}}}}
この関数はファイルがファイルシステム上で見ることができるよう保証
されている点を除き、\function{TemporaryFile()} と全く同じに働きます。
(\UNIX では、ディレクトリ エントリはunlinkされません)
ファイル名はファイルオブジェクトの \member{name} メンバから
取得することができます。このファイル名を使って一時ファイルをもう一度
開くとことができるかどうかは、プラットフォームによって異なります。
(\UNIX では可能でしたが、Windows NT以降では開く事ができません。)

\versionadded{2.3}
\end{funcdesc}

\begin{funcdesc}{mkstemp}{\optional{suffix\optional{,
                          prefix\optional{, dir\optional{, text}}}}}
可能な限り最も安全な手段で一時ファイルを生成します。
使用するプラットフォームで\function{os.open()} の \constant{O_EXCL}
フラグが正しく実装されている限り、ファイルの生成で競合条件が起こる
ことはありません。このファイルは、ファイルを生成したユーザのユーザ
ID からのみ読み書き可能です。使用するプラットフォームにおいて、
ファイルを実行可能かどうかを示す許可ビットが使われている場合、
ファイルは誰からも実行不可なように設定されます。
このファイルのファイル記述子は子プロセスに継承されません。

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

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

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

\var{dir} が指定された場合、一時ファイルは指定されたディレクトリ
下に作成されます; そうでない場合、標準のディレクトリが使われます。

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

\function{mkstemp()} は開かれたファイルを扱うための OS レベルの値
とファイルの絶対パス名が順番に並んだタプルを返します。
\versionadded{2.3}
\end{funcdesc}

\begin{funcdesc}{mkdtemp}{\optional{suffix\optional{, prefix\optional{, dir}}}}
可能な限り安全な方法で一時ディレクトリを作成します。
ディレクトリの生成で競合条件は発生しません。
ディレクトリを作成したユーザ ID だけが、このディレクトリ
に対して内容を読み出したり、書き込んだり、検索したりすることが
できます。

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

\var{prefix}、\var{suffix}、および \var{dir} 引数は \function{mkstemp()}
のものと同じです。

\function{mkdtemp()} は新たに生成されたディレクトリの絶対パス名を
返します。
\versionadded{2.3}
\end{funcdesc}

\begin{funcdesc}{mkdtemp}{\optional{suffix\optional{, prefix\optional{, dir}}}}
\deprecated{2.3}{Use \function{mkstemp()} instead.}
一時ファイルの絶対パス名を返します。このパス名は少なくともこの関数が
呼び出された時点ではファイルシステム中に存在しなかったパス名です。
\var{prefix}、\var{prefix}、 \var{suffix}、および \var{dir}
引数は \function{mkstemp()} のものと同じです。

\warning{この関数を使うとプログラムのセキュリティホールになる可能性
があります。この関数が返したファイル名を返した後、あなたがそのファイル名
を使って次に何かをしようとする段階に至る前に、誰か他の人間が
あなたにパンチをくらわせてしまうかもしれません。}
\end{funcdesc}

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

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

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

\begin{enumerate}
\item 環境変数 \envvar{TMPDIR} で与えられているディレクトリ名。
\item 環境変数 \envvar{TEMP} で与えられているディレクトリ名。
\item 環境変数 \envvar{TMP} で与えられているディレクトリ名。
\item プラットフォーム依存の場所:
    \begin{itemize}
    \item RiscOS では環境変数 \envvar{Wimp\$ScrapDir} で与えられて
いるディレクトリ名。
    \item Windows ではディレクトリ
          \file{C:\textbackslash{}TEMP}、
          \file{C:\textbackslash{}TMP}、
          \file{\textbackslash{}TEMP}、および
          \file{\textbackslash{}TMP} の順。
    \item その他の全てのプラットフォームでは、\file{/tmp}、
\file{/var/tmp}、および \file{/usr/tmp} の順。
    \end{itemize}
\item 最後の手段として、現在の作業ディレクトリ。
\end{enumerate}
\end{datadesc}

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

\begin{datadesc}{template}
\deprecated{2.0}{代わりに \function{gettempprefix()} を使ってください。}
この値に \code{None} 以外の値を設定した場合、\function{mktemp()}
が返すファイル名のディレクトリ部を含まない先頭部分 (プレフィクス) を
定義します。ファイル名を一意にするために、 6 つのランダムな文字および
数字がこのプレフィクスの後に追加されます。Windows では、標準の
プレフィクスは\file{\textasciitilde{}T} です; 他のシステムでは
\file{tmp} です。

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

\begin{funcdesc}{gettempprefix}{}
一時ファイルを生成する際に使われるファイル名の先頭部分を返します。
この先頭部分にはディレクトリ部は含まれません。変数 \var{template} 
を直接読み出すよりもこの関数を使うことを勧めます。
\versionadded{1.5.2}
\end{funcdesc}
