[Python-Dev] Breaking undocumented API

[Brett Cannon]

On Mon, Nov 8, 2010 at 13:03,  <exarkun at twistedmatrix.com> wrote:
> 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?

There is no way to directly trigger a DeprecationWarning for an
attribute. We can still document it, but there is just no way to
programmatically enforce it.

-Brett

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