[Python-Dev] Breaking undocumented API

[Glyph Lefkowitz]

On Nov 8, 2010, at 2:35 PM, exarkun at twistedmatrix.com wrote:

> On 09:57 pm, brett at python.org wrote:
>> On Mon, Nov 8, 2010 at 13:45,  <exarkun at twistedmatrix.com> wrote:
>>> On 09:25 pm, brett at python.org wrote:
>>>> 
>>>> 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.
>>> 
>>> What about `deprecatedModuleAttribute`
>>> (<http://twistedmatrix.com/documents/current/api/twisted.python.deprecate.html>)
>>> or zope.deprecation
>>> (<http://docs.zope.org/zope3/Book/deprecation/show.html>) which inspired it?
>> 
>> Just checked the code and it looks like it substitutes the module for
>> some proxy object? To begin that break subclass checks. After that I
>> don't know the ramifications without really digging into the
>> ModuleType code.
> 
> That could be fixed if ModuleType allowed subclassing. :)
> 
> For what it's worth, no one has complained about problems caused by `deprecatedModuleAttribute`, but we've only been using it for about two and a half years.

This seems like a pretty clear case of "practicality beats purity".  Not only has nobody complained about deprecatedModuleAttribute, but there are tons of things which show up in sys.modules that aren't modules in the sense of 'instances of ModuleType'.  The Twisted reactor, for example, is an instance, and we've been doing *that* for about 10 years with no complaints.