[Python-Dev] Breaking undocumented API
brett at python.org
Mon Nov 8 22:25:58 CET 2010
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.
>> 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,
>> 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.
More information about the Python-Dev