ループの開始と停止¶

loop.run_until_complete(future)¶

フューチャー (Future インスタンス) が完了するまで実行します。

引数がコルーチンオブジェクト の場合、暗黙のうちにasyncio.Task として実行されるようにスケジュールされます。

Future の結果を返すか、例外を送出します。

loop.run_forever()¶

stop() が呼び出されるまでイベントループを実行します。

Ifstop() is called beforerun_forever() is called,the loop will poll the I/O selector once with a timeout of zero,run all callbacks scheduled in response to I/O events (andthose that were already scheduled), and then exit.

run_forever() メソッドを実行中にstop() メソッドが呼び出された場合、イベントループは現在処理されているすべてのコールバックを実行してから終了します。 この場合、コールバックにより新たにスケジュールされるコールバックは実行されないことに注意してください; これら新たにスケジュールされたコールバックは、次にrun_forever() またはrun_until_complete() が呼び出されたときに実行されます。

loop.stop()¶

イベントループを停止します。

loop.is_running()¶

イベントループが現在実行中の場合True を返します。

loop.is_closed()¶

イベントループが閉じられていた場合True を返します。

loop.close()¶

イベントループをクローズします。

この関数が呼び出される時点で、イベントループが実行中であってはいけません。保留中のコールバックはすべて破棄されます。

このメソッドは全てのキューをクリアし、エグゼキューターが実行完了するのを待たずにシャットダウンします。

このメソッドはべき等 (何回実行しても結果は同じ) であり取り消せません。イベントループがクローズされた後、他のいかなるメソッドも呼び出すべきではありません。

asyncloop.shutdown_asyncgens()¶

Schedule all currently openasynchronous generator objects toclose with anaclose() call. After calling this method,the event loop will issue a warning if a new asynchronous generatoris iterated. This should be used to reliably finalize all scheduledasynchronous generators.

asyncio.run() を使った場合はこの関数を呼び出す必要はありません。

以下はプログラム例です:

try:loop.run_forever()finally:loop.run_until_complete(loop.shutdown_asyncgens())loop.close()

Added in version 3.6.

asyncloop.shutdown_default_executor(timeout=None)¶

Schedule the closure of the default executor and wait for it to join all ofthe threads in theThreadPoolExecutor.Once this method has been called,using the default executor withloop.run_in_executor()will raise aRuntimeError.

Thetimeout parameter specifies the amount of time(infloat seconds) the executor will be given to finish joining.With the default,None,the executor is allowed an unlimited amount of time.

If thetimeout is reached, aRuntimeWarning is emittedand the default executor is terminatedwithout waiting for its threads to finish joining.

注釈

Do not call this method when usingasyncio.run(),as the latter handles default executor shutdown automatically.

Added in version 3.9.

バージョン 3.12 で変更:Added thetimeout parameter.

コールバックのスケジューリング¶

loop.call_soon(callback,*args,context=None)¶

イベントループの次のイテレーションでcallback に指定したコールバック (callback) をargs 引数で呼び出すようにスケジュールします。

Return an instance ofasyncio.Handle,which can be used later to cancel the callback.

コールバックは登録された順に呼び出されます。各コールバックは厳密に1回だけ呼び出されます。

The optional keyword-onlycontext argument specifies acustomcontextvars.Context for thecallback to run in.Callbacks use the current context when nocontext is provided.

Unlikecall_soon_threadsafe(), this method is not thread-safe.

loop.call_soon_threadsafe(callback,*args,context=None)¶

A thread-safe variant ofcall_soon(). When scheduling callbacks fromanother thread, this functionmust be used, sincecall_soon() is notthread-safe.

This function is safe to be called from a reentrant context or signal handler,however, it is not safe or fruitful to use the returned handle in such contexts.

すでにクローズされたイベントループに対してこのメソッドが呼び出された場合RuntimeError 例外を送出します。これはメインアプリケーションが終了しているにもかかわらずセカンダリスレッドでメソッドが呼び出されるといった場合に起こりえます。

このドキュメントの並行処理とマルチスレッド処理 節を参照してください。

バージョン 3.7 で変更:キーワード引数context が追加されました。詳細はPEP 567 を参照してください。

# will schedule "print("Hello", flush=True)"loop.call_soon(functools.partial(print,"Hello",flush=True))

遅延コールバックのスケジューリング¶

イベントループは、コールバック関数を未来のある時点で呼び出されるようにスケジュールする仕組みを提供します。イベントループは時刻が戻らない単調な時計 (monotonic clock) を使って時刻を追跡します。

loop.call_later(delay,callback,*args,context=None)¶

delay 秒経過後にコールバック関数callback を呼び出すようにスケジュールします。delay には整数または浮動小数点数を指定します。

asyncio.TimerHandle のインスタンスを返します。このインスタンスを使ってスケジュールしたコールバックをキャンセルすることができます。

callback は厳密に一度だけ呼び出されます。2つのコールバックが完全に同じ時間にスケジュールされた場合、呼び出しの順序は未定義です。

オプションの位置引数args はコールバックが呼び出されるときに位置引数として渡されます。キーワード引数を指定してコールバックを呼び出したい場合はfunctools.partial() を使用してください。

オプションのキーワード引数context を使って、コールバック*callback* を実行する際のコンテキストcontextvars.Context を設定することができます。コンテキストcontext が指定されない場合は現在のコンテキストが使われます。

バージョン 3.7 で変更:キーワード引数context が追加されました。詳細はPEP 567 を参照してください。

バージョン 3.8 で変更:Python 3.7 またはそれ以前のバージョンでは、デフォルトイベントループの実装を利用した場合に遅延時間delay が1日を超えることができませんでした。この問題は Python 3.8 で修正されました。

loop.call_at(when,callback,*args,context=None)¶

絶対値の時刻when (整数または浮動小数点数) にコールバックを呼び出すようにスケジュールします。loop.time() と同じ参照時刻を使用します。

このメソッドの振る舞いはcall_later() と同じです。

asyncio.TimerHandle のインスタンスを返します。このインスタンスを使ってスケジュールしたコールバックをキャンセルすることができます。

バージョン 3.7 で変更:キーワード引数context が追加されました。詳細はPEP 567 を参照してください。

