16.2. `io` — 用于操控流的核心工具 ¶

16.2.1. 概述 ¶

The io 模块为 Python 处理各种类型 I/O 提供主要设施。有 3 种主要 I/O 类型： 文本 I/O , 二进制 I/O and 原生 I/O 。这些是一般类别，且它们中的每个都可以用于各种后备存储。属于这些类别的任何具体对象称为文件对象。其它常见术语是 stream and 像文件对象 .

Independently of its category, each concrete stream object will also have various capabilities: it can be read-only, write-only, or read-write. It can also allow arbitrary random access (seeking forwards or backwards to any location), or only sequential access (for example in the case of a socket or pipe).

所有流都关切赋予给它们的有关数据类型。例如，赋予 str 对象到 write() 方法对于二进制流将引发 TypeError 。同样，赋予 bytes 对象到 write() 方法对于文本流。

3.3 版改变：操作用于引发 IOError 现在引发 OSError ，由于 IOError 现在是别名化的 OSError .

16.2.1.1. 文本 I/O ¶

Text I/O 期望并产生 str 对象。这意味着每当后备存储是本机字节 (譬如：在文件情况下) 时，数据的编码和解码是透明的，还能可选翻译特定平台换行符。

创建文本流的最轻松方式是采用 open() ，可选指定编码：

f = open("myfile.txt", "r", encoding="utf-8")

内存文本流还可用作 StringIO 对象：

f = io.StringIO("some initial text data")

文本流 API 的详细描述在文档编制 TextIOBase .

16.2.1.2. 二进制 I/O ¶

二进制 I/O (也称 缓冲 I/O ) expects and produces bytes 对象。不履行编码、解码或翻译换行符。这种类别的流可以用于所有种类的非文本数据，且当期望手动控制文本数据的处理时也如此。

创建二进制流的最简单方式是采用 open() with 'b' 在模式字符串下：

f = open("myfile.jpg", "rb")

内存二进制流还可用作 BytesIO 对象：

f = io.BytesIO(b"some initial binary data: \x00\x01")

二进制流 API 的详细描述在文档化的 BufferedIOBase .

其它库模块可以提供创建文本 (或二进制) 流的额外方式。见 socket.socket.makefile() 例如。

16.2.1.3. 原生 I/O ¶

原生 I/O (也称 无缓冲 I/O ) 通常用作二进制和文本流的低级构建块；直接操纵来自用户代码的原生流很少有用。尽管如此，可以通过在禁用缓冲的二进制模式下打开文件，创建原生流：

f = open("myfile.jpg", "rb", buffering=0)

原生流 API 的详细描述在文档化的 RawIOBase .

16.2.2. 高级模块接口 ¶

io. DEFAULT_BUFFER_SIZE ¶

io. open ( file , mode='r' , buffering=-1 , encoding=None , errors=None , newline=None , closefd=True , opener=None ) ¶

exception io. BlockingIOError ¶

exception io. UnsupportedOperation ¶

16.2.2.1. 内存流 ¶

It is also possible to use a str or bytes -like object as a file for both reading and writing. For strings StringIO can be used like a file opened in text mode. BytesIO can be used like a file opened in binary mode. Both provide full read-write capabilities with random access.

另请参阅

sys: 包含标准 IO 流： sys.stdin , sys.stdout , and sys.stderr .

16.2.3. 类层次结构 ¶

I/O 流实现的组织是按类层次结构。首先抽象基类 (ABC) 用于指定流的各种类别，然后具体类提供标准流实现。

注意

ABC (抽象基类) 还提供了一些方法的默认实现，以帮助实现具体的流类。例如， BufferedIOBase 提供实现未优化的 readinto() and readline() .

At the top of the I/O hierarchy is the abstract base class IOBase . It defines the basic interface to a stream. Note, however, that there is no separation between reading and writing to streams; implementations are allowed to raise UnsupportedOperation 若它们不支持给定操作。

