python3从零学习-5.6.2、io.py模块

源代码: Lib/io.py

io.DEFAULT_BUFFER_SIZE

包含模块缓冲 I/O 类使用的默认缓冲区大小的 int。 在可能的情况下 open() 将使用文件的 blksize（由 os.stat() 获得）。

 

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

这是内置的 open() 函数的别名。

 

• cl ass io.IOBase

所有 I/O 类的抽象基类，作用于字节流。没有公共构造函数。

 

此类为许多方法提供了空的抽象实现，派生类可以有选择地重写。默认实现无法读取、写入或查找的文件。

Even though IOBase does not declare read(), readinto(), or write() because their signatures will vary, implementations and clients should consider those methods part of the interface. Also, implementations may raise a ValueError (or UnsupportedOperation) when operations they do not support are called.

 

The basic type used for binary data read from or written to a file is bytes. Other bytes-like objects are accepted as method arguments too. In some cases, such as readinto(), a writable object such as bytearray is required. Text I/O classes work with str data.

请注意，在关闭的流上调用任何方法（甚至查询）都是未定义的（undefined）。在这种情况下，实现可能会引发 ValueError 。

 

IOBase （及其子类）支持迭代器协议，这意味着可以迭代 IOBase 对象以产生流中的行。根据流是二进制流（产生字节）还是文本流（产生字符串），行的定义略有不同。请参见下面的 readline() 。

 

IOBase is also a context manager and therefore supports the with statement. In this example, file is closed after the with statement’s suite is finished—even if an exception occurs:

with open('spam.txt', 'w') as file:

    file.write('Spam and eggs!')

IOBase 提供以下数据属性和方法：

 

close()

刷新并关闭此流。如果文件已经关闭，则此方法无效。文件关闭后，对文件的任何操作（例如读取或写入）都会引发 ValueError 。

 

为方便起见，允许多次调用此方法。但是，只有第一个调用才会生效。

 

closed

如果流关闭，则为True。

 

fileno()

返回流的基础文件描述符（整数）—如果存在。如果 IO 对象不使用文件描述符，则会引发 OSError 。

 

flush()

刷新流的写入缓冲区（如果适用）。这对只读和非阻塞流不起作用。

 

isatty()

如果流是交互式的（即连接到终端/tty设备），则返回 True 。

 

readable()

如果可以读取流，则返回 True 。否则为 False ，且 read() 将引发 OSError 错误。

 

readline(size=-1)

从流中读取并返回一行。 如果指定了 size，将至多读取 size 个字节。

 

对于二进制文件行结束符总是 b'\n'；对于文本文件，可以用将 newline 参数传给 open() 的方式来选择要识别的行结束符。

 

readlines(hint=-1)

从流中读取并返回包含多行的列表。 可以指定 hint 来控制要读取的行数：如果（以字节/字符数表示的）所有行的总大小超出了 hint 则将不会读取更多的行。

 

请注意使用 for line in file: ... 就足够对文件对象进行迭代了，可以不必调用 file.readlines()。

 

seek(offset[, whence])

将流位置修改到给定的字节 offset。 offset 将相对于由 whence 指定的位置进行解析。 whence 的默认值为 SEEK_SET。 whence 的可用值有:

 

SEEK_SET 或 0 – 流的开头（默认值）；offset 应为零或正值

 

SEEK_CUR or 1 – 当前流位置；offset 可以为负值

 

SEEK_END or 2 – 流的末尾；offset 通常为负值

 

返回新的绝对位置。

 

3.1 新版功能: SEEK_* 常量.

 

3.3 新版功能: 某些操作系统还可支持其他的值，例如 os.SEEK_HOLE 或 os.SEEK_DATA。 特定文件的可用值还会取决于它是以文本还是二进制模式打开。

 

seekable()

如果流支持随机访问则返回 True。 如为 False，则 seek(), tell() 和 truncate() 将引发 OSError。

 

tell()

返回当前流的位置。

 

truncate(size=None)

将流的大小调整为给定的 size 个字节（如果未指定 size 则调整至当前位置）。 当前的流位置不变。 这个调整操作可扩展或减小当前文件大小。 在扩展的情况下，新文件区域的内容取决于具体平台（在大多数系统上，额外的字节会填充为零）。 返回新的文件大小。

 

在 3.5 版更改: 现在Windows在扩展时将文件填充为零。

 

writable()

如果流支持写入则返回 True。 如为 False，则 write() 和 truncate() 将引发 OSError。

 

writelines(lines)

将行列表写入到流。 不会添加行分隔符，因此通常所提供的每一行都带有末尾行分隔符。

 

__del__()

为对象销毁进行准备。 IOBase 提供了此方法的默认实现，该实现会调用实例的 close() 方法。

 

• class io.RawIOBase

原始二进制 I/O 的基类。 它继承自 IOBase。 没有公共构造器。

 

