Running and stopping the loop¶

loop.run_until_complete(future)¶

Run until thefuture (an instance ofFuture) hascompleted.

If the argument is acoroutine object itis implicitly scheduled to run as aasyncio.Task.

Return the Future’s result or raise its exception.

loop.run_forever()¶

Run the event loop untilstop() is called.

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.

Ifstop() is called whilerun_forever() is running,the loop will run the current batch of callbacks and then exit.Note that new callbacks scheduled by callbacks will not run in thiscase; instead, they will run the next timerun_forever() orrun_until_complete() is called.

loop.stop()¶

Stop the event loop.

loop.is_running()¶

ReturnTrue if the event loop is currently running.

loop.is_closed()¶

ReturnTrue if the event loop was closed.

loop.close()¶

Close the event loop.

The loop must not be running when this function is called.Any pending callbacks will be discarded.

This method clears all queues and shuts down the executor, but doesnot wait for the executor to finish.

This method is idempotent and irreversible. No other methodsshould be called after the event loop is closed.

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.

Note that there is no need to call this function whenasyncio.run() is used.

Example:

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.

Note

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

Added in version 3.9.

Changed in version 3.12:Added thetimeout parameter.

Scheduling callbacks¶

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

Schedule thecallbackcallback to be called withargs arguments at the next iteration of the event loop.

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

Callbacks are called in the order in which they are registered.Each callback will be called exactly once.

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.

RaisesRuntimeError if called on a loop that’s been closed.This can happen on a secondary thread when the main application isshutting down.

See theconcurrency and multithreadingsection of the documentation.

Changed in version 3.7:Thecontext keyword-only parameter was added. SeePEP 567for more details.

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

Scheduling delayed callbacks¶

Event loop provides mechanisms to schedule callback functionsto be called at some point in the future. Event loop uses monotonicclocks to track time.

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

Schedulecallback to be called after the givendelaynumber of seconds (can be either an int or a float).

An instance ofasyncio.TimerHandle is returned which canbe used to cancel the callback.

callback will be called exactly once. If two callbacks arescheduled for exactly the same time, the order in which theyare called is undefined.

The optional positionalargs will be passed to the callback whenit is called. If you want the callback to be called with keywordarguments usefunctools.partial().

An optional keyword-onlycontext argument allows specifying acustomcontextvars.Context for thecallback to run in.The current context is used when nocontext is provided.

Changed in version 3.7:Thecontext keyword-only parameter was added. SeePEP 567for more details.

Changed in version 3.8:In Python 3.7 and earlier with the default event loop implementation,thedelay could not exceed one day.This has been fixed in Python 3.8.

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

Schedulecallback to be called at the given absolute timestampwhen (an int or a float), using the same time reference asloop.time().

This method’s behavior is the same ascall_later().

An instance ofasyncio.TimerHandle is returned which canbe used to cancel the callback.

Changed in version 3.7:Thecontext keyword-only parameter was added. SeePEP 567for more details.

Changed in version 3.8:In Python 3.7 and earlier with the default event loop implementation,the difference betweenwhen and the current time could not exceedone day. This has been fixed in Python 3.8.

loop.time()¶

Return the current time, as afloat value, according tothe event loop’s internal monotonic clock.

Creating Futures and Tasks¶

loop.create_future()¶

Create anasyncio.Future object attached to the event loop.

This is the preferred way to create Futures in asyncio. This letsthird-party event loops provide alternative implementations ofthe Future object (with better performance or instrumentation).

Added in version 3.5.2.

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

Schedule the execution ofcoroutinecoro.Return aTask object.

Third-party event loops can use their own subclass ofTaskfor interoperability. In this case, the result type is a subclassofTask.

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.

If thename argument is provided and notNone, it is set asthe name of the task usingTask.set_name().

An optional keyword-onlycontext argument allows specifying acustomcontextvars.Context for thecoro to run in.The current context copy is created when nocontext is provided.

Changed in version 3.8:Added thename parameter.

Changed in version 3.11:Added thecontext parameter.

Changed in version 3.13.3:Addedkwargs which passes on arbitrary extra parameters, includingname andcontext.

Changed in version 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)¶

Set a task factory that will be used byloop.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.

Changed in version 3.13.3:Required that allkwargs are passed on toasyncio.Task.

Changed in version 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()¶

Return a task factory orNone if the default one is in use.

Opening network connections¶

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)¶

