[Python-Dev] Breaking undocumented API

Tue Nov 9 00:05:19 CET 2010

On 11/8/2010 2:58 PM, Brett Cannon wrote:
> I think we need to, as a group, decide how to handle undocumented APIs
> that don't have a leading underscore: they get treated just the same
> as the documented APIs, or are they private regardless and thus we can
> change them at our whim?

How about in between: deprecate as if private, but do so much more 
freely that we would for public stuff. I think this is what you actually 
propose. We might deprecate faster too.
> The main reason I have said that non-underscore names should be
> properly deprecated (assuming they are not contained in an
> underscored-named module) is that dir() and help() do not distinguish.
> If you are perusing a module from the interpreter prompt you have no
> way to know whether something is public or private if it lacks an
> underscore. Is it reasonable to assume that any API found through
> dir() or help() must be checked with the official docs before you can
> consider using it, even if you have no explicit need to read the
> official docs?
>> I (unfortunately) say no, which is why I have argued that
> non-underscored names need to be properly deprecated. This obviously
> places a nasty burden on us, though, so I don't like taking this

Completely naive question: Is there anything that could be automated to 
reduce the burden?
> position. Unless we can make it clearly known through help() or
> something that the official docs must be checked to know what can and
> cannot be reliably used I don't think it is reasonable to force users
> to not be able to rely on help() (we should probably change help() to
> print a big disclaimer for anything with a leading underscore,
> though).
>> But that doesn't mean we can't go through, fix up our names, and
> deprecate the old public names; that's fair game in my book.

-- 
Terry Jan Reedy