The RawIOBase ABC (抽象基类) 延伸 IOBase . It deals with the reading and writing of bytes to a stream. FileIO 子类 RawIOBase to provide an interface to files in the machine’s file system.

The BufferedIOBase ABC deals with buffering on a raw byte stream ( RawIOBase )。其子类， BufferedWriter , BufferedReader ，和 BufferedRWPair buffer streams that are readable, writable, and both readable and writable. BufferedRandom provides a buffered interface to random access streams. Another BufferedIOBase 子类， BytesIO , is a stream of in-memory bytes.

The TextIOBase ABC, another subclass of IOBase , deals with streams whose bytes represent text, and handles encoding and decoding to and from strings. TextIOWrapper , which extends it, is a buffered text interface to a buffered raw stream ( BufferedIOBase ). Finally, StringIO 是用于文本的内存流。

Argument names are not part of the specification, and only the arguments of open() are intended to be used as keyword arguments.

下表汇总的 ABC (抽象基类) 提供通过 io 模块：

ABC (抽象基类)	继承	Stub 方法	混合方法和特性
`IOBase`		`fileno` , `seek` , and `truncate`	`close` , `closed` , `__enter__` , `__exit__` , `flush` , `isatty` , `__iter__` , `__next__` , `readable` , `readline` , `readlines` , `seekable` , `tell` , `writable` ，和 `writelines`
`RawIOBase`	`IOBase`	`readinto` and `write`	继承 `IOBase` 方法， `read` , and `readall`
`BufferedIOBase`	`IOBase`	`detach` , `read` , `read1` ，和 `write`	继承 `IOBase` 方法， `readinto`
`TextIOBase`	`IOBase`	`detach` , `read` , `readline` ，和 `write`	继承 `IOBase` 方法， `encoding` , `errors` ，和 `newlines`

16.2.3.1. I/O 基类 ¶

class io. IOBase ¶

close ( ) ¶

closed ¶

fileno ( ) ¶

flush ( ) ¶

isatty ( ) ¶

readable ( ) ¶

readline ( size=-1 ) ¶

readlines ( hint=-1 ) ¶

seek ( offset [ , whence ] ) ¶

seekable ( ) ¶

tell ( ) ¶

truncate ( size=None ) ¶

writable ( ) ¶

writelines ( lines ) ¶

__del__ ( ) ¶

class io. RawIOBase ¶

用于原生二进制 I/O 的基类。它继承 IOBase 。没有公共构造函数。

原生二进制 I/O 通常提供对底层 OS 设备 (或 API) 的低级访问，且不会试着将它封装在高级原语中 (这留给缓冲 I/O 和文本 I/O，本页稍后描述)。

除属性和方法来自 IOBase , RawIOBase 提供下列方法：

read ( size=-1 ) ¶

readall ( ) ¶: 读取并返回来自流的所有字节直到 EOF (文件末尾)，使用多次流调用若有必要。

readinto ( b ) ¶: 读取直到 len(b) bytes into bytearray b and return the number of bytes read. If the object is in non-blocking mode and no bytes are available, None 被返回。

write ( b ) ¶: 写入给定 bytes or bytearray 对象， b , to the underlying raw stream and return the number of bytes written. This can be less than len(b) , depending on specifics of the underlying raw stream, and especially if it is in non-blocking mode. None is returned if the raw stream is set not to block and no single byte could be readily written to it.

class io. BufferedIOBase ¶

用于支持某种缓冲的二进制流的基类。它继承 IOBase 。没有公共构造函数。

主要差异相比 RawIOBase 是方法 read() , readinto() and write() 将 (分别) 试着按请求读取尽可能多的输入 (或消耗所有给定输出)，以做出或许不止一次的系统调用为代价。

此外，这些方法会引发 BlockingIOError 若底层原生流处于非阻塞模式下且无法获得 (或给出) 足够数据；不像它们的 RawIOBase 搭档，他们从不会返回 None .

