[Python-Dev] "Provisional" considered harmful? [was: PEP 455: TransformDict]

[Stephen J. Turnbull]

As will become evident, I disagree with Steven at almost every point.
However, I think his point about users not reading documentation is
well-taken.  Due to hyperlinking, users are very likely to skip past
module docstrings.  I suggest two (perhaps informal) additions to the
documentation policy in PEP 411:

    (1) Provisional packages should be explicitly described as such in
        release announcements.  I think this is done already, cf.
        "Improvements in email" in the Release announcement and What's
        New for Python 3.3.0.[1]  However the policy should be explicit
        and the word "provisional" should be emphasized and linked to
        PEP 411.

    (2) Individual APIs in those packages should be documented as
        provisional.

Steven D'Aprano writes:

 > - Since people cannot rely on provisional features still being available 
 > in the future, if they care the slightest about forward compatibility, 
 > they dare not use them.

You exaggerate to the extent that you harm your argument.  People make
tradeoffs.  Some will choose the extreme you describe here, others
will take more risk.  Your real argument is that the benefits are
small because you expect that provisional stdlib packages will not get
much if any additional use over PyPI packages.  Can't know without
trying ... thus, the PEP.  Similar considerations apply to your other
arguments.

 > None of these arguments are documented in the PEP, let alone refuted.

They're not real arguments, as stated.  If you rephrase them as actual
arguments, they turn out to merely be the "half-empty" phrasing of the
"half-full" arguments used in favor.  Can't know without trying.

 > I don't think that "provisional" helps end users at all. If anything, it 
 > hurts them -- it means more uncertainty and doubt.

True, it *increases* the uncertainty *inside* the stdlib.  On the flip
side, it decreases uncertainty *overall* by announcing that the core
developers *want* this feature in stdlib *now*, and probably the API
won't change *at all*, and very probably the API won't change "much".

 > But for provisional packages, that promise doesn't apply, and
 > although PEP 411 says that packages won't be gratuitously removed,
 > I have to assume that any provisional package in version 3.x could
 > be gone without notice or warning in 3.x+1.

It's unlikely it will be "gone", it will end up on PyPI.

 > I don't see how that helps me.

Since you evidently demand absolute certainty, you're right, it
doesn't help you with respect to any given provisional package.  I'm
more flexible, and I greatly value having the core developers evaluate
the modules on PyPI (or the modules that have only seen the
flourescent lights of Google Labs up to now) for me, and putting their
Good Codesmithing Stamp of Approval on some of them more quickly.

And if in fact the policy works in the sense that more code gets into
the stdlib (non-provisionally) faster than without the PEP, in the
long run *you* benefit even with if you adopt a policy of using only
non-provisional APIs.

 > The PEP has a lengthy section that claims to be about how it will
 > help end users. It actually isn't -- it is about how inclusion in
 > the standard library helps end users.

Right.  And this PEP is about how to get good code into the stdlib
faster.  It's a means to that intermediate end, and transitively a
means to the real end of helping end users.

 > Not surprisingly, there's nothing about why reserving the right to
 > rip out a package without warning is good for end uers, since it
 > isn't.

What it really comes down to is you're saying you fear you will
frequently disagree with the judgment of python-dev with regard to the
options provided by "provisional".  You want them bound by hard and
fast rules.  That's fine; everybody has their own requirements.
Nevertheless, it's logically possible that as long as you pay
attention to "provisional" markings this PEP will be a win for you.

I agree with the PEP proponents that "logically possible" can be
strengthened to "probably true", but of course YMMV.




Footnotes: 
[1]  http://www.python.org/download/releases/3.3.0/
     http://docs.python.org/3.3/whatsnew/3.3.html