[Python-Dev] PEP 411: Provisional packages in the Python standard library (original) (raw)

Nick Coghlan ncoghlan at gmail.com
Sun Feb 12 05:07:25 CET 2012

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

More information about the Python-Dev mailing list