此外， read() 方法没有遵从默认实现对于 readinto() .

典型 BufferedIOBase 实现不应继承自 RawIOBase 实现，但包裹某个，像 BufferedWriter and BufferedReader 做的。

BufferedIOBase 提供 (或覆写) 了这些方法和属性，除了那些来自 IOBase :

raw ¶: 底层原生流 ( RawIOBase 实例) BufferedIOBase 的处理。这不属于 BufferedIOBase API 且在某些实现中可能不存在。

detach ( ) ¶

从缓冲分离底层原生流并返回它。

在原生流被分离后，缓冲处于不可用状态。

某些缓冲，像 BytesIO , do not have the concept of a single raw stream to return from this method. They raise UnsupportedOperation .

3.1 版新增。

read ( size=-1 ) ¶

读取并返回直到 size bytes. If the argument is omitted, None , or negative, data is read and returned until EOF is reached. An empty bytes object is returned if the stream is already at EOF.

If the argument is positive, and the underlying raw stream is not interactive, multiple raw reads may be issued to satisfy the byte count (unless EOF is reached first). But for interactive raw streams, at most one raw read will be issued, and a short result does not imply that EOF is imminent.

A BlockingIOError is raised if the underlying raw stream is in non blocking-mode, and has no data available at the moment.

read1 ( size=-1 ) ¶: 读取并返回直到 size bytes, with at most one call to the underlying raw stream’s read() method. This can be useful if you are implementing your own buffering on top of a BufferedIOBase 对象。

readinto ( b ) ¶

读取直到 len(b) bytes into bytearray b and return the number of bytes read.

像 read() , multiple reads may be issued to the underlying raw stream, unless the latter is interactive.

A BlockingIOError is raised if the underlying raw stream is in non blocking-mode, and has no data available at the moment.

write ( b ) ¶

写入给定 bytes or bytearray 对象， b and return the number of bytes written (never less than len(b) , since if the write fails an OSError will be raised). Depending on the actual implementation, these bytes may be readily written to the underlying stream, or held in a buffer for performance and latency reasons.

当在非阻塞模式下时， BlockingIOError is raised if the data needed to be written to the raw stream but it couldn’t accept all the data without blocking.

16.2.3.2. 原生文件 I/O ¶

class io. FileIO ( name , mode='r' , closefd=True , opener=None ) ¶

FileIO 表示的 OS 级别文件包含 bytes 数据。它实现了 RawIOBase 接口 (因此 IOBase 接口，也)。

The name 可以是 2 件事之一：

字符串或 bytes object representing the path to the file which will be opened;
an integer representing the number of an existing OS-level file descriptor to which the resulting FileIO object will give access.

The mode 可以是 'r' , 'w' , 'x' or 'a' for reading (default), writing, exclusive creation or appending. The file will be created if it doesn’t exist when opened for writing or appending; it will be truncated when opened for writing. FileExistsError will be raised if it already exists when opened for creating. Opening a file for creating implies writing, so this mode behaves in a similar way to 'w' 。添加 '+' to the mode to allow simultaneous reading and writing.

The read() (when called with a positive argument), readinto() and write() methods on this class will only make one system call.

自定义开启器可以用于传递可调用如 opener 。然后，获得文件对象底层文件描述符通过调用 opener 采用 ( name , flags ). opener 必须返回打开文件描述符 (传递 os.open as opener 导致功能类似于传递 None ).

新近创建的文件不可继承 .

见 open() 内置函数，例如使用 opener 参数。

3.3 版改变： The opener 参数被添加。 'x' 模式被添加。

3.4 版改变：文件现在不可继承。

除属性和方法来自 IOBase and RawIOBase , FileIO 提供下列数据属性：

mode ¶: 在构造函数中给定的模式。

名称 ¶: 文件名。这是文件的文件描述符当构造函数中未给定名称时。

16.2.3.3. 缓冲流 ¶

