tornado.iostream — Convenient wrappers for non-blocking sockets

实用程序类,用于写入和读取非阻塞文件和套接字.

Contents:

Base class

class tornado.iostream.BaseIOStream(max_buffer_size: int = None, read_chunk_size: int = None, max_write_buffer_size: int = None)[source]

写入非阻塞文件或套接字或从中读取的实用程序类.

我们支持无阻塞write()read_*()方法系列. 操作完成后, Awaitable将使用读取的数据进行解析(对于write()则为None ). 所有优秀的Awaitables将与解决StreamClosedError时,流关闭; BaseIOStream.set_close_callback也可以用于通知已关闭的流.

当流由于错误而关闭时,IOStream的error属性包含异常对象.

子类必须实现filenoclose_fdwrite_to_fdread_from_fd和可选的get_fd_error .

BaseIOStream constructor.

Parameters
  • max_buffer_size –要缓冲的最大传入数据量; 默认为100MB.

  • read_chunk_size – Amount of data to read at one time from the underlying transport; defaults to 64KB.

  • max_write_buffer_size –传出缓冲区的数据量; 默认为无限制.

在版本4.0中更改:添加max_write_buffer_size参数. 将默认的read_chunk_size更改为64KB.

在5.0版中进行了更改: io_loop参数(从4.1版弃用)已被删除.

Main interface

BaseIOStream.write(data: Union[bytes, memoryview]) → Future[None][source]

异步将给定数据写入此流.

此方法返回一个Future ,在完成写入后解析(结果为None ).

data参数的类型可以为bytesmemoryview .

在版本4.0中更改:如果未提供回调,则现在返回Future .

在版本4.5中进行了更改:添加了对memoryview参数的支持.

在版本6.0中更改: callback参数已删除. 请改用返回的Future .

BaseIOStream.read_bytes(num_bytes: int, partial: bool = False) → Awaitable[bytes][source]

异步读取多个字节.

如果partial为true,则在我们有任何字节要返回时(但绝不超过num_bytes )将立即返回数据.

在版本4.0中更改:添加了partial参数. 现在,回调参数是可选的,如果省略,则将返回Future .

在版本6.0中进行了更改: callbackstreaming_callback参数已被删除. 改用返回的Future (并且对于streaming_callback ,为partial=True ).

BaseIOStream.read_into(buf: bytearray, partial: bool = False) → Awaitable[int][source]

异步读取多个字节.

buf必须是一个可写缓冲区,将数据读取到该缓冲区中.

如果partial为true,则在读取任何字节后立即运行回调. 否则,当buf已完全填充读取数据时,它将运行.

5.0版中的新功能.

在版本6.0中更改: callback参数已删除. 请改用返回的Future .

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

异步阅读,直到找到给定的定界符.

结果包括读取的所有数据,包括定界符.

如果max_bytes不为None,则如果读取的max_bytes个字节以上并且找不到定界符,则连接将关闭.

在版本4.0中更改:添加了max_bytes参数. 现在, callback参数是可选的,如果省略,则将返回Future .

在版本6.0中更改: callback参数已删除. 请改用返回的Future .

BaseIOStream.read_until_regex(regex: bytes, max_bytes: int = None) → Awaitable[bytes][source]

异步阅读,直到我们匹配了给定的正则表达式.

结果包括与正则表达式以及它之前的所有内容匹配的数据.

如果max_bytes不为None,则如果读取的max_bytes个字节以上并且不满足正则表达式,则连接将关闭.

在版本4.0中更改:添加了max_bytes参数. 现在, callback参数是可选的,如果省略,则将返回Future .

在版本6.0中更改: callback参数已删除. 请改用返回的Future .

BaseIOStream.read_until_close() → Awaitable[bytes][source]

从套接字异步读取所有数据,直到关闭为止.

这将缓冲所有可用数据,直到达到max_buffer_size . 如果需要流量控制或取消,请使用带有read_bytes(partial=True)的循环.

在版本4.0中更改:回调参数现在是可选的,如果省略,则将返回Future .

在版本6.0中进行了更改: callbackstreaming_callback参数已被删除. 使用返回的Future (和read_bytespartial=Truestreaming_callback )来代替.

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

关闭此流.

If exc_info is true, set the error attribute to the current exception from sys.exc_info (or if exc_info is a tuple, use that instead of sys.exc_info).

BaseIOStream.set_close_callback(callback: Optional[Callable[[], None]]) → None[source]

流关闭时调用给定的回调.

对于使用Future接口的应用程序,这基本上不是必需的. 当流关闭时,所有未完成的Futures都将使用StreamClosedError解决. 但是,它仍然可以用作在没有其他读取或写入进行时发信号通知流已关闭的方式.

与其他基于回调的接口不同,在Tornado 6.0中并未删除set_close_callback .

BaseIOStream.closed() → bool[source]

如果流已关闭,则返回True .

BaseIOStream.reading() → bool[source]

