`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は読み取られたデータ（またはwrite()の場合はNone）で解決されます。保留中のすべてのAwaitableは、ストリームが閉じられたときに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][ソース]¶

このストリームに指定されたデータを非同期的に書き込みます。

このメソッドは、書き込みが完了したときに（Noneの結果で）解決されるFutureを返します。

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 が true の場合、データは返せるバイト数が存在したらすぐに返されます（ただし、num_bytes を超えることはありません）。

バージョン 4.0 で変更: partial 引数が追加されました。コールバック引数はオプションになり、省略した場合は Future が返されるようになりました。

バージョン 6.0 で変更: callback および streaming_callback 引数が削除されました。代わりに、返された Future を使用してください（streaming_callback の場合は partial=True を使用）。

BaseIOStream.read_into(buf: bytearray, partial: bool = False) → Awaitable[int][ソース]¶

指定されたバイト数を非同期的に読み込みます。

buf は、データが読み込まれる書き込み可能なバッファでなければなりません。

partial が true の場合、コールバックはバイトが読み込まれるとすぐに実行されます。それ以外の場合、buf が読み込まれたデータで完全に満たされたときに実行されます。

バージョン 5.0 で新規追加。

バージョン 6.0 で変更: callback引数が削除されました。代わりに返されたFutureを使用してください。

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

指定されたデリミタが見つかるまで非同期的に読み込みます。

結果には、デリミタを含む読み込まれたすべてのデータが含まれます。

max_bytes が None でない場合、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][ソース]¶

指定された正規表現に一致するまで非同期的に読み込みます。

結果には、正規表現に一致するデータと、その前にあるものがすべて含まれます。

max_bytes が None でない場合、max_bytes バイトより多く読み込まれても正規表現が満たされない場合は接続が閉じられます。

バージョン 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 を使用してください（streaming_callback の場合は read_bytes と partial=True を使用）。

BaseIOStream.close(exc_info: Union[None, bool, BaseException, Tuple[Optional[Type[BaseException]], Optional[BaseException], Optional[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[ソース]¶

このストリームの no-delay フラグを設定します。

デフォルトでは、TCP ストリームに書き込まれるデータは、帯域幅を最大限に効率的に使用するために (Nagle のアルゴリズムに従って) 一時的に保持される場合があります。no-delay フラグは、たとえ追加の帯域幅を消費することになったとしても、できるだけ早くデータを書き込むように要求します。

このフラグは現在、TCP ベースの IOStreams に対してのみ定義されています。

バージョン 3.1 で新規追加。

サブクラスのメソッド¶

BaseIOStream.fileno() → Union[int, _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 または同等のものを返した場合) は None を返し、EOF 時はゼロを返します。

バージョン 5.0 で変更: インターフェースが再設計され、新しく割り当てられたオブジェクトではなく、バッファーを受け取り、バイト数を返すようになりました。

BaseIOStream.get_fd_error() → Optional[Exception][ソース]¶

基盤となるファイルのエラーに関する情報を返します。

このメソッドは、IOLoopがファイル記述子でエラーを通知した後に呼び出され、追加情報を含むException（socket.errorなど）を返すか、そのような情報がない場合はNoneを返す必要があります。

実装¶

class tornado.iostream.IOStream(socket: socket, *args: Any, **kwargs: Any)[ソース]¶

ソケットベースのIOStreamの実装です。

このクラスは、BaseIOStreamの読み取りおよび書き込みメソッドと、connectメソッドをサポートします。

socketパラメーターは、接続済みでも未接続でも構いません。サーバー操作の場合、ソケットはsocket.acceptを呼び出した結果です。クライアント操作の場合、ソケットはsocket.socketで作成され、IOStreamに渡す前に接続されているか、IOStream.connectで接続されているかのいずれかです。

このクラスを使用した非常に単純な（そして壊れた）HTTPクライアント

import socket
import tornado

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__':
    asyncio.run(main())

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

ソケットをリモートアドレスに非ブロッキングで接続します。

コンストラクターに渡されたソケットが以前に接続されていない場合にのみ呼び出すことができます。addressパラメーターは、IOStreamコンストラクターに渡されるソケットのタイプに対するsocket.connectと同じ形式です。たとえば、(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], SSLContext]] = None, server_hostname: Optional[str] = None) → Awaitable[SSLIOStream][ソース]¶

このIOStreamをSSLIOStreamに変換します。

これにより、クリアテキストモードで始まり、初期ネゴシエーション後（SMTPおよびIMAPのSTARTTLS拡張など）にSSLに切り替わるプロトコルが有効になります。

このメソッドは、ストリームで未処理の読み取りまたは書き込みがある場合、またはIOStreamのバッファーにデータがある場合（オペレーティングシステムのソケットバッファー内のデータは許可されています）は使用できません。つまり、通常は最後のクリアテキストデータを読み書きした直後に使用する必要があります。また、接続後、読み取りまたは書き込みを行う前にすぐに使用することもできます。

ssl_options引数は、ssl.SSLContextオブジェクト、またはssl.SSLContext.wrap_socket関数のキーワード引数の辞書のいずれかです。server_hostname引数は、ssl_optionsで無効にされていない限り、証明書の検証に使用されます。

このメソッドは、結果が新しいSSLIOStreamであるFutureを返します。このメソッドが呼び出された後、元のストリームでの他の操作は未定義です。

このストリームでクローズコールバックが定義されている場合、新しいストリームに転送されます。

バージョン 4.0 で追加.

バージョン 4.2 で変更: SSL証明書はデフォルトで検証されるようになりました。無効にするには、ssl_options=dict(cert_reqs=ssl.CERT_NONE) を渡すか、適切に設定された (Python v3.12)のssl.SSLContext を使用してください。

class tornado.iostream.SSLIOStream(*args: (Python v3.12)のAny, **kwargs: (Python v3.12)のAny)[ソース]¶

ノンブロッキングSSLソケットへの書き込みと読み取りを行うためのユーティリティクラスです。

コンストラクタに渡されたソケットがすでに接続されている場合は、以下のようにラップする必要があります。

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

SSLIOStream を構築する前にラップします。未接続のソケットは、IOStream.connect が完了したときにラップされます。

ssl_options キーワード引数は、(Python v3.12)のssl.SSLContext オブジェクトか、(Python v3.12)のssl.SSLContext.wrap_socket のキーワード引数の辞書である可能性があります。

wait_for_handshake() → Future[SSLIOStream][ソース]¶

初期SSLハンドシェイクが完了するのを待ちます。

callback が指定された場合、ハンドシェイクが完了すると引数なしで呼び出されます。それ以外の場合、このメソッドは、ハンドシェイク完了後にストリーム自体に解決される Future を返します。

ハンドシェイクが完了すると、ピアの証明書やNPN/ALPN選択などの情報が self.socket でアクセスできます。

このメソッドは、サーバー側のストリームで使用するか、IOStream.start_tls を使用した後に使用することを目的としています。IOStream.connect (すでにハンドシェイクの完了を待機している) では使用しないでください。ストリームごとに一度だけ呼び出すことができます。

バージョン 4.2 で新規追加。

バージョン 6.0 で変更: callback引数が削除されました。代わりに返されたFutureを使用してください。

class tornado.iostream.PipeIOStream(fd: (Python v3.12)のint, *args: (Python v3.12)のAny, **kwargs: (Python v3.12)のAny)[ソース]¶

パイプベースの IOStream の実装です。

コンストラクタは、オープンファイルオブジェクトではなく、整数ファイルディスクリプタ (たとえば、(Python v3.12)のos.pipe によって返されるものなど) を受け取ります。パイプは一般に一方向であるため、PipeIOStream は読み取りまたは書き込みに使用できますが、両方には使用できません。

PipeIOStream は、Unixベースのプラットフォームでのみ利用可能です。

例外¶

exception tornado.iostream.StreamBufferFullError[ソース]¶: バッファが満杯のときに IOStream メソッドによって発生する例外です。

exception tornado.iostream.StreamClosedError(real_error: (Python v3.12)のOptional[(Python v3.12)のBaseException] = None)[ソース]¶

ストリームが閉じられたときに IOStream メソッドによって発生する例外です。

ストリームの他のコールバックの *後* (バッファリングされたデータを処理できるようにするため) にクローズコールバックが実行されるようにスケジュールされているため、クローズコールバックが表示される前にこのエラーが表示される場合があります。

real_error 属性には、ストリームを閉じる原因となった基になるエラー (存在する場合) が含まれています。

バージョン 4.3 で変更: real_error 属性を追加しました。

exception tornado.iostream.UnsatisfiableReadError[ソース]¶

読み取りを満足させることができない場合に発生する例外です。

max_bytes 引数付きで read_until および read_until_regex によって発生します。

tornado.iostream — ノンブロッキングソケットの便利なラッパー¶

基底クラス¶

メインインターフェース¶

サブクラスのメソッド¶

実装¶

例外¶

`tornado.iostream` — ノンブロッキングソケットの便利なラッパー¶