| 1 |
.. currentmodule:: asyncio |
| 2 |
|
| 3 |
|
| 4 |
.. _asyncio-policies: |
| 5 |
|
| 6 |
======== |
| 7 |
Policies |
| 8 |
======== |
| 9 |
|
| 10 |
.. warning:: |
| 11 |
|
| 12 |
Policies are deprecated and will be removed in Python 3.16. |
| 13 |
Users are encouraged to use the :func:`asyncio.run` function |
| 14 |
or the :class:`asyncio.Runner` with *loop_factory* to use |
| 15 |
the desired loop implementation. |
| 16 |
|
| 17 |
|
| 18 |
An event loop policy is a global object |
| 19 |
used to get and set the current :ref:`event loop <asyncio-event-loop>`, |
| 20 |
as well as create new event loops. |
| 21 |
The default policy can be :ref:`replaced <asyncio-policy-get-set>` with |
| 22 |
:ref:`built-in alternatives <asyncio-policy-builtin>` |
| 23 |
to use different event loop implementations, |
| 24 |
or substituted by a :ref:`custom policy <asyncio-custom-policies>` |
| 25 |
that can override these behaviors. |
| 26 |
|
| 27 |
The :ref:`policy object <asyncio-policy-objects>` |
| 28 |
gets and sets a separate event loop per *context*. |
| 29 |
This is per-thread by default, |
| 30 |
though custom policies could define *context* differently. |
| 31 |
|
| 32 |
Custom event loop policies can control the behavior of |
| 33 |
:func:`get_event_loop`, :func:`set_event_loop`, and :func:`new_event_loop`. |
| 34 |
|
| 35 |
Policy objects should implement the APIs defined |
| 36 |
in the :class:`AbstractEventLoopPolicy` abstract base class. |
| 37 |
|
| 38 |
|
| 39 |
.. _asyncio-policy-get-set: |
| 40 |
|
| 41 |
Getting and Setting the Policy |
| 42 |
============================== |
| 43 |
|
| 44 |
The following functions can be used to get and set the policy |
| 45 |
for the current process: |
| 46 |
|
| 47 |
.. function:: get_event_loop_policy() |
| 48 |
|
| 49 |
Return the current process-wide policy. |
| 50 |
|
| 51 |
.. deprecated:: 3.14 |
| 52 |
The :func:`get_event_loop_policy` function is deprecated and |
| 53 |
will be removed in Python 3.16. |
| 54 |
|
| 55 |
.. function:: set_event_loop_policy(policy) |
| 56 |
|
| 57 |
Set the current process-wide policy to *policy*. |
| 58 |
|
| 59 |
If *policy* is set to ``None``, the default policy is restored. |
| 60 |
|
| 61 |
.. deprecated:: 3.14 |
| 62 |
The :func:`set_event_loop_policy` function is deprecated and |
| 63 |
will be removed in Python 3.16. |
| 64 |
|
| 65 |
|
| 66 |
.. _asyncio-policy-objects: |
| 67 |
|
| 68 |
Policy Objects |
| 69 |
============== |
| 70 |
|
| 71 |
The abstract event loop policy base class is defined as follows: |
| 72 |
|
| 73 |
.. class:: AbstractEventLoopPolicy |
| 74 |
|
| 75 |
An abstract base class for asyncio policies. |
| 76 |
|
| 77 |
.. method:: get_event_loop() |
| 78 |
|
| 79 |
Get the event loop for the current context. |
| 80 |
|
| 81 |
Return an event loop object implementing the |
| 82 |
:class:`AbstractEventLoop` interface. |
| 83 |
|
| 84 |
This method should never return ``None``. |
| 85 |
|
| 86 |
.. versionchanged:: 3.6 |
| 87 |
|
| 88 |
.. method:: set_event_loop(loop) |
| 89 |
|
| 90 |
Set the event loop for the current context to *loop*. |
| 91 |
|
| 92 |
.. method:: new_event_loop() |
| 93 |
|
| 94 |
Create and return a new event loop object. |
| 95 |
|
| 96 |
This method should never return ``None``. |
| 97 |
|
| 98 |
.. deprecated:: 3.14 |
| 99 |
The :class:`AbstractEventLoopPolicy` class is deprecated and |
| 100 |
will be removed in Python 3.16. |
| 101 |
|
| 102 |
|
| 103 |
.. _asyncio-policy-builtin: |
| 104 |
|
| 105 |
asyncio ships with the following built-in policies: |
| 106 |
|
| 107 |
|
| 108 |
.. class:: DefaultEventLoopPolicy |
| 109 |
|
| 110 |
The default asyncio policy. Uses :class:`SelectorEventLoop` |
| 111 |
on Unix and :class:`ProactorEventLoop` on Windows. |
| 112 |
|
| 113 |
There is no need to install the default policy manually. asyncio |
| 114 |
is configured to use the default policy automatically. |
| 115 |
|
| 116 |
.. versionchanged:: 3.8 |
| 117 |
|
| 118 |
On Windows, :class:`ProactorEventLoop` is now used by default. |
| 119 |
|
| 120 |
.. versionchanged:: 3.14 |
| 121 |
The :meth:`get_event_loop` method of the default asyncio policy now |
| 122 |
raises a :exc:`RuntimeError` if there is no set event loop. |
| 123 |
|
| 124 |
.. deprecated:: 3.14 |
| 125 |
The :class:`DefaultEventLoopPolicy` class is deprecated and |
| 126 |
will be removed in Python 3.16. |
| 127 |
|
| 128 |
|
| 129 |
.. class:: WindowsSelectorEventLoopPolicy |
| 130 |
|
| 131 |
An alternative event loop policy that uses the |
| 132 |
:class:`SelectorEventLoop` event loop implementation. |
| 133 |
|
| 134 |
.. availability:: Windows. |
| 135 |
|
| 136 |
.. deprecated:: 3.14 |
| 137 |
The :class:`WindowsSelectorEventLoopPolicy` class is deprecated and |
| 138 |
will be removed in Python 3.16. |
| 139 |
|
| 140 |
|
| 141 |
.. class:: WindowsProactorEventLoopPolicy |
| 142 |
|
| 143 |
An alternative event loop policy that uses the |
| 144 |
:class:`ProactorEventLoop` event loop implementation. |
| 145 |
|
| 146 |
.. availability:: Windows. |
| 147 |
|
| 148 |
.. deprecated:: 3.14 |
| 149 |
The :class:`WindowsProactorEventLoopPolicy` class is deprecated and |
| 150 |
will be removed in Python 3.16. |
| 151 |
|
| 152 |
|
| 153 |
.. _asyncio-custom-policies: |
| 154 |
|
| 155 |
Custom Policies |
| 156 |
=============== |
| 157 |
|
| 158 |
To implement a new event loop policy, it is recommended to subclass |
| 159 |
:class:`DefaultEventLoopPolicy` and override the methods for which |
| 160 |
custom behavior is wanted, e.g.:: |
| 161 |
|
| 162 |
class MyEventLoopPolicy(asyncio.DefaultEventLoopPolicy): |
| 163 |
|
| 164 |
def get_event_loop(self): |
| 165 |
"""Get the event loop. |
| 166 |
|
| 167 |
This may be None or an instance of EventLoop. |
| 168 |
""" |
| 169 |
loop = super().get_event_loop() |
| 170 |
# Do something with loop ... |
| 171 |
return loop |
| 172 |
|
| 173 |
asyncio.set_event_loop_policy(MyEventLoopPolicy()) |