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 将通过读取数据来解决（或 None 对于 write() ）所有杰出 Awaitables 将解决 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 解决（结果是 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 是真的，一旦我们有任何字节要返回，就返回数据（但不会超过 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 如果为真，则在读取任何字节后立即运行回调。否则，当 buf 已完全填充了读取数据。

5.0 新版功能.

在 6.0 版更改: 这个 callback 参数已删除。使用返回的 Future 相反。

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

异步读取，直到找到给定的分隔符。

结果包括所有读取的数据，包括分隔符。

如果 max_bytes 不是“无”，如果超过 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]

异步读取，直到我们匹配给定的regex。

结果包括与regex匹配的数据以及之前的所有数据。

如果 max_bytes 不是“无”，如果超过 max_bytes 已读取个字节，但不满足regex。

在 4.0 版更改: 增加了 max_bytes 参数。这个 callback 参数现在是可选的，并且 Future 如果省略，则返回。

在 6.0 版更改: 这个 callback 参数已删除。使用返回的 Future 相反。

BaseIOStream.read_until_close() → Awaitable[bytes]

异步读取套接字中的所有数据，直到它关闭为止。

这将缓冲所有可用数据，直到 max_buffer_size 达到。如果需要流量控制或取消，请使用 read_bytes(partial=True) 相反。

在 4.0 版更改: 回调参数现在是可选的，并且 Future 如果省略，则返回。

在 6.0 版更改: 这个 callback 和 streaming_callback 参数已删除。使用返回的 Future （和 read_bytes 具有 partial=True 对于 streaming_callback 相反。

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

关闭此流。

如果 exc_info 是真的，设置 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, tornado.ioloop._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) 字节，存储在缓冲区中。返回读取的字节数。如果没有要读取的内容（套接字返回 EWOULDBLOCK 或等效物），在EOF上为零。

在 5.0 版更改: 重新设计的接口接受缓冲区并返回大量字节，而不是新分配的对象。

BaseIOStream.get_fd_error() → Optional[Exception]

返回有关基础文件中任何错误的信息。

此方法是在 IOLoop 已在文件描述符上发出错误信号，应返回异常（例如 socket.error 附加信息，如果没有此类信息，则不提供。

启动位置

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

基于套接字的 IOStream 实施。

此类支持 BaseIOStream 加一 connect 方法。

这个 socket 参数可以是连接的，也可以是未连接的。对于服务器操作，套接字是调用 socket.accept . 对于客户端操作，使用创建套接字 socket.socket ，并且可以在将其传递给 IOStream 或与 IOStream.connect .

使用此类的一个非常简单（且已损坏）的HTTP客户端：

import tornado.ioloop
import tornado.iostream
import socket

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__':
    tornado.ioloop.IOLoop.current().run_sync(main)
    s = socket.socket(socket.AF_INET, socket.SOCK_STREAM, 0)
    stream = tornado.iostream.IOStream(s)
    stream.connect(("friendfeed.com", 80), send_request)
    tornado.ioloop.IOLoop.current().start()

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

将套接字连接到远程地址而不阻塞。

仅当传递给构造函数的套接字以前未连接时才能调用。地址参数的格式与for相同 socket.connect 对于传递给iostream构造函数的套接字类型，例如 (ip, port) 元组。此处接受主机名，但将同步解析并阻止IOLoop。如果您有主机名而不是IP地址，则 TCPClient 建议使用类，而不是直接调用此方法。 TCPClient 将执行异步DNS解析并处理IPv4和IPv6。

如果 callback 如果未指定，则在连接完成时将不带参数调用它；如果未指定，则此方法返回 Future （成功连接后的结果将是流本身）。

在SSL模式下， server_hostname 参数将用于证书验证（除非在 ssl_options ）和sni（如果支持；需要python 2.7.9+）。

注意打电话是安全的 IOStream.write 当连接挂起时，在这种情况下，数据将在连接就绪后立即写入。打电话 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], ssl.SSLContext]] = None, server_hostname: Optional[str] = None) → Awaitable[tornado.iostream.SSLIOStream]

转换此 IOStream 对 SSLIOStream .

这将启用以明文模式开始并在某些初始协商（例如 STARTTLS 对SMTP和IMAP的扩展）。

如果流上有未完成的读或写操作，或者iostream的缓冲区中有任何数据（操作系统的套接字缓冲区中允许有数据），则不能使用此方法。这意味着它通常必须在读取或写入最后一个明文数据后立即使用。它还可以在连接之后、任何读或写之前立即使用。

这个 ssl_options 参数可以是 ssl.SSLContext 对象或关键字参数字典 ssl.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套接字的实用程序类。

如果传递给构造函数的套接字已连接，则应使用以下内容进行包装：

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

在构造 SSLIOStream . 未连接的插座将在 IOStream.connect 完成了。

这个 ssl_options 关键字参数可以是 ssl.SSLContext 对象或关键字字典参数 ssl.wrap_socket

wait_for_handshake() → Future[SSLIOStream]

等待初始SSL握手完成。

如果A callback 如果给定，则在握手完成后将不带参数调用它；否则，此方法将返回 Future 它将在握手完成后解析为流本身。

一旦握手完成，就可以在上访问对等方的证书和NPN/ALPN选择等信息。 self.socket .

此方法用于服务器端流或在使用之后 IOStream.start_tls ；不应与 IOStream.connect （已经等待握手完成）。每个流只能调用一次。

4.2 新版功能.

在 6.0 版更改: 这个 callback 参数已删除。使用返回的 Future 相反。

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

基于管道 IOStream 实施。

构造函数接受一个整数文件描述符（例如 os.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 参数。