On Mon, Jul 22, 2019 at 10:02:12PM -0000, Kyle Stanley wrote about renaming non-public names with a leading underscore:
Good point, this would probably have to be a gradual change if it did happen, rather than being at all once. If it were to happen with a proper deprecation cycle and clear communication, I think it would result in significantly less confusion overall and provide a higher degree of consistency across stdlib in the long term.
You say "significantly less confusion" but I don't think there's much confusion in the first place, so any benefit will be a marginal improvement in clarity, not solving a serious problem. In all my years of using Python, I can only recall one major incident where confusion between public/non-public naming conventions caused a serious problem -- and the details are fuzzy. One of the std lib modules had imported a function for internal use, and then removed it, breaking code that wrongly treated it as part of the public API. So it clearly *does* happen that people misuse private implementation details, but frankly that's going to happen even if we named them all "_private_implementation_detail_dont_use_this_you_have_been_warned" *wink* So in my opinion, "fixing" the std lib to prefix all non-public names to use a leading underscore is going to have only a minor benefit. To that we have to counter with the costs: 1. Somebody has to do the work, review the changes, etc and that takes time and energy that might be better spent on other things. 2. Most abuses of non-public names are harmless; but by deprecating and then changing the name, we guarantee that we'll break people's code, even if it otherwise would have happily worked for years. (Even if it is *strictly speaking* wrong and bad for people to use non-public names in their code, "no harm, no foul" applies: we shouldn't break their code just to make a point.) 3. Leading underscores adds a cost when reading code: against the clarity of "its private" we have the physical cost of reading underscores and the question of how to pronounce them. 4. And the significant cost when writing code. Almost all imports will have to be written like these: import sys as _sys from math import sin as _sin, cos as _cos as well as the mental discipline to ensure that every non-public name in the module is prefixed with an underscore. Let me be frank: you want to shift responsibility of recognising public APIs from the user of the code to the author of the code. Regardless of whether it is worthwhile or not, that's a real cost for developers. That cost is why we have the rule "unless explicitly documented public, all imports are private even if not prefixed with an underscore". All these costs strongly suggest to me that we shouldn't try to "fix" the entire std lib. Let's fix issues when and as they come up, on a case-by-case basis, rather than pre-emptively churning a lot of code. -- Steven