bpo-31950: Improve event loop policy doc (#4306)

pitrou · web-flow · commit 4135c8939572 · 2017-11-07T10:26:32.000+01:00
diff --git a/Doc/library/asyncio-eventloops.rst b/Doc/library/asyncio-eventloops.rst
@@ -148,10 +148,9 @@ process based on the calling context. A policy is an object implementing the
 :class:`AbstractEventLoopPolicy` interface.
 
 For most users of :mod:`asyncio`, policies never have to be dealt with
-explicitly, since the default global policy is sufficient.
+explicitly, since the default global policy is sufficient (see below).
 
-The default policy defines context as the current thread, and manages an event
-loop per thread that interacts with :mod:`asyncio`. The module-level functions
+The module-level functions
 :func:`get_event_loop` and :func:`set_event_loop` provide convenient access to
 event loops managed by the default policy.
 
@@ -189,6 +188,13 @@ An event loop policy must implement the following interface:
       context, :meth:`set_event_loop` must be called explicitly.
 
 
+The default policy defines context as the current thread, and manages an event
+loop per thread that interacts with :mod:`asyncio`.  If the current thread
+doesn't already have an event loop associated with it, the default policy's
+:meth:`~AbstractEventLoopPolicy.get_event_loop` method creates one when
+called from the main thread, but raises :exc:`RuntimeError` otherwise.
+
+
 Access to the global loop policy
 --------------------------------
 
@@ -200,3 +206,24 @@ Access to the global loop policy
 
    Set the current event loop policy. If *policy* is ``None``, the default
    policy is restored.
+
+
+Customizing the event loop policy
+---------------------------------
+
+To implement a new event loop policy, it is recommended you subclass the
+concrete default event loop policy :class:`DefaultEventLoopPolicy`
+and override the methods for which you want to change behavior, for example::
+
+    class MyEventLoopPolicy(asyncio.DefaultEventLoopPolicy):
+
+        def get_event_loop(self):
+            """Get the event loop.
+
+            This may be None or an instance of EventLoop.
+            """
+            loop = super().get_event_loop()
+            # Do something with loop ...
+            return loop
+
+    asyncio.set_event_loop_policy(MyEventLoopPolicy())
