"tempfile" --- 一時ファイルやディレクトリの作成
***********************************************

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

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

このモジュールは一時ファイルやディレクトリを作成します。 サポートされ
ている全てのプラットフォームで動作します。 "TemporaryFile"、
"NamedTemporaryFile"、"TemporaryDirectory"、 "SpooledTemporaryFile" は
自動的に後始末をし、コンテキストマネージャとして使うことの出来る高水準
のインターフェイスです。 "mkstemp()" と "mkdtemp()" は手動で後始末をし
なければならない低水準の関数です。

ユーザが呼び出し可能な全ての関数とコンストラクタは追加の引数を受け取り
ます。 その引数によって一時ファイルやディレクトリの場所と名前を直接操
作することが出来ます。 このモジュールに使用されるファイル名はランダム
な文字を含みます。そのためファイルは共有された一時ディレクトリに安全に
作成されます。 後方互換性を保つために引数の順序は若干奇妙です。 分かり
やすさのためにキーワード引数を使用してください。

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

tempfile.TemporaryFile(mode='w+b', buffering=- 1, encoding=None, newline=None, suffix=None, prefix=None, dir=None, *, errors=None)

   一時的な記憶領域として使うことの出来る *file-like object* を返しま
   す。 ファイルは "mkstemp()" と同じルールにより安全に作成されます。
   オブジェクトは閉じられる (オブジェクトのガベージコレクションによる
   暗黙的なものも含みます) とすぐに破壊されます。 Unix では、そのファ
   イルのディレクトリエントリは全く作成されないか、ファイル作成後すぐ
   に削除されます。 これは他のプラットフォームではサポートされません。
   よって、この関数で作成された一時ファイルがファイルシステムで可視な
   名前を持つかどうかをコードで当てにすべきではありません。

   返されたオブジェクトをコンテキストマネージャとして使うことが出来ま
   す （使用例 を参照してください）。 コンテキストの完了やファイルオブ
   ジェクトの破壊で、一時ファイルはファイルシステムから削除されます。

   作成されたファイルを閉じることなく読み書きできるように、 *mode* 引
   数のデフォルトは "'w+b'" です。 保存されるデータに関わらず全てのプ
   ラットフォーム上で一貫して動作するようにバイナリモードが使用されま
   す。 *buffering*、*encoding*、*errors*、*newline* は、 "open()" に
   対する引数として解釈されます。

   *dir*、*prefix*、*suffix* 引数の意味とデフォルトは "mkstemp()" のも
   のと同じです。

   返されたオブジェクトは、POSIXプラットフォームでは本物のファイルオブ
   ジェクトです。 それ以外のプラットフォームでは、"file" 属性が下層の
   本物のファイルであるファイル様オブジェクトです。

   "os.O_TMPFILE" フラグは、利用可能で動作する場合に用いられます
   (Linux 固有で、Linux kernel 3.11 以降)。

   On platforms that are neither Posix nor Cygwin, TemporaryFile is an
   alias for NamedTemporaryFile.

   引数 "fullpath" を指定して 監査イベント "tempfile.mkstemp" を送出し
   ます。

   バージョン 3.5 で変更: 利用可能であれば "os.O_TMPFILE" フラグが使用
   されます。

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

tempfile.NamedTemporaryFile(mode='w+b', buffering=- 1, encoding=None, newline=None, suffix=None, prefix=None, dir=None, delete=True, *, errors=None)

   この関数は、ファイルシステム上でファイルが可視の名前を持つことが保
   証される (Unix においてはディレクトリエントリが unlink されない) 点
   以外は "TemporaryFile()" と正確に同じことを行います。 その名前は、
   返されたファイル様オブジェクトの "name" 属性から取得することができ
   ます。 名前付き一時ファイルがまだ開かれている間にこの名前を使って再
   度ファイルを開くことができるかどうかは、プラットフォームによって異
   なります (Unix 上では可能ですが、 Windows ではできません)。
   *delete* が真の場合 (デフォルト)、ファイルは閉じられたら即座に削除
   されます。 返されたオブジェクトは常にファイル様オブジェクトで、その
   "file" 属性は元になった本物のファイルオブジェクトです。 このファイ
   ルライクオブジェクトは、通常のファイルのように "with" 文の中で使用
   することができます。

   引数 "fullpath" を指定して 監査イベント "tempfile.mkstemp" を送出し
   ます。

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

