Clarify what to override when subclassing random.Random
Open
@tim-one is already working on this.
Since Mar 18, 2025.
stdlib
type-bug
- Dominant language
- Python
- Stars
- 77.2k
- Forks
- 35.9k
- PR merge metrics
- PR metrics pending
Description
Documentation
In current documentation about the random.Random class, it said that overriding getrandbits() is optional, so it may make people think just overriding random() is sufficient to control the behavior of the class. But in practice methods like randbytes use getrandbits, which is implemented in C to get randomness from MT19937. So it has the following behavior:
import random
class CustomRand(random.Random):
def random(self):
print("CustomRand.random()") # does not get called
return 0.5
myrand = CustomRand()
myrand.seed(123) # just for demonstrating that randbytes still use MT19937
r1 = myrand.randbytes(4)
random.seed(123)
r2 = random.randbytes(4)
print(r1 == r2) # True
Which shows that overriding random() only is not sufficient. From the issue #84466, this seems to be the expected behavior (or not?). So I think this should be documented that overriding getrandbits() is not optional.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Assessment
This issue has not been assessed yet.