原始二进制 I/O 通常提供对下层 OS 设备或 API 的低层级访问，而不尝试将其封装到高层级的基元中（这是留给缓冲 I/O 和 Text I/O 的，将在下文中描述）。

 

在 IOBase 的属性和方法之外，RawIOBase 还提供了下列方法:

 

read(size=-1)

从对象中读取 size 个字节并将其返回。 作为一个便捷选项，如果 size 未指定或为 -1，则返回所有字节直到 EOF。 在其他情况下，仅会执行一次系统调用。 如果操作系统调用返回字节数少于 size 则此方法也可能返回少于 size 个字节。

 

如果返回 0 个字节而 size 不为零 0，这表明到达文件末尾。 如果处于非阻塞模式并且没有更多字节可用，则返回 None。

 

默认实现会转至 readall() 和 readinto()。

 

readall()

从流中读取并返回所有字节直到 EOF，如有必要将对流执行多次调用。

 

readinto(b)

Read bytes into a pre-allocated, writable bytes-like object b, and return the number of bytes read. If the object is in non-blocking mode and no bytes are available, None is returned.

 

write(b)

将给定的 bytes-like object b 写入到下层的原始流，并返回所写入的字节数。 这可以少于 b 的总字节数，具体取决于下层原始流的设定，特别是如果它处于非阻塞模式的话。 如果原始流设为非阻塞并且不能真正向其写入单个字节时则返回 None。 调用者可以在此方法返回后释放或改变 b，因此该实现应该仅在方法调用期间访问 b。

 

• class io.BufferedIOBase

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

 

与 RawIOBase 的主要差别在于 read(), readinto() 和 write() 等方法将（分别）尝试按照要求读取尽可能多的输入或是耗尽所有给定的输出，其代价是可能会执行一次以上的系统调用。

 

除此之外，那些方法还可能引发 BlockingIOError，如果下层的原始数据流处于非阻塞模式并且无法接受或给出足够数据的话；不同于对应的 RawIOBase 方法，它们将永远不会返回 None。

 

并且，read() 方法也没有转向 readinto() 的默认实现。

 

典型的 BufferedIOBase 实现不应当继承自 RawIOBase 实现，而要包装一个该实现，正如 BufferedWriter 和 BufferedReader 所做的那样。

 

BufferedIOBase 在 IOBase 的现有成员以外还提供或重载了下列方法和属性:

 

raw

由 BufferedIOBase 处理的下层原始流 (RawIOBase 的实例)。 它不是 BufferedIOBase API 的组成部分并且不存在于某些实现中。

 

detach()

从缓冲区分离出下层原始流并将其返回。

 

在原始流被分离之后，缓冲区将处于不可用的状态。

 

某些缓冲区例如 BytesIO 并无可从此方法返回的单独原始流的概念。 它们将会引发 UnsupportedOperation。

 

3.1 新版功能.

 

read(size=-1)

读取并返回最多 size 个字节。 如果省略此参数则返回 None，如果参数为负值则读取并返回所有数据直到 EOF。 如果流已经到达 EOF 则返回一个空的 bytes 对象。

 

如果此参数为正值，并且下层原始流不可交互，则可能发起多个原始读取以满足字节计数（直至先遇到 EOF）。 但对于可交互原始流，则将至多发起一个原始读取，并且简短的结果并不意味着已到达 EOF。

 

BlockingIOError 会在下层原始流不处于阻塞模式，并且当前没有可用数据时被引发。

 

 

read1(size=-1)

通过至多一次对下层流的 read() (或 readinto()) 方法的调用读取并返回至多 size 个字节。 这适用于在 BufferedIOBase 对象之上实现你自己的缓冲区的情况。

 

readinto(b)

Read bytes into a pre-allocated, writable bytes-like object b and return the number of bytes read.

 

类似于 read()，可能对下层原始流发起多次读取，除非后者为交互式。

 

BlockingIOError 会在下层原始流不处于阻塞模式，并且当前没有可用数据时被引发。

 

readinto1(b)

将字节数据读入预先分配的可写 bytes-like object b，其中至多使用一次对下层原始流 read() (或 readinto()) 方法的调用。 返回所读取的字节数。

 

BlockingIOError 会在下层原始流不处于阻塞模式，并且当前没有可用数据时被引发。

 

3.5 新版功能.

 

write(b)

写入给定的 bytes-like object b，并返回写入的字节数 (总是等于 b 的字节长度，因为如果写入失败则会引发 OSError)。 根据具体实现的不同，这些字节可能被实际写入下层流，或是出于运行效率和冗余等考虑而暂存于缓冲区。

 

当处于非阻塞模式时，如果需要将数据写入原始流但它无法在不阻塞的情况下接受所有数据则将引发 BlockingIOError。

 

调用者可能会在此方法返回后释放或改变 b，因此该实现应当仅在方法调用期间访问 b。