[Numpy-discussion] [SciPy-dev] adopting Python Style Guide for classes

[Jarrod Millman]

On 10/3/07, Perry Greenfield <perry at stsci.edu> wrote:
> 2) API changes should only be made in major releases, not minor
> releases (IMHO).

+1

> 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.

> 4) More information should be provided as to what actually will
> change in the public interface. I suspect that it isn't obvious to
> many what will change. From the mailing list discussions there
> doesn't even seem to be consensus on the factory functions or type
> objects (more on these later). Many of the remaining objects are
> probably used internally (essentially private) and will affect few
> outside of the numpy developers. Since users typically deal mostly
> with factory functions, and other functions, they may not deal with
> classes much (outside of types). So listing the public classes so
> affected will help people understand what changes typical users will
> see, and what changes advanced users will see. While this is
> annoying, I think someone needs to write up an explicit list of those
> public classes that will be changed (and those that won't) so we all
> know what we will face. It may be a very small list and thus
> alleviate concern about the process. It may show some surprises that
> people hadn't thought about. Not doing this before making the changes
> seems very unwise.

As long as we agree in principle how we want classes named, I think
there is little need to rush to change existing class names.

> 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.

-- 
Jarrod Millman
Computational Infrastructure for Research Labs
10 Giannini Hall, UC Berkeley
phone: 510.643.4014
http://cirl.berkeley.edu/