From 11fb43c9756b5c1aba4fb2b0274a6103e4e13327 Mon Sep 17 00:00:00 2001 From: Eli Bendersky Date: Fri, 10 Feb 2012 07:10:16 +0200 Subject: [PATCH] PEP 411 - Provisional packages in the Python standard library. Initial draft --- pep-0411.txt | 185 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 185 insertions(+) create mode 100644 pep-0411.txt diff --git a/pep-0411.txt b/pep-0411.txt new file mode 100644 index 000000000..b6f0bf38b --- /dev/null +++ b/pep-0411.txt @@ -0,0 +1,185 @@ +PEP: 411 +Title: Provisional packages in the Python standard library +Version: $Revision$ +Last-Modified: $Date$ +Author: Nick Coghlan , + Eli Bendersky +Status: Draft +Type: Informational +Content-Type: text/x-rst +Created: 2012-02-10 +Python-Version: 3.3 +Post-History: 2012-02-xx FIXME + + +Abstract +======== + +The process of including a new package into the Python standard library is +hindered by the API lock-in and promise of backward compatibility implied by +a package being formally part of Python. This PEP describes a methodology +for marking a standard library package "provisional" for the period of a single +minor release. A provisional package may have its API modified prior to +"graduating" into a "stable" state. On one hand, this state provides the +package with the benefits of being formally part of the Python distribution. +On the other hand, the core development team explicitly states that no promises +are made with regards to the the stability of the package's API, which may +change for the next release. While it is considered an unlikely outcome, +such packages may even be removed from the standard library without a +deprecation period if the concerns regarding their API or maintenante prove +well-founded. + + +Proposal - a documented provisional state +========================================= + +Whenever the Python core development team decides that a new package should be +included into the standard library, but isn't entirely sure about whether the +package's API is optimal, the package can be included and placed in a special +"provisional" state. + +In the next minor release, the package may either be "graduated" into a normal +"stable" state in the standard library, or be rejected and removed entirely +from the Python source tree. If the package ends up graduating into the +stable state after being provisional for a minor release, its API may be +changed according to accumulated feedback. The core development team +explicitly makes no guarantees about API stability and backward compatibility +of provisional packages. + +Marking a package provisional +----------------------------- + +A package will be marked provisional by including the following paragraph as +a note at the top of its documentation page: + + The 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. + +Which packages should go through the provisional state +------------------------------------------------------ + +We expect most packages proposed for addition into the Python standard library +to go through a minor release in the provisional state. There may, however, +be some exceptions, such as packages that use a pre-defined API (for example +``lzma``, which generally follows the API of the existing ``bz2`` package), +or packages with an API that has wide acceptance in the Python development +community. + +In any case, packages that are proposed to be added to the standard library, +whether via the provisional state or directly, must fulfill the acceptance +conditions set by PEP 2. + +Criteria for "graduation" +------------------------- + +In principle, most provisional packages should eventually graduate to the +stable standard library. Some reasons for not graduating are: + +* The package may prove to be unstable or fragile, without sufficient developer + support 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-case +basis. The point to emphasize here is that a packages's inclusion in the +standard library as "provisional" in some release does not guarantee it will +continue being part of Python in the next release. + + +Rationale +========= + +Benefits for the core development team +-------------------------------------- + +Currently, the core developers are really reluctant to add new interfaces to +the standard library. This is because as soon as they're published in a +release, API design mistakes get locked in due to backward compatibility +concerns. + +By gating all major API additions through some kind of a provisional mechanism +for a full release, we get one full release cycle of community feedback +before we lock in the APIs with our standard backward compatibility guarantee. + +We can also start integrating provisional packages with the rest of the standard +library early, so long as we make it clear to packagers that the provisional +packages should not be considered optional. The only difference between +provisional APIs and the rest of the standard library is that provisional APIs +are 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 X +are horrible, download this 3rd party library instead", those superior tools +are more likely to be just be an import away. + +For environments where developers are required to conduct due diligence on +their upstream dependencies (severely harming the cost-effectiveness of, or +even ruling out entirely, much of the material on PyPI), the key benefit lies +in ensuring that all modules in the provisional state are clearly under +python-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 via + the standard Python documentation tools (i.e. ReST source, output generated + with Sphinx and published on http://docs.python.org). +* Testing: The package test suites are run on the python.org buildbot fleet + and results published via http://www.python.org/dev/buildbot. +* Issue management: Bugs and feature requests are handled on + http://bugs.python.org +* Source control: The master repository for the software is published + on http://hg.python.org. + + +Candidates for provisional inclusion into the standard library +============================================================== + +For Python 3.3, there are a number of clear current candidates: + +* ``regex`` (http://pypi.python.org/pypi/regex) - approved by Guido [#]_. +* ``daemon`` (PEP 3143) +* ``ipaddr`` (PEP 3144) + +Other possible future use cases include: + +* Improved HTTP modules (e.g. ``requests``) +* HTML 5 parsing support (e.g. ``html5lib``) +* Improved URL/URI/IRI parsing +* A standard image API (PEP 368) +* Encapsulation of the import state (PEP 368) +* Standard event loop API (PEP 3153) +* A binary version of WSGI for Python 3 (e.g. PEP 444) +* Generic function support (e.g. ``simplegeneric``) + + +Rejected alternatives and variations +==================================== + +See PEP 408. + + +References +========== + +.. [#] http://mail.python.org/pipermail/python-dev/2012-January/115962.html + +Copyright +========= + +This document has been placed in the public domain. + + +.. + Local Variables: + mode: indented-text + indent-tabs-mode: nil + sentence-end-double-space: t + fill-column: 70 + coding: utf-8 + End: