On Fri, 4 Jun 2021, 4:17 am Gregory P. Smith, <greg@krypto.org> wrote:
Overall agreement. Your list of ast and code objects and bytecode instructions are thingsĀ that I'd _hope_ people already consider unstable so declaring them as such just makes sense if we're not doing that already.

Another example of a public API that explicitly declares itself unstable is "ssl.get_default_context()" (along with any TLS-enabled API that uses it). It was made that way so the default TLS settings could evolve with the times, even on maintenance branches. The secrets module has a similar caveat on its default token lengths (i.e. making them longer is considered an acceptable API change - if consuming code can't handle that for some reason, it should set an explicit length).

The metaprogramming APIs for customisation of class creation also arguably qualify - we've previously imposed new obligations on metaclass developers as a consequence of adding features like zero-arg super() and the descriptor naming hooks.

It occurs to me that PEP 387 (the backwards compatibility policy) should probably mention that these formally unstable APIs exist, and link to a page in the standard library docs that:

* references the formally unstable APIs
* specifies the points where potentially incompatible changes are allowed (normally new feature releases, but the default SSL/TLS context definition may change in maintenance releases if necessary)