python官方文档怎么样_python官方文档——asyncio

Futures

Future对象用来衔接低级的基于回调函数的代码和高级的async/await代码。

Future函数

asyncio.isfuture(obj)

如果obj是下列情况之一返回True：

一个asyncio.Future实例

一个asyncio.Task实例

一个拥有_asyncio_future_blocking属性的类Future对象(python3.5加入的)

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

返回：

如果obj是Future、Task、类Future对象，返回obj

如果obj是一个corotine对象，返回一个Task包装的对象

如果obj是一个可等待对象，返回一个等待obj的Task对象

如果obj不是上述的对象，会引发TypeError异常。

重要：参考create_task()函数，一个更好的创建Task的方式。

python3.5.5：此函数接受任何awaitable对象。

Future对象

class asyncio.Future(*, loop=None)

一个Future对象表示一个异步操作的结果。不是线程安全的。

Future是一个awaitable对象。协程能等待Future对象直到他们得到一个结果或者抛出一个异常，再或者他们被取消。

典型的，Future被用于基于低级的回调函数代码和高级的async/await代码交互。（例如，使用asyncio transports实现的协议）。

首要规则是，不要在面向用户的API中揭露Future对象，推荐的方式是创建一个Future对象来调用loop.create_future()。这是一种可供选择的和事件循环(event loop)交互的方式，来实现优化他们自己的Future对象。

在3.7中修改：添加支持contextvars模块。

result()

返回Future对象的结果。

如果Future完成并通过set_result()函数产出一个结果，此时结果就被返回了。

如果Future完成并通过set_exceptions()函数返回一个异常，此时方法就会抛出一个异常。

如果Future被取消了，此方法会引发一个CancelledError异常。

如果Future还没有完成，此方法会引发一个InvalidStateError异常。

set_result(result)

标记Future已经完成并设置它的结果。

如果Future已经完成则会抛出一个InvalidStateError异常。

set_exception(exeption)

标记Future已经完成并设置一个异常。

如果Futre已经完成则会抛出一个InvalidStateError。

done()

如果Future完成，则返回True。

如果Future被取消或者通过调用set_result()得到了一个结果，再或者调用set_exception()设置了一个异常时，都会被认为Future已经完成。

cancelled()

如果Future被取消则返回True。

此方法经常被用于检查Future在被设置结果或者异常之前是否被取消。

if not fut.cancelled():

fut.set_result(42)

add_done_callback(callback, *, context=None)

当Future完成时，添加一个回调函数来运行。

回调函数和Future对象作为仅有的参数被调用。

如果当方法被调用时Future已经完成，回调函数被安排和loop.call_soon()一起。

一个可选的，唯一的context参数允许指定一个自定义的contextvars.Context用于运行回调函数。当没有上下文被提供时，使用当前上下文。

functools.partial()被用于给回调函数传递参数，比如:

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

fut.add_done_callback(

functools.partial(print, "Future:"))

在python3.7中被修改：context关键字参数被添加。详情可以参照PEP 567。

remove_done_callback(callback)

从回调函数列表中删除回调函数。

返回被删除的回调函数的数量，一般都是1，除非一个回调函数被添加了多次。

cancel()

取消Future，并安排回调函数。

如果Future已经完成或者被取消了，返回False。否则，把Future的状态改为cancelled，安排回调函数并返回True。

exception()

返回设置在这个Future上的异常。

只有在Future完成时被返回(如果异常没有被设置，返回None)。

如果Future被取消了，这个方法抛出CancelledError异常。

如果Futre还未完成，这个方法抛出InvalidStateError异常。

get_loop()

返回Future绑定了的事件循环。(3.7中加入)

这个例子创建了一个Future对象，创建并安排了一个异步任务来给Future设置结果，等待直到Future有结果：

async def set_after(fut, delay, value):

# Sleep for *delay* seconds.

await asyncio.sleep(delay)

# Set *value* as a result of *fut* Future.

fut.set_result(value)

async def main():

# 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(await fut)

asyncio.run(main())

重要：Future对象被设计用来模仿concurrent.futures.Future。

关键的不同包括下面几点：

和asyncio Future不同，concurrent.futures.Future实例不可被阻塞(await)。

asyncio.Future.result()和asnycio.Future.exception()不接受timeout参数。

asyncio.Future.result()和asnycio.Future.exception()当Future还未完成时抛出一个InvalidStateError异常。

回调函数被asyncio.Future.add_done_callback()注册，没有被立即调用，而是被放在了loop.call_soon()中。

asyncio Future与concurrent.futures.wait()、concurrent.futures.as_completed()不兼容。