asyncio非同步IO——Streams詳解

馬鳴謙發表於2018-11-30
非同步

前言

本文翻譯自python3.7官方文件——asyncio-stream,譯者馬鳴謙,郵箱 1612557569@qq.com。轉載請註明出處。

資料流（Streams）

資料流（Streams）是用於處理網路連線的高階非同步/等待就緒(async/await-ready)原語,可以在不使用回撥和底層傳輸協議的情況下傳送和接收資料。

以下是一個用asyncio實現的TCP回顯客戶端：

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())

    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!`))

完整程式碼見例子一節。

Stream方法

以下所列的高層asyncio方法可以被用作建立和處理Stream：

  • coroutine **asyncio.open_connection(host=None,*,loop=None,limit=None,ssl=None,family=0,proto=0,flags=0,sock=None,local_addr=None,server_hostname=None,ssl_handshake_timeout=None)**
    • 建立一個網路連線，並返回一對（reader,writer）物件。
    • 返回的reader和writer物件是StreamReader和StreamWriter類的例項。
    • loop是可選引數，在此方法被某個協程await時能夠自動確定。
    • limit限定返回的StreamReader例項使用的緩衝區大小。預設情況下，緩衝區限制為64KiB。
    • 其餘的引數被直接傳遞給loop.create_connection()。
    • python3.7新增：ssl_handshake_timeout引數。
  • coroutine **asyncio.start_server(client_connected_cb,host=None,port=None,*,loop=None,limit=None,family=socket.AF_UNSPEC,flags=socket.AI_PASSIVE,sock=None,backlog=100,ssl=None,reuse_address=None,reuse_port=None,ssl_handshake_timeout=None,start_serving=True)**
    • 啟動一個socket服務端。
    • client_connected_cb指定的回撥函式，在新連線建立的時候被呼叫。該回撥函式接收StreamReader和StreamWriter類的‘例項對’(reader,writer)作為兩個引數。
    • client_connected_cb可以是普通的可呼叫函式，也可以是協程函式。如果是協程函式，那麼會被自動封裝為Task物件處理。
    • loop是可選引數，在此方法被某個協程await時能夠自動確定。
    • limit限定返回的StreamReader例項使用的緩衝區大小。預設情況下，緩衝區限定值為64KiB。
    • 其餘的引數被直接傳遞給loop.create_server()。
    • python3.7新增：ssl_handshake_timeout和start_serving引數。

Unix Sockets

  • coroutine **asyncio.open_unix_connection(path=None,*,loop=None,limit=None,ssl=None,sock=None,server_hostname=None,ssl_handshake_timeout=None)**
    • 建立一個Unix socket連線，並返回一對(reader,writer)物件。
    • 與open_connection類似，只是執行在Unix sockets上。
    • 另見loop.create_unix_connection()
    • 可用於：Unix
    • python3.7新增：ssl_handshake_timeout引數。
    • python3.7修正：path引數可以為類path(path-like)物件
  • coroutine **asyncio.start_unix_server(client_connected_cb, path=None, *, loop=None, limit=None, sock=None, backlog=100, ssl=None, ssl_handshake_timeout=None, start_serving=True)**
    • 啟動一個Unix socket 服務端。
    • 類似於start_server,只是執行在Unix sockets上。
    • 另見loop.create_unix_server
    • 可用於：Unix
    • python3.7新增：ssl_handshake_timeout引數。
    • python3.7修正：path引數可以為類path(path-like)物件

StreamReader

class asyncio.StreamReader

定義一個讀取器物件，提供從IO資料流中讀取資料的API。
不建議 直接例項化StreamReader物件。建議通過open_connection()或start_server()建立此類物件。

  • coroutine read(n=-1)
    • 最多讀取n位元組資料。如果n未設定，或被設定為-1，則讀取至EOF標誌，並返回讀到的所有位元組。
    • 如果在緩衝區仍為空時遇到EOF，則返回一個空的bytes物件。
  • coroutine readline()
    • 讀取一行（以
      為標誌）。
    • 如果在找到
      之前遇到EOF，則返回已讀取到的資料段。
    • 如果遇到EOF時內部緩衝區仍為空，則返回空的bytes物件。
  • coroutine readexactly(n)
    • 精確讀取n位元組資料。
    • 如果在尚未讀夠n位元組時遇到EOF，則引發IncompleteReadError異常。已經讀取的部分資料可以通過IncompleteReadError.partial屬性獲取。
  • coroutine readuntil(separator=b`
    `)
    • 從資料流中讀取資料直到遇到separator。
    • 如果執行成功，讀到的資料和分隔符將從內部緩衝區裡移除。返回的資料會在末尾包含分隔符。
    • 如果讀取資料的總量超過了配置的資料流緩衝區限制，則引發LimitOverrunError,資料會被留在內部緩衝區中，可以被再次讀取。
    • 如果在找到separator分隔符之前遇到EOF，則引發IncompleteReadError異常，內部緩衝區會被重置。IncompleteReadError.partial屬性會包含部分separator。
    • python3.5.2新增。
  • at_eof()
    • 如果緩衝區為空，且feed_eof()被呼叫，則返回True。

StreamWriter

class asyncio.StreamWriter

定義一個寫入器物件，提供向IO資料流中寫入資料的API。
不建議直接例項化StreamWriter物件，建議通過open_connection或start_server例項化物件。

  • can_writer_eof()
    • 如果下層傳輸支援write_eof方法，則返回True,否則返回False。
  • write_eof()
    • 在緩衝的寫入資料被重新整理後，關閉資料流的寫入端。
  • transport
    • 返回下層的asyncio傳輸。
  • get_extra_info(name,default=None)
    • 訪問可選的傳輸資訊。
  • write(data)
    • 向資料流中寫入資料。
    • 此方法不受流量控制的影響。write()應同drain()一同使用。
  • writelines()
    • 向資料流中寫入bytes列表（或任何的可迭代物件）。
    • 此方法不受流量控制的影響。應與drain()一同使用。
  • coroutine drain()
    • 等待恢復資料寫入的時機。例如：
    writer.write(data)
await writer.drain()
    • 這是一個與底層IO輸入緩衝區互動的流量控制方法。當緩衝區達到上限時，drain()阻塞，待到緩衝區回落到下限時，寫操作可以被恢復。當不需要等待時，drain()會立即返回。
  • close()
    • 關閉資料流。
  • is_closing()
    • 如果資料流已經關閉或正在關閉，則返回True。
  • coroutine wait_closed()
    • 保持等待，直到資料流關閉。
    • 保持等待，直到底層連線被關閉，應該在close()後呼叫此方法。
    • Python3.7新增。

示例

利用Stream實現TCP回顯客戶端

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())

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

    print(`Close the connection`)
    writer.close()

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

利用Stream實現TCP回顯服務端

import asyncio

async def handle_echo(reader, writer):
    data = await reader.read(100)
    message = data.decode()
    addr = writer.get_extra_info(`peername`)

    print(f"Received {message!r} from {addr!r}")

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

    print("Close the connection")
    writer.close()

async def main():
    server = await asyncio.start_server(
        handle_echo, `127.0.0.1`, 8888)

    addr = server.sockets[0].getsockname()
    print(f`Serving on {addr}`)

    async with server:
        await server.serve_forever()

asyncio.run(main())

獲取HTTP頭

import asyncio
import urllib.parse
import sys

async def print_http_headers(url):
    url = urllib.parse.urlsplit(url)
    if url.scheme == `https`:
        reader, writer = await asyncio.open_connection(
            url.hostname, 443, ssl=True)
    else:
        reader, writer = await asyncio.open_connection(
            url.hostname, 80)

    query = (
        f"HEAD {url.path or `/`} HTTP/1.0
"
        f"Host: {url.hostname}
"
        f"
"
    )

    writer.write(query.encode(`latin-1`))
    while True:
        line = await reader.readline()
        if not line:
            break

        line = line.decode(`latin1`).rstrip()
        if line:
            print(f`HTTP header> {line}`)

    # Ignore the body, close the socket
    writer.close()

url = sys.argv[1]
asyncio.run(print_http_headers(url))

用法：

python example.py http://example.com/path/page.html

或：

python example.py https://example.com/path/page.html

利用Stream註冊等待資料的開放socket

import asyncio
import socket

async def wait_for_data():
    # Get a reference to the current event loop because
    # we want to access low-level APIs.
    loop = asyncio.get_running_loop()

    # Create a pair of connected sockets.
    rsock, wsock = socket.socketpair()

    # Register the open socket to wait for data.
    reader, writer = await asyncio.open_connection(sock=rsock)

    # Simulate the reception of data from the network
    loop.call_soon(wsock.send, `abc`.encode())

    # Wait for data
    data = await reader.read(100)

    # Got data, we are done: close the socket
    print("Received:", data.decode())
    writer.close()

    # Close the second socket
    wsock.close()

asyncio.run(wait_for_data())

相關文章