[Python-Dev] PEP 411: Provisional packages in the Python standard library

[Steven D'Aprano]

Eric Snow wrote:
> On Fri, Feb 10, 2012 at 8:10 PM, Eli Bendersky <eliben at gmail.com> wrote:
>> On Fri, Feb 10, 2012 at 22:13, Jim J. Jewett <jimjjewett at gmail.com> 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