module random: randint() range error

[GitHubsSilverBullet]

Port, board and/or hardware

rp2

MicroPython version

MicroPython v1.26.0 on 2025-08-09; Raspberry Pi Pico with RP2040

The upper limit of the randint(a,b) doesn't behave as described in the documentation.

Reproduction

#!/micropython
# -*- coding: UTF-8 -*-
# vim: fileencoding=utf-8: ts=4: sw=4: expandtab:
import random

print('random.randint(a, b)')
print('    Return a random integer in the range [a, b] (INCLUDING!)')
print()
for VALUE in (2**31-1, 2**31 ,2**32-1):
    try:
        print(f'Testing {VALUE}: ', end='')
        print(f'{random.randint(0,VALUE)}  OK')
    except OverflowError as oe:
        print(f'Exception: {oe} ({VALUE})')

Expected behaviour

Expected to work up to the upper limit of 2³² - 1

Observed behaviour

random.randint(a, b)
    Return a random integer in the range [a, b] (INCLUDING!)

Testing 2147483647: 2094930763  OK
Testing 2147483648: Exception: overflow converting long int to machine word (2147483648)
Testing 4294967295: Exception: overflow converting long int to machine word (4294967295)

Additional Information

No, I've provided everything above.

Code of Conduct

Yes, I agree

[robert-hh]

The maximum range should be documented.

[GitHubsSilverBullet]

Yes, it should be documented as -2³¹+1 … 2³¹ - 1. One could then calculate:
result_u32 = randint(-2**31+1, 2**31-1) + 2**31
Basically unreadable code, but working.

[robert-hh]

Actually is is documented: https://docs.micropython.org/en/latest/genrst/modules.html#random
That may be not the first place to look for.

[GitHubsSilverBullet]

That may be not the first place to look for.

How true. But I agree, if the full range is needed (or a multiple on 2ⁿ), in other word for 32 in 4 billion cases, than that's the way to go.
For all other cases it wouldn't work. ;-)