So using the pep457(?) convention, the function has the signature ([low, ] high), which is perfectly reasonable.

The bug and confusion here is the handling of keyword arguments, not the way in which positional parameters are interpreted (which matches range).

For backwards compatibility, a check could be built in which checks if low is greater than high, in which case the order can be reversed (while raising a warning).

This isn't fully BC since this currently raises an error, and so an error would change to a warning and a vector output. It might have been clearer if this function was called randrange, although I think it would be less discoverable..

Fair points. Would getting rid of the keyword arguments altogether (like range does) be a better solution?

Definitions should perhaps be (like range)

randint(high, *, size=None, dtype='l')
randint(low, high, size=None, dtype='l')

which aren't quite perfect, but would explain the intent.

Instead of re-ordering
it would have been easier if documentation says

high (required)
low (optional, default to 0)

in this way
randint(5) will basically mean randint(high=5) //range is [0,5)

I can create a PR for the same if this makes sense.

Hello, I just came across this issue exactly because I find very confusing the documentation about numpy.random.randint.

The current documentation shows random.randint(low, high=None, size=None, dtype=int) that is quite misleading since one can think that by calling random.randint(a) a will be assigned to low.

I would propose to adopt the same notation used by the official python documentation for the range() function.
The result could be more readable and more clear. In that way it would look like:

random.randint(high, low=0 size=None, dtype=int)
random.randint(low, high, size=None, dtype=int)

Do you think I can directly open a PR for that?

@ffranchina I think that is a good idea. Open one and let's see how the docs render in the PR CI run.

Instead of re-ordering it would have been easier if documentation says

high (required)
low (optional, default to 0)

in this way randint(5) will basically mean randint(high=5) //range is [0,5)

I can create a PR for the same if this makes sense.

Still not resolved in version 1.26 docs, i.e. low is required, high is optional which is wrong.