Skip to content

More informative docstrings in the random module #109745

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 7 commits into from
Sep 26, 2023

Conversation

rhettinger
Copy link
Contributor

Add the expected mean and variance to the docstrings. It helps with understanding the parameters which is important because conventions vary. Also, it would save someone like me from having to look these up periodically.

@AA-Turner AA-Turner added the needs backport to 3.11 only security fixes label Sep 22, 2023
@AA-Turner
Copy link
Member

I think it may also be worth updating the documentation to include this information, to quickly refer to it without opening an interpreter.

A

@rhettinger
Copy link
Contributor Author

rhettinger commented Sep 24, 2023

FWIW here's session showing actual versus expected:

>>> from random import uniform, triangular, expovariate, gammavariate, betavariate, binomialvariate
>>> from statistics import mean, variance
>>> n = 10 ** 6

>>> a, b = 75, 20
>>> mean(uniform(a, b) for i in range(n)), (a + b) / 2
(47.514550556196895, 47.5)
>>> variance(uniform(a, b) for i in range(n)), (b - a) ** 2 / 12
(252.13423065351284, 252.08333333333334)

>>> low, high, mode = 100, 150, 110
>>> mean(triangular(low, high, mode) for i in range(n)), (low + high + mode) / 3
(120.0327029921039, 120.0)
>>> variance(triangular(low, high, mode) for i in range(n)), (low**2 + high**2 + mode**2 - low*high - low*mode - high*mode) / 18
(116.58565949632437, 116.66666666666667)

>>> lambd = 0.625
>>> mean(expovariate(lambd) for i in range(n)), 1 / lambd
(1.6019558105152012, 1.6)
>>> variance(expovariate(lambd) for i in range(n)), 1 / lambd ** 2
(2.5613327986115277, 2.56)

>>> alpha = 1.5; beta = 0.625
>>> mean(gammavariate(alpha, beta) for i in range(n)), alpha * beta
(0.9361273191982766, 0.9375)
>>> variance(gammavariate(alpha, beta) for i in range(n)), alpha * beta ** 2
(0.5886486276596401, 0.5859375)

>>> alpha = 5; beta = 8
>>> mean(betavariate(alpha, beta) for i in range(n)), alpha / (alpha + beta)
(0.38450002539757394, 0.38461538461538464)
>>> variance(betavariate(alpha, beta) for i in range(n)), alpha * beta / ((alpha + beta)**2 * (alpha + beta + 1))
(0.016937933060186688, 0.0169061707523246)

>>> n = 25; p = 0.375
>>> mean(binomialvariate(n, p) for i in range(n)), n * p
(9.28, 9.375)
>>> variance(binomialvariate(n, p) for i in range(n)), n * p * (1 - p)
(5.333333333333333, 5.859375)

@rhettinger rhettinger merged commit 19bf398 into python:main Sep 26, 2023
@miss-islington
Copy link
Contributor

Thanks @rhettinger for the PR 🌮🎉.. I'm working now to backport this PR to: 3.11, 3.12.
🐍🍒⛏🤖

@miss-islington
Copy link
Contributor

Sorry, @rhettinger, I could not cleanly backport this to 3.11 due to a conflict.
Please backport using cherry_picker on command line.
cherry_picker 19bf3986958fc8269a1eb6d741bb60c91d6b5e58 3.11

miss-islington pushed a commit to miss-islington/cpython that referenced this pull request Sep 26, 2023
(cherry picked from commit 19bf398)

Co-authored-by: Raymond Hettinger <[email protected]>
@miss-islington miss-islington assigned rhettinger and unassigned tim-one Sep 26, 2023
@bedevere-app
Copy link

bedevere-app bot commented Sep 26, 2023

GH-109905 is a backport of this pull request to the 3.12 branch.

@bedevere-app bedevere-app bot removed the needs backport to 3.12 only security fixes label Sep 26, 2023
@AA-Turner
Copy link
Member

@rhettinger -- what are your thoughts on including these data in the documentation for random? I'm happy to prepare a PR if you don't object.

A

csm10495 pushed a commit to csm10495/cpython that referenced this pull request Sep 28, 2023
@rhettinger
Copy link
Contributor Author

@AA-Turner I don't think this needs to be in the main docs. It is more of an on-line reference.

@rhettinger rhettinger deleted the random_docstrings branch September 29, 2023 19:44
Yhg1s pushed a commit that referenced this pull request Oct 2, 2023
…109905)

More informative docstrings in the random module (gh-109745)
(cherry picked from commit 19bf398)

Co-authored-by: Raymond Hettinger <[email protected]>
Glyphack pushed a commit to Glyphack/cpython that referenced this pull request Sep 2, 2024
@ZeroIntensity ZeroIntensity removed the needs backport to 3.11 only security fixes label Feb 17, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
docs Documentation in the Doc dir skip issue skip news
Projects
None yet
Development

Successfully merging this pull request may close these issues.

5 participants