tornado.iostream — 非阻塞套接字的便捷封裝

用於寫入和讀取非阻塞檔案和套接字的工具類別。

目錄

• BaseIOStream：用於讀取和寫入的通用介面。

• IOStream：使用非阻塞套接字實作 BaseIOStream。

• SSLIOStream：具備 SSL 感知功能的 IOStream 版本。

• PipeIOStream：基於管道的 IOStream 實作。

基底類別

class tornado.iostream.BaseIOStream(max_buffer_size: Optional[int] = None, read_chunk_size: Optional[int] = None, max_write_buffer_size: Optional[int] = None)

用於寫入和讀取非阻塞檔案或套接字的工具類別。

我們支援非阻塞的 write() 和一系列 read_*() 方法。當操作完成時，Awaitable 將解析為讀取的資料（或 write() 為 None）。當串流關閉時，所有未完成的 Awaitable 都會解析為 StreamClosedError；BaseIOStream.set_close_callback 也可用於接收串流關閉的通知。

當串流因錯誤而關閉時，IOStream 的 error 屬性會包含例外物件。

子類別必須實作 fileno、close_fd、write_to_fd、read_from_fd，以及選擇性地實作 get_fd_error。

BaseIOStream 建構子。

參數

• max_buffer_size – 要緩衝的傳入資料最大量；預設為 100MB。

• read_chunk_size – 每次從底層傳輸讀取的資料量；預設為 64KB。

• max_write_buffer_size – 要緩衝的傳出資料量；預設為無限。

在 4.0 版變更：新增 max_write_buffer_size 參數。將預設的 read_chunk_size 變更為 64KB。

在 5.0 版變更：已移除 io_loop 引數（自 4.1 版起已淘汰）。

主要介面

BaseIOStream.write(data: Union[bytes, memoryview]) → Future[None]

以非同步方式將給定的資料寫入此串流。

此方法會傳回 Future，當寫入完成時，該 Future 將解析（結果為 None）。

data 引數的類型可以是 bytes 或 memoryview。

在 4.0 版變更：如果未提供回呼，現在會傳回 Future。

在 4.5 版變更：新增對 memoryview 引數的支援。

在 6.0 版變更：已移除 callback 引數。請改用傳回的 Future。

BaseIOStream.read_bytes(num_bytes: int, partial: bool = False) → Awaitable[bytes]

以非同步方式讀取一定數量的位元組。

如果 partial 為 true，則會在我們有任何位元組可以傳回時立即傳回資料（但永遠不會超過 num_bytes）

變更於 4.0 版本: 新增了 partial 參數。回呼參數現在為選用，如果省略，將會回傳 Future。

變更於 6.0 版本: 已移除 callback 和 streaming_callback 參數。請改用回傳的 Future (以及 partial=True 來取代 streaming_callback)。

BaseIOStream.read_into(buf: bytearray, partial: bool = False) → Awaitable[int]

以非同步方式讀取一定數量的位元組。

buf 必須是一個可寫入的緩衝區，資料將會被讀入其中。

如果 partial 為 true，則在讀取到任何位元組時立即執行回呼。否則，當 buf 完全填滿讀取到的資料時才會執行。

於 5.0 版本新增。

在 6.0 版變更：已移除 callback 引數。請改用傳回的 Future。

BaseIOStream.read_until(delimiter: bytes, max_bytes: Optional[int] = None) → Awaitable[bytes]

非同步讀取直到找到指定的定界符號。

結果會包含所有讀取的資料，包括定界符號。

如果 max_bytes 不是 None，則如果已讀取超過 max_bytes 個位元組且找不到定界符號，則會關閉連線。

變更於 4.0 版本: 新增了 max_bytes 參數。callback 參數現在為選用，如果省略，將會回傳 Future。

在 6.0 版變更：已移除 callback 引數。請改用傳回的 Future。

BaseIOStream.read_until_regex(regex: bytes, max_bytes: Optional[int] = None) → Awaitable[bytes]

非同步讀取直到符合指定的正規表示式。

結果會包含符合正規表示式的資料以及其之前的所有內容。

如果 max_bytes 不是 None，則如果已讀取超過 max_bytes 個位元組且不滿足正規表示式，則會關閉連線。

變更於 4.0 版本: 新增了 max_bytes 參數。callback 參數現在為選用，如果省略，將會回傳 Future。

在 6.0 版變更：已移除 callback 引數。請改用傳回的 Future。

BaseIOStream.read_until_close() → Awaitable[bytes]

非同步讀取 socket 中的所有資料，直到關閉為止。

這將會緩衝所有可用的資料，直到達到 max_buffer_size 為止。如果需要流量控制或取消，請改用迴圈搭配 read_bytes(partial=True)。

變更於 4.0 版本: 回呼參數現在為選用，如果省略，將會回傳 Future。

變更於 6.0 版本: 已移除 callback 和 streaming_callback 參數。請改用回傳的 Future (以及使用 partial=True 的 read_bytes 來取代 streaming_callback)。

