Documentation for Event objects in threading module could be more clear with a code example.

http://docs.python.org/3.4/library/threading.html#event-objects

I will create a code example by the end of Sunday, April 21.

See the patch with a code example attached.

Example added to threading.rst


For example, the following code demonstrates a controlled thread termination using an event object.  The event is used to request the termination of several threads.

import threading
import time

stopevent = threading.Event()

class TestThread(threading.Thread):
    def run(self):
        """ main control loop """
        print ("Thread ", self.ident, " starts")
        count = 0
        while not stopevent.is_set():
            count += 1
            stopevent.wait(1.0)
            print ("loop ", count, "in thread ", self.ident)
        print ("Thread ", self.ident, " ends")

for i in range (2):
    testthread = TestThread()
    testthread.start()
time.sleep (3)
stopevent.set()

An example should generally show something interesting or non-obvious, which isn't the case here. IMHO an Event is simple enough to use that it doesn't need an example; furthermore, the example you are proposing doesn't really showcase anything interesting, functionally :-)

Thank you for the feedback, Antoine. 

The example shows how to essentially kill threads through an event facilitated request, something that I consider to be useful and non-obvious.

I trust that you and others will make the right decision and will keep your feedback in mind for any future patches.