[Python-Dev] PEP 408 -- Standard library preview package (original) (raw)

Steven D'Aprano steve at pearwood.info
Fri Jan 27 21:43:46 CET 2012

Eli Bendersky wrote:

Hello,

Following an earlier discussion on python-ideas [1], we would like to propose the following PEP for review. Discussion is welcome.

I think you need to emphasize that modules in preview are NOT expected to have a forward-compatible, stable, API. This is a feature of preview, not a bug, and I believe it is the most important feature.

I see responses to this PEP that assume that APIs will be stable, and that having a module fail to graduate out of preview should be an extraordinary event. But if this is the case, then why bother with preview? It just adds complexity to the process -- if preview.spam and spam are expected to be the same, then just spam straight into the std lib and be done with it.

This PEP only makes sense if we assume that preview.spam and spam will be different, even if only in minor ways, and that there might not even be a spam. There should be no expectation that every preview module must graduate, or that every standard library module must go through preview. If it is stable and uncontroversial, preview adds nothing to the process.

Even when there are candidates for inclusion with relatively stable APIs, like regex, we should assume that there will be API differences between preview.regex and regex, simply because it is less harmful to expect changes that don't eventuate than to expect stability and be surprised by changes.

This, I believe, rules out Antoine's suggestion that modules remain importable from preview even after graduation to a full member of the standard library. We simply can't say have all three of these statements true at the same time:

  1. regular standard library modules are expected to be backward compatible
  2. preview modules are not expected to be forward compatible
  3. preview.spam is an alias to regular standard library spam

At least one of them has to go. Since both 1) and 2) are powerful features, and 3) is only a convenience, the obvious one to drop is 3). I note that the PEP, as it is currently written, explicitly states that preview.spam will be dropped when it graduates to spam. This is a good thing and should not be changed.

Keeping preview.spam around after graduation is, I believe, actively harmful. It adds complexity to the developer's decision-making process ("Should I import spam from preview, or just import spam? What's the difference?"). It gives a dangerous impression that code written for preview.spam will still work for spam.

We should be discouraging simple-minded recipes like

try: import spam except ImportError: from preview import spam spam.foo(a, b, c)

since they undermine the vital feature of preview that the signature and even the existence of spam.foo is subject to change.

I would go further and suggest that preview be explicitly called unstable. If that name is scary, and it frightens some users off, good! The last thing we want is when 3.4 comes around to have dozens of bug reports along the line of "spam.foo() and preview.spam.foo() have different function signatures and aren't compatible". Of course they do. That's why preview.spam existed in the first place, to allow the API to mature without the expectation that it was already stable.

Since preview.spam (or, as I would prefer, unstable.spam) and spam cannot be treated as drop-in replacements, what is preview.spam good for? Without a stable API, preview.spam is not suitable for use in production applications that expect to run under multiple versions of the standard library.

I think the PEP needs more use-cases on who might use preview.spam, and why. These come to my mind:

I am reminded of the long, often acrimonious arguments that took place on Python-Dev a few years back about the API for the ipaddr library. A lot of the arguments could have been short-circuited if we had said "putting ipaddr into preview does not constitute acceptance of its API".

(On the other hand, if preview becomes used in the future for library authors to fob-off criticism for 18 months in the hope it will just be forgotten, then this will be a bad thing.)

-- Steven

More information about the Python-Dev mailing list