class tempfile.SpooledTemporaryFile(max_size=0, mode='w+b', buffering=- 1, encoding=None, newline=None, suffix=None, prefix=None, dir=None, *, errors=None)

   このクラスはファイルサイズが *max_size* を超えるかファイルの
   "fileno()" メソッドが呼ばれるまで、データがメモリにスプールされる点
   以外は "TemporaryFile()" と正確に同じことを行います。 上記条件を満
   たすと内容はディスクに書き込まれ、操作は "TemporaryFile()" と同様に
   進みます。

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

   返されたオブジェクトはファイル様オブジェクトで、その "_file" 属性は
   (バイナリかテキスト *mode* が指定されたかどうかに依存して)
   "io.BytesIO" か "io.TextIOWrapper" オブジェクト、あるいは
   "rollover()" が呼ばれたかどうかに依存して本物のファイルオブジェクト
   になります。 このファイル様オブジェクトは、通常のファイルオブジェク
   トと同じように "with" 文中で使用することが出来ます。

   バージョン 3.3 で変更: truncate メソッドが "size" 引数を受け取るよ
   うになりました。

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

class tempfile.TemporaryDirectory(suffix=None, prefix=None, dir=None, ignore_cleanup_errors=False)

   このクラスは "mkdtemp()" と同じルールを使用して安全に一時ディレクト
   リを作成します。返されたオブジェクトは、コンテキストマネージャとし
   て使用することができます (使用例 を参照)。コンテキストの完了や一時
   ディレクトリオブジェクトを破壊すると、新規作成された一時ディレクト
   リとその中身はファイルシステムから削除されます。

   ディレクトリ名は返されたオブジェクトの "name" 属性から取得できます
   。返されたオブジェクトがコンテキストマネージャとして使用された場合
   、 "name" は "with" 文内の "as" 節のターゲットがあればそれに割り当
   てられます。

   The directory can be explicitly cleaned up by calling the
   "cleanup()" method. If *ignore_cleanup_errors* is true, any
   unhandled exceptions during explicit or implicit cleanup (such as a
   "PermissionError" removing open files on Windows) will be ignored,
   and the remaining removable items deleted on a "best-effort" basis.
   Otherwise, errors will be raised in whatever context cleanup occurs
   (the "cleanup()" call, exiting the context manager, when the object
   is garbage-collected or during interpreter shutdown).

   引数 "fullpath" を指定して 監査イベント "tempfile.mkdtemp" を送出し
   ます。

   バージョン 3.2 で追加.

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

tempfile.mkstemp(suffix=None, prefix=None, dir=None, text=False)

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

   "TemporaryFile()" と違って、 "mkstemp()" のユーザは用済みになった時
   に一時ファイルを削除しなければなりません。

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

   *prefix* が "None" でない場合、ファイル名はその接頭辞で始まります。
   そうでない場合、デフォルトの接頭辞が使われます。 必要に応じ、デフォ
   ルトは "gettempprefix()" または "gettempprefixb()" の返り値です。

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

   *suffix*、*prefix*、*dir* のいずれかが "None" でない場合、それらは
   同じ型でなければなりません。 bytes の場合、返された名前は str でな
   はく bytes です。 他の挙動はデフォルトで返り値を bytes に強制的にし
   たい場合は "suffix=b''" を渡してください。

   *text* に真を指定した場合は、ファイルはテキストモードで開かれます。
   そうでない場合(デフォルト)は、ファイルはバイナリモードで開かれます
   。

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

   引数 "fullpath" を指定して 監査イベント "tempfile.mkstemp" を送出し
   ます。

   バージョン 3.5 で変更: *suffix*、*prefix*、*dir* は bytes の返り値
   を得るために bytes で渡すことが出来ます。 それ以前は str のみ許され
   ていました。 適切なデフォルト値を使用するよう、*suffix* と *prefix*
   は "None" を受け入れ、デフォルトにするようになりました。

   バージョン 3.6 で変更: *dir* パラメタが *path-like object* を受け付
   けるようになりました。

tempfile.mkdtemp(suffix=None, prefix=None, dir=None)

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

   "mkdtemp()" のユーザは用済みになった時に一時ディレクトリとその中身
   を削除しなければなりません。

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

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

   引数 "fullpath" を指定して 監査イベント "tempfile.mkdtemp" を送出し
   ます。

   バージョン 3.5 で変更: *suffix*、*prefix*、*dir* は bytes の返り値
   を得るために bytes で渡すことが出来ます。 それ以前は str のみ許され
   ていました。 適切なデフォルト値を使用するよう、*suffix* と *prefix*
   は "None" を受け入れ、デフォルトにするようになりました。

   バージョン 3.6 で変更: *dir* パラメタが *path-like object* を受け付
   けるようになりました。