バージョン 3.8 で変更:Python 3.7 またはそれ以前のバージョンでは、デフォルトイベントループの実装を利用した場合に現在の時刻とwhen との差が1日を超えることができませんでした。この問題は Python 3.8 で修正されました。

loop.time()¶

現在の時刻をfloat 値で返します。時刻はイベントループが内部で参照している時刻が戻らない単調な時計 (monotonic clock) に従います。

フューチャーとタスクの生成¶

loop.create_future()¶

イベントループに接続したasyncio.Future オブジェクトを生成します。

asyncio でフューチャーオブジェクトを作成するために推奨される方法です。このメソッドにより、サードパーティ製のイベントループがFutures クラスの(パフォーマンスや計測方法が優れた) 代替実装を提供することを可能にします。

Added in version 3.5.2.

loop.create_task(coro,*,name=None,context=None,**kwargs)¶

Schedule the execution ofcoroutinecoro.Return aTask object.

サードパーティのイベントループは相互運用のための自身のTask のサブクラスを使用できます。この場合、結果はTask のサブクラスになります。

The full function signature is largely the same as that of theTask constructor (or factory) - all of the keyword arguments tothis function are passed through to that interface, exceptname,orcontext if it isNone.

name 引数が指定され、値がNone でない場合、Task.set_name() メソッドによりname がタスクの名前として設定されます。

省略可能なキーワード引数context によって、coro を実行するためのカスタムのcontextvars.Context を指定できます。context が省略された場合、現在のコンテキストのコピーが作成されます。

バージョン 3.8 で変更:name パラメータを追加しました。

バージョン 3.11 で変更:context パラメータを追加しました。

バージョン 3.13.3 で変更:Addedkwargs which passes on arbitrary extra parameters, includingname andcontext.

バージョン 3.13.4 で変更:Rolled back the change that passes onname andcontext (if it is None),while still passing on other arbitrary keyword arguments (to avoid breaking backwards compatibility with 3.13.3).

loop.set_task_factory(factory)¶

loop.create_task() が使用するタスクファクトリーを設定します。

Iffactory isNone the default task factory will be set.Otherwise,factory must be acallable with the signature matching(loop,coro,**kwargs), whereloop is a reference to the activeevent loop, andcoro is a coroutine object. The callablemust pass on allkwargs, and return aasyncio.Task-compatible object.

バージョン 3.13.3 で変更:Required that allkwargs are passed on toasyncio.Task.

バージョン 3.13.4 で変更:name is no longer passed to task factories.context is no longer passedto task factories if it isNone.

loop.get_task_factory()¶

タスクファクトリを返します。デフォルトのタスクファクトリを使用中の場合はNone を返します。

ネットワーク接続の確立¶

asyncloop.create_connection(protocol_factory,host=None,port=None,*,ssl=None,family=0,proto=0,flags=0,sock=None,local_addr=None,server_hostname=None,ssl_handshake_timeout=None,ssl_shutdown_timeout=None,happy_eyeballs_delay=None,interleave=None,all_errors=False)¶

host とport で指定されたアドレスとのストリーミングトランスポート接続をオープンします。

The socket family can be eitherAF_INET orAF_INET6 depending onhost (or thefamilyargument, if provided).

The socket type will beSOCK_STREAM.

protocol_factory はasyncio プロトコル の実装を返す呼び出し可能オブジェクトでなければなりません。

このメソッドはバックグラウンドで接続の確立を試みます。成功した場合、メソッドは(transport,protocol) のペアを返します。

時系列での下層処理の概要は以下のとおりです:

1. 接続を確立し、その接続に対するトランスポート が生成されます。

2. protocol_factory が引数なしで呼び出され、ファクトリがプロトコル インスタンスを返すよう要求します。

3. プロトコルインスタンスがconnection_made() メソッドを呼び出すことにより、トランスポートと紐付けられます。

4. 成功すると(transport,protocol) タプルが返されます。

作成されたトランスポートは実装依存の双方向ストリームです。

その他の引数:

• ssl: 偽値以外が与えられた場合、SSL/TLS トランスポートが作成されます (デフォルトでは暗号化なしの TCP トランスポートが作成されます)。ssl がssl.SSLContext オブジェクトの場合、このコンテキストがトランスポートを作成するために使用されます;ssl がTrue の場合、ssl.create_default_context() が返すデフォルトのコンテキストが使われます。

  参考

  SSL/TLS セキュリティについての考察

• server_hostname は対象サーバーの証明書との一致を確認するためのホスト名を設定または上書きします。この引数はssl がNone でない場合のみ設定すべきです。デフォルトではhost に指定したサーバー名が使用されます。host が空の文字列の場合のデフォルト値は設定されていません。その場合、server_hostname を必ず指定してください。server_hostname も空の文字列の場合は、ホスト名の一致確認は行われません (これは深刻なセキュリティリスクであり、中間者攻撃を受ける可能性があります)。

• family,proto,flags は任意のアドレスファミリであり、host 解決のための getaddrinfo() 経由で渡されるプロトコルおよびフラグになります。このオプションが与えられた場合、これらはすべてsocket モジュール定数に従った整数でなければなりません。

• happy_eyeballs_delay が設定されると、この接続に対して Happy Eyeballs が有効化されます。設定する値は浮動小数点数であり、次の接続試行を開始する前に、現在の接続試行が完了するのを待つ時間を秒単位で表現します。この値はRFC 8305 で定義されている "接続試行遅延" に相当します。RFC で推奨されている実用的なデフォルト値は0.25 (250 ミリ秒) です。

• interleave はホスト名が複数の IP アドレスに名前解決される場合のアドレスの並べ替えを制御します。0 または未指定の場合並べ替えは行われず、getaddrinfo() が返す順番にしたがってアドレスへの接続を試行します。正の整数が指定されると、アドレスはアドレスファミリに応じてインターリーブされます。このとき、与えられた整数はRFC 8305 で定義される "最初のアドレスファミリカウント (First Address Family Count)" として解釈されます。デフォルト値は、happy_eyeballs_delay が指定されない場合は0 であり、指定された場合は1 です。

