random needs doc for "gauss" versus "normalvariate"

[charlienewey]

BPO	39108
Nosy	@rhettinger, @terryjreedy, @miss-islington, @charlienewey
PRs	bpo-39108: Document threading issues for random.gauss() #22928 [3.9] bpo-39108: Document threading issues for random.gauss() (GH-22928) #22972

^{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-10-25.15:49:05.350>
created_at = <Date 2019-12-20.11:45:13.521>
labels = ['3.8', 'type-feature', '3.7', '3.9', 'docs']
title = 'random needs doc for "gauss" versus "normalvariate"'
updated_at = <Date 2020-10-25.15:49:05.350>
user = 'https://github.com/charlienewey'

bugs.python.org fields:

activity = <Date 2020-10-25.15:49:05.350>
actor = 'rhettinger'
assignee = 'rhettinger'
closed = True
closed_date = <Date 2020-10-25.15:49:05.350>
closer = 'rhettinger'
components = ['Documentation']
creation = <Date 2019-12-20.11:45:13.521>
creator = 'cnewey'
dependencies = []
files = []
hgrepos = []
issue_num = 39108
keywords = ['patch']
message_count = 5.0
messages = ['358703', '358740', '358754', '379580', '379583']
nosy_count = 5.0
nosy_names = ['rhettinger', 'terry.reedy', 'docs@python', 'miss-islington', 'cnewey']
pr_nums = ['22928', '22972']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue39108'
versions = ['Python 3.7', 'Python 3.8', 'Python 3.9']

[charlienewey]

The Python 3 documentation for the "random" module mentions two possible ways to generate a random variate drawn from a normal distribution - "random.gauss" and "random.normalvariate" (see: https://docs.python.org/3/library/random.html#random.gauss).

It's not clear what the distinction is other than apparently the "random.gauss" function is faster. Digging through the source code, it eventually becomes apparent that "random.gauss" is NOT thread safe... but this isn't mentioned in the documentation anywhere.

Further, the documentation doesn't make explicit reference to the particular method used for generating these Gaussian variates.

Basically what I'm getting at is that it's difficult to tell which function ("gauss" or "randomvariate") I should be using. I feel that the documentation could be clarified here. I'm happy to do this in a PR at some point if required.

[terryjreedy]

You could start by posting suggested new text here.