Seems like the only incompatibility between the proposals is this bit:
If you change this to “if something with an underscore is meant for third-parties to use reliably across [major/minor/micro]-releases, that is a bug” then there’s no inconsistency left.
Our own rules shouldn’t conflate what users/3rd parties should do - they should focus on what we will do. We can then infer good practices for 3rd parties, or they can infer them themselves.
For example, if our rules are “in the absense of documentation[1] an API may be modified in any release. Py*
APIs require documentation and _Py*
APIs do not require any documentation,” then the caller has all the information necessary to decide whether one of our APIs is safe for their context.
If you want to start writing the rules from the POV of the consumer, then you also need to write a separate set of rules for us. But we’re easier to predict, so I’d just start with rules for us and let consumers figure themselves out
Feel free to specify where such documentation should be, to avoid people treating PEPs as docs. ↩︎