缓冲 I/O 流为 I/O 设备提供更高级接口，相比原生 I/O。

class io. BytesIO ( [ initial_bytes ] ) ¶

使用内存 bytes 缓冲实现的流。它继承 BufferedIOBase 。丢弃缓冲当 close() 方法被调用。

自变量 initial_bytes contains optional initial bytes 数据。

BytesIO 提供或覆盖这些方法，除了那些来自 BufferedIOBase and IOBase :

getbuffer ( ) ¶

返回可读/可写视图，在不拷贝缓冲内容的情况下。还有，变异视图会透明地更新缓冲内容：

>>> b = io.BytesIO(b"abcdef")
>>> view = b.getbuffer()
>>> view[2:4] = b"56"
>>> b.getvalue()
b'ab56ef'

注意

只要视图存在， BytesIO 对象不可以重置大小或关闭。

3.2 版新增。

getvalue ( ) ¶: 返回 bytes 包含缓冲的整个内容。

read1 ( ) ¶: 在 BytesIO ，这如同 read() .

class io. BufferedReader ( raw , buffer_size=DEFAULT_BUFFER_SIZE ) ¶

提供高级访问的缓冲，对可读、顺序 RawIOBase 对象。它继承 BufferedIOBase . When reading data from this object, a larger amount of data may be requested from the underlying raw stream, and kept in an internal buffer. The buffered data can then be returned directly on subsequent reads.

构造函数创建 BufferedReader 对于给定可读 raw 流和 buffer_size 。若 buffer_size 被省略， DEFAULT_BUFFER_SIZE 被使用。

BufferedReader 提供或覆盖这些方法，除了那些来自 BufferedIOBase and IOBase :

peek ( [ size ] ) ¶: Return bytes from the stream without advancing the position. At most one single read on the raw stream is done to satisfy the call. The number of bytes returned may be less or more than requested.

read ( [ size ] ) ¶: 读取并返回 size bytes, or if size is not given or negative, until EOF or if the read call would block in non-blocking mode.

read1 ( size ) ¶: 读取并返回直到 size bytes with only one call on the raw stream. If at least one byte is buffered, only buffered bytes are returned. Otherwise, one raw stream read call is made.

class io. BufferedWriter ( raw , buffer_size=DEFAULT_BUFFER_SIZE ) ¶

A buffer providing higher-level access to a writeable, sequential RawIOBase 对象。它继承 BufferedIOBase . When writing to this object, data is normally placed into an internal buffer. The buffer will be written out to the underlying RawIOBase object under various conditions, including:

when the buffer gets too small for all pending data;
当 flush() 被调用；
当 seek() 被请求 (对于 BufferedRandom 对象)；
当 BufferedWriter 对象被关闭 (或销毁)。

构造函数创建 BufferedWriter for the given writeable raw stream. If the buffer_size 不给定，默认为 DEFAULT_BUFFER_SIZE .

BufferedWriter 提供或覆盖这些方法，除了那些来自 BufferedIOBase and IOBase :

flush ( ) ¶: Force bytes held in the buffer into the raw stream. A BlockingIOError should be raised if the raw stream blocks.

write ( b ) ¶: 写入 bytes or bytearray 对象， b and return the number of bytes written. When in non-blocking mode, a BlockingIOError 被引发若需要写出缓冲，但原生流阻塞。

class io. BufferedRandom ( raw , buffer_size=DEFAULT_BUFFER_SIZE ) ¶

A buffered interface to random access streams. It inherits BufferedReader and BufferedWriter , and further supports seek() and tell() 功能。

The constructor creates a reader and writer for a seekable raw stream, given in the first argument. If the buffer_size is omitted it defaults to DEFAULT_BUFFER_SIZE .

BufferedRandom is capable of anything BufferedReader or BufferedWriter can do.

class io. BufferedRWPair ( reader , writer , buffer_size=DEFAULT_BUFFER_SIZE ) ¶

