PEP 411: Provisional packages in the Python standard library
Hi all,
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.
It is pasted below, as well as online at
http://www.python.org/dev/peps/pep-0411/.
Comments are welcome.
Eli
------------------------------------------------
PEP: 411
Title: Provisional packages in the Python standard library
Version: $Revision$
Last-Modified: $Date$
Author: Nick Coghlan
Other than the misspelling of "maintenante" instead of "maintenance", LGTM.
On Fri, Feb 10, 2012 at 09:06, Eli Bendersky
Hi all,
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.
It is pasted below, as well as online at http://www.python.org/dev/peps/pep-0411/.
Comments are welcome.
Eli
------------------------------------------------
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-10 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 marked as "provisional".
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.
Moving a package from the provisional to the stable state simply implies removing this note from its documentation page.
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 packages 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: _______________________________________________ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/brett%40python.org
Eli Bendersky wrote (in http://mail.python.org/pipermail/python-dev/2012-February/116393.html ):
A package will be marked provisional by including the following paragraph as a note at the top of its documentation page:
I really would like some marker available from within Python itself. Use cases: (1) During development, the documentation I normally read first is whatever results from import module; help(module), or possibly dir(module). (2) At BigCorp, there were scheduled times to move as much as possible to the current (or current-1) version. Regardless of policy, full regression test suites don't generally exist. If Python were viewed as part of the infrastructure (rather than as part of a specific application), or if I were responsible for maintaining an internal application built on python, that would be the time to upgrade python -- and I would want an easy way to figure out which applications and libraries I should concentrate on for testing.
* Encapsulation of the import state (PEP 368)
Wrong PEP number. I'm guessing that you meant 406. -- If there are still threading problems with my replies, please email me with details, so that I can try to resolve them. -jJ
On Fri, Feb 10, 2012 at 1:13 PM, Jim J. Jewett
Eli Bendersky wrote (in http://mail.python.org/pipermail/python-dev/2012-February/116393.html ):
A package will be marked provisional by including the following paragraph as a note at the top of its documentation page:
I really would like some marker available from within Python itself.
Use cases:
(1) During development, the documentation I normally read first is whatever results from import module; help(module), or possibly dir(module).
(2) At BigCorp, there were scheduled times to move as much as possible to the current (or current-1) version. Regardless of policy, full regression test suites don't generally exist. If Python were viewed as part of the infrastructure (rather than as part of a specific application), or if I were responsible for maintaining an internal application built on python, that would be the time to upgrade python -- and I would want an easy way to figure out which applications and libraries I should concentrate on for testing.
+1 on both -eric
Jim J. Jewett wrote:
Eli Bendersky wrote (in http://mail.python.org/pipermail/python-dev/2012-February/116393.html ):
A package will be marked provisional by including the following paragraph as a note at the top of its documentation page:
I really would like some marker available from within Python itself.
+1 -- Steven
On Fri, Feb 10, 2012 at 22:13, Jim J. Jewett
Eli Bendersky wrote (in http://mail.python.org/pipermail/python-dev/2012-February/116393.html ):
A package will be marked provisional by including the following paragraph as a note at the top of its documentation page:
I really would like some marker available from within Python itself.
Use cases:
(1) During development, the documentation I normally read first is whatever results from import module; help(module), or possibly dir(module).
(2) At BigCorp, there were scheduled times to move as much as possible to the current (or current-1) version. Regardless of policy, full regression test suites don't generally exist. If Python were viewed as part of the infrastructure (rather than as part of a specific application), or if I were responsible for maintaining an internal application built on python, that would be the time to upgrade python -- and I would want an easy way to figure out which applications and libraries I should concentrate on for testing.
The big problem with this is that it's something that will have to be maintained, so it adds some additional burden (I suppose it will have to be tested as well). An easy way for (2) would be just grepping on the Python docs for the provisional note and seeing which modules have it. Anyhow, I'm not against the idea. I just think it has to be discussed in more detail so all the implications are understood.
* Encapsulation of the import state (PEP 368)
Wrong PEP number. I'm guessing that you meant 406.
Yep, thanks. Fixed. Eli
On Fri, Feb 10, 2012 at 8:10 PM, Eli Bendersky
On Fri, Feb 10, 2012 at 22:13, Jim J. Jewett
wrote: Eli Bendersky wrote (in http://mail.python.org/pipermail/python-dev/2012-February/116393.html ):
A package will be marked provisional by including the following paragraph as a note at the top of its documentation page:
I really would like some marker available from within Python itself.
<snip>
The big problem with this is that it's something that will have to be maintained, so it adds some additional burden (I suppose it will have to be tested as well).
An easy way for (2) would be just grepping on the Python docs for the provisional note and seeing which modules have it.
Anyhow, I'm not against the idea. I just think it has to be discussed in more detail so all the implications are understood.
Is there more to it than having a simple __provisional__ attribute on the module and/or a list at sys.provisional_modules? -eric
On Sat, Feb 11, 2012 at 1:39 PM, Eric Snow
Is there more to it than having a simple __provisional__ attribute on the module and/or a list at sys.provisional_modules?
Yes. As soon as we touch functional code, it because something to be tested and the process overhead on our end is noticeably higher. However, I'd be fine with requiring that a short form for the notice appear at the start of the module docstring. For example: "The API of this module is currently provisional. Refer to the documentation for details." This would then be seen by pydoc and help(), as well as being amenable to programmatic inspection. Also, with a documented provisional status, I think keeping things provisional for as long as it takes us to make up our minds they're right is fine. Cheers, Nick. -- Nick Coghlan | ncoghlan@gmail.com | Brisbane, Australia
On Sat, Feb 11, 2012 at 04:32:56PM +1000, Nick Coghlan wrote:
This would then be seen by pydoc and help(), as well as being amenable to programmatic inspection.
Would using warnings.warn('This is a provisional API and may change radically from' ' release to release', ProvisionalWarning) where ProvisionalWarning is a new exception/warning category (a subclaass of FutureWarning?) be considered too intrusive? -Toshio
On Fri, Feb 10, 2012 at 11:32 PM, Nick Coghlan
On Sat, Feb 11, 2012 at 1:39 PM, Eric Snow
wrote: Is there more to it than having a simple __provisional__ attribute on the module and/or a list at sys.provisional_modules?
Yes. As soon as we touch functional code, it because something to be tested and the process overhead on our end is noticeably higher.
However, I'd be fine with requiring that a short form for the notice appear at the start of the module docstring. For example:
"The API of this module is currently provisional. Refer to the documentation for details."
This would then be seen by pydoc and help(), as well as being amenable to programmatic inspection.
Sounds good enough to me. Realistically, the utility of getting provisional modules distributed with the stdlib far outweighs the theoretical use cases of programmatic inspection. If something like "__provisional__" turns out to be really useful, that bridge can be crossed later. I certainly don't want this PEP bogged down by a relatively superfluous point. :) -eric
Eric Snow wrote:
On Fri, Feb 10, 2012 at 8:10 PM, Eli Bendersky
wrote: On Fri, Feb 10, 2012 at 22:13, Jim J. Jewett
wrote: Eli Bendersky wrote (in http://mail.python.org/pipermail/python-dev/2012-February/116393.html ):
A package will be marked provisional by including the following paragraph as a note at the top of its documentation page: I really would like some marker available from within Python itself.
<snip> The big problem with this is that it's something that will have to be maintained, so it adds some additional burden (I suppose it will have to be tested as well).
"Big problem"? Maintenance of bsddb3 has been a big problem. Maintenance of a single module-level name for provisional packages is a small problem. The PEP already gives boilerplate which is required to go into the documentation of provisional packages. Requiring a top level name, and test for that, is no harder than what's already expected, and it is a constant difficulty regardless of package. In fact, we could (should?) have a single test that applies to all packages in the std lib: for package in packages: if isprovisional(package): assert hasattr(package, '__provisional__') assert package documentation includes boilerplate else: assert not hasattr(package, '__provisional__') assert package documentation does not include boilerplate Arguably, the canonical test for whether a package is provisional or not should be the existence of __provisional__: for package in packages: if hasattr(package, '__provisional__') assert package documentation includes boilerplate else: assert package documentation does not includes boilerplate
An easy way for (2) would be just grepping on the Python docs for the provisional note and seeing which modules have it.
Not all OSes include grep. Not all Python installations include the docs. -- Steven
On Sat, 11 Feb 2012, Steven D'Aprano wrote:
Arguably, the canonical test for whether a package is provisional or not should be the existence of __provisional__:
for package in packages: if hasattr(package, '__provisional__') assert package documentation includes boilerplate else: assert package documentation does not includes boilerplate
Could the documentation generator simply insert the boilerplate if and only if the package has the __provisional__ attribute? I'm not an expert in Python documentation but isn't it generated from properly-formatted comments within the Python source? Isaac Morland CSCF Web Guru DC 2554C, x36650 WWW Software Specialist
On Sun, Feb 12, 2012 at 2:45 AM, Isaac Morland
Could the documentation generator simply insert the boilerplate if and only if the package has the __provisional__ attribute? I'm not an expert in Python documentation but isn't it generated from properly-formatted comments within the Python source?
It can be, but, in the case of the standard library, generally isn't. While there's a certain attraction to using a __provisional__ attribute (checked by both Sphinx and pydoc) to standardise the boilerplate for provisional APIs, I don't think PEP 411 should be conditional on deciding *how* we implement the notices. It should just say "provisional APIs permit well justified changes that would otherwise be disallowed by backwards compatibility concerns, and these are the notices that must be put in place to indicate to users that an API is provisional". Whether we do that via copy-and-paste in the docs and docstring or by a flag in the source code is really an implementation detail separate from the process definition. Cheers, Nick. -- Nick Coghlan | ncoghlan@gmail.com | Brisbane, Australia
On 2/10/2012 9:06 AM, Eli Bendersky wrote:
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 marked as "provisional".
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.
This could be interpreted as limiting provisional status to one release cycle. I suggest that you add 'or continued as provisional'. In particular, if the api *is* changed, another provisional period might be advisable.
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
'as long as' implies no particular limit. -- Terry Jan Reedy
On Fri, Feb 10, 2012 at 23:56, Terry Reedy
On 2/10/2012 9:06 AM, Eli Bendersky wrote:
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 marked as "provisional".
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.
This could be interpreted as limiting provisional status to one release cycle. I suggest that you add 'or continued as provisional'. In particular, if the api *is* changed, another provisional period might be advisable.
I think this was agreed upon when PEP 408 was discussed. Keeping a package provisional for too long is detrimental. Isn't a single release enough to decide that we want something or not? Keep in mind that many users won't touch the provisional packages in production code - we would like to make new parts of the stdlib functional as soon as possible.
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
'as long as' implies no particular limit.
Perhaps it should also? Eli
On Fri, 10 Feb 2012 16:06:15 +0200
Eli Bendersky
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.
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) Regards Antoine.
On Sun, Feb 12, 2012 at 1:20 AM, Antoine Pitrou
On Fri, 10 Feb 2012 16:06:15 +0200 Eli Bendersky
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@gmail.com | Brisbane, Australia
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.
I have updated PEP 411, following the input from this discussion. The updated PEP is at: http://hg.python.org/peps/file/default/pep-0411.txt Changes: - Specified that a package may remain provisional for longer than a single minor release - Shortened the suggested documentation notice, linking to the glossary which will contain the full text - Adding a notice to the package's docstring, which may be programmatically inspected. Eli
participants (11)
-
Antoine Pitrou
-
Brett Cannon
-
Eli Bendersky
-
Eric Snow
-
Isaac Morland
-
Jim J. Jewett
-
Nick Coghlan
-
Stephen J. Turnbull
-
Steven D'Aprano
-
Terry Reedy
-
Toshio Kuratomi