tempfile.gettempdir()

   一時ファイルに用いられるディレクトリの名前を返します。 これはモジュ
   ール内の全ての関数の *dir* 引数のデフォルト値を定義します。

   Python は呼び出したユーザがファイルを作ることの出来るディレクトリを
   検索するのに標準的なリストを使用します。 そのリストは:

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

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

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

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

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

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

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

   この検索の結果はキャッシュされます。以下の "tempdir" の記述を参照し
   てください。

   バージョン 3.10 で変更: Always returns a str.  Previously it would
   return any "tempdir" value regardless of type so long as it was not
   "None".

tempfile.gettempdirb()

   "gettempdir()" と同じですが返り値は bytesです。

   バージョン 3.5 で追加.

tempfile.gettempprefix()

   一時ファイルを生成する際に使われるファイル名の接頭辞を返します。 こ
   れにはディレクトリ部は含まれません。

tempfile.gettempprefixb()

   "gettempprefix()" と同じですが返り値は bytes です。

   バージョン 3.5 で追加.

The module uses a global variable to store the name of the directory
used for temporary files returned by "gettempdir()".  It can be set
directly to override the selection process, but this is discouraged.
All functions in this module take a *dir* argument which can be used
to specify the directory. This is the recommended approach that does
not surprise other unsuspecting code by changing global API behavior.

tempfile.tempdir

   When set to a value other than "None", this variable defines the
   default value for the *dir* argument to the functions defined in
   this module, including its type, bytes or str.  It cannot be a
   *path-like object*.

   "tempdir" が (デフォルトの) "None" の場合、 "gettempprefix()" を除
   く上記のいずれかの関数を呼び出す際は常に "gettempdir()" で述べられ
   ているアルゴリズムによって初期化されます。

   注釈:

     Beware that if you set "tempdir" to a bytes value, there is a
     nasty side effect: The global default return type of "mkstemp()"
     and "mkdtemp()" changes to bytes when no explicit "prefix",
     "suffix", or "dir" arguments of type str are supplied. Please do
     not write code expecting or depending on this. This awkward
     behavior is maintained for compatibility with the historical
     implementation.


使用例
======

"tempfile" モジュールの典型的な使用法のいくつかの例を挙げます:

   >>> import tempfile

   # create a temporary file and write some data to it
   >>> fp = tempfile.TemporaryFile()
   >>> fp.write(b'Hello world!')
   # read data from file
   >>> fp.seek(0)
   >>> fp.read()
   b'Hello world!'
   # close the file, it will be removed
   >>> fp.close()

   # create a temporary file using a context manager
   >>> with tempfile.TemporaryFile() as fp:
   ...     fp.write(b'Hello world!')
   ...     fp.seek(0)
   ...     fp.read()
   b'Hello world!'
   >>>
   # file is now closed and removed

   # create a temporary directory using the context manager
   >>> with tempfile.TemporaryDirectory() as tmpdirname:
   ...     print('created temporary directory', tmpdirname)
   >>>
   # directory and contents have been removed


非推奨の関数と変数
==================

一時ファイルを作成する歴史的な手法は、まず "mktemp()" 関数でファイル名
を作り、その名前を使ってファイルを作成するというものでした。 残念なが
らこの方法は安全ではありません。 なぜなら、"mktemp()" の呼び出しと最初
のプロセスが続いてファイル作成を試みる間に、異なるプロセスがその名前で
ファイルを同時に作成するかもしれないからです。 解決策は二つのステップ
を同時に行い、ファイルをすぐに作成するというものです。 この方法は
"mkstemp()" や上述している他の関数で使用されています。

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

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

   呼び出し時には存在しなかった、ファイルの絶対パス名を返します。
   *prefix*、*suffix*、*dir* 引数は "mkstemp()" のものと似ていますが、
   bytes のファイル名、"suffix=None"、そして "prefix=None" がサポート
   されていない点で異なります。

   警告:

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

        >>> f = NamedTemporaryFile(delete=False)
        >>> f.name
        '/tmp/tmptjujjt'
        >>> f.write(b"Hello World!\n")
        13
        >>> f.close()
        >>> os.unlink(f.name)
        >>> os.path.exists(f.name)
        False
