io --- 處理流的核心工具?
源代碼: Lib/io.py
概述?
io 模塊提供了 Python 用于處理各種 I/O 類型的主要工具。三種主要的 I/O類型分別為: 文本 I/O, 二進(jìn)制 I/O 和 原始 I/O。這些是泛型類型，有很多種后端存儲(chǔ)可以用在他們上面。一個(gè)隸屬于任何這些類型的具體對(duì)象被稱作 file object。 其他同類的術(shù)語還有 流 和 類文件對(duì)象。
獨(dú)立于其類別，每個(gè)具體流對(duì)象也將具有各種功能：它可以是只讀，只寫或讀寫。它還可以允許任意隨機(jī)訪問（向前或向后尋找任何位置），或僅允許順序訪問（例如在套接字或管道的情況下）。
所有流對(duì)提供給它們的數(shù)據(jù)類型都很敏感。例如將 str 對(duì)象給二進(jìn)制流的 write() 方法會(huì)引發(fā) TypeError。將 bytes 對(duì)象提供給文本流的 write() 方法也是如此。
文本 I/O?
文本I/O預(yù)期并生成 str 對(duì)象。這意味著，無論何時(shí)后臺(tái)存儲(chǔ)是由字節(jié)組成的（例如在文件的情況下），數(shù)據(jù)的編碼和解碼都是透明的，并且可以選擇轉(zhuǎn)換特定于平臺(tái)的換行符。
創(chuàng)建文本流的最簡單方法是使用 open()，可以選擇指定編碼：
f = open("myfile.txt", "r", encoding="utf-8")
內(nèi)存中文本流也可以作為 StringIO 對(duì)象使用：
f = io.StringIO("some initial text data")
TextIOBase 的文檔中詳細(xì)描述了文本流的API
二進(jìn)制 I/O?
二進(jìn)制I/O（也稱為緩沖I/O）預(yù)期 bytes-like objects 并產(chǎn)生 bytes 對(duì)象。不執(zhí)行編碼、解碼或換行轉(zhuǎn)換。這種類型的流可以用于所有類型的非文本數(shù)據(jù)，并且還可以在需要手動(dòng)控制文本數(shù)據(jù)的處理時(shí)使用。
創(chuàng)建二進(jìn)制流的最簡單方法是使用 open()，并在模式字符串中指定 'b' ：
f = open("myfile.jpg", "rb")
內(nèi)存中二進(jìn)制流也可以作為 BytesIO 對(duì)象使用：
f = io.BytesIO(b"some initial binary data: \x00\x01")
BufferedIOBase 的文檔中詳細(xì)描述了二進(jìn)制流 API。
其他庫模塊可以提供額外的方式來創(chuàng)建文本或二進(jìn)制流。參見 socket.socket.makefile() 的示例。
高階模塊接口?
-
io.DEFAULT_BUFFER_SIZE? 包含模塊緩沖 I/O 類使用的默認(rèn)緩沖區(qū)大小的 int。 在可能的情況下
open()將使用文件的 blksize（由os.stat()獲得）。
-
io.open(file, mode='r', buffering=-1, encoding=None, errors=None, newline=None, closefd=True, opener=None)? 這是內(nèi)置的
open()函數(shù)的別名。
-
exception
io.BlockingIOError? 這是內(nèi)置的
BlockingIOError異常的兼容性別名。
-
exception
io.UnsupportedOperation? 在流上調(diào)用不支持的操作時(shí)引發(fā)的繼承
OSError和ValueError的異常。
內(nèi)存中的流?
也可以使用 str 或 bytes-like object 作為文件進(jìn)行讀取和寫入。對(duì)于字符串， StringIO 可以像在文本模式下打開的文件一樣使用。 BytesIO 可以像以二進(jìn)制模式打開的文件一樣使用。兩者都提供完整的隨機(jī)讀寫功能。
參見
sys包含標(biāo)準(zhǔn)IO流:
sys.stdin,sys.stdout和sys.stderr。
類的層次結(jié)構(gòu)?
I/O 流的實(shí)現(xiàn)被組織為類的層次結(jié)構(gòu)。 首先是 抽象基類 (ABC)，用于指定流的各種類別，然后是提供標(biāo)準(zhǔn)流實(shí)現(xiàn)的具體類。
注解
抽象基類還提供某些方法的默認(rèn)實(shí)現(xiàn)，以幫助實(shí)現(xiàn)具體的流類。例如
BufferedIOBase提供了readinto()和readline()的未優(yōu)化實(shí)現(xiàn)。
I/O層次結(jié)構(gòu)的頂部是抽象基類 IOBase 。它定義了流的基本接口。但是請(qǐng)注意，對(duì)流的讀取和寫入之間沒有分隔。如果實(shí)現(xiàn)不支持指定的操作，則會(huì)引發(fā) UnsupportedOperation 。
RawIOBase ABC 是 IOBase 的子類。它負(fù)責(zé)將字節(jié)讀取和寫入流中。 RawIOBase 的子類 FileIO 提供計(jì)算機(jī)文件系統(tǒng)中文件的接口。
BufferedIOBase ABC處理原始字節(jié)流 ( RawIOBase) 上的緩沖。其子類 BufferedWriter、BufferedReader 和 BufferedRWPair 緩沖流是可讀、可寫以及可讀寫的。 BufferedRandom 為隨機(jī)訪問流提供緩沖接口。 BufferedIOBase 的另一個(gè)子類 BytesIO 是內(nèi)存中字節(jié)流。
TextIOBase ABC是 IOBase 的另一個(gè)子類，它處理字節(jié)表示文本的流，并處理字符串之間的編碼和解碼。 TextIOWrapper 是其一個(gè)擴(kuò)展，它是原始緩沖流（ BufferedIOBase ）的緩沖文本接口。最后， StringIO 是一個(gè)用于文本的內(nèi)存流。
參數(shù)名不是規(guī)范的一部分，只有 open() 的參數(shù)才用作關(guān)鍵字參數(shù)。
下表總結(jié)了抽象基類提供的 io 模塊：
抽象基類 |
繼承 |
Stub 方法 |
Mixin方法和屬性 |
|---|---|---|---|
|
|
||
|
繼承 |
||
|
繼承 |
||
|
繼承 |
I/O 基類?
-
class
io.IOBase? 所有 I/O 類的抽象基類，作用于字節(jié)流。沒有公共構(gòu)造函數(shù)。
此類為許多方法提供了空的抽象實(shí)現(xiàn)，派生類可以有選擇地重寫。默認(rèn)實(shí)現(xiàn)無法讀取、寫入或查找的文件。
盡管
IOBase沒有聲明read()或write()，因?yàn)樗鼈兊暮灻麜?huì)有所不同，但是實(shí)現(xiàn)和客戶端應(yīng)該將這些方法視為接口的一部分。此外，當(dāng)調(diào)用不支持的操作時(shí)可能會(huì)引發(fā)ValueError（或UnsupportedOperation）。從文件讀取或?qū)懭胛募亩M(jìn)制數(shù)據(jù)的基本類型為
bytes。其他 bytes-like objects 也可以作為方法參數(shù)。文本I/O類使用str數(shù)據(jù)。請(qǐng)注意，在關(guān)閉的流上調(diào)用任何方法（甚至查詢）都是未定義的（undefined）。在這種情況下，實(shí)現(xiàn)可能會(huì)引發(fā)
ValueError。IOBase（及其子類）支持迭代器協(xié)議，這意味著可以迭代IOBase對(duì)象以產(chǎn)生流中的行。根據(jù)流是二進(jìn)制流（產(chǎn)生字節(jié)）還是文本流（產(chǎn)生字符串），行的定義略有不同。請(qǐng)參見下面的readline()。IOBase也是一個(gè)上下文管理器，因此支持with語句。 在這個(gè)示例中，file 將在with語句塊執(zhí)行完成之后被關(guān)閉 --- 即使是發(fā)生了異常:with open('spam.txt', 'w') as file: file.write('Spam and eggs!')
IOBase提供以下數(shù)據(jù)屬性和方法：-
close()? 刷新并關(guān)閉此流。如果文件已經(jīng)關(guān)閉，則此方法無效。文件關(guān)閉后，對(duì)文件的任何操作（例如讀取或?qū)懭耄┒紩?huì)引發(fā)
ValueError。為方便起見，允許多次調(diào)用此方法。但是，只有第一個(gè)調(diào)用才會(huì)生效。
-
closed? 如果流關(guān)閉，則為True。
-
flush()? 刷新流的寫入緩沖區(qū)（如果適用）。這對(duì)只讀和非阻塞流不起作用。
-
isatty()? 如果流是交互式的（即連接到終端/tty設(shè)備），則返回
True。
-
readline(size=-1)? 從流中讀取并返回一行。 如果指定了 size，將至多讀取 size 個(gè)字節(jié)。
對(duì)于二進(jìn)制文件行結(jié)束符總是
b'\n'；對(duì)于文本文件，可以用將 newline 參數(shù)傳給open()的方式來選擇要識(shí)別的行結(jié)束符。
-
readlines(hint=-1)? 從流中讀取并返回包含多行的列表。 可以指定 hint 來控制要讀取的行數(shù)：如果（以字節(jié)/字符數(shù)表示的）所有行的總大小超出了 hint 則將不會(huì)讀取更多的行。
請(qǐng)注意使用
for line in file: ...就足夠?qū)ξ募?duì)象進(jìn)行迭代了，可以不必調(diào)用file.readlines()。
-
seek(offset, whence=SEEK_SET)? 將流位置修改到給定的字節(jié) offset。 offset 將相對(duì)于由 whence 指定的位置進(jìn)行解析。 whence 的默認(rèn)值為
SEEK_SET。 whence 的可用值有:SEEK_SET或0-- 流的開頭（默認(rèn)值）；offset 應(yīng)為零或正值SEEK_CURor1-- 當(dāng)前流位置；offset 可以為負(fù)值SEEK_ENDor2-- 流的末尾；offset 通常為負(fù)值
返回新的絕對(duì)位置。
3.1 新版功能:
SEEK_*常量.3.3 新版功能: 某些操作系統(tǒng)還可支持其他的值，例如
os.SEEK_HOLE或os.SEEK_DATA。 特定文件的可用值還會(huì)取決于它是以文本還是二進(jìn)制模式打開。
-
seekable()? 如果流支持隨機(jī)訪問則返回
True。 如為False，則seek(),tell()和truncate()將引發(fā)OSError。
-
tell()? 返回當(dāng)前流的位置。
-
truncate(size=None)? 將流的大小調(diào)整為給定的 size 個(gè)字節(jié)（如果未指定 size 則調(diào)整至當(dāng)前位置）。 當(dāng)前的流位置不變。 這個(gè)調(diào)整操作可擴(kuò)展或減小當(dāng)前文件大小。 在擴(kuò)展的情況下，新文件區(qū)域的內(nèi)容取決于具體平臺(tái)（在大多數(shù)系統(tǒng)上，額外的字節(jié)會(huì)填充為零）。 返回新的文件大小。
在 3.5 版更改: 現(xiàn)在Windows在擴(kuò)展時(shí)將文件填充為零。
-
writable()? 如果流支持寫入則返回
True。 如為False，則write()和truncate()將引發(fā)OSError。
-
writelines(lines)? 將行列表寫入到流。 不會(huì)添加行分隔符，因此通常所提供的每一行都帶有末尾行分隔符。
-
-
class
io.RawIOBase? 原始二進(jìn)制 I/O 的基類。 它繼承自
IOBase。 沒有公共構(gòu)造器。原始二進(jìn)制 I/O 通常提供對(duì)下層 OS 設(shè)備或 API 的低層級(jí)訪問，而不嘗試將其封裝到高層級(jí)的基元中（這是留給緩沖 I/O 和 Text I/O 的，將在下文中描述）。
在
IOBase的屬性和方法之外，RawIOBase還提供了下列方法:-
read(size=-1)? 從對(duì)象中讀取 size 個(gè)字節(jié)并將其返回。 作為一個(gè)便捷選項(xiàng)，如果 size 未指定或?yàn)?-1，則返回所有字節(jié)直到 EOF。 在其他情況下，僅會(huì)執(zhí)行一次系統(tǒng)調(diào)用。 如果操作系統(tǒng)調(diào)用返回字節(jié)數(shù)少于 size 則此方法也可能返回少于 size 個(gè)字節(jié)。
如果返回 0 個(gè)字節(jié)而 size 不為零 0，這表明到達(dá)文件末尾。 如果處于非阻塞模式并且沒有更多字節(jié)可用，則返回
None。默認(rèn)實(shí)現(xiàn)會(huì)轉(zhuǎn)至
readall()和readinto()。
-
readall()? 從流中讀取并返回所有字節(jié)直到 EOF，如有必要將對(duì)流執(zhí)行多次調(diào)用。
-
readinto(b)? 將字節(jié)數(shù)據(jù)讀入預(yù)先分配的可寫 bytes-like object b，并返回所讀取的字節(jié)數(shù)。 例如，b 可以是一個(gè)
bytearray。 如果對(duì)象處理非阻塞模式并且沒有更多字節(jié)可用，則返回None。
-
write(b)? 將給定的 bytes-like object b 寫入到下層的原始流，并返回所寫入的字節(jié)數(shù)。 這可以少于 b 的總字節(jié)數(shù)，具體取決于下層原始流的設(shè)定，特別是如果它處于非阻塞模式的話。 如果原始流設(shè)為非阻塞并且不能真正向其寫入單個(gè)字節(jié)時(shí)則返回
None。 調(diào)用者可以在此方法返回后釋放或改變 b，因此該實(shí)現(xiàn)應(yīng)該僅在方法調(diào)用期間訪問 b。
-
-
class
io.BufferedIOBase? 支持某種緩沖的二進(jìn)制流的基類。 它繼承自
IOBase。 沒有公共構(gòu)造器。與
RawIOBase的主要差別在于read(),readinto()和write()等方法將（分別）嘗試按照要求讀取盡可能多的輸入或是耗盡所有給定的輸出，其代價(jià)是可能會(huì)執(zhí)行一次以上的系統(tǒng)調(diào)用。除此之外，那些方法還可能引發(fā)
BlockingIOError，如果下層的原始數(shù)據(jù)流處于非阻塞模式并且無法接受或給出足夠數(shù)據(jù)的話；不同于對(duì)應(yīng)的RawIOBase方法，它們將永遠(yuǎn)不會(huì)返回None。并且，
read()方法也沒有轉(zhuǎn)向readinto()的默認(rèn)實(shí)現(xiàn)。典型的
BufferedIOBase實(shí)現(xiàn)不應(yīng)當(dāng)繼承自RawIOBase實(shí)現(xiàn)，而要包裝一個(gè)該實(shí)現(xiàn)，正如BufferedWriter和BufferedReader所做的那樣。BufferedIOBase在IOBase的現(xiàn)有成員以外還提供或重載了下列方法和屬性:-
raw? 由
BufferedIOBase處理的下層原始流 (RawIOBase的實(shí)例)。 它不是BufferedIOBaseAPI 的組成部分并且不存在于某些實(shí)現(xiàn)中。
-
detach()? 從緩沖區(qū)分離出下層原始流并將其返回。
在原始流被分離之后，緩沖區(qū)將處于不可用的狀態(tài)。
某些緩沖區(qū)例如
BytesIO并無可從此方法返回的單獨(dú)原始流的概念。 它們將會(huì)引發(fā)UnsupportedOperation。3.1 新版功能.
-
read(size=-1)? 讀取并返回最多 size 個(gè)字節(jié)。 如果此參數(shù)被省略、為
None或?yàn)樨?fù)值，則讀取并返回所有數(shù)據(jù)直到 EOF。 如果流已經(jīng)到達(dá) EOF 則返回一個(gè)空的bytes對(duì)象。如果此參數(shù)為正值，并且下層原始流不可交互，則可能發(fā)起多個(gè)原始讀取以滿足字節(jié)計(jì)數(shù)（直至先遇到 EOF）。 但對(duì)于可交互原始流，則將至多發(fā)起一個(gè)原始讀取，并且簡短的結(jié)果并不意味著已到達(dá) EOF。
BlockingIOError會(huì)在下層原始流不處于阻塞模式，并且當(dāng)前沒有可用數(shù)據(jù)時(shí)被引發(fā)。
-
read1([size])? 通過至多一次對(duì)下層流的
read()(或readinto()) 方法的調(diào)用讀取并返回至多 size 個(gè)字節(jié)。 這適用于在BufferedIOBase對(duì)象之上實(shí)現(xiàn)你自己的緩沖區(qū)的情況。如果 size 為
-1(默認(rèn)值)，則返回任意數(shù)量的字節(jié)（多于零字節(jié)，除非已到達(dá) EOF）。
-
readinto(b)? 將字節(jié)數(shù)據(jù)讀入預(yù)先分配的可寫 bytes-like object b 并返回所讀取的字節(jié)數(shù)。 例如，b 可以是一個(gè)
bytearray。類似于
read()，可能對(duì)下層原始流發(fā)起多次讀取，除非后者為交互式。BlockingIOError會(huì)在下層原始流不處于阻塞模式，并且當(dāng)前沒有可用數(shù)據(jù)時(shí)被引發(fā)。
-
readinto1(b)? 將字節(jié)數(shù)據(jù)讀入預(yù)先分配的可寫 bytes-like object b，其中至多使用一次對(duì)下層原始流
read()(或readinto()) 方法的調(diào)用。 返回所讀取的字節(jié)數(shù)。BlockingIOError會(huì)在下層原始流不處于阻塞模式，并且當(dāng)前沒有可用數(shù)據(jù)時(shí)被引發(fā)。3.5 新版功能.
-
write(b)? 寫入給定的 bytes-like object b，并返回寫入的字節(jié)數(shù) (總是等于 b 的字節(jié)長度，因?yàn)槿绻麑懭胧t會(huì)引發(fā)
OSError)。 根據(jù)具體實(shí)現(xiàn)的不同，這些字節(jié)可能被實(shí)際寫入下層流，或是出于運(yùn)行效率和冗余等考慮而暫存于緩沖區(qū)。當(dāng)處于非阻塞模式時(shí)，如果需要將數(shù)據(jù)寫入原始流但它無法在不阻塞的情況下接受所有數(shù)據(jù)則將引發(fā)
BlockingIOError。調(diào)用者可能會(huì)在此方法返回后釋放或改變 b，因此該實(shí)現(xiàn)應(yīng)當(dāng)僅在方法調(diào)用期間訪問 b。
-
原始文件 I/O?
-
class
io.FileIO(name, mode='r', closefd=True, opener=None)? FileIO代表在 OS 層級(jí)上包含文件的字節(jié)數(shù)據(jù)。 它實(shí)現(xiàn)了RawIOBase接口（因而也實(shí)現(xiàn)了IOBase接口）。name 可以是以下兩項(xiàng)之一：
代表將被打開的文件路徑的字符串或
bytes對(duì)象。 在此情況下 closefd 必須為True(默認(rèn)值) 否則將會(huì)引發(fā)異常。代表一個(gè)現(xiàn)有 OS 層級(jí)文件描述符的號(hào)碼的整數(shù)，作為結(jié)果的
FileIO對(duì)象將可訪問該文件。 當(dāng) FileIO 對(duì)象被關(guān)閉時(shí)此 fd 也將被關(guān)閉，除非 closefd 設(shè)為False。
mode 可以為
'r','w','x'或'a'分別表示讀取（默認(rèn)模式）、寫入、獨(dú)占新建或添加。 如果以寫入或添加模式打開的文件不存在將自動(dòng)新建；當(dāng)以寫入模式打開時(shí)文件將先清空。 以新建模式打開時(shí)如果文件已存在則將引發(fā)FileExistsError。 以新建模式打開文件也意味著要寫入，因此該模式的行為與'w'類似。 在模式中附帶'+'將允許同時(shí)讀取和寫入。該類的
read()(當(dāng)附帶正值參數(shù)調(diào)用時(shí)),readinto()和write()方法將只執(zhí)行一次系統(tǒng)調(diào)用。可以通過傳入一個(gè)可調(diào)用對(duì)象作為 opener 來使用自定義文件打開器。 然后通過調(diào)用 opener 并傳入 (name, flags) 來獲取文件對(duì)象所對(duì)應(yīng)的下層文件描述符。 opener 必須返回一個(gè)打開文件描述符（傳入
os.open作為 opener 的結(jié)果在功能上將與傳入None類似）。新創(chuàng)建的文件是 不可繼承的。
有關(guān) opener 參數(shù)的示例，請(qǐng)參見內(nèi)置函數(shù)
open()。在 3.3 版更改: 增加了 opener 參數(shù)。增加了
'x'模式。在 3.4 版更改: 文件現(xiàn)在禁止繼承。
在
IOBase和RawIOBase的屬性和方法之外，FileIO還提供了下列數(shù)據(jù)屬性:-
mode? 構(gòu)造函數(shù)中給定的模式。
-
name? 文件名。當(dāng)構(gòu)造函數(shù)中沒有給定名稱時(shí)，這是文件的文件描述符。
緩沖流?
相比原始 I/O，緩沖 I/O 流提供了針對(duì) I/O 設(shè)備的更高層級(jí)接口.
-
class
io.BytesIO([initial_bytes])? 一個(gè)使用內(nèi)存字節(jié)緩沖區(qū)的流實(shí)現(xiàn)。 它繼承自
BufferedIOBase。 在close()方法被調(diào)用時(shí)將會(huì)丟棄緩沖區(qū)。可選參數(shù) initial_bytes 是一個(gè)包含初始數(shù)據(jù)的 bytes-like object。
BytesIO在繼承自BufferedIOBase和IOBase的成員以外還提供或重載了下列方法:-
getbuffer()? 返回一個(gè)對(duì)應(yīng)于緩沖區(qū)內(nèi)容的可讀寫視圖而不必拷貝其數(shù)據(jù)。 此外，改變視圖將透明地更新緩沖區(qū)內(nèi)容:
>>> b = io.BytesIO(b"abcdef") >>> view = b.getbuffer() >>> view[2:4] = b"56" >>> b.getvalue() b'ab56ef'
注解
只要視圖保持存在，
BytesIO對(duì)象就無法被改變大小或關(guān)閉。3.2 新版功能.
-
readinto1(b)? 在
BytesIO中，這與readinto()相同。3.5 新版功能.
-
-
class
io.BufferedReader(raw, buffer_size=DEFAULT_BUFFER_SIZE)? 一個(gè)提供對(duì)可讀的序列型
RawIOBase對(duì)象更高層級(jí)訪問的緩沖區(qū)。 它繼承自BufferedIOBase。 當(dāng)從此對(duì)象讀取數(shù)據(jù)時(shí)，可能會(huì)從下層原始流請(qǐng)求更大量的數(shù)據(jù)，并存放到內(nèi)部緩沖區(qū)中。 接下來可以在后續(xù)讀取時(shí)直接返回緩沖數(shù)據(jù)。根據(jù)給定的可讀 raw 流和 buffer_size 創(chuàng)建
BufferedReader的構(gòu)造器。 如果省略 buffer_size，則會(huì)使用DEFAULT_BUFFER_SIZE。BufferedReader在繼承自BufferedIOBase和IOBase的成員以外還提供或重載了下列方法:-
peek([size])? 從流返回字節(jié)數(shù)據(jù)而不前移位置。 完成此調(diào)用將至多讀取一次原始流。 返回的字節(jié)數(shù)量可能少于或多于請(qǐng)求的數(shù)量。
-
read([size])? 讀取并返回 size 個(gè)字節(jié)，如果 size 未給定或?yàn)樨?fù)值，則讀取至 EOF 或是在非阻塞模式下讀取調(diào)用將會(huì)阻塞。
-
read1([size])? 在原始流上通過單次調(diào)用讀取并返回至多 size 個(gè)字節(jié)。 如果至少緩沖了一個(gè)字節(jié)，則只返回緩沖的字節(jié)。 在其他情況下，將執(zhí)行一次原始流讀取。
在 3.7 版更改: size 參數(shù)現(xiàn)在是可選的。
-
-
class
io.BufferedWriter(raw, buffer_size=DEFAULT_BUFFER_SIZE)? 一個(gè)提供對(duì)可讀的序列型
RawIOBase對(duì)象更高層級(jí)訪問的緩沖區(qū)。 它繼承自BufferedIOBase。 當(dāng)寫入到此對(duì)象時(shí)，數(shù)據(jù)通常會(huì)被放入到內(nèi)部緩沖區(qū)中。 緩沖區(qū)將在滿足某些條件的情況下被寫到下層的RawIOBase對(duì)象，包括:當(dāng)緩沖區(qū)對(duì)于所有掛起數(shù)據(jù)而言太小時(shí)；
當(dāng)
flush()被調(diào)用時(shí)當(dāng)（為
BufferedRandom對(duì)象）請(qǐng)求seek()時(shí)；當(dāng)
BufferedWriter對(duì)象被關(guān)閉或銷毀時(shí)。
該構(gòu)造器會(huì)為給定的可寫 raw 流創(chuàng)建一個(gè)
BufferedWriter。 如果未給定 buffer_size，則使用默認(rèn)的DEFAULT_BUFFER_SIZE。BufferedWriter在繼承自BufferedIOBase和IOBase的成員以外還提供或重載了下列方法:-
flush()? 將緩沖區(qū)中保存的字節(jié)數(shù)據(jù)強(qiáng)制放入原始流。 如果原始流發(fā)生阻塞則應(yīng)當(dāng)引發(fā)
BlockingIOError。
-
write(b)? 寫入 bytes-like object b 并返回寫入的字節(jié)數(shù)。 當(dāng)處于非阻塞模式時(shí)，如果緩沖區(qū)需要被寫入但原始流發(fā)生阻塞則將引發(fā)
BlockingIOError。
-
class
io.BufferedRandom(raw, buffer_size=DEFAULT_BUFFER_SIZE)? 隨機(jī)訪問流的帶緩沖的接口。 它繼承自
BufferedReader和BufferedWriter，并進(jìn)一步支持seek()和tell()功能。該構(gòu)造器會(huì)為在第一個(gè)參數(shù)中給定的可查找原始流創(chuàng)建一個(gè)讀取器和寫入器。 如果省略 buffer_size 則使用默認(rèn)的
DEFAULT_BUFFER_SIZE。BufferedRandom能做到BufferedReader或BufferedWriter所能做的任何事。
-
class
io.BufferedRWPair(reader, writer, buffer_size=DEFAULT_BUFFER_SIZE)? 一個(gè)帶緩沖的 I/O 對(duì)象，它將兩個(gè)單向
RawIOBase對(duì)象 -- 一個(gè)可讀，另一個(gè)可寫 -- 組合為單個(gè)雙向端點(diǎn)。 它繼承自BufferedIOBase。reader 和 writer 分別是可讀和可寫的
RawIOBase對(duì)象。 如果省略 buffer_size 則使用默認(rèn)的DEFAULT_BUFFER_SIZE。BufferedRWPair實(shí)現(xiàn)了BufferedIOBase的所有方法，但detach()除外，調(diào)用該方法將引發(fā)UnsupportedOperation。警告
BufferedRWPair不會(huì)嘗試同步訪問其下層的原始流。 你不應(yīng)當(dāng)將傳給它與讀取器和寫入器相同的對(duì)象；而要改用BufferedRandom。
文本 I/O?
-
class
io.TextIOBase? 文本流的基類。 該類提供了基于字符和行的流 I/O 接口。 它繼承自
IOBase。 該類無公有構(gòu)造器。TextIOBase在來自IOBase的成員以外還提供或重載了以下數(shù)據(jù)屬性和方法:-
encoding? 用于將流的字節(jié)串解碼為字符串以及將字符串編碼為字節(jié)串的編碼格式名稱。
-
errors? 解碼器或編碼器的錯(cuò)誤設(shè)置。
-
newlines? 一個(gè)字符串、字符串元組或者
None，表示目前已經(jīng)轉(zhuǎn)寫的新行。 根據(jù)具體實(shí)現(xiàn)和初始構(gòu)造器旗標(biāo)的不同，此屬性或許會(huì)不可用。
-
buffer? 由
TextIOBase處理的下層二進(jìn)制緩沖區(qū)（為一個(gè)BufferedIOBase的實(shí)例）。 它不是TextIOBaseAPI 的組成部分并且不存在于某些實(shí)現(xiàn)中。
-
detach()? 從
TextIOBase分離出下層二進(jìn)制緩沖區(qū)并將其返回。在下層緩沖區(qū)被分離后，
TextIOBase將處于不可用的狀態(tài)。某些
TextIOBase的實(shí)現(xiàn)，例如StringIO可能并無下層緩沖區(qū)的概念，因此調(diào)用此方法將引發(fā)UnsupportedOperation。3.1 新版功能.
-
readline(size=-1)? 讀取至換行符或 EOF 并返回單個(gè)
str。 如果流已經(jīng)到達(dá) EOF，則將返回一個(gè)空字符串。如果指定了 size ，最多將讀取 size 個(gè)字符。
-
seek(offset, whence=SEEK_SET)? 將流位置改為給定的偏移位置 offset。 具體行為取決于 whence 形參。 whence 的默認(rèn)值為
SEEK_SET。SEEK_SET或0: 從流的開始位置起查找（默認(rèn)值）；offset 必須為TextIOBase.tell()所返回的數(shù)值或?yàn)榱恪?任何其他 offset 值都將導(dǎo)致未定義的行為。SEEK_CUR或1: "查找" 到當(dāng)前位置；offset 必須為零，表示無操作（所有其他值均不受支持）。SEEK_END或2: 查找到流的末尾；offset 必須為零（所有其他值均不受支持）。
以數(shù)字形式返回新的絕對(duì)位置。
3.1 新版功能:
SEEK_*常量.
-
tell()? 以不透明數(shù)字形式返回當(dāng)前流的位置。 該數(shù)字通常并不代表下層二進(jìn)制存儲(chǔ)中對(duì)應(yīng)的字節(jié)數(shù)。
-
write(s)? 將字符串 s 寫入到流并返回寫入的字符數(shù)。
-
-
class
io.TextIOWrapper(buffer, encoding=None, errors=None, newline=None, line_buffering=False, write_through=False)? 一個(gè)基于
BufferedIOBase二進(jìn)制流的緩沖文本流。 它繼承自TextIOBase。encoding 給出流被解碼或編碼時(shí)將使用的編碼格式。 它默認(rèn)為
locale.getpreferredencoding(False)。errors 是一個(gè)可選的字符串，它指明編碼格式和編碼格式錯(cuò)誤的處理方式。 傳入
'strict'將在出現(xiàn)編碼格式錯(cuò)誤時(shí)引發(fā)ValueError(默認(rèn)值None具有相同的效果)，傳入'ignore'將忽略錯(cuò)誤。 (請(qǐng)注意忽略編碼格式錯(cuò)誤會(huì)導(dǎo)致數(shù)據(jù)丟失。)'replace'會(huì)在出現(xiàn)錯(cuò)誤數(shù)據(jù)時(shí)插入一個(gè)替換標(biāo)記 (例如'?')。'backslashreplace'將把錯(cuò)誤數(shù)據(jù)替換為一個(gè)反斜杠轉(zhuǎn)義序列。 在寫入時(shí)，還可以使用'xmlcharrefreplace'(替換為適當(dāng)?shù)?XML 字符引用) 或'namereplace'(替換為\N{...}轉(zhuǎn)義序列)。 任何其他通過codecs.register_error()注冊(cè)的錯(cuò)誤處理方式名稱也可以被接受。newline 控制行結(jié)束符處理方式。 它可以為
None,'','\n','\r'和'\r\n'。 其工作原理如下:當(dāng)從流中讀取輸入時(shí)，如果 newline 為
None，則會(huì)啟用 universal newlines 模式。 輸入中的行結(jié)束符可以為'\n','\r'或'\r\n'，在返回給調(diào)用者之前它們會(huì)被統(tǒng)一轉(zhuǎn)寫為'\n'。 如果參數(shù)為''，也會(huì)啟用通用換行模式，但行結(jié)束符會(huì)不加轉(zhuǎn)寫即返回給調(diào)用者。 如果它具有任何其他合法的值，則輸入行將僅由給定的字符串結(jié)束，并且行結(jié)束符會(huì)不加轉(zhuǎn)寫即返回給調(diào)用者。將輸出寫入流時(shí)，如果 newline 為
None，則寫入的任何'\n'字符都將轉(zhuǎn)換為系統(tǒng)默認(rèn)行分隔符os.linesep。如果 newline 是''或'\n'，則不進(jìn)行翻譯。如果 newline 是任何其他合法值，則寫入的任何'\n'字符將被轉(zhuǎn)換為給定的字符串。
如果 line_buffering 為
True，則當(dāng)一個(gè)寫入調(diào)用包含換行符或回車時(shí)將會(huì)應(yīng)用flush()。如果 write_through 為
True，對(duì)write()的調(diào)用會(huì)確保不被緩沖：在TextIOWrapper對(duì)象上寫入的任何數(shù)據(jù)會(huì)立即交給其下層的 buffer 來處理。在 3.3 版更改: 已添加 write_through 參數(shù)
在 3.3 版更改: 默認(rèn)的 encoding 現(xiàn)在將為
locale.getpreferredencoding(False)而非locale.getpreferredencoding()。 不要使用locale.setlocale()來臨時(shí)改變區(qū)域編碼格式，要使用當(dāng)前區(qū)域編碼格式而不是用戶的首選編碼格式。TextIOWrapper在繼承自TextIOBase及其父類的現(xiàn)有成員以外還提供了下列成員:-
line_buffering? 是否啟用行緩沖。
-
write_through? 寫入是否要立即傳給下層的二進(jìn)制緩沖。
3.7 新版功能.
-
reconfigure(*[, encoding][, errors][, newline][, line_buffering][, write_through])? 使用 encoding, errors, newline, line_buffering 和 write_through 的新設(shè)置來重新配置此文本流。
未指定的形參將保留當(dāng)前設(shè)定，例外情況是當(dāng)指定了 encoding 但未指定 errors 時(shí)將會(huì)使用
errors='strict'。如果已經(jīng)有數(shù)據(jù)從流中被讀取則將無法再改變編碼格式或行結(jié)束符。 另一方面，在寫入數(shù)據(jù)之后再改變編碼格式則是可以的。
此方法會(huì)在設(shè)置新的形參之前執(zhí)行隱式的流刷新。
3.7 新版功能.
-
class
io.StringIO(initial_value='', newline='\n')? 用于文本 I/O 的內(nèi)存數(shù)據(jù)流。 當(dāng)調(diào)用
close()方法時(shí)將會(huì)丟棄文本緩沖區(qū)。緩沖區(qū)的初始值可通過提供 initial_value 來設(shè)置。 如果啟用了行結(jié)束符轉(zhuǎn)寫，換行將以
write()所用的方式被編碼。 數(shù)據(jù)流位置將被設(shè)為緩沖區(qū)的開頭。newline 參數(shù)的規(guī)則與
TextIOWrapper所用的一致。 默認(rèn)規(guī)則是僅將\n字符視為行結(jié)束符并且不執(zhí)行換行符轉(zhuǎn)寫。 如果 newline 設(shè)為None，在所有平臺(tái)上換行符都將被寫入為\n，但當(dāng)讀取時(shí)仍然會(huì)執(zhí)行通用換行編碼格式。StringIO在繼承自TextIOBase及其父類的現(xiàn)有成員以外還提供了以下方法:用法示例：
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? 用于在 universal newlines 模式下解碼換行符的輔助編解碼器。 它繼承自
codecs.IncrementalDecoder。
性能?
本節(jié)討論所提供的具體 I/O 實(shí)現(xiàn)的性能。
二進(jìn)制 I/O?
即使在用戶請(qǐng)求單個(gè)字節(jié)時(shí)，也只讀取和寫入大塊數(shù)據(jù)。通過該方法，緩沖 I/O 也隱藏了調(diào)用和執(zhí)行操作系統(tǒng)無緩沖 I/O 例程時(shí)的任何低效性。。增益取決于操作系統(tǒng)和執(zhí)行的 I/O 類型。例如，在某些現(xiàn)代操作系統(tǒng)上（例如Linux），無緩沖磁盤 I/O 可以與緩沖 I/O 一樣快。但最重要的是，無論平臺(tái)和支持設(shè)備如何，緩沖 I/O 都能提供可預(yù)測(cè)的性能。因此，對(duì)于二進(jìn)制數(shù)據(jù)，幾乎總是首選使用緩沖的I / O而不是未緩沖的I / O。
文本 I/O?
二進(jìn)制存儲(chǔ)（如文件）上的文本 I/O 比同一存儲(chǔ)上的二進(jìn)制 I/O 慢得多，因?yàn)樗枰褂米址幗獯a器在Unicode和二進(jìn)制數(shù)據(jù)之間進(jìn)行轉(zhuǎn)換。這在處理大量文本數(shù)據(jù)（如大型日志文件）時(shí)會(huì)變得非常明顯。此外，由于使用的重構(gòu)算法 TextIOWrapper.tell() 和 TextIOWrapper.seek() 都相當(dāng)慢。
多線程?
FileIO 對(duì)象是線程安全的，只要它們包裝的操作系統(tǒng)調(diào)用（比如Unix下的 read(2) ）也是線程安全的。
二進(jìn)制緩沖對(duì)象（例如 BufferedReader, BufferedWriter, BufferedRandom 和 BufferedRWPair）使用鎖來保護(hù)其內(nèi)部結(jié)構(gòu)；因此，可以安全地一次從多個(gè)線程中調(diào)用它們。
TextIOWrapper 對(duì)象不再是線程安全的。
可重入性?
二進(jìn)制緩沖對(duì)象（ BufferedReader ， BufferedWriter ， BufferedRandom 和 BufferedRWPair 的實(shí)例）不是可重入的。雖然在正常情況下不會(huì)發(fā)生可重入調(diào)用，但是可能會(huì)在 signal 處理程序中執(zhí)行 I/O 而產(chǎn)生。如果線程嘗試重新輸入已經(jīng)訪問的緩沖對(duì)象，則會(huì)引發(fā) RuntimeError 。注意，這并不禁止其他線程進(jìn)入緩沖對(duì)象。
上面的內(nèi)容隱含地?cái)U(kuò)展到文本文件，因?yàn)?open() 函數(shù)會(huì)把緩沖對(duì)象包裝在 TextIOWrapper 中。這包括標(biāo)準(zhǔn)流，因此也會(huì)影響內(nèi)置函數(shù) print() 。