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.

The ideal way to declare an API as unstable is to constantly change it in a breaking manner.  With every release and potentially even within some patch releases when the point really needs to be made.  Even when you didn't have a reason to change anything.  If you don't do that, people are going to find it convenient, discover stability, assume it exists, depend on it, and complain about breakage no matter what was stated.  https://www.hyrumslaw.com/

One obvious now in hindsight question: Why are any of these APIs even public? They all deserve underscore prefixed names to highlight their private-ness and potential instability.


On Thu, Jun 3, 2021 at 10:46 AM Guido van Rossum <guido@python.org> wrote:
In practice, provisional APIs have been quite stable. The term "provisional" was introduced for PEPs that introduce new modules, where we wanted to allow some wiggle room for changes based on experience with using the new module during the first release cycle where it's made available. You can think of it as a sort of extended beta period for that module only. Generally provisional status only lasts for one release cycle.

"Unstable" has a different meaning -- it's for APIs (including modules) that are likely to change in every release (or most releases, anyway). Users are not discouraged from using these, but they *must* be mindful of their code breaking with every new release.

I could imagine some unstability to allow incompatible changes in bugfix releases, though for my main use case it would be sufficient to only allow those in minor releases.

On Thu, Jun 3, 2021 at 10:32 AM Senthil Kumaran <senthil@python.org> wrote:
On Thu, Jun 03, 2021 at 10:10:53AM -0700, Guido van Rossum wrote:
> This is not a complete thought yet, but it occurred to me that while we have
> deprecated APIs (which will eventually go away), and provisional APIs (which
> must mature a little before they're declared stable), and stable APIs (which
> everyone can rely on), it might be good to also have something like *unstable*
> APIs, which will continually change without ever going away or stabilizing.

The first grey area will between Provisional API vs Unstable API.

Do developers consider provisional APIs as stable and start relying upon
heavily? I am not sure.

I also lack the experience for the use-cases that you are thinking


--Guido van Rossum (python.org/~guido)
Python-Dev mailing list -- python-dev@python.org
To unsubscribe send an email to python-dev-leave@python.org
Message archived at https://mail.python.org/archives/list/python-dev@python.org/message/ZUTAVE3S3QMWNIBGTBDOTJ7M62CTO57R/
Code of Conduct: http://python.org/psf/codeofconduct/