Open a streaming transport connection to a givenaddress specified byhost andport.

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

The socket type will beSOCK_STREAM.

protocol_factory must be a callable returning anasyncio protocol implementation.

This method will try to establish the connection in the background.When successful, it returns a(transport,protocol) pair.

The chronological synopsis of the underlying operation is as follows:

1. The connection is established and atransportis created for it.

2. protocol_factory is called without arguments and is expected toreturn aprotocol instance.

3. The protocol instance is coupled with the transport by calling itsconnection_made() method.

4. A(transport,protocol) tuple is returned on success.

The created transport is an implementation-dependent bidirectionalstream.

Other arguments:

• ssl: if given and not false, a SSL/TLS transport is created(by default a plain TCP transport is created). Ifssl isassl.SSLContext object, this context is used to createthe transport; ifssl isTrue, a default context returnedfromssl.create_default_context() is used.

  See also

  SSL/TLS security considerations

• server_hostname sets or overrides the hostname that the targetserver’s certificate will be matched against. Should only be passedifssl is notNone. By default the value of thehost argumentis used. Ifhost is empty, there is no default and you must pass avalue forserver_hostname. Ifserver_hostname is an emptystring, hostname matching is disabled (which is a serious securityrisk, allowing for potential man-in-the-middle attacks).

• family,proto,flags are the optional address family, protocoland flags to be passed through to getaddrinfo() forhost resolution.If given, these should all be integers from the correspondingsocket module constants.

• happy_eyeballs_delay, if given, enables Happy Eyeballs for thisconnection. It shouldbe a floating-point number representing the amount of time in secondsto wait for a connection attempt to complete, before starting the nextattempt in parallel. This is the “Connection Attempt Delay” as definedinRFC 8305. A sensible default value recommended by the RFC is0.25(250 milliseconds).

• interleave controls address reordering when a host name resolves tomultiple IP addresses.If0 or unspecified, no reordering is done, and addresses aretried in the order returned bygetaddrinfo(). If a positive integeris specified, the addresses are interleaved by address family, and thegiven integer is interpreted as “First Address Family Count” as definedinRFC 8305. The default is0 ifhappy_eyeballs_delay is notspecified, and1 if it is.

• sock, if given, should be an existing, already connectedsocket.socket object to be used by the transport.Ifsock is given, none ofhost,port,family,proto,flags,happy_eyeballs_delay,interleaveandlocal_addr should be specified.

  Note

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

• local_addr, if given, is a(local_host,local_port) tuple usedto bind the socket locally. Thelocal_host andlocal_portare looked up usinggetaddrinfo(), similarly tohost andport.

• ssl_handshake_timeout is (for a TLS connection) the time in secondsto wait for the TLS handshake to complete before aborting the connection.60.0 seconds ifNone (default).

• 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).

Changed in version 3.5:Added support for SSL/TLS inProactorEventLoop.

Changed in version 3.6:The socket optionsocket.TCP_NODELAY is set by defaultfor all TCP connections.

Changed in version 3.7:Added thessl_handshake_timeout parameter.

Changed in version 3.8:Added thehappy_eyeballs_delay andinterleave parameters.

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

Changed in version 3.11:Added thessl_shutdown_timeout parameter.

Changed in version 3.12:all_errors was added.

See also

Theopen_connection() function is a high-level alternativeAPI. It returns a pair of (StreamReader,StreamWriter)that can be used directly in async/await code.

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)¶

Create a datagram connection.

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 must be a callable returning aprotocol implementation.

A tuple of(transport,protocol) is returned on success.

Other arguments:

• local_addr, if given, is a(local_host,local_port) tuple usedto bind the socket locally. Thelocal_host andlocal_portare looked up usinggetaddrinfo().

• remote_addr, if given, is a(remote_host,remote_port) tuple usedto connect the socket to a remote address. Theremote_host andremote_port are looked up usinggetaddrinfo().

• family,proto,flags are the optional address family, protocoland flags to be passed through togetaddrinfo() forhostresolution. If given, these should all be integers from thecorrespondingsocket module constants.

• 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 tells the kernel to allow this endpoint to sendmessages to the broadcast address.

• sock can optionally be specified in order to use a preexisting,already connected,socket.socket object to be used by thetransport. If specified,local_addr andremote_addr should be omitted(must beNone).

  Note

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