• sock を与える場合、トランスポートに使用される、既存の、かつ接続済のsocket.socket オブジェクトを指定します。sock を指定する場合、host、port、family、proto、flags、happy_eyeballs_delay、interleave およびlocal_addr のいずれも指定してはいけません。

  注釈

  Thesock argument transfers ownership of the socket to thetransport created. To close the socket, call the transport'sclose() method.

• local_addr を与える場合、ソケットをローカルにバインドするために使用する(local_host,local_port) タプルを指定します。local_host とlocal_port は、host およびport と同じくgetaddrinfo() を使ってルックアップされます。

• ssl_handshake_timeout は TLS ハンドシェイクが完了するまでの (TLS 接続のための) 待ち時間を秒単位で指定します。指定した待ち時間を超えると接続は中断します。None が与えられた場合はデフォルト値60.0 が使われます。

• ssl_shutdown_timeout is the time in seconds to wait for the SSL shutdownto complete before aborting the connection.30.0 seconds ifNone(default).

• all_errors determines what exceptions are raised when a connection cannotbe created. By default, only a singleException is raised: the firstexception if there is only one or all errors have same message, or a singleOSError with the error messages combined. Whenall_errors isTrue,anExceptionGroup will be raised containing all exceptions (even if thereis only one).

バージョン 3.5 で変更:ProactorEventLoop において SSL/TLS のサポートが追加されました。

バージョン 3.6 で変更:The socket optionsocket.TCP_NODELAY is set by defaultfor all TCP connections.

バージョン 3.7 で変更:Added thessl_handshake_timeout parameter.

バージョン 3.8 で変更:happy_eyeballs_delay とinterleave が追加されました。

Happy Eyeballs Algorithm: Success with Dual-Stack Hosts.When a server's IPv4 path and protocol are working, but the server'sIPv6 path and protocol are not working, a dual-stack clientapplication experiences significant connection delay compared to anIPv4-only client. This is undesirable because it causes thedual-stack client to have a worse user experience. This documentspecifies requirements for algorithms that reduce this user-visibledelay and provides an algorithm.

For more information:https://datatracker.ietf.org/doc/html/rfc6555

バージョン 3.11 で変更:ssl_shutdown_timeout パラメータが追加されました。

バージョン 3.12 で変更:all_errors が追加されました

参考

open_connection() 関数は高水準の代替 API です。この関数は(StreamReader,StreamWriter) のペアを返し、 async/await コードから直接使うことができます。

asyncloop.create_datagram_endpoint(protocol_factory,local_addr=None,remote_addr=None,*,family=0,proto=0,flags=0,reuse_port=None,allow_broadcast=None,sock=None)¶

データグラム接続 (UDP) を生成します。

The socket family can be eitherAF_INET,AF_INET6, orAF_UNIX,depending onhost (or thefamily argument, if provided).

The socket type will beSOCK_DGRAM.

protocol_factory はasyncio プロトコル の実装を返す呼び出し可能オブジェクトでなければなりません。

成功すると(transport,protocol) タプルが返されます。

その他の引数:

• local_addr が指定される場合、ソケットをローカルにバインドするための(local_host,local_port) のタプルを指定します。local_host とlocal_port はgetaddrinfo() メソッドを使用して検索されます。

• remote_addr が指定される場合、(remote_host,remote_por) のタプルで、ソケットをリモートアドレスに束縛するために使用されます。remote_host とremote_port はgetaddrinfo() を使用して検索されます。

• family,proto,flags は任意のアドレスファミリです。これらのファミリ、プロトコル、フラグは、host 解決のためgetaddrinfo() 経由でオプションで渡されます。これらのオプションを指定する場合、すべてsocket モジュール定数に従った整数でなければなりません。

• reuse_port tells the kernel to allow this endpoint to be bound to thesame port as other existing endpoints are bound to, so long as they allset this flag when being created. This option is not supported on Windowsand some Unixes. If thesocket.SO_REUSEPORT constant is notdefined then this capability is unsupported.

• allow_broadcast は、カーネルに、このエンドポイントがブロードキャストアドレスにメッセージを送信することを許可するように指示します。

• オプションのsock を指定することで、既存の、すでに接続されているsocket.socket をトランスポートで使用することができます。このオプションを使用する場合、local_addr とremote_addr は省略してください (None でなければなりません)。

  注釈

  Thesock argument transfers ownership of the socket to thetransport created. To close the socket, call the transport'sclose() method.

UDP echo クライアントプロトコル およびUDP echo サーバープロトコル の例を参照してください。

バージョン 3.4.4 で変更:Thefamily,proto,flags,reuse_address,reuse_port,allow_broadcast, andsock parameters were added.

バージョン 3.8 で変更:Windows サポートが追加されました。

バージョン 3.8.1 で変更:Thereuse_address parameter is no longer supported, as usingsocket.SO_REUSEADDRposes a significant security concern forUDP. Explicitly passingreuse_address=True will raise an exception.

SO_REUSEADDR を使って、同一の UDP ソケットアドレスに対して複数のプロセスが異なる UID でソケットを割り当てている場合、受信パケットは複数のソケット間にランダムに分散する可能性があります。

For supported platforms,reuse_port can be used as a replacement forsimilar functionality. Withreuse_port,socket.SO_REUSEPORTis used instead, which specificallyprevents processes with differing UIDs from assigning sockets to the samesocket address.

バージョン 3.11 で変更:Thereuse_address parameter, disabled since Python 3.8.1,3.7.6 and 3.6.10, has been entirely removed.

asyncloop.create_unix_connection(protocol_factory,path=None,*,ssl=None,sock=None,server_hostname=None,ssl_handshake_timeout=None,ssl_shutdown_timeout=None)¶

Unix 接続を生成します。

The socket family will beAF_UNIX; sockettype will beSOCK_STREAM.

成功すると(transport,protocol) タプルが返されます。

path は Unix ドメインソケット名で、sock パラメータが指定されない場合は必須です。 抽象 Unix ソケット、str、bytes、 andPath 形式でのパスがサポートされています。

このメソッドの引数についての詳細はloop.create_connection() メソッドのドキュメントを参照してください。

Availability: Unix.

