#
9 ファイルオブジェクト

ファイルオブジェクト は C の`stdio` パッケージを使って実装されており、 2.1 節の ``組み込み関数'' で解説されている組み込みのコンストラクタ `file()` で生成することができます。 11 ファイルオブジェクトはまた、`os.popen()` や `os.fdopen()` 、ソケットオブジェクトの `makefile()` メソッドのような、他の組み込み関数およびメソッドによっても返されます。

ファイル操作が I/O 関連の理由で失敗した場合例外 `IOError` が送出されます。この理由には例えば `seek()` を端末デバイスに 行ったり、読み出し専用で開いたファイルに書き込みを行うといった、 何らかの理由によってそのファイルで定義されていない操作を行った ような場合も含まれます。

ファイルは以下のメソッドを持ちます:

`close`( | )

  ファイルを閉じます。閉じられたファイルはそれ以後読み書きすることは できません。ファイルが開かれていることが必要な操作は、ファイルが 閉じられた後はすべて `ValueError` を送出します。 `close` を一度以上呼び出してもかまいません。

  Python 2.5 から `with` 文を使えばこのメソッドを直接呼び出す必要 はなくなりました。たとえば、以下のコードは `f` を `with` ブロックを抜ける際に自動的に閉じます。

      from __future__ import with_statement

      with open("hello.txt") as f:
          for line in f:
              print line

  古いバージョンの Python では同じ効果を得るために次のようにしなければい けませんでした。

      f = open("hello.txt")
      try:
          for line in f:
              print line
      finally:
          f.close()

  注意: 全ての Python の ``ファイル的'' 型が `with` 文用の コンテキスト・マネージャとして使えるわけではありません。もし、全ての ファイル的オブジェクトで動くようにコードを書きたいのならば、オブジェクトを 直接使うのではなく `contextlib` にある `closing()` を 使うと良いでしょう。詳細はセクション 26.5 を参照してください。

`flush`( | )

  `stdio` の `fflush()` のように、内部バッファを フラッシュします。ファイル類似のオブジェクトによっては、この 操作は何も行いません。

`fileno`( | )

  背後にある実装系がオペレーティングシステムに I/O 操作を要求するために 用いる、整数の ``ファイル記述子'' を返します。この値は他の用途として、 `fcntl` モジュールや `os.read()` やその仲間のような、ファイル記述子を必要とする低レベルのインタフェース で役に立ちます。 注意: ファイル類似のオブジェクトが実際のファイルに関連付けられていない 場合、このメソッドを提供すべきではありません。

`isatty`( | )

  ファイルが tty (または類似の) デバイスに接続されている場合 `True` を返し、そうでない場合 `False` を返します。 注意: ファイル類似のオブジェクトが実際のファイルに関連付けられていない 場合、このメソッドを実装すべきではありません。

`next`( | )

  ファイルオブジェクトはそれ自身がイテレータです。すなわち、 `iter(f)` は (f が閉じられていない限り) f を返します。`for` ループ (例えば `for line in f: print line`) のようにファイルがイテレータとして 使われた場合、`next()` メソッドが繰り返し呼び出されます。 個のメソッドは次の入力行を返すか、または EOF に到達したときに `StopIteration` を送出します。ファイル内の各行に対する `for` ループ (非常によくある操作です) を効率的な方法で 行うために、`next()` メソッドは隠蔽された先読みバッファ を使います。先読みバッファを使った結果として、(`readline()` のような) 他のファイルメソッドと `next()` を組み合わせて使うと うまく動作しません。しかし、`seek()` を使ってファイル位置 を絶対指定しなおすと、先読みバッファはフラッシュされます。

  バージョン 2.3 で 新たに追加 された仕様です。