SeeUDP echo client protocol andUDP echo server protocol examples.

Changed in version 3.4.4:Thefamily,proto,flags,reuse_address,reuse_port,allow_broadcast, andsock parameters were added.

Changed in version 3.8:Added support for Windows.

Changed in version 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.

When multiple processes with differing UIDs assign sockets to anidentical UDP socket address withSO_REUSEADDR, incoming packets canbecome randomly distributed among the sockets.

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.

Changed in version 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)¶

Create a Unix connection.

The socket family will beAF_UNIX; sockettype will beSOCK_STREAM.

A tuple of(transport,protocol) is returned on success.

path is the name of a Unix domain socket and is required,unless asock parameter is specified. Abstract Unix sockets,str,bytes, andPath paths aresupported.

See the documentation of theloop.create_connection() methodfor information about arguments to this method.

Availability: Unix.

Changed in version 3.7:Added thessl_handshake_timeout parameter.Thepath parameter can now be apath-like object.

Changed in version 3.11:Added thessl_shutdown_timeout parameter.

Creating network servers¶

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.

Returns aServer object.

Arguments:

• protocol_factory must be a callable returning aprotocol implementation.

• Thehost parameter can be set to several types which determine wherethe server would be listening:

  • Ifhost is a string, the TCP server is bound to a single networkinterface specified byhost.

  • Ifhost is a sequence of strings, the TCP server is bound to allnetwork interfaces specified by the sequence.

  • Ifhost is an empty string orNone, all interfaces areassumed and a list of multiple sockets will be returned (most likelyone for IPv4 and another one for IPv6).

• Theport parameter can be set to specify which port the server shouldlisten on. If0 orNone (the default), a random unused port willbe selected (note that ifhost resolves to multiple network interfaces,a different random port will be selected for each interface).

• 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 is a bitmask forgetaddrinfo().

• sock can optionally be specified in order to use a preexistingsocket object. If specified,host andport must not be specified.

  Note

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

• backlog is the maximum number of queued connections passed tolisten() (defaults to 100).

• ssl can be set to anSSLContext instance to enableTLS over the accepted connections.

• reuse_address tells the kernel to reuse a local socket inTIME_WAIT state, without waiting for its natural timeout toexpire. If not specified will automatically be set toTrue onUnix.

• 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 onWindows.

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

Changed in version 3.13:Added thekeep_alive parameter.

• ssl_handshake_timeout is (for a TLS server) the time in seconds to waitfor the TLS handshake to complete before aborting the connection.60.0 seconds ifNone (default).

• 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 set toTrue (the default) causes the created serverto start accepting connections immediately. When set toFalse,the user should await onServer.start_serving() orServer.serve_forever() to make the server to start acceptingconnections.

Changed in version 3.5:Added support for SSL/TLS inProactorEventLoop.

Changed in version 3.5.1:Thehost parameter can be a sequence of strings.

Changed in version 3.6:Addedssl_handshake_timeout andstart_serving parameters.The socket optionsocket.TCP_NODELAY is set by defaultfor all TCP connections.

Changed in version 3.11:Added thessl_shutdown_timeout parameter.

See also

Thestart_server() function is a higher-level alternative APIthat returns a pair ofStreamReader andStreamWriterthat can be used in an async/await code.

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 is the name of a Unix domain socket, and is required,unless asock argument is provided. Abstract Unix sockets,str,bytes, andPath pathsare supported.

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.

See the documentation of theloop.create_server() methodfor information about arguments to this method.

Availability: Unix.

Changed in version 3.7:Added thessl_handshake_timeout andstart_serving parameters.Thepath parameter can now be aPath object.

Changed in version 3.11:Added thessl_shutdown_timeout parameter.

Changed in version 3.13:Added thecleanup_socket parameter.

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

Wrap an already accepted connection into a transport/protocol pair.

This method can be used by servers that accept connections outsideof asyncio but that use asyncio to handle them.

Parameters:

• protocol_factory must be a callable returning aprotocol implementation.

• sock is a preexisting socket object returned fromsocket.accept.

  Note

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

• ssl can be set to anSSLContext to enable SSL overthe accepted connections.

• ssl_handshake_timeout is (for an SSL connection) the time in seconds towait for the SSL handshake to complete before aborting the connection.60.0 seconds ifNone (default).

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

Returns a(transport,protocol) pair.

Added in version 3.5.3.

