Future Functions¶

asyncio.isfuture(obj)¶

ReturnTrue ifobj is either of:

• an instance ofasyncio.Future,

• an instance ofasyncio.Task,

• a Future-like object with a_asyncio_future_blockingattribute.

Added in version 3.5.

asyncio.ensure_future(obj,*,loop=None)¶

Return:

• obj argument as is, ifobj is aFuture,aTask, or a Future-like object (isfuture()is used for the test.)

• aTask object wrappingobj, ifobj is acoroutine (iscoroutine() is used for the test);in this case the coroutine will be scheduled byensure_future().

• aTask object that would await onobj, ifobj is anawaitable (inspect.isawaitable() is used for the test.)

Ifobj is neither of the above aTypeError is raised.

Important

See also thecreate_task() function which is thepreferred way for creating new Tasks.

Save a reference to the result of this function, to avoida task disappearing mid-execution.

Changed in version 3.5.1:The function accepts anyawaitable object.

Deprecated since version 3.10:Deprecation warning is emitted ifobj is not a Future-like objectandloop is not specified and there is no running event loop.

asyncio.wrap_future(future,*,loop=None)¶

Wrap aconcurrent.futures.Future object in aasyncio.Future object.

Deprecated since version 3.10:Deprecation warning is emitted iffuture is not a Future-like objectandloop is not specified and there is no running event loop.

Future Object¶

classasyncio.Future(*,loop=None)¶

A Future represents an eventual result of an asynchronousoperation. Not thread-safe.

Future is anawaitable object. Coroutines can await onFuture objects until they either have a result or an exceptionset, or until they are cancelled. A Future can be awaited multipletimes and the result is same.

Typically Futures are used to enable low-levelcallback-based code (e.g. in protocols implemented using asynciotransports)to interoperate with high-level async/await code.

The rule of thumb is to never expose Future objects in user-facingAPIs, and the recommended way to create a Future object is to callloop.create_future(). This way alternative event loopimplementations can inject their own optimized implementationsof a Future object.

Changed in version 3.7:Added support for thecontextvars module.

Deprecated since version 3.10:Deprecation warning is emitted ifloop is not specifiedand there is no running event loop.

result()¶

Return the result of the Future.

If the Future isdone and has a result set by theset_result() method, the result value is returned.

If the Future isdone and has an exception set by theset_exception() method, this method raises the exception.

If the Future has beencancelled, this method raisesaCancelledError exception.

If the Future’s result isn’t yet available, this method raisesanInvalidStateError exception.

set_result(result)¶

Mark the Future asdone and set its result.

Raises anInvalidStateError error if the Future isalreadydone.

set_exception(exception)¶

Mark the Future asdone and set an exception.

Raises anInvalidStateError error if the Future isalreadydone.

done()¶

ReturnTrue if the Future isdone.

A Future isdone if it wascancelled or if it has a resultor an exception set withset_result() orset_exception() calls.

cancelled()¶

ReturnTrue if the Future wascancelled.

The method is usually used to check if a Future is notcancelled before setting a result or an exception for it:

ifnotfut.cancelled():fut.set_result(42)

add_done_callback(callback,*,context=None)¶

Add a callback to be run when the Future isdone.

Thecallback is called with the Future object as its onlyargument.

If the Future is alreadydone when this method is called,the callback is scheduled withloop.call_soon().

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

functools.partial() can be used to pass parametersto the callback, e.g.:

# Call 'print("Future:", fut)' when "fut" is done.fut.add_done_callback(functools.partial(print,"Future:"))

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

remove_done_callback(callback)¶

Removecallback from the callbacks list.

Returns the number of callbacks removed, which is typically 1,unless a callback was added more than once.

cancel(msg=None)¶

Cancel the Future and schedule callbacks.

If the Future is alreadydone orcancelled, returnFalse.Otherwise, change the Future’s state tocancelled,schedule the callbacks, and returnTrue.

Changed in version 3.9:Added themsg parameter.

exception()¶

Return the exception that was set on this Future.

The exception (orNone if no exception was set) isreturned only if the Future isdone.

If the Future has beencancelled, this method raises aCancelledError exception.

If the Future isn’tdone yet, this method raises anInvalidStateError exception.

get_loop()¶

Return the event loop the Future object is bound to.

Added in version 3.7.

This example creates a Future object, creates and schedules anasynchronous Task to set result for the Future, and waits untilthe Future has a result:

asyncdefset_after(fut,delay,value):# Sleep for *delay* seconds.awaitasyncio.sleep(delay)# Set *value* as a result of *fut* Future.fut.set_result(value)asyncdefmain():# Get the current event loop.loop=asyncio.get_running_loop()# Create a new Future object.fut=loop.create_future()# Run "set_after()" coroutine in a parallel Task.# We are using the low-level "loop.create_task()" API here because# we already have a reference to the event loop at hand.# Otherwise we could have just used "asyncio.create_task()".loop.create_task(set_after(fut,1,'... world'))print('hello ...')# Wait until *fut* has a result (1 second) and print it.print(awaitfut)asyncio.run(main())