[Python-Dev] Breaking undocumented API (original) (raw)

exarkun at twistedmatrix.com exarkun at twistedmatrix.com
Mon Nov 8 22:03:18 CET 2010

On 07:58 pm, brett at python.org wrote:

I don't think a strict don't remove without deprecation policy is workable.  For example, is trace.rxblank constant part of the trace module API that needs to be preserved indefinitely?  I don't even know if it is possible to add a deprecation warning to it, but CoverageResults.blankre would certainly be a better place for it. The deprecation policy obviously cannot apply to module-level attributes.

I'm not sure why this is. Can you elaborate?

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

+1

Jean-Paul

More information about the Python-Dev mailing list