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
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4