classification
Title: random.getrandbits: Should it be explicit that it returns unsigned/non-negative integer?
Type: Stage: resolved
Components: Documentation Versions: Python 3.10, Python 3.9
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: rhettinger Nosy List: ZackerySpytz, miss-islington, pfalcon, rhettinger
Priority: low Keywords: patch

Created on 2020-12-03 17:53 by pfalcon, last changed 2020-12-19 03:10 by rhettinger. This issue is now closed.

Pull Requests
URL Status Linked Edit
PR 23667 closed ZackerySpytz, 2020-12-07 00:56
PR 23843 merged rhettinger, 2020-12-18 18:10
PR 23851 merged miss-islington, 2020-12-19 01:03
Messages (5)
msg382434 - (view) Author: Paul Sokolovsky (pfalcon) * Date: 2020-12-03 17:53
Current docs for random.getrandbits() ( https://docs.python.org/3/library/random.html#random.getrandbits ) read (3.9.1rc1 at the top of the page):

Returns a Python integer with k random bits. This method is supplied with the MersenneTwister generator and some other generators may also provide it as an optional part of the API. When available, getrandbits() enables randrange() to handle arbitrarily large ranges.

So, based that it talks about "bits", it's easy to imagine that the result is unsigned. But it's interesting that it mentions "a Python integer", not even just "integer". And Python integers are known to be signed.

So I'd say, there's enough of ambiguity in there, and would be nice to explicitly specify that it's "unsigned (non-negative) Python integer".


If there's interest for the background of concern, some implementations may have "small" and "large" integers underlyingly (which used to be exposed at the user-level in Python2). "Small" integers would be cheaper, but of course, they would be signed. So, at certain value of getrandbits() parameter, there may be a temptation to use up a sign bit of a small integer, instead of going straight to allocating expensive large integer. It should be clear this is NOT a valid "optimization", and result should be always non-negative.
msg382466 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2020-12-04 06:47
Do you care to propose a minimal PR adding the word "unsigned"?

Marking as low priority because the referenced docs are over a decade old and we've not seen a single case of someone being confused by it.
msg382622 - (view) Author: Paul Sokolovsky (pfalcon) * Date: 2020-12-07 08:01
Raymond Hettinger: Thanks for acking it would be a useful change!

ZackerySpytz: Thanks for making a patch!
msg383345 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2020-12-19 01:03
New changeset 5646414ae1fce620b919056f7999dfd15da78e9c by Raymond Hettinger in branch 'master':
bpo-42559: Not that getrandbits() is non-negative. (GH-23843)
https://github.com/python/cpython/commit/5646414ae1fce620b919056f7999dfd15da78e9c
msg383354 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2020-12-19 03:10
New changeset d458d8dab0abaf781c923f80f8eb832d0c683e88 by Miss Islington (bot) in branch '3.9':
bpo-42559: Not that getrandbits() is non-negative. (GH-23843) (GH-23851)
https://github.com/python/cpython/commit/d458d8dab0abaf781c923f80f8eb832d0c683e88
History
Date User Action Args
2020-12-19 03:10:57rhettingersetstatus: open -> closed
resolution: fixed
stage: patch review -> resolved
2020-12-19 03:10:15rhettingersetmessages: + msg383354
2020-12-19 01:03:22miss-islingtonsetnosy: + miss-islington
pull_requests: + pull_request22715
2020-12-19 01:03:17rhettingersetmessages: + msg383345
2020-12-18 18:10:01rhettingersetpull_requests: + pull_request22704
2020-12-07 08:01:08pfalconsetmessages: + msg382622
2020-12-07 00:56:56ZackerySpytzsetkeywords: + patch
nosy: + ZackerySpytz

pull_requests: + pull_request22534
stage: patch review
2020-12-04 06:47:29rhettingersetpriority: normal -> low

assignee: rhettinger
components: + Documentation
versions: + Python 3.10
nosy: + rhettinger

messages: + msg382466
2020-12-03 17:53:56pfalconcreate