18.5.1.1.Run an event loop¶

AbstractEventLoop.run_forever()¶

Run untilstop() is called. Ifstop() is called beforerun_forever() is called, this polls the I/O selector oncewith a timeout of zero, runs all callbacks scheduled in response toI/O events (and those that were already scheduled), and then exits.Ifstop() is called whilerun_forever() is running,this will run the current batch of callbacks and then exit. Notethat callbacks scheduled by callbacks will not run in that case;they will run the next timerun_forever() is called.

Changed in version 3.5.1.

AbstractEventLoop.run_until_complete(future)¶

Run until theFuture is done.

If the argument is acoroutine object, it is wrapped byensure_future().

Return the Future’s result, or raise its exception.

AbstractEventLoop.is_running()¶

Returns running status of event loop.

AbstractEventLoop.stop()¶

Stop running the event loop.

This causesrun_forever() to exit at the next suitableopportunity (see there for more details).

Changed in version 3.5.1.

AbstractEventLoop.is_closed()¶

ReturnsTrue if the event loop was closed.

New in version 3.4.2.

AbstractEventLoop.close()¶

Close the event loop. The loop must not be running. Pendingcallbacks will be lost.

This clears the queues and shuts down the executor, but does not wait forthe executor to finish.

This is idempotent and irreversible. No other methods should be called afterthis one.

coroutineAbstractEventLoop.shutdown_asyncgens()¶

Schedule all currently openasynchronous generator objects toclose with anaclose() call. After calling this method,the event loop will issue a warning whenever a new asynchronous generatoris iterated. Should be used to finalize all scheduled asynchronousgenerators reliably. Example:

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

New in version 3.6.

18.5.1.2.Calls¶

Mostasyncio functions don’t accept keywords. If you want to passkeywords to your callback, usefunctools.partial(). For example,loop.call_soon(functools.partial(print,"Hello",flush=True)) will callprint("Hello",flush=True).

AbstractEventLoop.call_soon(callback,*args)¶

Arrange for a callback to be called as soon as possible. The callback iscalled aftercall_soon() returns, when control returns to the eventloop.

This operates as aFIFO queue, callbacksare called in the order in which they are registered. Each callbackwill be called exactly once.

Any positional arguments after the callback will be passed to thecallback when it is called.

An instance ofasyncio.Handle is returned, which can beused to cancel the callback.

Use functools.partial to pass keywords to the callback.

AbstractEventLoop.call_soon_threadsafe(callback,*args)¶

Likecall_soon(), but thread safe.

See theconcurrency and multithreadingsection of the documentation.

18.5.1.3.Delayed calls¶

The event loop has its own internal clock for computing timeouts.Which clock is used depends on the (platform-specific) event loopimplementation; ideally it is a monotonic clock. This will generally bea different clock thantime.time().

AbstractEventLoop.call_later(delay,callback,*args)¶

Arrange for thecallback to be called after the givendelayseconds (either an int or float).

An instance ofasyncio.Handle is returned, which can beused to cancel the callback.

callback will be called exactly once per call tocall_later().If two callbacks are scheduled for exactly the same time, it isundefined which will be called first.

The optional positionalargs will be passed to the callback when itis called. If you want the callback to be called with some namedarguments, use a closure orfunctools.partial().

Use functools.partial to pass keywords to the callback.

AbstractEventLoop.call_at(when,callback,*args)¶

Arrange for thecallback to be called at the given absolute timestampwhen (an int or float), using the same time reference asAbstractEventLoop.time().

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

An instance ofasyncio.Handle is returned, which can beused to cancel the callback.

Use functools.partial to pass keywords to the callback.

AbstractEventLoop.time()¶

Return the current time, as afloat value, according to theevent loop’s internal clock.

18.5.1.4.Futures¶

AbstractEventLoop.create_future()¶

Create anasyncio.Future object attached to the loop.

This is a preferred way to create futures in asyncio, as eventloop implementations can provide alternative implementationsof the Future class (with better performance or instrumentation).

New in version 3.5.2.

18.5.1.5.Tasks¶

AbstractEventLoop.create_task(coro)¶

Schedule the execution of acoroutine object: wrap it ina future. Return aTask object.

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

This method was added in Python 3.4.2. Use theasync() function tosupport also older Python versions.

New in version 3.4.2.

AbstractEventLoop.set_task_factory(factory)¶

Set a task factory that will be used byAbstractEventLoop.create_task().

