[Python-Dev] Breaking undocumented API

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