Interactive help for random.randrange omits randrange(stop)

The documentation for package random contains:

function:: randrange(stop)
           randrange(start, stop[, step])

However, if I run help(random.randrange) in the interactive shell (Python 3.10.8 on MacOS), I only get:

randrange(start, stop=None, step=1) method of random.Random instance
    Choose a random item from range(start, stop[, step]).

Same with pydoc random.randrange.

Why is the first instance randrange(stop) missing in the interactive help?

The documentation is from random.rst:

Whereas the help(random.randrange) command looks up the docstring from the source in random.py:

When you call randrange(stop), you’re really calling randrange(start) with default values for stop=None and step=1, and it effectively uses the start value for stop:

And the full docs page actually warns against using keyword arguments, to avoid any unexpected results from this argument juggling:

Keyword arguments should not be used because they can be interpreted
in unexpected ways. For example randrange(start=100) is interpreted
as randrange(0, 100, 1).

Looks like a documentation bug to me.

Another way we could write the function signature would be

randrange([start,] stop[, step])

but the double barreled version

function:: randrange(stop)
           randrange(start, stop[, step])

is probably easier to understand.

I’ll fix this to read::

Choose a random item from range(stop) or range(start, stop[, step]).

Will also add the suggestion to not use keyword arguments because randrange(stop=10) raises a TypeError and randrange(start=10) gives an unexpected result. A stop keyword argument only makes sense when start has been specified: randrange(start=100, stop=200).

1 Like