Iffactory isNone the default task factory will be set.

Iffactory is acallable, it should have a signature matching(loop,coro), whereloop will be a reference to the activeevent loop,coro will be a coroutine object. The callablemust return anasyncio.Future compatible object.

New in version 3.4.4.

AbstractEventLoop.get_task_factory()¶

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

New in version 3.4.4.

18.5.1.6.Creating connections¶

coroutineAbstractEventLoop.create_connection(protocol_factory,host=None,port=None,*,ssl=None,family=0,proto=0,flags=0,sock=None,local_addr=None,server_hostname=None)¶

Create a streaming transport connection to a given Internethost andport: socket familyAF_INET orAF_INET6 depending onhost (orfamily if specified),socket typeSOCK_STREAM.protocol_factory must be acallable returning aprotocol instance.

This method is acoroutine which will try toestablish the connection in the background. When successful, thecoroutine returns a(transport,protocol) pair.

The chronological synopsis of the underlying operation is as follows:

1. The connection is established, and atransportis created to represent it.

2. protocol_factory is called without arguments and must return aprotocol instance.

3. The protocol instance is tied to the transport, and itsconnection_made() method is called.

4. The coroutine returns successfully with the(transport,protocol)pair.

The created transport is an implementation-dependent bidirectional stream.

Note

protocol_factory can be any kind of callable, not necessarilya class. For example, if you want to use a pre-createdprotocol instance, you can passlambda:my_protocol.

Options that change how the connection is created:

• 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 context with someunspecified default settings is used.

  See also

  SSL/TLS security considerations

• server_hostname, is only for use together withssl,and sets or overrides the hostname that the target server’s certificatewill be matched against. 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 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.

• 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,flagsandlocal_addr should be specified.

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

Changed in version 3.5:On Windows withProactorEventLoop, SSL/TLS is now supported.

See also

Theopen_connection() function can be used to get a pair of(StreamReader,StreamWriter) instead of a protocol.

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

Note

The parameterreuse_address is no longer supported, as usingSO_REUSEADDR poses a significant security concern forUDP. Explicitly passingreuse_address=True will raise an exception.

When multiple processes with differing UIDs assign sockets to anindentical 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,SO_REUSEPORT is used instead, which specificallyprevents processes with differing UIDs from assigning sockets to the samesocket address.

Create a datagram connection.

Create datagram connection: socket familyAF_INET orAF_INET6 depending onhost (orfamily if specified),socket typeSOCK_DGRAM.protocol_factory must be acallable returning aprotocol instance.

This method is acoroutine which will try toestablish the connection in the background. When successful, thecoroutine returns a(transport,protocol) pair.

Options changing how the connection is created:

• local_addr, if given, is a(local_host,local_port) tuple usedto bind the socket to 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 UNIX’s. If theSO_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).

On Windows withProactorEventLoop, this method is not supported.

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.6.10:Thereuse_address parameter is no longer supporter due to securityconcerns

coroutineAbstractEventLoop.create_unix_connection(protocol_factory,path,*,ssl=None,sock=None,server_hostname=None)¶

Create UNIX connection: socket familyAF_UNIX, sockettypeSOCK_STREAM. TheAF_UNIX socketfamily is used to communicate between processes on the same machineefficiently.

This method is acoroutine which will try toestablish the connection in the background. When successful, thecoroutine returns a(transport,protocol) pair.

path is the name of a UNIX domain socket, and is required unless asockparameter is specified. Abstract UNIX sockets,str, andbytes paths are supported.

See theAbstractEventLoop.create_connection() method for parameters.

Availability: UNIX.

18.5.1.7.Creating listening connections¶

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

Create a TCP server (socket typeSOCK_STREAM) bound tohost andport.

Return aServer object, itssockets attributecontains created sockets. Use theServer.close() method to stop theserver: close listening sockets.

Parameters:

• Thehost parameter can be a string, in that case the TCP server isbound tohost andport. Thehost parameter can also be a sequenceof strings and in that case the TCP server is bound to all hosts of thesequence. Ifhost is an empty string orNone, all interfaces areassumed and a list of multiple sockets will be returned (most likely onefor IPv4 and another one for IPv6).

• family can be set to eithersocket.AF_INET orAF_INET6 to force the socket to use IPv4 or IPv6. If not setit will be determined from host (defaults tosocket.AF_UNSPEC).

• flags is a bitmask forgetaddrinfo().