`read`( | [size])

  最大で size バイトをファイルから読み込みます (size バイト を取得する前に EOF に到達した場合、それ以下の長さになります) size 引数が負であるか省略された場合、EOF に到達するまでの 全てのデータを読み込みます。読み出されたバイト列は文字列オブジェクト として返されます。直後に EOF に到達した場合、空の文字列が返されます。 (端末のようなある種のファイルでは、 EOF に到達した後でファイルを 読みつづけることにも意味があります。) このメソッドは、size バイトに可能な限り近くデータを取得するために、背後の C 関数 `fread()` を 1 度以上呼び出すかもしれないので注意してください。 また、非ブロック・モードでは、size パラメータが与えられなくても、 要求されたよりも少ないデータが返される場合があることに注意してください。

`readline`( | [size])

  ファイルから一行を読み出します。末尾の改行文字は文字列中に 残されます（ですが、ファイルが不完全な行で終わっている場合は 何も残らないかもしれません）。 12引数 size が指定されていて負数でない場合、 (末尾の改行を含めて) 読み込む最大のバイト数です。この場合、 不完全な行が返されるかもしれません。空文字列が返されるのは、 直後に EOF に到達した場合 だけ です。 注意: `stdio` の `fgets()` と違い、入力中に ヌル文字 (`'\0'`) が含まれていれば、ヌル文字を含んだ 文字列が返されます。

`readlines`( | [sizehint])

  `readline()` を使ってに到達するまで読み出し、EOF 読み出された行を含むリストを返します。オプションの sizehint 引数が存在すれば、EOFまで読み出す代わりに 完全な行を全体で大体 sizehint バイトになるように (おそらく内部バッファサイズを切り詰めて) 読み出します。 ファイル類似のインタフェースを実装しているオブジェクトは、 sizehint を実装できないか効率的に実装できない場合には 無視してもかまいません。

`xreadlines`( | )

  個のメソッドは `iter(f)` と同じ結果を返します。 バージョン 2.1 で 新たに追加 された仕様です。
  リリース 2.3 で撤廃されました。 代わりに "`for line in file`" を使ってください。

`seek`( | offset[, whence])

  `stdio` の `fseek()` と同様に、ファイルの現在位置を 返します。whence 引数はオプションで、標準の値は `0` (絶対位置指定) です; 他に取り得る値は `1` (現在のファイル位置 から相対的に seek する) および `2` (ファイルの末端から相対的に seek する) です。戻り値はありません。ファイルを追記モード (モード `'a'` または `'a+'`) で開いた場合、書き込みを行う までに行った`seek()` 操作はすべて元に戻されるので注意してください。 ファイルが追記のみの書き込みモード (`'a'`) で開かれた場合、 このメソッドは実質何も行いませんが、読み込みが可能な追記モード (`'a+'`) で開かれたファイルでは役に立ちます。 ファイルをテキストモードで (`'b'` なしで) 開いた場合、 `tell()` が返すオフセットのみが正しい値になります。 他のオフセット値を使った場合、その振る舞いは未定義です。

  全てのファイルオブジェクトが seek できるとは限らないので注意してください。

`tell`( | )

  `stdio` の `ftell()` と同様、ファイルの現在位置を 返します。

  注意: Windows では、(`fgets()` の後で) Unix-スタイルの改行 のファイルを読むときに`tell()` が不正な値を返すことがあります。 この問題に遭遇しないためにはバイナリーモード (`'rb'`) を使うよう にしてください。

`truncate`( | [size])

  ファイルのサイズを切り詰めます。オプションの size が存在 すれば、ファイルは (最大で) 指定されたサイズに切り詰められます。 標準設定のサイズの値は、現在のファイル位置までのファイルサイズです。 現在のファイル位置は変更されません。指定されたサイズがファイルの 現在のサイズを越える場合、その結果はプラットフォーム依存なので 注意してください: 可能性としては、ファイルは変更されないか、 指定されたサイズまでゼロで埋められるか、指定されたサイズまで 未定義の新たな内容で埋められるか、があります。 利用可能な環境: Windows, 多くの Unix 系。

`write`( | str)

  文字列をファイルに書き込みます。戻り値はありません。バッファリング によって、`flush()` または `close()` が呼び出されるまで 実際にファイル中に文字列が書き込まれないこともあります。

