串流¶

原始碼：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=None, ssl_shutdown_timeout=None, start_serving=True, cleanup_socket=True)¶

啟動一個 Unix socket 伺服器。

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

If cleanup_socket is true then the Unix socket will automatically be removed from the filesystem when the server is closed, unless the socket has been replaced after the server has been created.

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

備註

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

可用性: Unix.

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

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

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

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

StreamReader¶

class asyncio.