バージョン 3.7 で変更:Added thessl_handshake_timeout parameter.Thepath parameter can now be apath-like object.

バージョン 3.11 で変更:ssl_shutdown_timeout パラメータが追加されました。

ネットワークサーバの生成¶

asyncloop.create_server(protocol_factory,host=None,port=None,*,family=socket.AF_UNSPEC,flags=socket.AI_PASSIVE,sock=None,backlog=100,ssl=None,reuse_address=None,reuse_port=None,keep_alive=None,ssl_handshake_timeout=None,ssl_shutdown_timeout=None,start_serving=True)¶

Create a TCP server (socket typeSOCK_STREAM) listeningonport of thehost address.

Server オブジェクトを返します。

引数:

• protocol_factory はasyncio プロトコル の実装を返す呼び出し可能オブジェクトでなければなりません。

• host パラメータはいくつかの方法で指定することができ、その値によってサーバーがどこをリッスンするかが決まります。

  • host が文字列の場合、 TCP サーバーはhost で指定した単一のネットワークインターフェースに束縛されます。

  • host が文字列のシーケンスである場合、 TCP サーバーはそのシーケンスで指定された全てのネットワークインターフェースに束縛されます。

  • host が空の文字列かNone の場合、すべてのインターフェースが想定され、複合的なソケットのリスト (通常は一つが IPv4、もう一つが IPv6) が返されます。

• Параметрport можна встановити, щоб вказати, який порт сервер повинен слухати. Якщо0 абоNone (за замовчуванням), буде вибрано випадковий невикористаний порт (зауважте, що якщоhost розпізнає кілька мережевих інтерфейсів, для кожного інтерфейсу буде вибрано окремий випадковий порт).

• family can be set to eithersocket.AF_INET orAF_INET6 to force the socket to use IPv4 or IPv6.If not set, thefamily will be determined from host name(defaults toAF_UNSPEC).

• flags はgetaddrinfo() のためのビットマスクになります。

• サーバーで既存のソケットオブジェクトを使用するために、オプションの引数sock にソケットオブジェクトを設定することができます。指定した場合、host とport を指定してはいけません。

  注釈

  Thesock argument transfers ownership of the socket to theserver created. To close the socket, call the server'sclose() method.

• backlog はlisten() に渡される、キューに入るコネクションの最大数になります (デフォルトは 100)。

• 確立した接続の上で TLS を有効化するために、ssl にSSLContext のインスタンスを指定することができます。

• reuse_address は、TIME_WAIT 状態にあるローカルソケットを、その状態が自然にタイムアウトするのを待つことなく再利用するようカーネルに指示します（訳註: ソケットのオプション SO_REUSEADDR を使用します）。指定しない場合、UNIX では自動的にTrue が設定されます。

• reuse_port は、同じポートにバインドされた既存の端点すべてがこのフラグを設定して生成されている場合に限り、この端点を既存の端点と同じポートにバインドすることを許可するよう、カーネルに指示します（訳註: ソケットのオプション SO_REUSEPORT を使用します）。このオプションは、Windows ではサポートされていません。

• keep_alive set toTrue keeps connections active by enabling theperiodic transmission of messages.

バージョン 3.13 で変更:Added thekeep_alive parameter.

• ssl_handshake_timeout は TLS ハンドシェイクが完了するまでの (TLS サーバーのための) 待ち時間を秒単位で指定します。指定した待ち時間を超えると接続は中断します。None が与えられた場合はデフォルト値60.0 が使われます。

• ssl_shutdown_timeout is the time in seconds to wait for the SSL shutdownto complete before aborting the connection.30.0 seconds ifNone(default).

• start_serving がTrue に設定された場合 (これがデフォルトです)、 生成されたサーバーは即座に接続の受け付けを開始します。False が指定された場合、ユーザーは接続の受け付けを開始するためにServer.start_serving() またはServer.serve_forever() を待ち受け (await) る必要があります。

バージョン 3.5 で変更:ProactorEventLoop において SSL/TLS のサポートが追加されました。

バージョン 3.5.1 で変更:host パラメータに文字列のシーケンスを指定できるようになりました。

バージョン 3.6 で変更:Addedssl_handshake_timeout andstart_serving parameters.The socket optionsocket.TCP_NODELAY is set by defaultfor all TCP connections.

バージョン 3.11 で変更:ssl_shutdown_timeout パラメータが追加されました。

参考

start_server() 関数は高水準の代替 API です。この関数はStreamReader とStreamWriter のペアを返し、async/await コードから使うことができます。

asyncloop.create_unix_server(protocol_factory,path=None,*,sock=None,backlog=100,ssl=None,ssl_handshake_timeout=None,ssl_shutdown_timeout=None,start_serving=True,cleanup_socket=True)¶

Similar toloop.create_server() but works with theAF_UNIX socket family.

path は Unix ドメインソケット名で、sock パラメータが指定されない場合は必須です。 抽象 Unix ソケット、str、bytes、 andPath 形式でのパスがサポートされています。

Ifcleanup_socket is true then the Unix socket will automaticallybe removed from the filesystem when the server is closed, unless thesocket has been replaced after the server has been created.

このメソッドの引数についての詳細はloop.create_server() メソッドのドキュメントを参照してください。

Availability: Unix.

バージョン 3.7 で変更:Added thessl_handshake_timeout andstart_serving parameters.Thepath parameter can now be aPath object.

バージョン 3.11 で変更:ssl_shutdown_timeout パラメータが追加されました。

バージョン 3.13 で変更:Added thecleanup_socket parameter.

asyncloop.connect_accepted_socket(protocol_factory,sock,*,ssl=None,ssl_handshake_timeout=None,ssl_shutdown_timeout=None)¶

すでに確立した接続を transport と protocol のペアでラップします。

このメソッドは asyncio の範囲外で確立された接続を使うサーバーに対しても使えますが、その場合でも接続は asyncio を使って処理されます。

引数:

• protocol_factory はasyncio プロトコル の実装を返す呼び出し可能オブジェクトでなければなりません。

• sock はsocket.accept メソッドが返す既存のソケットオブジェクトです。

  注釈

  Thesock argument transfers ownership of the socket to thetransport created. To close the socket, call the transport'sclose() method.

