io
--- ストリームを扱うコアツール¶
ソースコード: Lib/io.py
概要¶
io
モジュールは様々な種類の I/O を扱う Python の主要な機能を提供しています。 I/O には主に3つの種類があります; テキスト I/O, バイナリ I/O, raw I/O です。これらは汎用的なカテゴリで、各カテゴリには様々なストレージが利用されます。これらのいずれかのカテゴリに属する具象オブジェクトは全て file object と呼ばれます。他によく使われる用語として ストリーム と file-like オブジェクト があります。
それぞれの具象ストリームオブジェクトは、カテゴリに応じた機能を持ちます。ストリームは読み込み専用、書き込み専用、読み書き可能のいずかになります。任意のランダムアクセス(前方、後方の任意の場所にシークする)が可能かもしれませんし、シーケンシャルアクセスしかできないかもしれません(例えばソケットやパイプなど)。
All streams are careful about the type of data you give to them. For example
giving a str
object to the write()
method of a binary stream
will raise a TypeError
. So will giving a bytes
object to the
write()
method of a text stream.
テキスト I/O¶
テキスト I/O は、 str
オブジェクトを受け取り、生成します。すなわち、背後にあるストレージがバイト列 (例えばファイルなど) を格納するときは常に、透過的にデータのエンコード・デコードを行ない、オプションでプラットフォーム依存の改行文字変換を行います。
The easiest way to create a text stream is with open()
, optionally
specifying an encoding:
f = open("myfile.txt", "r", encoding="utf-8")
StringIO
オブジェクトはインメモリーのテキストストリームです:
f = io.StringIO("some initial text data")
テキストストリームの API は TextIOBase
のドキュメントで詳しく解説します。
バイナリ I/O¶
バイナリー I/O (buffered I/O とも呼ばれます) は bytes-like オブジェクト を受け取り bytes
オブジェクトを生成します。エンコード、デコード、改行文字変換は一切行いません。このカテゴリのストリームは全ての非テキストデータや、テキストデータの扱いを手動で管理したい場合に利用することができます。
The easiest way to create a binary stream is with open()
with 'b'
in
the mode string:
f = open("myfile.jpg", "rb")
BytesIO
はインメモリーのバイナリストリームです:
f = io.BytesIO(b"some initial binary data: \x00\x01")
バイナリーストリーム API は BufferedIOBase
のドキュメントで詳しく解説します。
他のライブラリモジュールが、別のテキスト・バイナリーストリームを生成する方法を提供しています。例えば socket.socket.makefile()
などです。
Raw I/O¶
Raw I/O (unbuffered I/O とも呼ばれます) は、バイナリーストリームやテキストストリームの低水準の部品としてよく利用されます。ユーザーコードで直接 raw ストリームを扱うべき場面は滅多にありません。とはいえ、バッファリングを無効にしてファイルをバイナリーモードで開くことで raw ストリームを作ることができます:
f = open("myfile.jpg", "rb", buffering=0)
raw ストリーム API は RawIOBase
のドキュメントで詳しく解説します。
Text Encoding¶
The default encoding of TextIOWrapper
and open()
is
locale-specific (locale.getencoding()
).
However, many developers forget to specify the encoding when opening text files encoded in UTF-8 (e.g. JSON, TOML, Markdown, etc...) since most Unix platforms use UTF-8 locale by default. This causes bugs because the locale encoding is not UTF-8 for most Windows users. For example:
# May not work on Windows when non-ASCII characters in the file.
with open("README.md") as f:
long_description = f.read()
Accordingly, it is highly recommended that you specify the encoding
explicitly when opening text files. If you want to use UTF-8, pass
encoding="utf-8"
. To use the current locale encoding,
encoding="locale"
is supported since Python 3.10.
参考
- Python UTF-8 Mode
Python UTF-8 Mode can be used to change the default encoding to UTF-8 from locale-specific encoding.
- PEP 686
Python 3.15 will make Python UTF-8 Mode default.
Opt-in EncodingWarning¶
Added in version 3.10: See PEP 597 for more details.
To find where the default locale encoding is used, you can enable
the -X warn_default_encoding
command line option or set the
PYTHONWARNDEFAULTENCODING
environment variable, which will
emit an EncodingWarning
when the default encoding is used.
If you are providing an API that uses open()
or
TextIOWrapper
and passes encoding=None
as a parameter, you
can use text_encoding()
so that callers of the API will emit an
EncodingWarning
if they don't pass an encoding
. However,
please consider using UTF-8 by default (i.e. encoding="utf-8"
) for
new APIs.
高水準のモジュールインターフェイス¶
- io.DEFAULT_BUFFER_SIZE¶
このモジュールの buffered I/O クラスで利用されるデフォルトのバッファーサイズを表す整数です。可能であれば、
open()
は file の blksize (os.stat()
で取得される) を利用します。
- io.open(file, mode='r', buffering=-1, encoding=None, errors=None, newline=None, closefd=True, opener=None)¶
組み込みの
open()
関数のエイリアスです。This function raises an auditing event
open
with arguments path, mode and flags. The mode and flags arguments may have been modified or inferred from the original call.
- io.open_code(path)¶
'rb'
モードでファイルを開きます。この関数はファイルの中身を実行可能なコードとして扱いたい場合にのみ使用します。path should be a
str
and an absolute path.The behavior of this function may be overridden by an earlier call to the
PyFile_SetOpenCodeHook()
. However, assuming that path is astr
and an absolute path,open_code(path)
should always behave the same asopen(path, 'rb')
. Overriding the behavior is intended for additional validation or preprocessing of the file.Added in version 3.8.
- io.text_encoding(encoding, stacklevel=2, /)¶
This is a helper function for callables that use
open()
orTextIOWrapper
and have anencoding=None
parameter.This function returns encoding if it is not
None
. Otherwise, it returns"locale"
or"utf-8"
depending on UTF-8 Mode.This function emits an
EncodingWarning
ifsys.flags.warn_default_encoding
is true and encoding isNone
. stacklevel specifies where the warning is emitted. For example:def read_text(path, encoding=None): encoding = io.text_encoding(encoding) # stacklevel=2 with open(path, encoding) as f: return f.read()
In this example, an
EncodingWarning
is emitted for the caller ofread_text()
.See Text Encoding for more information.
Added in version 3.10.
バージョン 3.11 で変更:
text_encoding()
returns "utf-8" when UTF-8 mode is enabled and encoding isNone
.
- exception io.BlockingIOError¶
互換性のための、組み込みの
BlockingIOError
例外のエイリアスです。
- exception io.UnsupportedOperation¶
OSError
とValueError
を継承した例外です。ストリームがサポートしていない操作を行おうとした時に送出されます。
参考
sys
標準 IO ストリームを持っています:
sys.stdin
,sys.stdout
,sys.stderr
。
クラス階層¶
I/O ストリームの実装はクラス階層に分けて整理されています。まずストリームのカテゴリを分類するための 抽象基底クラス (ABC) があり、続いて標準のストリーム実装を行う具象クラス群があります。
注釈
The abstract base classes also provide default implementations of some
methods in order to help implementation of concrete stream classes. For
example, BufferedIOBase
provides unoptimized implementations of
readinto()
and readline()
.
I/O 階層の最上位には抽象基底クラスの IOBase
があります。 IOBase
ではストリームに対して基本的なインターフェースを定義しています。 しかしながら、ストリームに対する読み込みと書き込みが分離されていないことに注意してください。 実装においては与えられた操作をサポートしない場合は UnsupportedOperation
を送出することが許されています。
RawIOBase
ABC は IOBase
を拡張します。このクラスはストリームからの bytes の読み書きを扱います。 FileIO
は、 RawIOBase
を継承してマシンのファイルシステム中のファイルへのインターフェースを提供します。
The BufferedIOBase
ABC extends IOBase
. It deals with
buffering on a raw binary stream (RawIOBase
). Its subclasses,
BufferedWriter
, BufferedReader
, and BufferedRWPair
buffer raw binary streams that are writable, readable, and both readable and writable,
respectively. BufferedRandom
provides a buffered interface to seekable streams.
Another BufferedIOBase
subclass, BytesIO
, is a stream of
in-memory bytes.
TextIOBase
ABC は IOBase
を拡張します。このクラスはテキストをあらわすバイトストリームを対象とし、バイトデータと文字列の間のエンコーディングやデコーディングを適切に行います。 TextIOWrapper
は TextIOBase
を拡張し、バッファリングされた生のストリーム (BufferedIOBase
) に対するバッファリングされたテキストのインターフェースです。最後に、 StringIO
はメモリ上のテキストデータに対するストリームです。
引数名は規約に含まれていません。 そして open()
の引数だけがキーワード引数として用いられることが意図されています。
次のテーブルは io
モジュールが提供する ABC の概要です:
ABC |
継承元 |
スタブメソッド |
Mixin するメソッドとプロパティ |
---|---|---|---|
|
|
||
|
|
||
|
|
||
|
|
I/O 基底クラス¶
- class io.IOBase¶
The abstract base class for all I/O classes.
継承先のクラスが選択的にオーバライドできるように、このクラスは多くのメソッドに空の抽象実装をしています。デフォルトの実装では、読み込み、書き込み、シークができないファイルを表現します。
Even though
IOBase
does not declareread()
orwrite()
because their signatures will vary, implementations and clients should consider those methods part of the interface. Also, implementations may raise aValueError
(orUnsupportedOperation
) when operations they do not support are called.ファイルへのバイナリデータの読み書きに用いられる基本型は
bytes
です。 他の bytes-like オブジェクト もメソッドの引数として受け付けられます。 テキスト I/O クラスはstr
データを扱います。閉じられたストリームに対するメソッド呼び出しは (問い合わせであっても) 未定義です。この場合、実装は
ValueError
を送出することがあります。IOBase
(とそのサブクラス) はイテレータプロトコルをサポートします。IOBase
オブジェクトをイテレートすると、ストリーム内の行が yield されます。ストリーム内の行の定義は、そのストリームが (バイト列を yield する) バイナリストリームか (文字列を yield する) テキストストリームかによって、 少し異なります。下のreadline()
を参照してください。IOBase
はコンテキストマネージャでもあります。そのためwith
構文をサポートします。 次の例では、with
構文が終わった後で---たとえ例外が発生した場合でも、 file は閉じられます。with open('spam.txt', 'w') as file: file.write('Spam and eggs!')
IOBase
は以下のデータ属性とメソッドを提供します:- close()¶
このストリームをフラッシュして閉じます。このメソッドはファイルが既に閉じられていた場合は特に何の効果もありません。いったんファイルが閉じられると、すべてのファイルに対する操作 (例えば読み込みや書き込み) で
ValueError
が発生します。利便性のためにこのメソッドを複数回呼ぶことは許されています。しかし、効果があるのは最初の1回だけです。
- closed¶
ストリームが閉じられていた場合
True
になります。
- flush()¶
適用可能であればストリームの書き込みバッファをフラッシュします。読み出し専用や非ブロッキングストリームでは何もしません。
- isatty()¶
ストリームが対話的であれば (つまりターミナルや tty デバイスにつながっている場合)
True
を返します。
- readline(size=-1, /)¶
ストリームから 1 行読み込んで返します。もし size が指定された場合、最大で size バイトが読み込まれます。
バイナリファイルでは行末文字は常に
b'\n'
となります。テキストファイルでは、認識される行末文字を選択するためにopen()
に対する newline 引数が使われます。
- readlines(hint=-1, /)¶
ストリームから行のリストを読み込んで返します。 hint を指定することで、読み込む行数を制御できます。もし読み込んだすべての行のサイズ (バイト数、もしくは文字数) が hint の値を超えた場合、それ以上の行は読み込まれません。
引数 hint の値が
0
以下、およびNone
の場合は、ヒントがないものとして取り扱われます。Note that it's already possible to iterate on file objects using
for line in file: ...
without callingfile.readlines()
.
- seek(offset, whence=os.SEEK_SET, /)¶
Change the stream position to the given byte offset, interpreted relative to the position indicated by whence, and return the new absolute position. Values for whence are:
os.SEEK_SET
or0
-- start of the stream (the default); offset should be zero or positiveos.SEEK_CUR
or1
-- current stream position; offset may be negativeos.SEEK_END
or2
-- end of the stream; offset is usually negative
Added in version 3.1: The
SEEK_*
constants.Added in version 3.3: Some operating systems could support additional values, like
os.SEEK_HOLE
oros.SEEK_DATA
. The valid values for a file could depend on it being open in text or binary mode.
- seekable()¶
ストリームがランダムアクセスをサポートしている場合、
True
を返します。False
の場合、seek()
、tell()
、truncate()
を使用するとOSError
を発生させます。
- tell()¶
現在のストリーム位置を返します。
- truncate(size=None, /)¶
ストリームのサイズを、指定された size バイト (または size が指定されていない場合、現在位置) に変更します。現在のストリーム位置は変更されません。このサイズ変更により、現在のファイルサイズを拡大または縮小させることができます。拡大の場合には、新しいファイル領域の内容はプラットホームによって異なります (ほとんどのシステムでは、追加のバイトが 0 で埋められます)。新しいファイルサイズが返されます。
バージョン 3.5 で変更: Windows で、拡大時に追加領域を 0 で埋めるようになりました。
- writable()¶
Return
True
if the stream supports writing. IfFalse
,write()
andtruncate()
will raiseOSError
.
- writelines(lines, /)¶
ストリームに行のリストを書き込みます。行区切り文字は追加されないので、書き込む各行の行末に行区切り文字を含ませるのが一般的です。
- class io.RawIOBase¶
Base class for raw binary streams. It inherits from
IOBase
.生のバイナリストリームは典型的に、背後にある OS デバイスや API への低水準なアクセスを提供し、それらを高水準の基本要素へカプセル化しようとはしません (そのような機能は後述するバッファされたバイナリストリームやテキストストリームのような高水準のクラスで行われます)。
RawIOBase
はIOBase
が提供するメソッドに加えて、以下のメソッドを提供します:- read(size=-1, /)¶
オブジェクトを size バイトまで読み込み、それを返します。 簡単のため、 size が指定されていないか -1 の場合は、 EOF までの全てのバイトを返します。 そうでない場合は、システムコール呼び出しが一度だけ行われます。 オペレーティングシステムコールから返ってきたものが size バイトより少なければ、 size バイトより少ない返り値になることがあります。
size が 0 でないのに 0 バイトが返った場合、それはファイルの終端を表します。オブジェクトがノンブロッキングモードで、1 バイトも読み込めなければ、
None
が返されます。デフォルトの実装は
readall()
とreadinto()
に従います。
- readall()¶
EOF までストリームからすべてのバイトを読み込みます。必要な場合はストリームに対して複数の呼び出しをします。
- readinto(b, /)¶
あらかじめ確保された書き込み可能な bytes 類オブジェクト b にバイト列を読み込み、読み込んだバイト数を返します。 例えば、 b は
bytearray
です。 オブジェクトがノンブロッキングモードで、 1 バイトも読み込めなければ、None
が返されます。
- write(b, /)¶
与えられた bytes-like オブジェクト b を生ストリームに書き込み、書き込んだバイト数を返します。これは、根底の生ストリームの性質や、特にノンブロッキングである場合に、 b のバイト数より小さくなることがあります。生ストリームがブロックされないように設定されていて、かつ1バイトも即座に書き込むことができなければ、
None
が返されます。このメソッドから返った後で呼び出し元は b を解放したり変更したりするかもしれないので、実装はメソッド呼び出しの間だけ b にアクセスすべきです。
- class io.BufferedIOBase¶
Base class for binary streams that support some kind of buffering. It inherits from
IOBase
.RawIOBase
との主な違いは、メソッドread()
、readinto()
およびwrite()
は 、ことによると複数回のシステムコールを行って、(それぞれ) 要求されただけの入力を読み込もうとしたり与えられた出力の全てを消費しようとしたりする点です。加えて、元になる生ストリームが非ブロッキングモードでかつ準備ができていない場合に、これらのメソッドは、
BlockingIOError
を送出するかもしれません。対応するRawIOBase
バージョンと違って、None
を返すことはありません。さらに、
read()
メソッドは、readinto()
に従うデフォルト実装を持ちません。通常の
BufferedIOBase
実装はRawIOBase
実装を継承せずに、BufferedWriter
とBufferedReader
がするようにこれをラップすべきです。BufferedIOBase
はIOBase
から継承した属性とメソッドに加えて、以下のデータ属性とメソッドを提供またはオーバーライドします:- raw¶
BufferedIOBase
が扱う根底の生ストリーム (RawIOBase
インスタンス) を返します。これはBufferedIOBase
API には含まれず、よって実装に含まれないことがあります。
- detach()¶
根底の生ストリームをバッファから分離して返します。
生ストリームが取り外された後、バッファは使用不能状態になります。
バッファには、
BytesIO
など、このメソッドで返される単体のストリームという概念を持たないものがあります。これらはUnsupportedOperation
を送出します。Added in version 3.1.
- read(size=-1, /)¶
最大で size バイト読み込んで返します。 引数が省略されるか、
None
か、または負の値であった場合、 データは EOF に到達するまで読み込まれます。 ストリームが既に EOF に到達していた場合は空のbytes
オブジェクトが返されます。引数が正で、元になる生ストリームが対話的でなければ、必要なバイト数を満たすように複数回の生 read が発行されるかもしれません (先に EOF に到達しない限りは)。対話的な場合は、最大で一回の raw read しか発行されず、短い結果でも EOF に達したことを意味しません。
元になる生ストリームがノンブロッキングモードで、呼び出された時点でデータを持っていなければ、
BlockingIOError
が送出されます。
- read1(size=-1, /)¶
根底の raw ストリームの
read()
(またはreadinto()
) メソッドを高々 1 回呼び出し、最大で size バイト読み込み、返します。これは、BufferedIOBase
オブジェクトの上に独自のバッファリングを実装するときに便利です。size に
-1
(デフォルト値)を指定すると任意バイト長を返します(EOFに到達していなければ返されるバイト数は 0 より大きくなります)
- readinto(b, /)¶
あらかじめ確保された書き込み可能な bytes 類オブジェクト b にバイト列を読み込み、読み込んだバイト数を返します。 例えば、 b は
bytearray
です。read()
と同様に、下層の raw ストリームが対話的でない限り、複数の読み込みは下層の raw ストリームに与えられるかもしれません。元になる生ストリームがノンブロッキングモードで、呼び出された時点でデータを持っていなければ、
BlockingIOError
が送出されます。
- readinto1(b, /)¶
根底の raw ストリームの
read()
(またはreadinto()
) メソッドを高々 1 回呼び出し、あらかじめ確保された書き込み可能な bytes-like オブジェクト b にバイト列を読み込みます。読み込んだバイト数を返します。元になる生ストリームがノンブロッキングモードで、呼び出された時点でデータを持っていなければ、
BlockingIOError
が送出されます。Added in version 3.5.
- write(b, /)¶
与えられた bytes-like オブジェクト b を書き込み、書き込んだバイト数を返します (これは常に b のバイト数と等しくなります。なぜなら、もし書き込みに失敗した場合は
OSError
が発生するからです)。実際の実装に依存して、これらのバイト列は根底のストリームに即座に書き込まれることもあれば、パフォーマンスやレイテンシの関係でバッファに保持されることもあります。ノンブロッキングモードであるとき、バッファが満杯で根底の生ストリームが書き込み時点でさらなるデータを受け付けられない場合
BlockingIOError
が送出されます。このメソッドが戻った後で、呼び出し元は b を解放、または変更するかもしれないので、実装はメソッド呼び出しの間だけ b にアクセスすべきです。
生ファイルI/O¶
- class io.FileIO(name, mode='r', closefd=True, opener=None)¶
A raw binary stream representing an OS-level file containing bytes data. It inherits from
RawIOBase
.name は、次の 2 つのいずれかです。
開くファイルへのパスを表す文字列または
bytes
オブジェクト。 この場合、closefd はTrue
(デフォルト) でなければなりません。True
でない場合、エラーが送出されます。結果の
FileIO
オブジェクトがアクセスを与える、既存の OS レベルファイル記述子の数を表す整数。FileIO オブジェクトが閉じられると、closefd がFalse
に設定されていない場合、この fd も閉じられます。
mode は 読み込み(デフォルト)、書き込み、排他的作成、追記に対し
'r'
、'w'
、'x'
、'a'
です。ファイルは書き込みや追記で開かれたときに存在しない場合作成されます。書き込みのときにファイルの内容は破棄されます。作成時に既に存在する場合はFileExistsError
が送出されます。作成のためにファイルを開くのは暗黙的に書き込みなので、このモードは'w'
と同じように振る舞います。読み込みと書き込みを同時に許可するにはモードに'+'
を加えてください。The
read()
(when called with a positive argument),readinto()
andwrite()
methods on this class will only make one system call.呼び出し可能オブジェクトを opener として与えることで、カスタムのオープナーが使えます。そしてファイルオブジェクトの基底のファイルディスクリプタは、opener を (name, flags) で呼び出して得られます。opener は開いたファイルディスクリプタを返さなければなりません。 (
os.open
を opener として渡すと、None
を渡したのと同様の機能になります。)新たに作成されたファイルは 継承不可 です。
opener 引数を使う例については
open()
組み込み関数を参照してください。バージョン 3.3 で変更: opener 引数が追加されました。
'x'
モードが追加されました。バージョン 3.4 で変更: ファイルが継承不可になりました。
FileIO
はRawIOBase
とIOBase
から継承したデータ属性に加えて以下のデータ属性を提供します:- mode¶
コンストラクタに渡されたモードです。
- name¶
ファイル名。コンストラクタに名前が渡されなかったときはファイル記述子になります。
バッファ付きストリーム¶
バッファ付き I/O ストリームは、I/O デバイスに生 I/O より高レベルなインターフェースを提供します。
- class io.BytesIO(initial_bytes=b'')¶
A binary stream using an in-memory bytes buffer. It inherits from
BufferedIOBase
. The buffer is discarded when theclose()
method is called.省略可能な引数 initial_bytes は、初期データを含んだ bytes-like オブジェクト です。
BytesIO
はBufferedIOBase
またはIOBase
からのメソッドに加えて、以下のメソッドを提供もしくはオーバーライドします:- getbuffer()¶
バッファの内容をコピーすることなく、その内容の上に、読み込み及び書き込みが可能なビューを返します。また、このビューを変更すると、バッファの内容は透過的に更新されます:
>>> b = io.BytesIO(b"abcdef") >>> view = b.getbuffer() >>> view[2:4] = b"56" >>> b.getvalue() b'ab56ef'
注釈
ビューが存在する限り、
BytesIO
オブジェクトはリサイズやクローズされません。Added in version 3.2.
- readinto1(b, /)¶
BytesIO
においては、このメソッドはreadinto()
と同じです。Added in version 3.5.
- class io.BufferedReader(raw, buffer_size=DEFAULT_BUFFER_SIZE)¶
A buffered binary stream providing higher-level access to a readable, non seekable
RawIOBase
raw binary stream. It inherits fromBufferedIOBase
.このオブジェクトからデータを読み出した時、背後にある生のストリームからはより大きな量のデータの読み出しがリクエストされ、内部バッファに読み出したデータが保持されることがあります。バッファされたデータはその後の読み出し処理で直接返すことができます。
このコンストラクタは与えられた raw ストリームと buffer_size に対し
BufferedReader
を生成します。 buffer_size が省略された場合、代わりにDEFAULT_BUFFER_SIZE
が使われます。BufferedReader
はBufferedIOBase
またはIOBase
からのメソッドに加えて、以下のメソッドを提供もしくはオーバーライドします:- peek(size=0, /)¶
位置を進めずにストリームからバイト列を返します。これを果たすために生ストリームに対して行われる read は高々一度だけです。返されるバイト数は、要求より少ないかもしれませんし、多いかもしれません。
- read(size=-1, /)¶
size バイトを読み込んで返します。size が与えられないか負の値ならば、EOF まで、または非ブロッキングモード中で read 呼び出しがブロックされるまでを返します。
- read1(size=-1, /)¶
raw ストリームに対しただ一度の呼び出しで最大 size バイトを読み込んで返します。少なくとも 1 バイトがバッファされていれば、バッファされているバイト列だけが返されます。それ以外の場合は raw ストリームの読み込みが一回呼び出されます。
バージョン 3.7 で変更: size 引数が任意になりました。
- class io.BufferedWriter(raw, buffer_size=DEFAULT_BUFFER_SIZE)¶
A buffered binary stream providing higher-level access to a writeable, non seekable
RawIOBase
raw binary stream. It inherits fromBufferedIOBase
.このオブジェクトに対して書き込みを行なったとき、データは通常内部バッファに配置されます。バッファは以下に示すさまざまな条件で背後にある
RawIOBase
オブジェクトに書き込まれます:保留中の全データに対してバッファが足りなくなったとき;
when
flush()
is called;when a
seek()
is requested (forBufferedRandom
objects);BufferedWriter
オブジェクトが閉じられたり破棄されたりしたとき。
このコンストラクタは与えられた書き込み可能な raw ストリームに対し
BufferedWriter
を生成します。 buffer_size が省略された場合、DEFAULT_BUFFER_SIZE
がデフォルトになります。BufferedWriter
はBufferedIOBase
またはIOBase
からのメソッドに加えて、以下のメソッドを提供もしくはオーバーライドします:- flush()¶
バッファに保持されたバイト列を生ストリームに強制的に流し込みます。生ストリームがブロックした場合
BlockingIOError
が送出されます。
- write(b, /)¶
bytes-like オブジェクト b を書き込み、書き込んだバイト数を返します。ノンブロッキング時、バッファが書き込まれるべきなのに生ストリームがブロックした場合
BlockingIOError
が送出されます。
- class io.BufferedRandom(raw, buffer_size=DEFAULT_BUFFER_SIZE)¶
A buffered binary stream providing higher-level access to a seekable
RawIOBase
raw binary stream. It inherits fromBufferedReader
andBufferedWriter
.このコンストラクタは第一引数として与えられるシーク可能な生ストリームに対し、リーダーおよびライターを作成します。 buffer_size が省略された場合、
DEFAULT_BUFFER_SIZE
がデフォルトになります。BufferedRandom
is capable of anythingBufferedReader
orBufferedWriter
can do. In addition,seek()
andtell()
are guaranteed to be implemented.
- class io.BufferedRWPair(reader, writer, buffer_size=DEFAULT_BUFFER_SIZE, /)¶
A buffered binary stream providing higher-level access to two non seekable
RawIOBase
raw binary streams---one readable, the other writeable. It inherits fromBufferedIOBase
.reader と writer はそれぞれ読み込み可能、書き込み可能な
RawIOBase
オブジェクトです。 buffer_size が省略された場合DEFAULT_BUFFER_SIZE
がデフォルトになります。BufferedRWPair
は、UnsupportedOperation
を送出するdetach()
を除く、BufferedIOBase
の全てのメソッドを実装します。警告
BufferedRWPair
は下層の生ストリームのアクセスを同期しようとはしません。同じオブジェクトをリーダとライタとして渡してはいけません。その場合は代わりにBufferedRandom
を使用してください。
テキスト I/O¶
- class io.TextIOBase¶
Base class for text streams. This class provides a character and line based interface to stream I/O. It inherits from
IOBase
.IOBase
から継承した属性とメソッドに加えて、TextIOBase
は以下のデータ属性とメソッドを提供しています:- encoding¶
エンコーディング名で、ストリームのバイト列を文字列にデコードするとき、また文字列をバイト列にエンコードするときに使われます。
- errors¶
このエンコーダやデコーダのエラー設定です。
- newlines¶
文字列、文字列のタプル、または
None
で、改行がどのように読み換えられるかを指定します。実装や内部コンストラクタのフラグに依って、これは利用できないことがあります。
- buffer¶
TextIOBase
が扱う根底のバイナリバッファ (BufferedIOBase
インスタンス) です。これはTextIOBase
API には含まれず、よって実装に含まれない場合があります。
- detach()¶
根底のバイナリバッファを
TextIOBase
から分離して返します。根底のバッファが取り外された後、
TextIOBase
は使用不能状態になります。TextIOBase
実装には、StringIO
など、根底のバッファという概念を持たないものがあります。これらを呼び出すとUnsupportedOperation
を送出します。Added in version 3.1.
- readline(size=-1, /)¶
Read until newline or EOF and return a single
str
. If the stream is already at EOF, an empty string is returned.size が指定された場合、最大 size 文字が読み込まれます。
- seek(offset, whence=SEEK_SET, /)¶
Change the stream position to the given offset. Behaviour depends on the whence parameter. The default value for whence is
SEEK_SET
.SEEK_SET
or0
: seek from the start of the stream (the default); offset must either be a number returned byTextIOBase.tell()
, or zero. Any other offset value produces undefined behaviour.SEEK_CUR
or1
: "seek" to the current position; offset must be zero, which is a no-operation (all other values are unsupported).SEEK_END
or2
: seek to the end of the stream; offset must be zero (all other values are unsupported).
新しい絶対位置を、不透明な数値で返します。
Added in version 3.1: The
SEEK_*
constants.
- tell()¶
ストリームの現在位置を不透明な数値で返します。この値は根底のバイナリストレージ内でのバイト数を表すとは限りません。
- write(s, /)¶
文字列 s をストリームに書き出し、書き出された文字数を返します。
- class io.TextIOWrapper(buffer, encoding=None, errors=None, newline=None, line_buffering=False, write_through=False)¶
A buffered text stream providing higher-level access to a
BufferedIOBase
buffered binary stream. It inherits fromTextIOBase
.encoding gives the name of the encoding that the stream will be decoded or encoded with. It defaults to
locale.getencoding()
.encoding="locale"
can be used to specify the current locale's encoding explicitly. See Text Encoding for more information.errors はオプションの文字列で、エンコードやデコードの際のエラーをどのように扱うかを指定します。エンコードエラーがあったときに
ValueError
例外を送出させるには'strict'
を渡します (デフォルトのNone
でも同じです)。エラーを無視させるには'ignore'
を渡します。 (エンコーディングエラーを無視するとデータを喪失する可能性があることに注意してください。)'replace'
は不正な形式の文字の代わりにマーカ (たとえば'?'
) を挿入させます。'backslashreplace'
を指定すると、不正な形式のデータをバックスラッシュ付きのエスケープシーケンスに置換します。書き込み時には'xmlcharrefreplace'
(適切な XML 文字参照に置換) や'namereplace'
(\N{...}
エスケープシーケンスに置換) も使えます。他にもcodecs.register_error()
で登録されたエラー処理名が有効です。newline は行末をどのように処理するかを制御します 。
None
,''
,'\n'
,'\r'
,'\r\n'
のいずれかです。これは以下のように動作します:ストリームからの入力を読み込んでいるとき、もし newline が
None
ならば universal newlines モードが有効になります。入力中の行は'\n'
,'\r'
, または'\r\n'
のいずれで終わってもよく、それらは呼び出し元に返される前に``'n'`` に変換されます。 newline が''
の場合、 universal newlines モードは有効になりますが、行末のコードは変換されずに呼び出し元に返されます。 newline がその他の有効な値の場合は、入力行は与えられた文字列のみで終端され、行末は変換されずに呼び出し元に返されます。ストリームへの出力の書き込み時、newline が
None
の場合、全ての'\n'
文字はシステムのデフォルトの行セパレータos.linesep
に変換されます。 newline が''
または'\n'
の場合は変換されません。newline がその他の正当な値の場合、全ての'\n'
文字は与えられた文字列に変換されます。
If line_buffering is
True
,flush()
is implied when a call to write contains a newline character or a carriage return.If write_through is
True
, calls towrite()
are guaranteed not to be buffered: any data written on theTextIOWrapper
object is immediately handled to its underlying binary buffer.バージョン 3.3 で変更: write_through 引数が追加されました。
バージョン 3.3 で変更: encoding の規定値が
locale.getpreferredencoding()
からlocale.getpreferredencoding(False)
になりました。locale.setlocale()
を用いてロケールのエンコーディングを一時的に変更してはいけません。ユーザが望むエンコーディングではなく現在のロケールのエンコーディングを使用してください。バージョン 3.10 で変更: The encoding argument now supports the
"locale"
dummy encoding name.TextIOWrapper
はTextIOBase
とIOBase
から継承したものに加えて以下のデータ属性をメソッドを提供します:- line_buffering¶
行バッファリングが有効かどうか。
- write_through¶
書き込みが、根柢のバイナリバッファに即座に渡されるかどうか。
Added in version 3.7.
- reconfigure(*, encoding=None, errors=None, newline=None, line_buffering=None, write_through=None)¶
このテキストストリームを encoding, errors, newline, line_buffering と write_through を新しい設定として再設定します。
encoding が指定されており、errors が指定されていないときに、
errors='strict'
が使われている場合を除き、指定されなかったパラメータは現在の設定が保持されます。ストリームからすでにデータが読み出されていた場合、encodingとnewlineは変更できません。一方で、書き込み後にencodingを変更することはできます。
このメソッドは、新しい設定を適用するまえにストリームをフラッシュします。
Added in version 3.7.
バージョン 3.11 で変更: The method supports
encoding="locale"
option.
- seek(cookie, whence=os.SEEK_SET, /)¶
Set the stream position. Return the new stream position as an
int
.Four operations are supported, given by the following argument combinations:
seek(0, SEEK_SET)
: Rewind to the start of the stream.seek(cookie, SEEK_SET)
: Restore a previous position; cookie must be a number returned bytell()
.seek(0, SEEK_END)
: Fast-forward to the end of the stream.seek(0, SEEK_CUR)
: Leave the current stream position unchanged.
Any other argument combinations are invalid, and may raise exceptions.
参考
os.SEEK_SET
,os.SEEK_CUR
, andos.SEEK_END
.
- class io.StringIO(initial_value='', newline='\n')¶
A text stream using an in-memory text buffer. It inherits from
TextIOBase
.テキストバッファは
close()
メソッドが呼び出されたときに破棄されます。The initial value of the buffer can be set by providing initial_value. If newline translation is enabled, newlines will be encoded as if by
write()
. The stream is positioned at the start of the buffer which emulates opening an existing file in aw+
mode, making it ready for an immediate write from the beginning or for a write that would overwrite the initial value. To emulate opening a file in ana+
mode ready for appending, usef.seek(0, io.SEEK_END)
to reposition the stream at the end of the buffer.newline 引数は
TextIOWrapper
の同名の引数と同じように働きます。ただし、出力をストリームに書き込む時に newline がNone
の場合には、改行は全てのプラットフォームで\n
になります。TextIOBase
とIOBase
から継承したメソッドに加えてStringIO
は以下のメソッドを提供しています:- getvalue()¶
Return a
str
containing the entire contents of the buffer. Newlines are decoded as if byread()
, although the stream position is not changed.
使用例:
import io output = io.StringIO() output.write('First line.\n') print('Second line.', file=output) # Retrieve file contents -- this will be # 'First line.\nSecond line.\n' contents = output.getvalue() # Close object and discard memory buffer -- # .getvalue() will now raise an exception. output.close()
- class io.IncrementalNewlineDecoder¶
A helper codec that decodes newlines for universal newlines mode. It inherits from
codecs.IncrementalDecoder
.
性能¶
このセクションでは与えられた具体的な I/O 実装の性能について議論します。
バイナリ I/O¶
バッファ付き I/O は、ユーザが 1 バイトだけ要求した場合でさえ、データを大きな塊でのみ読み書きします。これにより、オペレーティングシステムのバッファ無し I/O ルーチンを呼び出して実行する非効率性はすべて隠されます。その成果は、OS と、実行される I/O の種類によって異なります。例えば、Linux のような現行の OS では、バッファ無しディスク I/O がバッファ付き I/O と同じくらい早いことがあります。しかし、どのプラットフォームとデバイスにおいても、バッファ付き I/O は最低でも予測可能なパフォーマンスを提供します。ですから、バイナリデータに対しては、バッファ無し I/O を使用するより、バッファ付きの I/O を使用するほうが望ましい場合がほとんどです。
テキスト I/O¶
Text I/O over a binary storage (such as a file) is significantly slower than
binary I/O over the same storage, because it requires conversions between
unicode and binary data using a character codec. This can become noticeable
handling huge amounts of text data like large log files. Also,
tell()
and seek()
are both quite slow
due to the reconstruction algorithm used.
しかし StringIO
は、ネイティブなインメモリ Unicode コンテナで、 BytesIO
と同程度の速度を示します。
マルチスレッディング¶
FileIO
objects are thread-safe to the extent that the operating system
calls (such as read(2) under Unix) they wrap are thread-safe too.
バイナリバッファ付きオブジェクト (BufferedReader
, BufferedWriter
, BufferedRandom
および BufferedRWPair
のインスタンス) は、その内部構造をロックを使って保護します。このため、これらを複数のスレッドから同時に呼び出しても安全です。
TextIOWrapper
オブジェクトはスレッドセーフではありません。
リエントラント性¶
バイナリバッファ付きオブジェクト (BufferedReader
, BufferedWriter
, BufferedRandom
および BufferedRWPair
のインスタンス) は、リエントラント (再入可能) ではありません。リエントラントな呼び出しは普通の状況では起こりませんが、 I/O を signal
ハンドラで行なっているときに起こりえます。スレッドが、すでにアクセスしているバッファ付きオブジェクトに再び入ろうとすると RuntimeError
が送出されます。これは、バッファ付きオブジェクトに複数のスレッドから入ることを禁止するわけではありません。
The above implicitly extends to text files, since the open()
function
will wrap a buffered object inside a TextIOWrapper
. This includes
standard streams and therefore affects the built-in print()
function as
well.