Changed in version 3.7:Added thessl_handshake_timeout parameter.

Changed in version 3.11:Added thessl_shutdown_timeout parameter.

Transferring files¶

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

Send afile over atransport. Return the total number of bytessent.

The method uses high-performanceos.sendfile() if available.

file must be a regular file object opened in binary mode.

offset tells from where to start reading the file. If specified,count is the total number of bytes to transmit as opposed tosending the file until EOF is reached. File position is always updated,even when this method raises an error, andfile.tell() can be used to obtain the actualnumber of bytes sent.

fallback set toTrue makes asyncio to manually read and sendthe file when the platform does not support the sendfile system call(e.g. Windows or SSL socket on Unix).

RaiseSendfileNotAvailableError if the system does not supportthesendfile syscall andfallback isFalse.

Added in version 3.7.

TLS Upgrade¶

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

Upgrade an existing transport-based connection to 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.

Parameters:

• transport andprotocol instances that methods likecreate_server() andcreate_connection() return.

• sslcontext: a configured instance ofSSLContext.

• server_side passTrue when a server-side connection is beingupgraded (like the one created bycreate_server()).

• server_hostname: sets or overrides the host name that the targetserver’s certificate will be matched against.

• ssl_handshake_timeout is (for a TLS connection) the time in seconds towait for the TLS handshake to complete before aborting the connection.60.0 seconds ifNone (default).

• 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.

Changed in version 3.11:Added thessl_shutdown_timeout parameter.

Watching file descriptors¶

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

Start monitoring thefd file descriptor for read availability andinvokecallback with the specified arguments oncefd is available forreading.

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)¶

Start monitoring thefd file descriptor for write availability andinvokecallback with the specified arguments oncefd is available forwriting.

Any preexisting callback registered forfd is cancelled and replaced bycallback.

Usefunctools.partial()to pass keyword arguments tocallback.

loop.remove_writer(fd)¶

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

See alsoPlatform Support sectionfor some limitations of these methods.

Working with socket objects directly¶

In general, protocol implementations that use transport-based APIssuch asloop.create_connection() andloop.create_server()are faster than implementations that work with sockets directly.However, there are some use cases when performance is not critical, andworking withsocket objects directly is moreconvenient.

asyncloop.sock_recv(sock,nbytes)¶

Receive up tonbytes fromsock. Asynchronous version ofsocket.recv().

Return the received data as a bytes object.

sock must be a non-blocking socket.

Changed in version 3.7:Even though this method was always documented as a coroutinemethod, releases before Python 3.7 returned aFuture.Since Python 3.7 this is anasyncdef method.

asyncloop.sock_recv_into(sock,buf)¶

Receive data fromsock into thebuf buffer. Modeled after the blockingsocket.recv_into() method.

Return the number of bytes written to the buffer.

sock must be a non-blocking socket.

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 must be a non-blocking socket.

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 must be a non-blocking socket.

Added in version 3.11.

asyncloop.sock_sendall(sock,data)¶

Senddata to thesock socket. Asynchronous version ofsocket.sendall().

This method continues to send to the socket until either all dataindata has been sent or an error occurs.None is returnedon success. On error, an exception is raised. Additionally, there is no wayto determine how much data, if any, was successfully processed by thereceiving end of the connection.

sock must be a non-blocking socket.

Changed in version 3.7:Even though the method was always documented as a coroutinemethod, before Python 3.7 it returned aFuture.Since Python 3.7, this is anasyncdef method.

asyncloop.sock_sendto(sock,data,address)¶

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

Return the number of bytes sent.

sock must be a non-blocking socket.

Added in version 3.11.

asyncloop.sock_connect(sock,address)¶

Connectsock to a remote socket ataddress.

Asynchronous version ofsocket.connect().

sock must be a non-blocking socket.

Changed in version 3.5.2:address no longer needs to be resolved.sock_connectwill try to check if theaddress is already resolved by callingsocket.inet_pton(). If not,loop.getaddrinfo() will be used to resolve theaddress.

See also

loop.create_connection()andasyncio.open_connection().

asyncloop.sock_accept(sock)¶

Accept a connection. Modeled after the blockingsocket.accept() method.

The socket must be bound to an address and listeningfor connections. The return value is a pair(conn,address) whereconnis anew socket object usable to send and receive data on the connection,andaddress is the address bound to the socket on the other end of theconnection.

sock must be a non-blocking socket.

