串流¶

原始碼：Lib/asyncio/streams.py

串流是支援 async/await (async/await-ready) 的高階原語 (high-level primitive)，用於處理網路連線。串流不需要使用回呼 (callback) 或低階協定和傳輸 (transport) 就能夠傳送和接收資料。

這是一個使用 asyncio 串流編寫的 TCP echo 用戶端範例：

import asyncio

async def tcp_echo_client(message):
    reader, writer = await asyncio.open_connection(
        '127.0.0.1', 8888)

    print(f'Send: {message!r}')
    writer.write(message.encode())
    await writer.drain()

    data = await reader.read(100)
    print(f'Received: {data.decode()!r}')

    print('Close the connection')
    writer.close()
    await writer.wait_closed()

asyncio.run(tcp_echo_client('Hello World!'))

另請參閱下方 Examples 段落。

串流函式

下面的高階 asyncio 函式可以用來建立和處理串流：

async asyncio.open_connection(host=None, port=None, *, limit=None, ssl=None, family=0, proto=0, flags=0, sock=None, local_addr=None, server_hostname=None, ssl_handshake_timeout=None, ssl_shutdown_timeout=None, happy_eyeballs_delay=None, interleave=None)¶

建立網路連線並回傳一對 (reader, writer) 物件。

回傳的 reader 和 writer 物件是 StreamReader 和 StreamWriter 類別的實例。

limit 指定了回傳的 StreamReader 實例所使用的緩衝區 (buffer) 大小限制。limit 預設為 64 KiB。

其餘的引數會直接傳遞到 loop.create_connection()。

備註

The sock argument transfers ownership of the socket to the StreamWriter created. To close the socket, call its close() method.

在 3.7 版的變更: 新增 ssl_handshake_timeout 參數。

在 3.8 版的變更: 新增 happy_eyeballs_delay 和 interleave 參數。

在 3.10 版的變更: 移除 loop 參數。

在 3.11 版的變更: 新增 ssl_shutdown_timeout 參數。

async asyncio.start_server(client_connected_cb, host=None, port=None, *, limit=None, family=socket.AF_UNSPEC, flags=socket.AI_PASSIVE, sock=None, backlog=100, ssl=None, reuse_address=None, reuse_port=None, keep_alive=None, ssl_handshake_timeout=None, ssl_shutdown_timeout=None, start_serving=True)¶

啟動 socket 伺服器。

當一個新的用戶端連線被建立時，回呼函式 client_connected_cb 就會被呼叫。該函式會接收到一對引數 (reader, writer)，分別為 StreamReader 和 StreamWriter 的實例。

client_connected_cb 既可以是普通的可呼叫物件 (callable)，也可以是一個協程函式；如果它是一個協程函式，它將自動作為 Task 來被排程。

limit 指定了回傳的 StreamReader 實例所使用的緩衝區 (buffer) 大小限制。limit 預設為 64 KiB。

剩下的引數將會直接傳遞給 loop.create_server()。

備註

The sock argument transfers ownership of the socket to the server created. To close the socket, call the server's close() method.

在 3.7 版的變更: 新增 ssl_handshake_timeout 與 start_serving 參數。

在 3.10 版的變更: 移除 loop 參數。

在 3.11 版的變更: 新增 ssl_shutdown_timeout 參數。

在 3.13 版的變更: 新增 keep_alive 參數。

Unix Sockets

async asyncio.open_unix_connection(path=None, *, limit=None, ssl=None, sock=None, server_hostname=None, ssl_handshake_timeout=None, ssl_shutdown_timeout=None)¶

建立一個 Unix socket 連線並回傳一對 (reader, writer)。

與 open_connection() 相似，但是是操作 Unix sockets。

另請參閱 loop.create_unix_connection() 文件。

備註

The sock argument transfers ownership of the socket to the StreamWriter created. To close the socket, call its close() method.

可用性: Unix.

在 3.7 版的變更: 新增 ssl_handshake_timeout 參數。path 參數現在可以是個 path-like object

在 3.10 版的變更: 移除 loop 參數。

在 3.11 版的變更: 新增 ssl_shutdown_timeout 參數。

async asyncio.start_unix_server(client_connected_cb, path=None, *, limit=None, sock=None, backlog=100, ssl=None, ssl_handshake_timeout