源代碼: 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。