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

Nick Coghlan ncoghlan at gmail.com
Sun Feb 12 04:59:16 CET 2012

On Sun, Feb 12, 2012 at 1:20 AM, Antoine Pitrou <solipsis at pitrou.net> wrote:

On Fri, 10 Feb 2012 16:06:15 +0200 Eli Bendersky <eliben at gmail.com> wrote:

Following the intensive and fruitful discussion of the (now rejected) PEP 408 (http://mail.python.org/pipermail/python-dev/2012-January/115850.html), we've drafted PEP 411 to summarize the conclusions with regards to the process of marking packages provisional. Note that this is an informational PEP, and that for the sake of completeness it duplicates some of the contents of PEP 408. 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.

No, those words are far too strong. "Provisional" is exactly the right word for the meaning we want to convey (see http://dictionary.reference.com/browse/provisional, especially the second sense). Radical changes to provisional modules are highly unlikely (if we're that wrong about a module, we're more likely to just drop it than we are to change it significantly), but tweaks to eliminate rough edges are a real possibility. Truly experimental, unstable code has no place in the standard library in the first place (that's one of the things PyPI is for).

For the record (and the PEP should probably mention this), the end user facing explanation of provisional modules is closely modelled on the one Red Hat use in explaining their Tech Preview concept: https://access.redhat.com/support/offerings/techpreview/

(Unfortunately, Google don't appear to have a clear user facing explanation of the meaning of "experimental" disclaimers in Google App Engine APIs, although it appears such APIs really are closer in nature to being truly experimental than what we're proposing for the stdlib)

Now, what would make sense is to have a definition of "provisional API" in the glossary, and link to that from the module docs, rather than explaining the concept separately in each provisional module.

The notice in each package could then be shortened to:

The <X> API has been included in the standard library on a

provisional basis. Backwards incompatible changes (up to and including removal of the API) may occur if deemed necessary by the standard library developers.

The phrase "provisional basis" would then be a link to the glossary term "provisional API", defined as:

A provisional API is one which has been deliberately excluded from

the standard library's normal backwards compatibility guarantees. While major changes to such APIs are not expected, as long as they are marked as provisional, backwards incompatible changes (up to and including removal of the API) may occur if deemed necessary by the standard library developers. Such changes will not be made gratuitously - they will occur only if serious flaws are uncovered that were missed prior to inclusion of the API.

This process allows the standard library to continue to evolve

over time, without locking in problematic design errors for extended periods of time. See PEP 411 for more details.

Cheers, Nick.

-- Nick Coghlan   |   ncoghlan at gmail.com   |   Brisbane, Australia

More information about the Python-Dev mailing list