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 _______________________________________________ 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
