[SciPy-Dev] Mea culpa: deprecation and API changes

[Warren Weckesser]

Ryan May wrote:
> On Wed, Jun 2, 2010 at 7:04 PM, Warren Weckesser
> <warren.weckesser at enthought.com> wrote:
>   
>> Warren Weckesser wrote:
>>     
>>> Opinion wanted:  codata.find(sub) used to print a list of strings.  A
>>> while ago, in response to http://projects.scipy.org/scipy/ticket/996,  I
>>> changed it to return the list of strings.  But this is an API change,
>>> and should follow the deprecation policy.  One way to do this is to
>>> restore find() to its previous behavior, and deprecate the function.  At
>>> the same time, add a new function, find_string(sub), which returns the
>>> list of strings.  What do you think?
>>>
>>>
>>>       
>> Instead of creating a new function, I added a keyword argument whose
>> default value (True) preserves the old behavior.  When it is False, it
>> returns the keys instead of printing them.  In 0.9, the default behavior
>> will be reversed.
>>     
>
> Why not always return the list and just make only the print controlled
> by the kwarg? That way the return type of the function doesn't depend
> on a kwarg, which IIRC is considered bad style. You won't break
> existing code, which will just ignore the new return value.
>   

That seemed the most conservative approach, despite being bad style.  It 
can all be cleaned up in 0.9 anyway.

I'm currently working on "fixing" signal.waveforms.chirp to maintain 
compatibility for one release cycle.  More judgment calls will be 
required, and I'm sure that not everyone would do it the same way.

Anyone want to write the official "SciPy Developers Deprecation 
Guidelines (with recommended patterns of deprecation and a bunch of 
use-cases)"?

Warren

> Ryan
>
>