DOC, API: add random.__init__.pxd and document random.* functions - #14948

Rework the documentation in lines 36-52 to better guide users how to modify existing code to call default_rng

Add the legacy functions below so they are linked into the intersphinx index

Add this note and the See Also fragment to each of the exposed functions

Makes sense, short and to the point.

Per my comment in the random-quick-start, I really don't like the default_rng().whatever() construction. People should not be making a new Generator every line. If it's really important that people have a replacement for the np.random.whatever() calls that fits on one line, make those module-level aliases against a global Generator.

1. Instantiating a new Generator each time means more reading of /dev/urandom. While we don't pull a lot of data from it, it's still a system call, which is slow, and is going to block other processes trying to read it at the same time. If someone is mechanically replacing np.random.whatever() with np.random.default_rng().whatever(), that could be a lot of calls in tight loops.

2. I fear that this usage, especially when presented in this context, is going to engrain the idea that default_rng() returns the default Generator instance rather than creating a new one each time since that was the mental model of np.random.whatever().

+1 on these comments. Perhaps just note the new name of the function when using the default_rng rather than suggesting a specific function call?

Perhaps something along the lines of

New code should use the random method of a default_rng() instance (see random-quick-start for more detail).

is going to engrain the idea that default_rng() returns the default Generator

Perhaps we got the name wrong, and should call this make_default_rng?

At the very least, this sounds like something that needs to be drawn attention to in the docstring of default_rng.

It is. https://docs.scipy.org/doc/numpy/reference/random/generator.html#numpy.random.default_rng

I like the "Use the *** method of a default_rng() instance ..." text. Any other alternatives?

changed

Aren't there more bit generators in randomgen? If so, that seems worth mentioning. Otherwise, this subsection is probably best moved to THANKS.txt, it doesn't help the user.

There are many more there still.

toplevel is kind of an odd word. How about just Functions in numpy.random?

adopting

I'd also remove top-level here. And add a mention that using a Generator instance, as can be obtained from default_rng, should be preferred.

fixing

Let's not encourage the default_rng().whatever() construction.

adopting