• ssl にはSSLContext を指定できます。指定すると、受け付けたコネクション上での SSL を有効にします。

• ssl_handshake_timeout は SSL ハンドシェイクが完了するまでの (SSL 接続のための) 待ち時間を秒単位で指定します。None が与えられた場合はデフォルト値60.0 が使われます。

• ssl_shutdown_timeout is the time in seconds to wait for the SSL shutdownto complete before aborting the connection.30.0 seconds ifNone(default).

(transport,protocol) のペアを返します。

Added in version 3.5.3.

バージョン 3.7 で変更:Added thessl_handshake_timeout parameter.

バージョン 3.11 で変更:ssl_shutdown_timeout パラメータが追加されました。

ファイルの転送¶

asyncloop.sendfile(transport,file,offset=0,count=None,*,fallback=True)¶

transport を通じてfile を送信します。送信したデータの総バイト数を返します。

このメソッドは、もし利用可能であれば高性能なos.sendfile() を利用します。

file はバイナリモードでオープンされた通常のファイルオブジェクトでなければなりません。

offset はファイルの読み込み開始位置を指定します。count が指定された場合、ファイルの EOF までファイルを送信する代わりに、count で指定された総バイト数の分だけ送信します。ファイルオブジェクトが指し示す位置は、メソッドがエラーを送出した場合でも更新されます。この場合実際に送信されたバイト数はfile.tell() メソッドで取得することができます。

fallback をTrue に指定することで、 asyncio がプラットフォームが sendfile システムコールをサポートしていない場合 (たとえば Windows や Unix の SSL ソケットなど) に別の方法でファイルの読み込みと送信を行うようにすることができます。

システムがsendfile システムコールをサポートしておらず、かつfallback がFalse の場合、SendfileNotAvailableError 例外を送出します。

Added in version 3.7.

TLS へのアップグレード¶

asyncloop.start_tls(transport,protocol,sslcontext,*,server_side=False,server_hostname=None,ssl_handshake_timeout=None,ssl_shutdown_timeout=None)¶

既存のトランスポートベースの接続を TLS にアップグレードします。

Create a TLS coder/decoder instance and insert it between thetransportand theprotocol. The coder/decoder implements bothtransport-facingprotocol andprotocol-facing transport.

Return the created two-interface instance. Afterawait, theprotocolmust stop using the originaltransport and communicate with the returnedobject only because the coder cachesprotocol-side data and sporadicallyexchanges extra TLS session packets withtransport.

In some situations (e.g. when the passed transport is already closing) thismay returnNone.

引数:

• transport とprotocol には、create_server() やcreate_connection() が返すものと同等のインスタンスを指定します。

• sslcontext: 構成済みのSSLContext インスタンスです。

• (create_server() で生成されたような) サーバーサイドの接続をアップグレードする場合はserver_side にTrue を渡します。

• server_hostname: 対象のサーバーの証明書との照合に使われるホスト名を設定または上書きします。

• ssl_handshake_timeout は TLS ハンドシェイクが完了するまでの (TLS 接続のための) 待ち時間を秒単位で指定します。指定した待ち時間を超えると接続は中断します。None が与えられた場合はデフォルト値60.0 が使われます。

• ssl_shutdown_timeout is the time in seconds to wait for the SSL shutdownto complete before aborting the connection.30.0 seconds ifNone(default).

Added in version 3.7.

バージョン 3.11 で変更:ssl_shutdown_timeout パラメータが追加されました。

ファイル記述子の監視¶

loop.add_reader(fd,callback,*args)¶

ファイル記述子fd に対する読み込みが可能かどうかの監視を開始し、fd が読み込み可能になると、指定した引数でコールバックcallback を呼び出します。

Any preexisting callback registered forfd is cancelled and replaced bycallback.

loop.remove_reader(fd)¶

Stop monitoring thefd file descriptor for read availability. ReturnsTrue iffd was previously being monitored for reads.

loop.add_writer(fd,callback,*args)¶

ファイル記述子fd に対する書き込みが可能かどうかの監視を開始し、fd が書き込み可能になると、指定した引数でコールバックcallback を呼び出します。

Any preexisting callback registered forfd is cancelled and replaced bycallback.

コールバックcallback にキーワード引数を渡す 場合はfunctools.partial() を使ってください。

loop.remove_writer(fd)¶

Stop monitoring thefd file descriptor for write availability. ReturnsTrue iffd was previously being monitored for writes.

これらのメソッドに対する制限事項についてはプラットフォームのサポート状況 節も参照してください。

ソケットオブジェクトと直接やりとりする¶

一般に、loop.create_connection() やloop.create_server() のようなトランスポートベースの API を使ったプロトコルの実装はソケットと直接やり取りする実装に比べて高速です。しかしながら、パフォーマンスが重要でなく、直接socket オブジェクトとやりとりした方が便利なユースケースがいくつかあります。

asyncloop.sock_recv(sock,nbytes)¶

nbytes で指定したバイト数までのデータをソケットsock から受信します。 このメソッドはsocket.recv() の非同期版です。

受信したデータをバイトオブジェクトとして返します。

sock はノンブロッキングソケットでなければなりません。

バージョン 3.7 で変更:このメソッドは常にコルーチンメソッドとしてドキュメントに記載されてきましたが、 Python 3.7 以前のリリースではFuture オブジェクトを返していました。 Python 3.7 からはasyncdef メソッドになりました。

asyncloop.sock_recv_into(sock,buf)¶

ソケットsock からデータを受信してバッファbuf に格納します。ブロッキングコードのsocket.recv_into() メソッドをモデルとしています。

バッファに書き込んだデータのバイト数を返します。

sock はノンブロッキングソケットでなければなりません。

Added in version 3.7.

asyncloop.sock_recvfrom(sock,bufsize)¶

Receive a datagram of up tobufsize fromsock. Asynchronous version ofsocket.recvfrom().

Return a tuple of (received data, remote address).

sock はノンブロッキングソケットでなければなりません。

Added in version 3.11.

asyncloop.sock_recvfrom_into(sock,buf,nbytes=0)¶