• sock can optionally be specified in order to use a preexistingsocket object. If specified,host andport should be omitted (must beNone).

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

• ssl can be set to anSSLContext to enable SSL over theaccepted 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.

This method is acoroutine.

Changed in version 3.5:On Windows withProactorEventLoop, SSL/TLS is now supported.

See also

The functionstart_server() creates a (StreamReader,StreamWriter) pair and calls back a function with this pair.

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

coroutineAbstractEventLoop.create_unix_server(protocol_factory,path=None,*,sock=None,backlog=100,ssl=None)¶

Similar toAbstractEventLoop.create_server(), but specific to thesocket familyAF_UNIX.

This method is acoroutine.

Availability: UNIX.

coroutineBaseEventLoop.connect_accepted_socket(protocol_factory,sock,*,ssl=None)¶

Handle an accepted connection.

This is used by servers that accept connections outside ofasyncio but that use asyncio to handle them.

Parameters:

• sock is a preexisting socket object returned from anacceptcall.

• ssl can be set to anSSLContext to enable SSL over theaccepted connections.

This method is acoroutine. When completed, thecoroutine returns a(transport,protocol) pair.

New in version 3.5.3.

18.5.1.8.Watch file descriptors¶

On Windows withSelectorEventLoop, only socket handles are supported(ex: pipe file descriptors are not supported).

On Windows withProactorEventLoop, these methods are not supported.

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

Start watching the file descriptor for read availability and then call thecallback with specified arguments.

Use functools.partial to pass keywords to the callback.

AbstractEventLoop.remove_reader(fd)¶

Stop watching the file descriptor for read availability.

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

Start watching the file descriptor for write availability and then call thecallback with specified arguments.

Use functools.partial to pass keywords to the callback.

AbstractEventLoop.remove_writer(fd)¶

Stop watching the file descriptor for write availability.

Thewatch a file descriptor for read eventsexample uses the low-levelAbstractEventLoop.add_reader() method to registerthe file descriptor of a socket.

18.5.1.9.Low-level socket operations¶

coroutineAbstractEventLoop.sock_recv(sock,nbytes)¶

Receive data from the socket. Modeled after blockingsocket.socket.recv() method.

The return value is a bytes objectrepresenting the data received. The maximum amount of data to be receivedat once is specified bynbytes.

WithSelectorEventLoop event loop, the socketsock must benon-blocking.

This method is acoroutine.

coroutineAbstractEventLoop.sock_sendall(sock,data)¶

Send data to the socket. Modeled after blockingsocket.socket.sendall() method.

The socket must be connected to a remote socket.This method continues to send data fromdata until either all data hasbeen sent or an error occurs.None is returned on success. On error,an exception is raised, and there is no way to determine how much data, ifany, was successfully processed by the receiving end of the connection.

WithSelectorEventLoop event loop, the socketsock must benon-blocking.

This method is acoroutine.

coroutineAbstractEventLoop.sock_connect(sock,address)¶

Connect to a remote socket ataddress. Modeled afterblockingsocket.socket.connect() method.

WithSelectorEventLoop event loop, the socketsock must benon-blocking.

This method is acoroutine.

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,AbstractEventLoop.getaddrinfo() will be used to resolve theaddress.

See also

AbstractEventLoop.create_connection()andasyncio.open_connection().

coroutineAbstractEventLoop.sock_accept(sock)¶

Accept a connection. Modeled after blockingsocket.socket.accept().

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.

The socketsock must be non-blocking.

This method is acoroutine.

See also

AbstractEventLoop.create_server() andstart_server().

18.5.1.10.Resolve host name¶

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

This method is acoroutine, similar tosocket.getaddrinfo() function but non-blocking.

coroutineAbstractEventLoop.getnameinfo(sockaddr,flags=0)¶

This method is acoroutine, similar tosocket.getnameinfo() function but non-blocking.

18.5.1.11.Connect pipes¶

On Windows withSelectorEventLoop, these methods are not supported.UseProactorEventLoop to support pipes on Windows.

coroutineAbstractEventLoop.connect_read_pipe(protocol_factory,pipe)¶

Register read pipe in eventloop.

protocol_factory should instantiate object withProtocolinterface.pipe is afile-like object.Return pair(transport,protocol), wheretransport supports theReadTransport interface.

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

This method is acoroutine.

coroutineAbstractEventLoop.connect_write_pipe(protocol_factory,pipe)¶

Register write pipe in eventloop.

