classification
Title: random needs doc for "gauss" versus "normalvariate"
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.9, Python 3.8, Python 3.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: rhettinger Nosy List: cnewey, docs@python, miss-islington, rhettinger, terry.reedy
Priority: normal Keywords: patch

Created on 2019-12-20 11:45 by cnewey, last changed 2020-10-25 15:49 by rhettinger. This issue is now closed.

Pull Requests
URL Status Linked Edit
PR 22928 merged rhettinger, 2020-10-23 22:40
PR 22972 merged miss-islington, 2020-10-25 14:59
Messages (5)
msg358703 - (view) Author: Charles Newey (cnewey) Date: 2019-12-20 11:45
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.
msg358740 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2019-12-20 21:49
You could start by posting suggested new text here.
msg358754 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2019-12-21 01:54
I can make the update for you.
msg379580 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2020-10-25 14:59
New changeset 3cde3788b68bce7deee1e6d31e265bbfce337731 by Raymond Hettinger in branch 'master':
bpo-39108: Document threading issues for random.gauss() (GH-22928)
https://github.com/python/cpython/commit/3cde3788b68bce7deee1e6d31e265bbfce337731
msg379583 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2020-10-25 15:48
New changeset af891a962b62268d76ace0d4768ab0e1934a2cd1 by Miss Skeleton (bot) in branch '3.9':
bpo-39108: Document threading issues for random.gauss() (GH-22928) (GH-22972)
https://github.com/python/cpython/commit/af891a962b62268d76ace0d4768ab0e1934a2cd1
History
Date User Action Args
2020-10-25 15:49:05rhettingersetstatus: open -> closed
resolution: fixed
stage: patch review -> resolved
2020-10-25 15:48:41rhettingersetmessages: + msg379583
2020-10-25 14:59:23miss-islingtonsetnosy: + miss-islington
pull_requests: + pull_request21887
2020-10-25 14:59:09rhettingersetmessages: + msg379580
2020-10-23 22:40:07rhettingersetkeywords: + patch
stage: patch review
pull_requests: + pull_request21850
2020-02-03 21:30:07mark.dickinsonsetnosy: - mark.dickinson
2019-12-21 01:54:16rhettingersetassignee: docs@python -> rhettinger
messages: + msg358754
2019-12-20 21:49:30terry.reedysetnosy: + terry.reedy
title: Documentation for "random.gauss" vs "random.normalvariate" is lacking -> random needs doc for "gauss" versus "normalvariate"
messages: + msg358740

versions: - Python 3.5, Python 3.6
2019-12-20 11:54:56xtreaksetnosy: + rhettinger, mark.dickinson
2019-12-20 11:45:13cneweycreate