[Python-Dev] Breaking undocumented API

[James Y Knight]

On Nov 17, 2010, at 11:38 AM, Guido van Rossum wrote:
> 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.

Well, that's certainly a possible policy. I'd suggest that adding notes to the docs after-the-fact is a singularly ineffective way of giving people advance warning of feature removal compared to having the interpreter/compiler/parser or whatever other tool warn you. And if that's to be python's policy, when it's possible to do better, I'm disappointed. (But won't respond further, my point is made.)

James