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

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

このモジュールは一時ファイルやディレクトリを作成します。 サポートされている全てのプラットフォームで動作します。 `TemporaryFile`、`NamedTemporaryFile`、`TemporaryDirectory`、 `SpooledTemporaryFile` は自動的に後始末をし、context managers コンテキストマネージャ として使うことの出来る高水準のインターフェイスです。 `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 では、そのファイルのディレクトリエントリは全く作成されないか、ファイル作成後すぐに削除されます。 これは他のプラットフォームではサポートされません。 よって、この関数で作成された一時ファイルがファイルシステムで可視な名前を持つかどうかをコードで当てにすべきではありません。

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

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

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

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

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

  プラットフォームが Posix でも Cygwin でもない場合は、TemporaryFile は 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, delete_on_close=True)

  This function operates exactly as `TemporaryFile()` does, except the following differences:

  - This function returns a file that is guaranteed to have a visible name in the file system.

  - To manage the named file, it extends the parameters of `TemporaryFile()` with delete and delete_on_close parameters that determine whether and how the named file should be automatically deleted.

  The returned object is always a file-like object whose `file` attribute is the underlying true file object. This file-like object can be used in a `with` statement, just like a normal file. The name of the temporary file can be retrieved from the `name` attribute of the returned file-like object. On Unix, unlike with the `TemporaryFile()`, the directory entry does not get unlinked immediately after the file creation.

  If delete is true (the default) and delete_on_close is true (the default), the file is deleted as soon as it is closed. If delete is true and delete_on_close is false, the file is deleted on context manager exit only, or else when the file-like object is finalized. Deletion is not always guaranteed in this case (see `object.__del__()`). If delete is false, the value of delete_on_close is ignored.

  Therefore to use the name of the temporary file to reopen the file after closing it, either make sure not to delete the file upon closure (set the delete parameter to be false) or, in case the temporary file is created in a `with` statement, set the delete_on_close parameter to be false. The latter approach is recommended as it provides assistance in automatic cleaning of the temporary file upon the context manager exit.

  Opening the temporary file again by its name while it is still open works as follows:

  - On POSIX the file can always be opened again.

  - On Windows, make sure that at least one of the following conditions are fulfilled:

    - delete is false

    - additional open shares delete access (e.g. by calling `os.open()` with the flag `O_TEMPORARY`)

    - delete is true but delete_on_close is false. Note, that in this case the additional opens that do not share delete access (e.g. created via builtin `open()`) must be closed before exiting the context manager, else the `os.unlink()` call on context manager exit will fail with a `PermissionError`.

  On Windows, if delete_on_close is false, and the file is created in a directory for which the user lacks delete access, then the `os.unlink()` call on exit of the context manager will fail with a `PermissionError`. This cannot happen when delete_on_close is true because delete access is requested by the open, which fails immediately if the requested access is not granted.

  On POSIX (only), a process that is terminated abruptly with SIGKILL cannot automatically delete any NamedTemporaryFiles it created.

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

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

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

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()` と同様に進みます。

  rollover()

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

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

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

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

  バージョン 3.11 で変更: Fully implements the `io.BufferedIOBase` and `io.TextIOBase` abstract base classes (depending on whether binary or text mode was specified).

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

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

  name

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

  cleanup()

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

  The delete parameter can be used to disable cleanup of the directory tree upon exiting the context. While it may seem unusual for a context manager to disable the action taken when exiting the context, it can be useful during debugging or when you need your cleanup behavior to be conditional based on other logic.

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

  Added in version 3.2.

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

  バージョン 3.12 で変更: delete パラメータが追加されました。

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 を受け付けるようになりました。

  バージョン 3.12 で変更: `mkdtemp()` now always returns an absolute path, even if dir is relative.

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です。

  Added in version 3.5.

tempfile.gettempprefix()

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

tempfile.gettempprefixb()

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

  Added in version 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.

## 使用例

Here are some examples of typical usage of the `tempfile` module:

    >>> 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 file using a context manager
    # close the file, use the name to open the file again
    >>> with tempfile.NamedTemporaryFile(delete_on_close=False) as fp:
    ...     fp.write(b'Hello world!')
    ...     fp.close()
    ... # the file is closed, but not removed
    ... # open the file again by using its name
    ...     with open(fp.name, mode='rb') as f:
    ...         f.read()
    b'Hello world!'
    >>>
    # file is now 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