Marking a package provisional

A package will be marked provisional by a notice in its documentation page andits docstring. The following paragraph will be added as a note at the top ofthe documentation page:

The <X> package has been included in the standard library on aprovisional basis. Backwards incompatible changes (up to and includingremoval of the package) may occur if deemed necessary by the coredevelopers.

The phrase “provisional basis” will then be a link to the glossary term“provisional package”, defined as:

A provisional package is one which has been deliberately excluded from thestandard library’s backwards compatibility guarantees. While majorchanges to such packages are not expected, as long as they are markedprovisional, backwards incompatible changes (up to and including removal ofthe package) may occur if deemed necessary by core developers. Such changeswill not be made gratuitously – they will occur only if serious flaws areuncovered that were missed prior to the inclusion of the package.

This process allows the standard library to continue to evolve over time,without locking in problematic design errors for extended periods of time.SeePEP 411 for more details.

The following will be added to the start of the package’s docstring:

The API of this package is currently provisional. Refer to thedocumentation for details.

Moving a package from the provisional to the stable state simply impliesremoving these notes from its documentation page and docstring.

Which packages should go through the provisional state

We expect most packages proposed for addition into the Python standard libraryto go through a feature release in the provisional state. There may, however,be some exceptions, such as packages that use a pre-defined API (for examplelzma, which generally follows the API of the existingbz2 package),or packages with an API that has wide acceptance in the Python developmentcommunity.

In any case, packages that are proposed to be added to the standard library,whether via the provisional state or directly, must fulfill the acceptanceconditions set byPEP 2.

Criteria for “graduation”

In principle, most provisional packages should eventually graduate to thestable standard library. Some reasons for not graduating are:

• The package may prove to be unstable or fragile, without sufficient developersupport to maintain it.
• A much better alternative package may be found during the preview release.

Essentially, the decision will be made by the core developers on a per-casebasis. The point to emphasize here is that a package’s inclusion in thestandard library as “provisional” in some release does not guarantee it willcontinue being part of Python in the next release. At the same time, the barfor making changes in a provisional package is quite high. We expect thatmost of the API of most provisional packages will be unchanged at graduation.Withdrawals are expected to be rare.

Benefits for the core development team

Currently, the core developers are really reluctant to add new interfaces tothe standard library. This is because as soon as they’re published in arelease, API design mistakes get locked in due to backward compatibilityconcerns.

By gating all major API additions through some kind of a provisional mechanismfor a full release, we get one full release cycle of community feedbackbefore we lock in the APIs with our standard backward compatibility guarantee.

We can also start integrating provisional packages with the rest of the standardlibrary early, so long as we make it clear to packagers that the provisionalpackages should not be considered optional. The only difference betweenprovisional APIs and the rest of the standard library is that provisional APIsare explicitly exempted from the usual backward compatibility guarantees.

Benefits for end users

For future end users, the broadest benefit lies in a better “out-of-the-box”experience - rather than being told “oh, the standard library tools for task Xare horrible, download this 3rd party library instead”, those superior toolsare more likely to be just be an import away.

For environments where developers are required to conduct due diligence ontheir upstream dependencies (severely harming the cost-effectiveness of, oreven ruling out entirely, much of the material on PyPI), the key benefit liesin ensuring that all packages in the provisional state are clearly underpython-dev’s aegis from at least the following perspectives:

• Licensing: Redistributed by the PSF under a Contributor Licensing Agreement.
• Documentation: The documentation of the package is published and organized viathe standard Python documentation tools (i.e. ReST source, output generatedwith Sphinx and published onhttp://docs.python.org).
• Testing: The package test suites are run on the python.org buildbot fleetand results published viahttp://www.python.org/dev/buildbot.
• Issue management: Bugs and feature requests are handled onhttp://bugs.python.org
• Source control: The master repository for the software is publishedonhttp://hg.python.org.