Returns True if we are currently reading from the stream.

BaseIOStream.writing() → bool[source]

如果当前正在写入流,则返回True .

BaseIOStream.set_nodelay(value: bool) → None[source]

设置此流的无延迟标志.

默认情况下,写入TCP流的数据可能会保留一段时间,以最有效地利用带宽(根据Nagle的算法). 无延迟标志要求尽快写入数据,即使这样做会消耗额外的带宽.

当前仅针对基于TCP的IOStreams定义此标志.

3.1版中的新功能.

Methods for subclasses

BaseIOStream.fileno() → Union[int, tornado.ioloop._Selectable][source]

返回此流的文件描述符.

BaseIOStream.close_fd() → None[source]

关闭此流基础的文件.

close_fdBaseIOStream ,不应在其他地方调用; 其他用户则应致电close .

BaseIOStream.write_to_fd(data: memoryview) → int[source]

尝试将data写入基础文件.

Returns the number of bytes written.

BaseIOStream.read_from_fd(buf: Union[bytearray, memoryview]) → Optional[int][source]

尝试从基础文件读取.

最多读取len(buf)个字节,并将其存储在缓冲区中. 返回读取的字节数. 如果没有要读取的内容(套接字返回EWOULDBLOCK或等效值),则返回EWOULDBLOCK ,而在EOF上返回零.

在版本5.0中进行了更改:接口经过重新设计,可以使用缓冲区并返回一定数量的字节,而不是新分配的对象.

BaseIOStream.get_fd_error() → Optional[Exception][source]

返回有关基础文件上任何错误的信息.

IOLoop发出文件描述符错误信号后,将调用此方法,并且应返回Exception(例如具有附加信息的socket.error ;如果没有可用的此类信息,则返回None).

Implementations

class tornado.iostream.IOStream(socket: socket.socket, *args, **kwargs)[source]

Socket-based IOStream implementation.

此类支持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: tuple, server_hostname: str = None) → Future[_IOStreamType][source]

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

仅当传递给构造函数的套接字先前未连接时才可以调用. 对于传递给IOStream构造函数的套接字类型,例如(ip, port)元组(ip, port) address参数的格式与socket.connect格式相同. 主机名在这里被接受,但是将被同步解析并阻止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: Union[Dict[str, Any], ssl.SSLContext] = None, server_hostname: str = None) → Awaitable[tornado.iostream.SSLIOStream][source]

Convert this IOStream to an SSLIOStream.

这将启用以纯文本模式开始并在经过一些初始协商后切换到SSL的协议(例如SMTP和IMAP的STARTTLS扩展).

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

ssl_options参数可以是ssl.SSLContext对象,也可以是ssl.wrap_socket函数的关键字参数字典. 除非在ssl_options禁用了server_hostname参数,否则它将用于证书验证.

此方法返回一个Future其结果是新的SSLIOStream . 调用此方法后,原始流上的任何其他操作均未定义.

如果在此流上定义了关闭回调,它将被转移到新流.

版本4.0中的新功能.

在4.2版中进行了更改:默认情况下,SSL证书已通过验证; 通过ssl_options=dict(cert_reqs=ssl.CERT_NONE)或适当配置的ssl.SSLContext来禁用.

class tornado.iostream.SSLIOStream(*args, **kwargs)[source]

实用程序类,用于写入非阻塞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][source]

等待初始SSL握手完成.

如果给出了callback ,则握手完成后将不加任何参数地调用它. 否则,此方法返回一个Future ,它将在握手完成后解析为流本身.

一旦握手完成,就可以在self.socket上访问诸如对等方的证书和NPN / ALPN选择之self.socket .

此方法旨在用于服务器端流或使用IOStream.start_tls ; 不应将其与IOStream.connect (已经等待握手完成)一起使用. 每个流只能调用一次.

4.2版中的新功能.

在版本6.0中更改: callback参数已删除. 请改用返回的Future .

class tornado.iostream.PipeIOStream(fd: int, *args, **kwargs)[source]

Pipe-based IOStream implementation.

构造函数采用整数文件描述符(例如os.pipe返回的描述符),而不是打开文件对象. 管道通常是单向的,因此PipeIOStream可用于读取或写入,但不能同时用于两者.

Exceptions

exception tornado.iostream.StreamBufferFullError[source]

缓冲区已满时, IOStream方法引发的异常.

exception tornado.iostream.StreamClosedError(real_error: BaseException = None)[source]

当流关闭时, IOStream方法引发的异常.

请注意,关闭回调计划在流上的其他回调之后运行(以允许处理缓冲的数据),因此在看到关闭回调之前,您可能会看到此错误.

real_error属性包含导致流关闭(如果有)的潜在错误.

在版本4.3中进行了更改:添加了real_error属性.

exception tornado.iostream.UnsatisfiableReadError[source]

无法满足读取条件时引发异常.

read_untilread_until_regex使用max_bytes参数read_until_regex .