BaseIOStream.close(exc_info: Union[None, bool, BaseException, Tuple[Optional[Type[BaseException]], Optional[BaseException], Optional[TracebackType]]] = False) → None

關閉此串流。

如果 exc_info 為 true，則將 error 屬性設定為來自 sys.exc_info 的目前例外狀況（如果 exc_info 是元組，則使用該元組而非 sys.exc_info）。

BaseIOStream.set_close_callback(callback: Optional[Callable[[], None]]) → None

當串流關閉時，呼叫給定的回呼函式。

對於使用 Future 介面的應用程式，這通常不是必要的；當串流關閉時，所有未完成的 Futures 都會解析為 StreamClosedError。然而，當沒有其他讀取或寫入正在進行時，它仍然可以作為發出串流已關閉訊號的方法。

與其他基於回呼的介面不同，set_close_callback 並未在 Tornado 6.0 中移除。

BaseIOStream.closed() → bool

如果串流已關閉，則返回 True。

BaseIOStream.reading() → bool

如果我們目前正在從串流讀取，則返回 True。

BaseIOStream.writing() → bool

如果我們目前正在寫入串流，則返回 True。

BaseIOStream.set_nodelay(value: bool) → None

設定此串流的無延遲標誌。

預設情況下，寫入 TCP 串流的資料可能會保留一段時間，以最有效率地使用頻寬（根據 Nagle 演算法）。無延遲標誌要求資料盡快寫入，即使這樣做會消耗額外的頻寬。

此標誌目前僅針對基於 TCP 的 IOStreams 定義。

3.1 版的新功能。

子類別的方法

BaseIOStream.fileno() → Union[int, _Selectable]

傳回此串流的檔案描述符。

BaseIOStream.close_fd() → None

關閉此串流的基礎檔案。

close_fd 由 BaseIOStream 呼叫，不應在其他地方呼叫；其他使用者應改為呼叫 close。

BaseIOStream.write_to_fd(data: memoryview) → int

嘗試將 data 寫入基礎檔案。

傳回寫入的位元組數。

BaseIOStream.read_from_fd(buf: Union[bytearray, memoryview]) → Optional[int]

嘗試從基礎檔案讀取。

讀取最多 len(buf) 個位元組，並將它們儲存在緩衝區中。傳回讀取的位元組數。如果沒有可讀取的內容（socket 返回 EWOULDBLOCK 或等效的值），則傳回 None，在 EOF 時傳回 0。

變更於 5.0 版: 介面重新設計為接受緩衝區並傳回位元組數，而不是新配置的物件。

BaseIOStream.get_fd_error() → Optional[Exception]

傳回關於底層檔案上任何錯誤的資訊。

此方法會在 IOLoop 在檔案描述器上發出錯誤訊號後呼叫，並應傳回一個 Exception (例如含有額外資訊的 socket.error)，如果沒有這類資訊，則傳回 None。

實作

class tornado.iostream.IOStream(socket: socket, *args: Any, **kwargs: Any)

基於 Socket 的 IOStream 實作。

此類別支援 BaseIOStream 中的讀取和寫入方法，以及 connect 方法。

socket 參數可以是已連線或未連線的。對於伺服器操作，socket 是呼叫 socket.accept 的結果。對於客戶端操作，socket 是使用 socket.socket 建立的，並且可以在傳遞給 IOStream 之前連線，或使用 IOStream.connect 連線。

一個非常簡單 (且有問題) 的 HTTP 客戶端使用此類別

import socket
import tornado

async def main():
    s = socket.socket(socket.AF_INET, socket.SOCK_STREAM, 0)
    stream = tornado.iostream.IOStream(s)
    await stream.connect(("friendfeed.com", 80))
    await stream.write(b"GET / HTTP/1.0\r\nHost: friendfeed.com\r\n\r\n")
    header_data = await stream.read_until(b"\r\n\r\n")
    headers = {}
    for line in header_data.split(b"\r\n"):
        parts = line.split(b":")
        if len(parts) == 2:
            headers[parts[0].strip()] = parts[1].strip()
    body_data = await stream.read_bytes(int(headers[b"Content-Length"]))
    print(body_data)
    stream.close()

if __name__ == '__main__':
    asyncio.run(main())

connect(address: Any, server_hostname: Optional[str] = None) → Future[_IOStreamType]

將 socket 連接到遠端位址，不會發生阻塞。

只有在傳遞給建構子的 socket 先前未連線時，才能呼叫此方法。address 參數的格式與傳遞給 IOStream 建構子的 socket 類型所使用的 socket.connect 相同，例如 (ip, port) 元組。這裡接受主機名稱，但會同步解析並阻塞 IOLoop。如果您有主機名稱而不是 IP 位址，建議使用 TCPClient 類別，而不是直接呼叫此方法。TCPClient 將執行非同步 DNS 解析並處理 IPv4 和 IPv6。