Changed in version 3.7:Even though the method was always documented as a coroutinemethod, before Python 3.7 it returned aFuture.Since Python 3.7, this is anasyncdef method.

See also

loop.create_server() andstart_server().

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

Send a file using high-performanceos.sendfile if possible.Return the total number of bytes sent.

Asynchronous version ofsocket.sendfile().

sock must be a non-blockingsocket.SOCK_STREAMsocket.

file must be a regular file object open in binary mode.

offset tells from where to start reading the file. If specified,count is the total number of bytes to transmit as opposed tosending the file until EOF is reached. File position is always updated,even when this method raises an error, andfile.tell() can be used to obtain the actualnumber of bytes sent.

fallback, when set toTrue, makes asyncio manually read and sendthe file when the platform does not support the sendfile syscall(e.g. Windows or SSL socket on Unix).

RaiseSendfileNotAvailableError if the system does not supportsendfile syscall andfallback isFalse.

sock must be a non-blocking socket.

Added in version 3.7.

DNS¶

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

Asynchronous version ofsocket.getaddrinfo().

asyncloop.getnameinfo(sockaddr,flags=0)¶

Asynchronous version ofsocket.getnameinfo().

Working with pipes¶

asyncloop.connect_read_pipe(protocol_factory,pipe)¶

Register the read end ofpipe in the event loop.

protocol_factory must be a callable returning anasyncio protocol implementation.

pipe is afile-like object.

Return pair(transport,protocol), wheretransport supportstheReadTransport interface andprotocol is an objectinstantiated by theprotocol_factory.

WithSelectorEventLoop event loop, thepipe is set tonon-blocking mode.

asyncloop.connect_write_pipe(protocol_factory,pipe)¶

Register the write end ofpipe in the event loop.

protocol_factory must be a callable returning anasyncio protocol implementation.

pipe isfile-like object.

Return pair(transport,protocol), wheretransport supportsWriteTransport interface andprotocol is an objectinstantiated by theprotocol_factory.

WithSelectorEventLoop event loop, thepipe is set tonon-blocking mode.

Unix signals¶

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

Setcallback as the handler for thesignum signal.

The callback will be invoked byloop, along with other queued callbacksand runnable coroutines of that event loop. Unlike signal handlersregistered usingsignal.signal(), a callback registered with thisfunction is allowed to interact with the event loop.

RaiseValueError if the signal number is invalid or uncatchable.RaiseRuntimeError if there is a problem setting up the handler.

Usefunctools.partial()to pass keyword arguments tocallback.

Likesignal.signal(), this function must be invoked in the mainthread.

loop.remove_signal_handler(sig)¶

Remove the handler for thesig signal.

ReturnTrue if the signal handler was removed, orFalse ifno handler was set for the given signal.

Availability: Unix.

Executing code in thread or process pools¶

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

Arrange forfunc to be called in the specified executor.

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.

Example:

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.

This method returns aasyncio.Future object.

Usefunctools.partial()to pass keyword arguments tofunc.

Changed in version 3.5.3:loop.run_in_executor() no longer configures themax_workers of the thread pool executor it creates, insteadleaving it up to the thread pool executor(ThreadPoolExecutor) to set thedefault.

loop.set_default_executor(executor)¶

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

Changed in version 3.11:executor must be an instance ofThreadPoolExecutor.

Error Handling API¶

Allows customizing how exceptions are handled in the event loop.

loop.set_exception_handler(handler)¶

Sethandler as the new event loop exception handler.

Ifhandler isNone, the default exception handler willbe set. Otherwise,handler must be a callable with the signaturematching(loop,context), whereloopis a reference to the active event loop, andcontextis adict object containing the details of the exception(seecall_exception_handler() documentation for detailsabout context).

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

Changed in version 3.12:The handler may be called in theContextof the task or handle where the exception originated.

loop.get_exception_handler()¶

Return the current exception handler, orNone if no customexception handler was set.

Added in version 3.5.2.

loop.default_exception_handler(context)¶

Default exception handler.

This is called when an exception occurs and no exceptionhandler is set. This can be called by a custom exceptionhandler that wants to defer to the default handler behavior.

context parameter has the same meaning as incall_exception_handler().

loop.call_exception_handler(context)¶

Call the current event loop exception handler.

context is adict object containing the following keys(new keys may be introduced in future Python versions):

• ‘message’: Error message;

