Eric Snow wrote:
On Fri, Feb 10, 2012 at 8:10 PM, Eli Bendersky <eli...@gmail.com> wrote:
On Fri, Feb 10, 2012 at 22:13, Jim J. Jewett <jimjjew...@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
_______________________________________________
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/archive%40mail-archive.com
