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. Examples would be the ast module (since the AST structure changes every time the grammar changes) and anything to do with code objects and bytecode (since we sometimes think of better ways to execute Python).

So maybe the docs should grow a standard way of saying "this is an unstable API"?

Would we need a PEP to create an initial list of APIs (modules, classes, etc.) that are considered unstable?

--
--Guido van Rossum (python.org/~guido)