All commit authors signed the Contributor License Agreement.

Most changes to Python require a NEWS entry.

Please add it using the blurb_it web app or the blurb command-line tool.

You can ignore the bot; purely documentation changes need neither changelog entries nor issue numbers.

Thank you for the suggestion, but we will decline.

In general, we don't modify the docs in response to someone having a bug in their code especially if the essential details have already been covered. Here, the docs already state, "you can instantiate your own instances of Random() to get generators that don’t share state." That gets to the heart of the matter.

Our style is to word the docs are affirmatively worded and not fill them with "warnings and dangers" unless a significant security risk is present.

It is just a general programming principle that changing a stateful object affects all users and viewers of the object. If a library function calls print() in the middle of a user's print routine, it will commingle the output. There are many examples. There isn't anything special about the random module in the regard.

Thanks again for the suggestion, but I think it doesn't improve the docs (and likely wouldn't have prevented your library author from writing the code the way they did). ISTM this intro section reads better without the programming practices side trip.

@rhettinger -- I think it might be useful to at least note that one of the items of shared state is the seed, which a developer on a quick read through may not realise.

There isn't a 'how to' guide for random at the moment, so I believe the module documentation is the best place. (Such a guide would probably be useful, but a different matter).

A

Thank you for the suggestion, but we will decline.

In general, we don't modify the docs in response to someone having a bug in their code especially if the essential details have already been covered. Here, the docs already state, "you can instantiate your own instances of Random() to get generators that don’t share state." That gets to the heart of the matter.

Does it though? if two authors calling the library exactly as the docs suggest they should, using random.* methods, leads to code behaving unexpectedly in confusing ways, isn't that a warning sign?

Our style is to word the docs are affirmatively worded and not fill them with "warnings and dangers" unless a significant security risk is present.

This is fair, I would be more than happy to reword to be more advice than warning but it seems like there is not much point.

It is just a general programming principle that changing a stateful object affects all users and viewers of the object. If a library function calls print() in the middle of a user's print routine, it will commingle the output. There are many examples. There isn't anything special about the random module in the regard.

TBH I'm not sure that print() is good counterexample of this regard – a print() call from a library doesn't a) cause subtle bugs you may not notice b) modify the behaviour of every subsequent print call you make – the only global state it modifies is the text printed to stdout. Logging config would be a better example, and I would note that logging.basicConfig is carefully designed to try to avoid shared global logging config state getting overwritten by badly-behaved libraries where possible because shared state is a huge problem.

This function does nothing if the root logger already has handlers configured, unless the keyword argument force is set to True.

I'm struggling to think of other examples in the stdlib where global state (not just reading/writing from stdin/stdout) is the important (and also not transparent)

Thanks again for the suggestion, but I think it doesn't improve the docs (and likely wouldn't have prevented your library author from writing the code the way they did). ISTM this intro section reads better without the programming practices side trip.

I mean if the docs said "this way might be a good idea" I'd like to imagine at least some library authors would pay attention to it, otherwise why are the docs there at all? Sure not all would. and I'll try to avoid what you call "side trips" in future suggestions.

@rhettinger -- I think it might be useful to at least note that one of the items of shared state is the seed, which a developer on a quick read through may not realise.

There isn't a 'how to' guide for random at the moment, so I believe the module documentation is the best place. (Such a guide would probably be useful, but a different matter).

A

I think this is better than nothing – I've had a go over at #93755