A buffered I/O object combining two unidirectional RawIOBase objects – one readable, the other writeable – into a single bidirectional endpoint. It inherits BufferedIOBase .

reader and writer are RawIOBase objects that are readable and writeable respectively. If the buffer_size is omitted it defaults to DEFAULT_BUFFER_SIZE .

BufferedRWPair 实现所有的 BufferedIOBase ‘s methods except for detach() ，其引发 UnsupportedOperation .

警告

BufferedRWPair does not attempt to synchronize accesses to its underlying raw streams. You should not pass it the same object as reader and writer; use BufferedRandom 代替。

16.2.3.4. 文本 I/O ¶

class io. TextIOBase ¶

Base class for text streams. This class provides a character and line based interface to stream I/O. There is no readinto() method because Python’s character strings are immutable. It inherits IOBase 。没有公共构造函数。

TextIOBase 提供 (或覆写) 了这些数据属性和方法，除了那些来自 IOBase :

encoding ¶

errors ¶: 解码器 (或编码器) 的错误设置。

newlines ¶: 字符串、字符串元组、或 None ，指示到目前为止翻译的换行符。从属实现和初始构造函数标志，这可能不可用。

buffer ¶: 底层二进制缓冲 ( BufferedIOBase 实例) TextIOBase 的处理。这不属于 TextIOBase API 且在某些实现中可能不存在。

detach ( ) ¶

分隔底层二进制缓冲从 TextIOBase 并返回它。

分离底层缓冲后， TextIOBase 处于不可用状态。

某些 TextIOBase 实现，像 StringIO ，可能没有底层缓冲概念且调用此方法会引发 UnsupportedOperation .

3.1 版新增。

read ( size ) ¶: 读取并返回最多 size 字符从流作为单 str 。若 size 为负或者 None ，读取直到 EOF (文件末尾)。

readline ( size=-1 ) ¶

读取直到换行符或 EOF (文件末尾) 并返回单 str 。若流已在 EOF (文件末尾)，返回空字符串。

若 size 有指定，最多 size 字符将被读取。

seek ( offset [ , whence ] ) ¶

Change the stream position to the given offset . Behaviour depends on the whence parameter. The default value for whence is SEEK_SET .

SEEK_SET or 0 : seek from the start of the stream (the default); offset must either be a number returned by TextIOBase.tell() , or zero. Any other offset 值 produces undefined behaviour.
SEEK_CUR or 1 : “seek” to the current position; offset must be zero, which is a no-operation (all other values are unsupported).
SEEK_END or 2 : seek to the end of the stream; offset must be zero (all other values are unsupported).

以不透明数字形式返回新的绝对位置。

3.1 版新增： The SEEK_* 常量。

tell ( ) ¶: Return the current stream position as an opaque number. The number does not usually represent a number of bytes in the underlying binary storage.

write ( s ) ¶: 写入字符串 s 到流并返回写入字符数。

class io. TextIOWrapper ( buffer , encoding=None , errors=None , newline=None , line_buffering=False , write_through=False ) ¶

缓冲文本流基于 BufferedIOBase 二进制流。它继承 TextIOBase .

encoding gives the name of the encoding that the stream will be decoded or encoded with. It defaults to locale.getpreferredencoding(False) .

errors is an optional string that specifies how encoding and decoding errors are to be handled. Pass 'strict' 会引发 ValueError exception if there is an encoding error (the default of None has the same effect), or pass 'ignore' to ignore errors. (Note that ignoring encoding errors can lead to data loss.) 'replace' 导致置换标记 (譬如 '?' ) to be inserted where there is malformed data. When writing, 'xmlcharrefreplace' (replace with the appropriate XML character reference) or 'backslashreplace' (replace with backslashed escape sequences) can be used. Any other error handling name that has been registered with codecs.register_error() is also valid.