protocol_factory should instantiate object withBaseProtocolinterface.pipe isfile-like object.Return pair(transport,protocol), wheretransport supportsWriteTransport interface.

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

This method is acoroutine.

18.5.1.12.UNIX signals¶

Availability: UNIX only.

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

Add a handler for a signal.

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

Use functools.partial to pass keywords to the callback.

AbstractEventLoop.remove_signal_handler(sig)¶

Remove a handler for a signal.

ReturnTrue if a signal handler was removed,False if not.

18.5.1.13.Executor¶

Call a function in anExecutor (pool of threads orpool of processes). By default, an event loop uses a thread pool executor(ThreadPoolExecutor).

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

Arrange for afunc to be called in the specified executor.

Theexecutor argument should be anExecutorinstance. The default executor is used ifexecutor isNone.

Use functools.partial to pass keywords to the *func*.

This method is acoroutine.

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

AbstractEventLoop.set_default_executor(executor)¶

Set the default executor used byrun_in_executor().

18.5.1.14.Error Handling API¶

Allows customizing how exceptions are handled in the event loop.

AbstractEventLoop.set_exception_handler(handler)¶

Sethandler as the new event loop exception handler.

Ifhandler isNone, the default exception handler willbe set.

Ifhandler is a callable object, it should have amatching signature to(loop,context), whereloopwill be a reference to the active event loop,contextwill be adict object (seecall_exception_handler()documentation for details about context).

AbstractEventLoop.get_exception_handler()¶

Return the exception handler, orNone if the default oneis in use.

New in version 3.5.2.

AbstractEventLoop.default_exception_handler(context)¶

Default exception handler.

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

context parameter has the same meaning as incall_exception_handler().

AbstractEventLoop.call_exception_handler(context)¶

Call the current event loop exception handler.

context is adict object containing the following keys(new keys may be introduced later):

• ‘message’: Error message;

• ‘exception’ (optional): Exception object;

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

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

• ‘protocol’ (optional):Protocol instance;

• ‘transport’ (optional):Transport instance;

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

Note

Note: this method should not be overloaded in subclassedevent loops. For any custom exception handling, useset_exception_handler() method.

18.5.1.15.Debug mode¶

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

New in version 3.4.2.

AbstractEventLoop.set_debug(enabled: bool)¶

Set the debug mode of the event loop.

New in version 3.4.2.

18.5.1.16.Server¶

classasyncio.Server¶

Server listening on sockets.

Object created by theAbstractEventLoop.create_server() method and thestart_server() function. Don’t instantiate the class directly.

close()¶

Stop serving: close listening sockets and set thesocketsattribute toNone.

The sockets that represent existing incoming client connections are leftopen.

The server is closed asynchronously, use thewait_closed()coroutine to wait until the server is closed.

coroutinewait_closed()¶

Wait until theclose() method completes.

This method is acoroutine.

sockets¶

List ofsocket.socket objects the server is listening to, orNone if the server is closed.

18.5.1.17.Handle¶

classasyncio.Handle¶

A callback wrapper object returned byAbstractEventLoop.call_soon(),AbstractEventLoop.call_soon_threadsafe(),AbstractEventLoop.call_later(),andAbstractEventLoop.call_at().

cancel()¶

Cancel the call. If the callback is already canceled or executed,this method has no effect.

18.5.1.18.Event loop examples¶

importasynciodefhello_world(loop):print('Hello World')loop.stop()loop=asyncio.get_event_loop()# Schedule a call to hello_world()loop.call_soon(hello_world,loop)# Blocking call interrupted by loop.stop()loop.run_forever()loop.close()

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.get_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()loop.run_forever()loop.close()

importasynciotry:fromsocketimportsocketpairexceptImportError:fromasyncio.windows_utilsimportsocketpair# Create a pair of connected file descriptorsrsock,wsock=socketpair()loop=asyncio.get_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())# Run the event looploop.run_forever()# We are done, close sockets and the event looprsock.close()wsock.close()loop.close()

importasyncioimportfunctoolsimportosimportsignaldefask_exit(signame):print("got signal%s: exit"%signame)loop.stop()loop=asyncio.get_event_loop()forsignamein('SIGINT','SIGTERM'):loop.add_signal_handler(getattr(signal,signame),functools.partial(ask_exit,signame))print("Event loop running forever, press Ctrl+C to interrupt.")print("pid%s: send SIGINT or SIGTERM to exit."%os.getpid())try:loop.run_forever()finally:loop.close()