[Python-Dev] Breaking undocumented API

[Guido van Rossum]

On Wed, Nov 17, 2010 at 8:23 AM, James Y Knight <foom at fuhm.net> wrote:
> On Nov 17, 2010, at 10:30 AM, Guido van Rossum wrote:
>> On Wed, Nov 17, 2010 at 7:24 AM, James Y Knight <foom at fuhm.net> wrote:
>>> On Nov 17, 2010, at 9:19 AM, Nick Coghlan wrote:
>>>> (and is a little trickier in the case of module level globals, since those can't be deprecated properly)
>>>
>>> People keep saying this, but there have already been examples shown of how to do it. I actually think that python should include a way to do so standard -- it's a reasonable enough desire, as shown by how many times in this thread the inability to do so has been mentioned. If the existing working 3rd-party mechanisms aren't good enough for python-dev standards, come up with a new way...
>>
>> That's quite the distraction from the current thread though. Start
>> discussing it on python-ideas, or submit a code fix, or something in
>> between. But the hackish way that some 3rd party frameworks use
>> (replacing the module object with a class instance in sys.modules) is
>> clearly not right for the standard library (I'll explain on
>> python-ideas if you insist).
>
> I just don't want people to use the current lack as an excuse to simply remove module attributes without prior deprecation (or make a compatibility policy which recommends doing such a thing). I'll leave it up to the experts on this list (or python-ideas...) to determine how to implement a module-level deprecation in a way that isn't considered "hackish". (Or, if there is no such way, there's also the alternative of simply never removing module-level names.)

Deprecation doesn't *require* logging a warning or raising an
exception. You can also add a note to the docs, or if it is
undocumented, just add a comment to the code. (Though if it is in
widespread use despite being undocumented, a better way would be to
document it first -- as immediately deprecated if necessary.)

Deprecation is in the end a way to give people advance warning about
future changes. The mechanism of the warning doesn't always have to be
implemented by the interpreter/compiler/parser or whatever other tool.

-- 
--Guido van Rossum (python.org/~guido)