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

[Nick Coghlan]

On Sun, Feb 12, 2012 at 2:45 AM, Isaac Morland <ijmorlan at uwaterloo.ca> wrote:
> 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 at gmail.com   |   Brisbane, Australia