Not sure if this is covered anywhere already, feel free to close if this is the case.

Without having the numpy documentation open, and just looking at the argument names for random.randint, the results I got were.. confusing, to say the least.

Without looking at the docs, what would the following code do: random.randint(low=2, size=5)?
My guess would be that it would give back five integers larger than or equal to 2. However, the result was quite different: array([1, 0, 0, 1, 1]).

Wait, so I specified low=2, but got back numbers which are all lower than low? What the...

The docs didn't help much at first, either: "unless high=None, in which case this parameter is one above the highest such integer" - what? Until I stumbled upon this: "If high is None (the default), then results are from [0, low)."

So high and low are switched based on the value of one of the parameters, which makes things very confusing. Much cleaner would be the following function definition:

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

Of course, this would not permit something like randint(1, 2), but randint(low=1, high=2) is arguably more readable anyway. 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).