如果指定了 callback，則會在連線完成時呼叫它，且不帶任何引數；如果沒有指定，此方法會傳回一個 Future (成功連線後，其結果將會是串流本身)。

在 SSL 模式下，server_hostname 參數將用於憑證驗證 (除非在 ssl_options 中停用) 和 SNI (如果支援；需要 Python 2.7.9+)。

請注意，在連線擱置時呼叫 IOStream.write 是安全的，在這種情況下，資料會在連線準備好時立即寫入。在 socket 連線之前呼叫 IOStream 讀取方法在某些平台上可行，但不是可移植的。

在 4.0 版中變更: 如果沒有給定回呼，則傳回一個 Future。

在 4.2 版中變更: 預設情況下會驗證 SSL 憑證；傳遞 ssl_options=dict(cert_reqs=ssl.CERT_NONE) 或適當設定的 ssl.SSLContext 給 SSLIOStream 建構子以停用。

在 6.0 版變更：已移除 callback 引數。請改用傳回的 Future。

start_tls(server_side: bool, ssl_options: Optional[Union[Dict[str, Any], SSLContext]] = None, server_hostname: Optional[str] = None) → Awaitable[SSLIOStream]

將此 IOStream 轉換為 SSLIOStream。

這可以啟用以明文模式開始，並在一些初始協商後切換到 SSL 的協定 (例如 SMTP 和 IMAP 的 STARTTLS 擴充)。

如果串流上有未完成的讀取或寫入，或 IOStream 的緩衝區中有任何資料 (允許作業系統 socket 緩衝區中的資料)，則無法使用此方法。這表示它通常必須在讀取或寫入最後的明文資料後立即使用。它也可以在連線後立即使用，在任何讀取或寫入之前。

ssl_options 引數可以是 ssl.SSLContext 物件或 ssl.SSLContext.wrap_socket 函式的關鍵字引數字典。server_hostname 引數將用於憑證驗證，除非在 ssl_options 中停用。

此方法傳回一個 Future，其結果是新的 SSLIOStream。在呼叫此方法後，對原始串流的任何其他操作都是未定義的。

如果在此串流上定義了關閉回呼，它將會轉移到新的串流。

4.0 版中的新功能。

在 4.2 版本變更: 預設情況下會驗證 SSL 憑證；傳遞 ssl_options=dict(cert_reqs=ssl.CERT_NONE) 或適當設定的 ssl.SSLContext 來停用。

class tornado.iostream.SSLIOStream(*args: Any, **kwargs: Any)

用於寫入和讀取非阻塞 SSL socket 的實用類別。

如果傳遞給建構函式的 socket 已經連線，則應使用

ssl.SSLContext(...).wrap_socket(sock, do_handshake_on_connect=False, **kwargs)

在建構 SSLIOStream 之前包裝。當 IOStream.connect 完成時，未連線的 socket 將會被包裝。

ssl_options 關鍵字引數可以是 ssl.SSLContext 物件，或是 ssl.SSLContext.wrap_socket 的關鍵字引數字典。

wait_for_handshake() → Future[SSLIOStream]

等待初始 SSL 交握完成。

如果給定 callback，則一旦交握完成，將會呼叫它且不帶任何引數；否則，此方法會傳回一個 Future，該 Future 將在交握完成後解析為串流本身。

一旦交握完成，即可在 self.socket 上存取對等憑證和 NPN/ALPN 選取等資訊。

此方法旨在用於伺服器端串流或在使用 IOStream.start_tls 之後；不應將其與 IOStream.connect 一起使用（後者已等待交握完成）。每個串流只能呼叫一次。

在 4.2 版本中新增。

在 6.0 版變更：已移除 callback 引數。請改用傳回的 Future。

class tornado.iostream.PipeIOStream(fd: int, *args: Any, **kwargs: Any)

基於 Pipe 的 IOStream 實作。

建構函式會接收一個整數檔案描述器（例如由 os.pipe 傳回的描述器），而不是開啟的檔案物件。Pipe 通常是單向的，因此 PipeIOStream 可用於讀取或寫入，但不能同時用於兩者。

PipeIOStream 僅在基於 Unix 的平台上可用。

例外

exception tornado.iostream.StreamBufferFullError

當緩衝區滿時，IOStream 方法引發的例外。

exception tornado.iostream.StreamClosedError(real_error: Optional[BaseException] = None)

當串流關閉時，IOStream 方法引發的例外。

請注意，關閉回呼會排程在串流上的其他回呼 *之後* 執行（以允許處理緩衝的資料），因此您可能會在看到關閉回呼之前看到此錯誤。

real_error 屬性包含導致串流關閉的基礎錯誤（如果有）。

在 4.3 版本變更: 新增了 real_error 屬性。

exception tornado.iostream.UnsatisfiableReadError

當無法滿足讀取時引發的例外。

由 read_until 和 read_until_regex 帶有 max_bytes 引數引發。