Receive a datagram of up tonbytes fromsock intobuf.Asynchronous version ofsocket.recvfrom_into().

Return a tuple of (number of bytes received, remote address).

sock はノンブロッキングソケットでなければなりません。

Added in version 3.11.

asyncloop.sock_sendall(sock,data)¶

データdata をソケットsock に送信します。socket.sendall() メソッドの非同期版です。

このメソッドはdata をすべて送信し終えるか、またはエラーが起きるまでデータをソケットに送信し続けます。送信に成功した場合None を返します。エラーの場合は例外が送出されます。エラーとなった場合、接続の受信側で正しく処理されたデータの総量を特定する方法はありません。

sock はノンブロッキングソケットでなければなりません。

バージョン 3.7 で変更:このメソッドは常にコルーチンメソッドとしてドキュメントに記載されてきましたが、 Python 3.7 以前のリリースではFuture オブジェクトを返していました。 Python 3.7 からはasyncdef メソッドになりました。

asyncloop.sock_sendto(sock,data,address)¶

Send a datagram fromsock toaddress.Asynchronous version ofsocket.sendto().

Return the number of bytes sent.

sock はノンブロッキングソケットでなければなりません。

Added in version 3.11.

asyncloop.sock_connect(sock,address)¶

ソケットsock をアドレスaddress のリモートソケットに接続します。

socket.connect() の非同期版です。

sock はノンブロッキングソケットでなければなりません。

バージョン 3.5.2 で変更:address を名前解決する必要はなくなりました。sock_connect はsocket.inet_pton() を呼び出してaddress が解決済みかどうかを確認します。未解決の場合、address の名前解決にはloop.getaddrinfo() メソッドが使われます。

参考

loop.create_connection() およびasyncio.open_connection()。

asyncloop.sock_accept(sock)¶

接続を受け付けます。ブロッキングコールのsocket.accept() メソッドをモデルとしています。

ソケットはアドレスに束縛済みで、接続を listen 中である必要があります。戻り値は(conn,address) のペアで、conn は接続を通じてデータの送受信を行うための新しい ソケットオブジェクト、address は接続先の端点でソケットに束縛されているアドレスを示します。

sock はノンブロッキングソケットでなければなりません。

バージョン 3.7 で変更:このメソッドは常にコルーチンメソッドとしてドキュメントに記載されてきましたが、 Python 3.7 以前のリリースではFuture オブジェクトを返していました。 Python 3.7 からはasyncdef メソッドになりました。

参考

loop.create_server() およびstart_server()。

asyncloop.sock_sendfile(sock,file,offset=0,count=None,*,fallback=True)¶

ファイルを送信します。利用可能なら高性能なos.sendfile を使います。送信したデータの総バイト数を返します。

socket.sendfile() メソッドの非同期版です。

sock はsocket.SOCK_STREAM タイプのノンブロッキングなsocket でなければなりません。

file はバイナリモードでオープンされた通常のファイルオブジェクトでなければなりません。

offset はファイルの読み込み開始位置を指定します。count が指定された場合、ファイルの EOF までファイルを送信する代わりに、count で指定された総バイト数の分だけ送信します。ファイルオブジェクトが指し示す位置は、メソッドがエラーを送出した場合でも更新されます。この場合実際に送信されたバイト数はfile.tell() メソッドで取得することができます。

fallback がTrue に設定された場合、 プラットフォームが sendfile システムコールをサポートしていない場合 (たとえば Windows や Unix の SSL ソケットなど) に asyncio が別の方法でファイルの読み込みと送信を行うようにすることができます。

システムがsendfile システムコールをサポートしておらず、かつfallback がFalse の場合、SendfileNotAvailableError 例外を送出します。

sock はノンブロッキングソケットでなければなりません。

Added in version 3.7.

DNS¶

asyncloop.getaddrinfo(host,port,*,family=0,type=0,proto=0,flags=0)¶

socket.getaddrinfo() の非同期版です。

asyncloop.getnameinfo(sockaddr,flags=0)¶

socket.getnameinfo() の非同期版です。

パイプとやりとりする¶

asyncloop.connect_read_pipe(protocol_factory,pipe)¶

イベントループの読み込み側終端にpipe を登録します。

protocol_factory はasyncio プロトコル の実装を返す呼び出し可能オブジェクトでなければなりません。

pipe にはfile-like オブジェクト を指定します。

(transport,protocol) のペアを返します。ここでtransport はReadTransport のインターフェースをサポートし、protocol はprotocol_factory ファクトリでインスタンス化されたオブジェクトです。

SelectorEventLoop イベントループの場合、pipe は非ブロックモードに設定されていなければなりません。

asyncloop.connect_write_pipe(protocol_factory,pipe)¶

pipe の書き込み側終端をイベントループに登録します。

protocol_factory はasyncio プロトコル の実装を返す呼び出し可能オブジェクトでなければなりません。

pipe はfile-like オブジェクト です。

(transport,protocol) のペアを返します。ここでtransport はWriteTransport のインスタンスであり、protocol はprotocol_factory ファクトリでインスタンス化されたオブジェクトです。

SelectorEventLoop イベントループの場合、pipe は非ブロックモードに設定されていなければなりません。

Unix シグナル¶

loop.add_signal_handler(signum,callback,*args)¶

コールバックcallback をシグナルsignum に対するハンドラに設定します。

コールバックはloop、登録された他のコールバック、およびイベントループの実行可能なコルーチンから呼び出されます。signal.signal() を使って登録されたシグナルハンドラと異なり、この関数で登録されたコールバックはイベントループと相互作用することが可能です。

シグナルナンバーが誤っているか捕捉不可能な場合ValueError が送出されます。ハンドラーの設定に問題があった場合RuntimeError が送出されます。

コールバックcallback にキーワード引数を渡す 場合はfunctools.partial() を使ってください。

signal.signal() と同じく、この関数はメインスレッドから呼び出されなければなりません。

loop.remove_signal_handler(sig)¶

シグナルsig に対するハンドラを削除します。

シグナルハンドラが削除された場合True を返します。シグナルに対してハンドラが設定されていない場合にはFalse を返します。

Availability: Unix.