`writelines`( | sequence)

  文字列からなるシーケンスをファイルに書き込みます。シーケンスは文字列を生成 する反復可能なオブジェクトなら何でもかまいません。よくあるのは 文字列からなるリストです。戻り値はありません。 (関数の名前は `readlines()` と対応づけてつけられました; `writelines()` は行間の区切りを追加しません)

ファイルはイテレータプロトコルをサポートします。各反復操作では `file.readline()` と同じ結果を返し、反復は `readline()` メソッドが空文字列を返した際に終了します。

ファイルオブジェクトはまた、多くの興味深い属性を提供します。 これらはファイル類似オブジェクトでは必要ではありませんが、 特定のオブジェクトにとって意味を持たせたいなら実装しなければ なりません。

`closed`
  現在のファイルオブジェクトの状態を示すブール値です。この値は 読み出し専用の属性です; `close()` メソッドがこの値を 変更します。全てのファイル類似オブジェクトで利用可能とは 限りません。

`encoding`
  このファイルが使っているエンコーディングです。Unicode 文字列が ファイルに書き込まれる際、Unicode 文字列はこのエンコーディングを 使ってバイト文字列に変換されます。さらに、ファイルが端末に 接続されている場合、この属性は端末が使っているとおぼしきエンコーディング (この情報は端末がうまく設定されていない場合には不正確なこともあります) を与えます。この属性は読み出し専用で、すべてのファイル類似オブジェクト にあるとは限りません。またこの値は `None` のこともあり、 この場合、ファイルはUnicode 文字列の変換のためにシステムのデフォルト エンコーディングを使います。

  バージョン 2.3 で 新たに追加 された仕様です。

`mode`
  ファイルの I/O モードです。ファイルが組み込み関数 `open()` で作成された場合、この値は引数 mode の値になります。 この値は読み出し専用の属性で、全てのファイル類似オブジェクトに 存在するとは限りません。

`name`
  ファイルオブジェクトが `open()` を使って生成された時の ファイルの名前です。そうでなければ、ファイルオブジェクト生成の 起源を示す何らかの文字列になり、"`<...>`" の形式を とります。この値は読み出し専用の属性で、全てのファイル類似オブジェクトに 存在するとは限りません。

`newlines`
  Python をビルドするとき、--with-universal-newlines オプションがconfigure に指定された場合（デフォルト）、 この読み出し専用の属性が存在します。一般的な 改行に変換する読み出しモードで開かれたファイルにおいて、この属性はファイ ルの読み出し中に遭遇した改行コードを追跡します。取り得る値は `'\ r'`、`'\n'`、`'\r\n'`、`None` (不明または、まだ改行 していない）、見つかった全ての改行文字を含むタプルのいずれかです。最後の タプルは、複数の改行慣例に遭遇したことを示します。一般的な改行文字を使う 読み出しモードで開かれていないファイルの場合、この属性の値は `None` です。

`softspace`
  `print` 文を使った場合、他の値を出力する前にスペース文字を 出力する必要があるかどうかを示すブール値です。 ファイルオブジェクトをシミュレート仕様とするクラスは書き込み可能な `softspace` 属性を持たなければならず、この値はゼロに初期化 されなければなりません。この値は Python で実装されているほとんどの クラスで自動的に初期化されます (属性へのアクセス手段を上書きする ようなオブジェクトでは注意が必要です); C で実装された型では、 書き込み可能な `softspace` 属性を提供しなければなりません。 注意: この属性は `print` 文を制御するために用いられますが、 `print` の内部状態を乱さないために、その実装を行うことは できません。

#### Footnotes

... で生成することができます。11
  `file()` は Python 2.2 で新しく追加されました。 古いバージョンの組み込み関数 `open()` は `file()` の別名です。
... 何も残らないかもしれません）。12
  改行を残す利点は、空の文字列が返ると EOF を示し、紛らわしくなくなるからです。また、ファイルの最後の行 が改行で終わっているかそうでない (ありえることです！) か (例えば、ファイルを行単位で読みながらその完全なコピーを作成 した場合には問題になります) を調べることができます。