Copy the example of the next URL:

https://docs.python.org/3/library/queue.html#queue.Queue.join

and paste into a file, then try to run it. It does not work.

I have tried a new one (attachment) that works.

In general examples in the documentation may lack some things like imports as they are implicit but in this case it also lack do_work(), source() and num_worker_threads.

You could use os.cpu_count() instead of your hard-coded value and the comment.

Can you open a pull request with your change?

The example is supposed to be a sketch of the overall pattern.  IMO, putting concrete and useless implementations of do_work() and source() make the example less intelligible.

Instead, we can add a note that the user needs to supply their own do_work() and source().

I am trying to help, if you want I change something of my PR tell me what.

I think most people need concrete examples to learn anything, but I may be wrong.

I consider that a note will not change anything.

I'm thinking of simplifying the example to focus on its core goal of demonstrating how to enqueue tasks and then wait for them to be finished:

    import threading, queue

    q = queue.Queue()

    def worker():
        while True:
            item = q.get()
            print(f'Working on {item}')
            print(f'Finished {item}')
            q.task_done()

    # turn-on the worker thread
    worker_thread = threading.Thread(target=worker)
    worker_thread.daemon = True
    worker_thread.start()

    # send thirty task requests to the worker
    for item in range(30):
        q.put(item)
    print('All task requests sent\n', end='')    

    # block until all tasks are done
    q.join()
    print('All work completed')

That is pretty clear! Thank you Raymond.

New changeset 88499f15f547ccf7b15d37b0eaf51cc40bad5c39 by Raymond Hettinger in branch 'master':
bpo-40387: Improve queue join() example. (GH-19724)
https://github.com/python/cpython/commit/88499f15f547ccf7b15d37b0eaf51cc40bad5c39

New changeset 179f22c3b786ce9baa3445923f8f9708dfa5d5b7 by Miss Islington (bot) in branch '3.8':
bpo-40387: Improve queue join() example. (GH-19724) (GH-19726)
https://github.com/python/cpython/commit/179f22c3b786ce9baa3445923f8f9708dfa5d5b7