tornado.netutil — 雜項網路工具

雜項網路工具程式碼。

tornado.netutil.bind_sockets(port: int, address: Optional[str] = None, family: AddressFamily = AddressFamily.AF_UNSPEC, backlog: int = 128, flags: Optional[int] = None, reuse_port: bool = False) → List[socket][原始碼]

建立監聽套接字，綁定到指定的連接埠和位址。

返回套接字物件的列表（如果給定的位址對應到多個 IP 位址，則返回多個套接字，這在混合使用 IPv4 和 IPv6 時最常見）。

位址可以是 IP 位址或主機名稱。如果它是主機名稱，則伺服器將會監聽與該名稱關聯的所有 IP 位址。位址可以是一個空字串或 None，以監聽所有可用的介面。Family 可以設定為 socket.AF_INET 或 socket.AF_INET6 以限制為 IPv4 或 IPv6 位址，否則如果可用，將會同時使用兩者。

backlog 參數的含義與 socket.listen() 相同。

flags 是 getaddrinfo 的 AI_* 旗標的位元遮罩，例如 socket.AI_PASSIVE | socket.AI_NUMERICHOST。

reuse_port 選項為列表中的每個套接字設定 SO_REUSEPORT 選項。如果您的平台不支援此選項，則會引發 ValueError。

tornado.netutil.bind_unix_socket(file: str, mode: int = 384, backlog: int = 128) → socket[原始碼]

建立監聽的 Unix 套接字。

如果具有指定名稱的套接字已存在，則將會刪除它。如果具有該名稱的任何其他檔案存在，則會引發例外狀況。

返回一個套接字物件（而不是像 bind_sockets 一樣的套接字物件列表）

tornado.netutil.add_accept_handler(sock: socket, callback: Callable[[socket, Any], None]) → Callable[[], None][原始碼]

新增一個 IOLoop 事件處理常式，以接受 sock 上的新連線。

當連線被接受時，將會執行 callback(connection, address) （connection 是一個套接字物件，而 address 是連線另一端的位址）。請注意，此簽章與用於 IOLoop 處理常式的 callback(fd, events) 簽章不同。

會返回一個可呼叫物件，當呼叫時，它將移除 IOLoop 事件處理常式，並停止處理進一步的傳入連線。

變更於 5.0 版: 已移除 io_loop 參數（自 4.1 版起已棄用）。

變更於 5.0 版: 返回一個可呼叫物件（之前返回 None）。

tornado.netutil.is_valid_ip(ip: str) → bool[原始碼]

如果給定的字串是格式正確的 IP 位址，則返回 True。

支援 IPv4 和 IPv6。

class tornado.netutil.Resolver(*args: Any, **kwargs: Any)[原始碼]

可設定的非同步 DNS 解析器介面。

預設情況下，會使用阻塞式實作（直接呼叫 socket.getaddrinfo）。可以使用 Resolver.configure 類別方法選擇其他實作方式。

Resolver.configure('tornado.netutil.ThreadedResolver')

Tornado 包含的此介面實作如下：

5.0 版本變更：預設實作已從 BlockingResolver 變更為 DefaultExecutorResolver。

6.2 版本變更：預設實作已從 DefaultExecutorResolver 變更為 DefaultLoopResolver。

resolve(host: str, port: int, family: AddressFamily = AddressFamily.AF_UNSPEC) → Awaitable[List[Tuple[int, Any]]][原始碼]

解析位址。

host 參數為字串，可能是主機名稱或字面 IP 位址。

傳回 Future，其結果是一個 (family, address) 配對的列表，其中 address 是一個適合傳遞給 socket.connect 的 tuple（即 IPv4 的 (host, port) 配對；IPv6 可能會有額外欄位）。如果傳遞了 callback，則完成時將使用結果作為參數執行。

引發

IOError – 如果無法解析位址。

4.4 版本變更：所有實作均標準化為引發 IOError。

6.0 版本變更：已移除 callback 參數。請改用傳回的可等待物件。

close() → None[原始碼]

關閉 Resolver，釋放所有已使用的資源。

3.1 版本新增。

class tornado.netutil.DefaultExecutorResolver(*args: Any, **kwargs: Any)[原始碼]

