[Python-checkins] peps: PEP 411 - Provisional packages in the Python standard library. Initial draft
eli.bendersky
python-checkins at python.org
Fri Feb 10 06:10:32 CET 2012
http://hg.python.org/peps/rev/0ce078bc98d9
changeset: 4042:0ce078bc98d9
user: Eli Bendersky <eliben at gmail.com>
date: Fri Feb 10 07:10:16 2012 +0200
summary:
PEP 411 - Provisional packages in the Python standard library. Initial draft
files:
pep-0411.txt | 185 +++++++++++++++++++++++++++++++++++++++
1 files changed, 185 insertions(+), 0 deletions(-)
diff --git a/pep-0411.txt b/pep-0411.txt
new file mode 100644
--- /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 <ncoghlan at gmail.com>,
+ Eli Bendersky <eliben at gmail.com>
+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 <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.
+
+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:
--
Repository URL: http://hg.python.org/peps
More information about the Python-checkins
mailing list