DOC: rename random.random_sample to random.random - #12303

Cannot rename random_sample, it is the "real" function. random.random is simply an alias defined in numpy/random/__init__.py and has no documentation of it's own. Could maybe mention it in the random_sample documentation in a See Also section as an alias.

@rkern @bashtage Do we have a policy going forward about these old convenience aliases?

Sorry, random_sample is part of the API and the official name of this function; it should not be changed. random is an alias to random_sample, which is why it refers to the name random_sample in its docstring; random is random_sample.

numpy.random was designed to be a drop-in replacement for a variety of random number generation code that existed in the Numeric days, both in Numeric and scipy, so there are a few of these aliases around where these different packages had different names for the same functionality.

Do we have a policy going forward about these old convenience aliases?

As far as I'm concerned, they can go through a standard deprecation cycle like we do for any other name changes, if the team wants to.

@streeck Closing for now, please make another PR if you want to pursue this after comments. I notice that numpy itself uses random.random in a number of tests,

charris@fc [numpy.git (master)]$ grep -rl '\brandom\.random\b' numpy
numpy/linalg/tests/test_linalg.py
numpy/linalg/linalg.py
numpy/testing/_private/utils.py
numpy/random/mtrand/mtrand.pyx
numpy/fft/tests/test_helper.py
numpy/polynomial/tests/test_classes.py
numpy/polynomial/tests/test_legendre.py
numpy/polynomial/tests/test_hermite.py
numpy/polynomial/tests/test_chebyshev.py
numpy/polynomial/tests/test_hermite_e.py
numpy/polynomial/tests/test_laguerre.py
numpy/polynomial/tests/test_polynomial.py
numpy/core/tests/test_multiarray.py
numpy/lib/polynomial.py
numpy/lib/tests/test_histograms.py
numpy/lib/tests/test_function_base.py
numpy/lib/tests/test_nanfunctions.py
numpy/lib/tests/test_index_tricks.py
numpy/lib/tests/test_io.py
numpy/lib/tests/test_regression.py

We might want to change those to random_sample. As to what to do about the generated documentation for aliases like this, I'm not sure of the best way forward. We could make them functions and write docstrings, which we will want to do anyway if we ever deprecate them.

The standard way is to give random() its own short docstring which says something like "this is an alias for random_sample, please see the random_sample documentation for more details.

Please don't open a new PR proposing to deprecate random(), there's little to gain from that.

@rgommers At the moment we have

ranf = random = sample = random_sample

So we would need to turn all of those into actual functions.

Indeed, but that's only 2 lines of code + the new docstrings.

Can't we just change

def random_sample(...):
    ...

random = random_sample

to

def random(...):
    ...

random_sample = random

np.random.random has the nice bonus of matching random.random, so in my opinion is the the better name - and making this change has no compatibility ramifications.

? np.random.random and random.random are both aliases for random_sample. Why change that? There is nothing particularly fundamental about random.random and we would still have the documentation problem.