queue example is a sketch

[sblancov]

BPO	40387
Nosy	@rhettinger, @miss-islington, @remilapeyre, @sblancov
PRs	bpo-40387: Fix example code for Queue.join #19713 bpo-40387 Improve queue join() example. #19724 [3.8] bpo-40387: Improve queue join() example. (GH-19724) #19726
Files	example.py: A working example

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = 'https://github.com/rhettinger'
closed_at = <Date 2020-04-27.01:24:14.447>
created_at = <Date 2020-04-25.07:58:55.598>
labels = ['type-feature', '3.8', '3.9', 'docs']
title = 'queue example is a sketch'
updated_at = <Date 2020-04-27.01:24:14.446>
user = 'https://github.com/sblancov'

bugs.python.org fields:

activity = <Date 2020-04-27.01:24:14.446>
actor = 'rhettinger'
assignee = 'rhettinger'
closed = True
closed_date = <Date 2020-04-27.01:24:14.447>
closer = 'rhettinger'
components = ['Documentation']
creation = <Date 2020-04-25.07:58:55.598>
creator = 'Santiago Blanco'
dependencies = []
files = ['49092']
hgrepos = []
issue_num = 40387
keywords = ['patch']
message_count = 8.0
messages = ['367263', '367274', '367279', '367323', '367333', '367336', '367338', '367339']
nosy_count = 6.0
nosy_names = ['rhettinger', 'docs@python', 'python-dev', 'miss-islington', 'remi.lapeyre', 'Santiago Blanco']
pr_nums = ['19713', '19724', '19726']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue40387'
versions = ['Python 3.8', 'Python 3.9']

[sblancov]

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.

[remilapeyre]

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?

[rhettinger]

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