Debian Codegraph @

Doc/library/asyncio-policy.rst

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