このモジュールは、(メモリファイル としても知られている) 文字列のバッファに対して読み書きを行うファイルのようなクラス、 StringIO を実装しています。 (通常の文字列については、 str と unicode を参照してください)
操作方法についてはファイルオブジェクトの説明を参照してください(セクション ファイルオブジェクト)。
StringIO オブジェクトを作る際に、コンストラクターに文字列を渡すことで初期化することができます。文字列を渡さない場合、最初は StringIO はカラです。どちらの場合でも最初のファイル位置は 0 から始まります。
StringIO オブジェクトはユニコードも 8-bit の文字列も受け付けますが、この2つを混ぜることには少し注意が必要です。 この2つが一緒に使われると、 getvalue() が呼ばれたときに、 (8th ビットを使っている)7-bit ASCII に解釈できない 8-bit の文字列は、 UnicodeError を引き起こします。
次にあげる StringIO オブジェクトのメソッドには特別な説明が必要です:
StringIO オブジェクトの close() メソッドが呼ばれる前ならいつでも、 “file” の中身全体を返します。 ユニコードと 8-bit の文字列を混ぜることの説明は、上の注意を参照してください。この2つの文字コードを混ぜると、このメソッドは UnicodeError を引き起こすかもしれません。
メモリバッファを解放します。 close された後の StringIO オブジェクトを操作しようとすると ValueError が送出されます。
使用例:
import StringIO
output = StringIO.StringIO()
output.write('First line.\n')
print >>output, 'Second line.'
# ファイルの内容を取り出す -- ここでは
# 'First line.\nSecond line.\n'
contents = output.getvalue()
# オブジェクトを閉じてメモリバッファを解放する --
# .getvalue() は例外を送出するようになる。
output.close()
cStringIO モジュールは StringIO モジュールと同様のインターフェースを提供しています。 StringIO.StringIO オブジェクトを酷使する場合、このモジュールにある StringIO() 関数をかわりに使うと効果的です。
このモジュールは、ビルトイン型のオブジェクトを返すファクトリー関数を提供しているので、サブクラス化して自分用の物を作ることはできません。 そうした場合には、オリジナルの StringIO モジュールを使ってください。
StringIO モジュールで実装されているメモリファイルとは異なり、このモジュールで提供されているものは、プレイン ASCII 文字列にエンコードできないユニコードを受け付けることができません。
Unicode文字列を使って StringIO() を呼び出すと、文字列をエンコードするのではなく Unicode 文字列の buffer 表現が利用されます。
また、引数に文字列を指定して StringIO() 呼び出すと読み出し専用のオブジェクトが生成されますが、この場合 cStringIO.StringIO() では write()メソッドを持たないオブジェクトを生成します。 これらのオブジェクトは普段は見えません。トレースバックに StringI と StringO として表示されます。
次にあげるデータオブジェクトも提供されています:
文字列をパラメーターに渡して StringIO() を呼んだときに作られるオブジェクトのオブジェクト型。
パラメーターを渡さすに StringIO() を呼んだときに返されるオブジェクトのオブジェクト型。
このモジュールには C API もあります。詳しくはこのモジュールのソースを参照してください。
使用例:
import cStringIO
output = cStringIO.StringIO()
output.write('First line.\n')
print >>output, 'Second line.'
# ファイルの内容を取り出す -- ここでは
# 'First line.\nSecond line.\n'
contents = output.getvalue()
# オブジェクトを閉じてメモリバッファを解放する --
# 以降 .getvalue() は例外を送出するようになる。
output.close()