• ‘exception’ (optional): Exception object;

• ‘future’ (optional):asyncio.Future instance;

• ‘task’ (optional):asyncio.Task instance;

• ‘handle’ (optional):asyncio.Handle instance;

• ‘protocol’ (optional):Protocol instance;

• ‘transport’ (optional):Transport instance;

• ‘socket’ (optional):socket.socket instance;

• ‘source_traceback’ (optional): Traceback of the source;

• ‘handle_traceback’ (optional): Traceback of the handle;

• ‘asyncgen’ (optional): Asynchronous generator that caused

  the exception.

Note

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

Enabling debug mode¶

loop.get_debug()¶

Get the debug mode (bool) of the event loop.

The default value isTrue if the environment variablePYTHONASYNCIODEBUG is set to a non-empty string,Falseotherwise.

loop.set_debug(enabled:bool)¶

Set the debug mode of the event loop.

Changed in version 3.7:The newPython Development Mode can now also be usedto enable the debug mode.

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.

Running Subprocesses¶

Methods described in this subsections are low-level. In regularasync/await code consider using the high-levelasyncio.create_subprocess_shell() andasyncio.create_subprocess_exec() convenience functions instead.

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

Create a subprocess from one or more string arguments specified byargs.

args must be a list of strings represented by:

• str;

• orbytes, encoded to thefilesystem encoding.

The first string specifies the program executable,and the remaining strings specify the arguments. Together, stringarguments form theargv of the program.

This is similar to the standard librarysubprocess.Popenclass called withshell=False and the list of strings passed asthe first argument; however, wherePopen takesa single argument which is list of strings,subprocess_exectakes multiple string arguments.

Theprotocol_factory must be a callable returning a subclass of theasyncio.SubprocessProtocol class.

Other parameters:

• stdin can be any of these:

  • a file-like object

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

  • thesubprocess.PIPE constant (default) which will create a newpipe and connect it,

  • the valueNone which will make the subprocess inherit the filedescriptor from this process

  • thesubprocess.DEVNULL constant which indicates that thespecialos.devnull file will be used

• stdout can be any of these:

  • a file-like object

  • thesubprocess.PIPE constant (default) which will create a newpipe and connect it,

  • the valueNone which will make the subprocess inherit the filedescriptor from this process

  • thesubprocess.DEVNULL constant which indicates that thespecialos.devnull file will be used

• stderr can be any of these:

  • a file-like object

  • thesubprocess.PIPE constant (default) which will create a newpipe and connect it,

  • the valueNone which will make the subprocess inherit the filedescriptor from this process

  • thesubprocess.DEVNULL constant which indicates that thespecialos.devnull file will be used

  • thesubprocess.STDOUT constant which will connect the standarderror stream to the process’ standard output stream

• All other keyword arguments are passed tosubprocess.Popenwithout interpretation, except forbufsize,universal_newlines,shell,text,encoding anderrors, which should not be specifiedat all.

  Theasyncio subprocess API does not support decoding the streamsas text.bytes.decode() can be used to convert the bytes returnedfrom the stream to text.

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.

See the constructor of thesubprocess.Popen classfor documentation on other arguments.

Returns a pair of(transport,protocol), wheretransportconforms to theasyncio.SubprocessTransport base class andprotocol is an object instantiated by theprotocol_factory.

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

Create a subprocess fromcmd, which can be astr or abytes string encoded to thefilesystem encoding,using the platform’s “shell” syntax.

This is similar to the standard librarysubprocess.Popenclass called withshell=True.

Theprotocol_factory must be a callable returning a subclass of theSubprocessProtocol class.

Seesubprocess_exec() for more details aboutthe remaining arguments.

Returns a pair of(transport,protocol), wheretransportconforms to theSubprocessTransport base class andprotocol is an object instantiated by theprotocol_factory.

Hello World with call_soon()¶

An example using theloop.call_soon() method to schedule acallback. The callback displays"HelloWorld" and then stops theevent loop:

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()

Display the current date with call_later()¶

An example of a callback displaying the current date every second. Thecallback uses theloop.call_later() method to reschedule itselfafter 5 seconds, and then stops the event loop:

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()

Watch a file descriptor for read events¶

Wait until a file descriptor received some data using theloop.add_reader() method and then close the event loop:

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()

Set signal handlers for SIGINT and SIGTERM¶

(Thissignals example only works on 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())