newline controls how line endings are handled. It can be None , '' , '\n' , '\r' ，和 '\r\n' 。其工作如下：

当从流读取输入时，若 newline is None , 通用换行符 mode is enabled. Lines in the input can end in '\n' , '\r' ，或 '\r\n' ，且这些会被翻译成 '\n' 在返回给调用者之前。若为 '' , universal newlines mode is enabled, but line endings are returned to the caller untranslated. If it has any of the other legal values, input lines are only terminated by the given string, and the line ending is returned to the caller untranslated.
当写入输出到流时，若 newline is None ，任何 '\n' 写入字符被翻译成系统默认行分隔符， os.linesep 。若 newline is '' or '\n' , no translation takes place. If newline 是任何其它合法值，任何 '\n' 写入字符被翻译成给定字符串。

若 line_buffering is True , flush() is implied when a call to write contains a newline character.

若 write_through is True ，调用 write() are guaranteed not to be buffered: any data written on the TextIOWrapper object is immediately handled to its underlying binary buffer .

3.3 版改变： The write_through 自变量被添加。

3.3 版改变：默认 encoding 现为 locale.getpreferredencoding(False) 而不是 locale.getpreferredencoding() . Don’t change temporary the locale encoding using locale.setlocale() , use the current locale encoding instead of the user preferred encoding.

TextIOWrapper provides one attribute in addition to those of TextIOBase 及其父级：

line_buffering ¶: 行缓冲是否被启用。

class io. StringIO ( initial_value='' , newline='\n' ) ¶

用于文本 I/O 的内存流。丢弃文本缓冲当 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.

The newline 自变量的工作像 TextIOWrapper . The default is to consider only \n characters as ends of lines and to do no newline translation. If newline 被设为 None , newlines are written as \n on all platforms, but universal newline decoding is still performed when reading.

StringIO 提供此方法，除了那些来自 TextIOBase 及其父级：

getvalue ( ) ¶: 返回 str containing the entire contents of the buffer. Newlines are decoded as if by read() , 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 ¶: 解码换行符的帮手编解码器，对于通用换行符模式。它继承 codecs.IncrementalDecoder .

16.2.4. 性能 ¶

本节讨论提供的具体 I/O 实现的性能。

16.2.4.1. 二进制 I/O ¶

By reading and writing only large chunks of data even when the user asks for a single byte, buffered I/O hides any inefficiency in calling and executing the operating system’s unbuffered I/O routines. The gain depends on the OS and the kind of I/O which is performed. For example, on some modern OSes such as Linux, unbuffered disk I/O can be as fast as buffered I/O. The bottom line, however, is that buffered I/O offers predictable performance regardless of the platform and the backing device. Therefore, it is almost always preferable to use buffered I/O rather than unbuffered I/O for binary data.

16.2.4.2. 文本 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, TextIOWrapper.tell() and TextIOWrapper.seek() are both quite slow due to the reconstruction algorithm used.

StringIO ，不管怎样，是本机内存 unicode 容器，且显露速度类似 BytesIO .

16.2.4.3. 多线程 ¶

FileIO 对象在操作系统调用程度是线程安全的 (譬如 read(2) 在 Unix)，它们的包裹也是线程安全的。

二进制缓冲对象 (实例化的 BufferedReader , BufferedWriter , BufferedRandom and BufferedRWPair ) protect their internal structures using a lock; it is therefore safe to call them from multiple threads at once.

TextIOWrapper 对象不是线程安全的。

16.2.4.4. 重入 ¶

二进制缓冲对象 (实例化的 BufferedReader , BufferedWriter , BufferedRandom and BufferedRWPair ) are not reentrant. While reentrant calls will not happen in normal situations, they can arise from doing I/O in a signal handler. If a thread tries to re-enter a buffered object which it is already accessing, a RuntimeError is raised. Note this doesn’t prohibit a different thread from entering the buffered object.

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 function print() 还。

16.2. io — 用于操控流的核心工具 ¶