On Fri, 4 Jun 2021, 4:17 am Gregory P. Smith, email@example.com 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)