スレッドまたはプロセスプールでコードを実行する¶

awaitableloop.run_in_executor(executor,func,*args)¶

指定したエグゼキュータで関数func が実行されるように準備します。

Theexecutor argument should be anconcurrent.futures.Executorinstance. The default executor is used ifexecutor isNone.The default executor can be set byloop.set_default_executor(),otherwise, aconcurrent.futures.ThreadPoolExecutor will belazy-initialized and used byrun_in_executor() if needed.

以下はプログラム例です:

importasyncioimportconcurrent.futuresdefblocking_io():# File operations (such as logging) can block the# event loop: run them in a thread pool.withopen('/dev/urandom','rb')asf:returnf.read(100)defcpu_bound():# CPU-bound operations will block the event loop:# in general it is preferable to run them in a# process pool.returnsum(i*iforiinrange(10**7))asyncdefmain():loop=asyncio.get_running_loop()## Options:# 1. Run in the default loop's executor:result=awaitloop.run_in_executor(None,blocking_io)print('default thread pool',result)# 2. Run in a custom thread pool:withconcurrent.futures.ThreadPoolExecutor()aspool:result=awaitloop.run_in_executor(pool,blocking_io)print('custom thread pool',result)# 3. Run in a custom process pool:withconcurrent.futures.ProcessPoolExecutor()aspool:result=awaitloop.run_in_executor(pool,cpu_bound)print('custom process pool',result)if__name__=='__main__':asyncio.run(main())

Note that the entry point guard (if__name__=='__main__')is required for option 3 due to the peculiarities ofmultiprocessing,which is used byProcessPoolExecutor.SeeSafe importing of main module.

このメソッドはasyncio.Future オブジェクトを返します。

関数func にキーワード引数を渡す 場合はfunctools.partial() を使ってください。

バージョン 3.5.3 で変更:loop.run_in_executor() は内部で生成するスレッドプールエグゼキュータのmax_workers を設定せず、代わりにスレッドプールエグゼキュータ (ThreadPoolExecutor) にデフォルト値を設定させるようになりました。

loop.set_default_executor(executor)¶

Setexecutor as the default executor used byrun_in_executor().executor must be an instance ofThreadPoolExecutor.

バージョン 3.11 で変更:executor must be an instance ofThreadPoolExecutor.

エラーハンドリング API¶

イベントループ内での例外の扱い方をカスタマイズできます。

loop.set_exception_handler(handler)¶

handler を新しいイベントループ例外ハンドラーとして設定します。

handler がNone の場合、デフォルトの例外ハンドラが設定されます。そうでなければ、handler は(loop,context) に一致する関数シグネチャを持った呼び出し可能オブジェクトでなければなりません。ここでloop はアクティブなイベントループへの参照であり、context は例外の詳細な記述からなるdict オブジェクトです (context についての詳細はcall_exception_handler() メソッドのドキュメントを参照してください)。

If the handler is called on behalf of aTask orHandle, it is run in thecontextvars.Context of that task or callback handle.

バージョン 3.12 で変更:The handler may be called in theContextof the task or handle where the exception originated.

loop.get_exception_handler()¶

現在の例外ハンドラを返します。カスタム例外ハンドラが設定されていない場合はNone を返します。

Added in version 3.5.2.

loop.default_exception_handler(context)¶

デフォルトの例外ハンドラーです。

デフォルト例外ハンドラは、例外ハンドラが未設定の場合、例外が発生した時に呼び出されます。デフォルト例外ハンドラの挙動を受け入れるために、カスタム例外ハンドラから呼び出すことも可能です。

引数context の意味はcall_exception_handler() と同じです。

loop.call_exception_handler(context)¶

現在のイベントループ例外ハンドラーを呼び出します。

context は以下のキーを含むdict オブジェクトです (将来の Python バージョンで新しいキーが追加される可能性があります):

• 'message': エラーメッセージ;

• 'exception' (任意): 例外オブジェクト;

• 'future' (任意):asyncio.Future インスタンス;

