[SciPy-dev] adopting Python Style Guide for classes

[Robert Kern]

Perry Greenfield wrote:
> On Oct 3, 2007, at 2:26 PM, Jarrod Millman wrote:
> 
>>> 3) Greater time should be provided to accommodate the transition. For
>>> example, there should not be deprecation warnings in the first
>>> version that this API appears in. The first release of this should
>>> not lead to nuisance messages for those that have other software that
>>> depends on this. (A tool that allows conditional messages would be
>>> good, but the default should be no message). The next release, sure.
>>> As a result, it means that the old API can't be removed until at
>>> least two releases after that.
>> I am not sure I agree with this.  For example, I think it would be
>> acceptable for NumPy 1.1.0 to have deprecation warning about changed
>> APIs.  Perhaps you were saying that NumPy 1.0.4 could use the new
>> class names in addition to the old names without complaint.  That
>> sounds reasonable to me.  Then when NumPy 1.1.0 comes out the old
>> style names would raise deprecation warnings.
>>
> The situation I'm trying to avoid is a too tight coupling between  
> numpy changes and client applications that use numpy. Suppose we  
> distribute an application that uses numpy. We could make the changes  
> to our application before the api-change release comes out (from svn)  
> and then when we release our new version (very soon after the api- 
> changed numpy comes out) we effectively force all of our users to  
> update immediately. The problem is that they may not want to update  
> on our schedule. They become annoyed at us.
> 
> So we take the other tack, we wait for a while before changing our  
> code to require the new numpy. This give the user community time to  
> switch their stuff too. But, now our code generates annoying  
> deprecation warnings that are useless to the people we distribute  
> applications to if they update to the new numpy before we do. Here's  
> where I display some ignorance. If the warnings use the standard lib  
> warning module, I'm guessing that we can add warnings filters to  
> suppress any warnings that arise from our code (but not having much  
> experience with it, it isn't clear to me whether the filter  
> suppresses all warnings arising from numpy or whether one can  
> suppress only those associated with ones that are from the  
> applications use). But it's good to clarify this point. If they are  
> present by default, an application needs to be able to suppress them.

The warnings module allows one to filter warnings very specifically, down to the
line number in the module where the warning is issued. If you can catalog the
warnings that are raised by your application (say by running your test suite),
then you can filter out just those.

>>> 5) In my humble opinion, we would be nuts--absolutely nuts--to change
>>> either the type classes or the factory functions. This would be
>>> foolish consistency at it's worst. We *just* went through the
>>> exercise of changing Int32 to int32 and so forth and we would have to
>>> change back again? This cannot be seriously considered.
>> I think that the general consensus is that we should keep int32,
>> rather than switch to Int32.
> 
> That's good. But what about array(), zeros(), ones(), arange(), etc.?

They're all functions and not affected.

-- 
Robert Kern

"I have come to believe that the whole world is an enigma, a harmless enigma
 that is made terrible by our own mad attempt to interpret it as though it had
 an underlying truth."
  -- Umberto Eco