gh-108322: Preserve backwards compatibility in NormalDist.samples() when a seed is given

[gpshead]

#108324 switched to a faster implementation of statistics.NormalDist.samples(), but a caveat is that it changes the specific outputs.

This preserves backwards compatibility when the user has asked for specific outputs by supplying a seed value. With an option for them to ask for the new algorithm implementation if desired.

When returning uniquely random values anyway (no seed), the new faster algorithm is used by default.

• Issue: Speed-up statistics.NormalDist.samples() #108322

---

📚 Documentation preview 📚: https://cpython-previews--108658.org.readthedocs.build/

[gpshead]

The existing documentation above this says of seed "this is useful for creation reproducible results, even in a multi-threading context." and the PR this is modifying mentions that random.gauss() is problematic describing the non-gauss version as better for being "more self contained and less vulnerable to concurrency issues (because gauss() is stateful between successive calls)."

I presume we might want call that implementation detail out with a sentence added to the above paragraph recommending the new use_gauss=False argument to people if that caveat matters to them? @rhettinger

[serhiy-storchaka]

It looks as an over-complication to me. Do you really expect users will use use_gauss=False in their code? It is not compatible with Python <=3.12, so it cannot be used in mass for a long time.

The reproducibility warranty in the random module extends only to random() (I would extend it also to randrange(), getrandbits() and few derived methods). Implementations and the output of more complex distributions was changed in the past (otherwise we could not fix bugs which caused losing precision, bias or hanging).

The statistics module do not even provide such warranty. Reproducibility only means that when you run the same Python (same minor version) on the same platform with the same seed you will get the same result. If it was not clear from the documentation, I think that the documentation should be made more clear.

[gpshead]

It could be an over complication. I'm proposing it because this is the kind of conversation that could've happened within the origin unreviewed PR.

Taking a look at how often statistics.NormalDist gets used in our huge codebase at work, it really doesn't (I see 2-3 uses, even including third party PyPI/github python code in my search corpus). And none of them specify a seed.

That's another decent indication that caution about behavior changes on this API aren't worthwhile. Thanks!