• 'task' (необов'язковий):asyncio.Task екземпляр;

• 'handle' (任意):asyncio.Handle インスタンス;

• 'protocol' (任意):プロトコル インスタンス;

• 'transport' (任意):トランスポート インスタンス;

• 'socket' (необов'язковий):socket.socket екземпляр;

• 'source_traceback' (optional): Traceback of the source;

• 'handle_traceback' (optional): Traceback of the handle;

• 'asyncgen' (необов'язково): асинхронний генератор, який викликав

  виняток.

注釈

This method should not be overloaded in subclassedevent loops. For custom exception handling, usetheset_exception_handler() method.

デバッグモードの有効化¶

loop.get_debug()¶

イベントループのデバッグモード (bool) を取得します。

環境変数PYTHONASYNCIODEBUG に空でない文字列が設定されている場合のデフォルト値はTrue、そうでない場合はFalse になります。

loop.set_debug(enabled:bool)¶

イベントループのデバッグモードを設定します。

バージョン 3.7 で変更:新しいPython 開発モード を使ってデバッグモードを有効化することができるようになりました。

loop.slow_callback_duration¶

This attribute can be used to set theminimum execution duration in seconds that is considered "slow".When debug mode is enabled, "slow" callbacks are logged.

Default value is 100 milliseconds.

サブプロセスの実行¶

この節で解説しているのは低水準のメソッドです。通常の async/await コードでは、高水準の関数であるasyncio.create_subprocess_shell() やasyncio.create_subprocess_exec() を代わりに使うことを検討してください。

asyncloop.subprocess_exec(protocol_factory,*args,stdin=subprocess.PIPE,stdout=subprocess.PIPE,stderr=subprocess.PIPE,**kwargs)¶

args で指定されたひとつの、または複数の文字列引数からサブプロセスを生成します。

args は下記のいずれかに当てはまる文字列のリストでなければなりません:

• str;

• またはファイルシステムのエンコーディング にエンコードされたbytes

引数の最初の文字列はプログラムの実行ファイルを指定します。それに続く残りの文字列は引数を指定し、そのプログラムに対するargv を構成します。

このメソッドは標準ライブラリのsubprocess.Popen クラスを、shell=False かつ最初の引数に文字列のリストを渡して呼び出した場合に似ています。しかし、Popen クラスは文字列のリストを引数としてひとつだけ取るのに対して、subprocess_exec は複数の文字列引数をとることができます。

protocol_factory はasyncio.SubprocessProtocol クラスの派生クラスを返す呼び出し可能オブジェクトでなければなりません。

その他の引数:

• stdin は下記のいずれかをとることができます:

  • a file-like object

  • an existing file descriptor (a positive integer), for example those created withos.pipe()

  • デフォルト値はsubprocess.PIPE 定数で、この場合新規にパイプを生成して接続します。

  • None が設定された場合、サブプロセスは元のプロセスのファイルデスクリプタを引き継ぎます。

  • subprocess.DEVNULL 定数を設定すると、特別なファイルos.devnull を使います。

• stdout は下記のいずれかをとることができます:

  • a file-like object

  • デフォルト値はsubprocess.PIPE 定数で、この場合新規にパイプを生成して接続します。

  • None が設定された場合、サブプロセスは元のプロセスのファイルデスクリプタを引き継ぎます。

  • subprocess.DEVNULL 定数を設定すると、特別なファイルos.devnull を使います。

• stderr は下記のいずれかをとることができます:

  • a file-like object

  • デフォルト値はsubprocess.PIPE 定数で、この場合新規にパイプを生成して接続します。

  • None が設定された場合、サブプロセスは元のプロセスのファイルデスクリプタを引き継ぎます。

  • subprocess.DEVNULL 定数を設定すると、特別なファイルos.devnull を使います。

  • subprocess.STDOUT 定数を設定すると、標準エラー出力ストリームをプロセスの標準出力ストリームに接続します。

• その他のすべてのキーワード引数は解釈されずにそのままsubprocess.Popen に渡されます。ただし、bufsize、universal_newlines、shell、text、encoding およびerrors は指定してはいけません。

  asyncio のサブプロセス API はストリームからテキストへのデコードをサポートしていません。ストリームからテキストに変換するにはbytes.decode() 関数を使ってください。

If a file-like object passed asstdin,stdout orstderr represents apipe, then the other side of this pipe should be registered withconnect_write_pipe() orconnect_read_pipe() for usewith the event loop.

他の引数についての詳細はsubprocess.Popen クラスのコンストラクタを参照してください。

(transport,protocol) のペアを返します。ここでtransport はasyncio.SubprocessTransport 基底クラスに適合するオブジェクトで、protocol はprotocol_factory によりインスタンス化されたオブジェクトです。

asyncloop.subprocess_shell(protocol_factory,cmd,*,stdin=subprocess.PIPE,stdout=subprocess.PIPE,stderr=subprocess.PIPE,**kwargs)¶

コマンドcmd からプラットフォームの "シェル" シンタックスを使ってサブプロセスを生成します。cmd はstr 文字列もしくはファイルシステムのエンコーディング でエンコードされたbytes 文字列です。

これは標準ライブラリのsubprocess.Popen クラスをshell=True で呼び出した場合と似ています。

protocol_factory はSubprocessProtocol の派生クラスを返す呼び出し可能オブジェクトでなければなりません。

その他の引数についての詳細はsubprocess_exec() メソッドを参照してください。

(transport,protocol) のペアを返します。ここでtransport はSubprocessTransport 基底クラスに適合するオブジェクトで、protocol はprotocol_factory によりインスタンス化されたオブジェクトです。

call_soon() を使った Hello World¶

loop.call_soon() メソッドを使ってコールバックをスケジュールする例です。コールバックは"HelloWorld" を出力しイベントループを停止します:

importasynciodefhello_world(loop):"""A callback to print 'Hello World' and stop the event loop"""print('Hello World')loop.stop()loop=asyncio.new_event_loop()# Schedule a call to hello_world()loop.call_soon(hello_world,loop)# Blocking call interrupted by loop.stop()try:loop.run_forever()finally:loop.close()

call_later() で現在の日時を表示する¶

毎秒現在時刻を表示するコールバックの例です。コールバックはloop.call_later() メソッドを使って自身を5秒後に実行するよう再スケジュールし、イベントループを停止します:

importasyncioimportdatetimedefdisplay_date(end_time,loop):print(datetime.datetime.now())if(loop.time()+1.0)<end_time:loop.call_later(1,display_date,end_time,loop)else:loop.stop()loop=asyncio.new_event_loop()# Schedule the first call to display_date()end_time=loop.time()+5.0loop.call_soon(display_date,end_time,loop)# Blocking call interrupted by loop.stop()try:loop.run_forever()finally:loop.close()

読み込みイベント用ファイル記述子の監視¶

ファイル記述子がloop.add_reader() メソッドを使って何らかのデータを受信するまで待機し、その後イベントループをクローズします:

importasynciofromsocketimportsocketpair# Create a pair of connected file descriptorsrsock,wsock=socketpair()loop=asyncio.new_event_loop()defreader():data=rsock.recv(100)print("Received:",data.decode())# We are done: unregister the file descriptorloop.remove_reader(rsock)# Stop the event looploop.stop()# Register the file descriptor for read eventloop.add_reader(rsock,reader)# Simulate the reception of data from the networkloop.call_soon(wsock.send,'abc'.encode())try:# Run the event looploop.run_forever()finally:# We are done. Close sockets and the event loop.rsock.close()wsock.close()loop.close()

SIGINT および SIGTERM 用のシグナルハンドラーの設定¶

(ここに挙げるsignals の例は Unix でのみ動きます。)

Register handlers for signalsSIGINT andSIGTERMusing theloop.add_signal_handler() method:

importasyncioimportfunctoolsimportosimportsignaldefask_exit(signame,loop):print("got signal%s: exit"%signame)loop.stop()asyncdefmain():loop=asyncio.get_running_loop()forsignamein{'SIGINT','SIGTERM'}:loop.add_signal_handler(getattr(signal,signame),functools.partial(ask_exit,signame,loop))awaitasyncio.sleep(3600)print("Event loop running for 1 hour, press Ctrl+C to interrupt.")print(f"pid{os.getpid()}: send SIGINT or SIGTERM to exit.")asyncio.run(main())