[Python-Dev] PEP 411: Provisional packages in the Python standard library (original) (raw)

Stephen J. Turnbull stephen at xemacs.org
Mon Feb 13 04:36:37 CET 2012

Antoine Pitrou writes:

I think the word "provisional" doesn't mean anything to many (non-native English speaking) people. I would like to suggest something clearer, e.g. "experimental" or "unstable" - which have the benefit of already having a meaning in other software-related contexts.

I sympathize, but unfortunately, as Nick points out, those words have different and inappropriate meanings, which will definately mislead and confuse native speakers. Nor is "provisional" a difficult concept, as I understand it. At the very least, it has an exact translation into Japanese, which makes it about as hard to find exact translations as I can imagine a human language could!

The <X> package has been included in the standard library on a
provisional basis. While major changes are not anticipated, as long as
this notice remains in place, backwards incompatible changes are
permitted if deemed necessary by the standard library developers. Such
changes will not be made gratuitously - they will occur only if
serious API flaws are uncovered that were missed prior to inclusion of
the package.

That's too wordy. Let's stay clear and to the point:

"This package is unstable/experimental. Its API may change in the next release."

(and put a link to the relevant FAQ section if necessary)

How about this?

This is a `provisional package`__.  Its API may change in the next
release.

__ faq#provisional_package

and the linked FAQ will also link to the full PEP and a dictionary definition.

More information about the Python-Dev mailing list