使用 IOLoop.run_in_executor 的解析器實作。

5.0 版本新增。

自 6.2 版本起已棄用：請改用 DefaultLoopResolver。

class tornado.netutil.DefaultLoopResolver(*args: Any, **kwargs: Any)[原始碼]

使用 asyncio.loop.getaddrinfo 的解析器實作。

class tornado.netutil.ExecutorResolver(*args: Any, **kwargs: Any)[原始碼]

使用 concurrent.futures.Executor 的解析器實作。

當您需要額外控制所使用的執行器時，請使用此項來取代 ThreadedResolver。

除非 close_resolver=False，否則執行器將在解析器關閉時關閉；如果您想在其他地方重複使用相同的執行器，請使用此選項。

變更於 5.0 版: 已移除 io_loop 參數（自 4.1 版起已棄用）。

自 5.0 版本起已棄用：現在預設的 Resolver 使用 asyncio.loop.getaddrinfo；請改用此選項，而不是這個類別。

class tornado.netutil.BlockingResolver(*args: Any, **kwargs: Any)[原始碼]

預設的 Resolver 實作，使用 socket.getaddrinfo。

雖然回呼函數在下一次 IOLoop 迭代之前不會執行，但在解析期間 IOLoop 將會被阻塞。

自 5.0 版本起已棄用：預設的 Resolver 現在使用 IOLoop.run_in_executor；請改用該方法，而非此類別。

class tornado.netutil.ThreadedResolver(*args: Any, **kwargs: Any)[原始碼]

多執行緒非阻塞 Resolver 實作。

需要安裝 concurrent.futures 套件（Python 3.2 以後的標準函式庫中提供，較舊版本可使用 pip install futures 安裝）。

執行緒池大小可以使用以下方式配置

Resolver.configure('tornado.netutil.ThreadedResolver',
                   num_threads=10)

在 3.1 版本中變更：所有 ThreadedResolvers 共用一個執行緒池，其大小由第一個建立的執行緒池設定。

自 5.0 版本起已棄用：預設的 Resolver 現在使用 IOLoop.run_in_executor；請改用該方法，而非此類別。

class tornado.netutil.OverrideResolver(*args: Any, **kwargs: Any)[原始碼]

用覆寫的對應包裝解析器。

這可用於進行本機 DNS 變更（例如用於測試），而無需修改系統範圍的設定。

該對應可以使用三種格式

{
    # Hostname to host or ip
    "example.com": "127.0.1.1",

    # Host+port to host+port
    ("login.example.com", 443): ("localhost", 1443),

    # Host+port+address family to host+port
    ("login.example.com", 443, socket.AF_INET6): ("::1", 1443),
}

在 5.0 版本中變更：新增對主機-埠-族系三元組的支援。

tornado.netutil.ssl_options_to_context(ssl_options: Union[Dict[str, Any], SSLContext], server_side: Optional[bool] = None) → SSLContext[原始碼]

嘗試將 ssl_options 字典轉換為 SSLContext 物件。

ssl_options 字典包含要傳遞給 ssl.SSLContext.wrap_socket 的關鍵字。在 Python 2.7.9+ 中，可以使用 ssl.SSLContext 物件。此函式會將字典形式轉換為其 SSLContext 對等形式，並可在接受兩種形式的元件需要升級到 SSLContext 版本以使用 SNI 或 NPN 等功能時使用。

在 6.2 版本中變更：新增 server_side 引數。在 Python 3.10 上省略此引數將導致 DeprecationWarning。

tornado.netutil.ssl_wrap_socket(socket: socket, ssl_options: Union[Dict[str, Any], SSLContext], server_hostname: Optional[str] = None, server_side: Optional[bool] = None, **kwargs: Any) → SSLSocket[原始碼]

傳回一個包裝指定 socket 的 ssl.SSLSocket。

ssl_options 可以是 ssl.SSLContext 物件或字典（如 ssl_options_to_context 所接受）。其他關鍵字引數會傳遞給 ssl.SSLContext.wrap_socket。

在 6.2 版本中變更：新增 server_side 引數。在 Python 3.10 上省略此引數將導致 DeprecationWarning。