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

To follow on to my previous posting on this topic given Robert's response. As I said previously, I was never strongly committed to one approach or the other. But since the v1 release has been made, I think more care needs to be given to consideration of proposals like this before actually charging off to make the changes. 1) Even though Robert is speaking for Travis, I think given Travis's role in numpy, it is important for Travis to speak directly to this when he gets the chance. 2) API changes should only be made in major releases, not minor releases (IMHO). 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. 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. 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. Perry Greenfield On Oct 2, 2007, at 1:24 PM, Jarrod Millman wrote:
Hello,
For those of you not on the Numpy developer's list, we have been talking about adopting the Python class naming convention to conform with Guido's style guide as closely as possible: http://www.python.org/dev/peps/pep-0008/ According to Guido, class names should use the CapWords convention. Most Python projects (eg, ETS, matploltlib) adhere to the Python naming conventions and it is confusing that NumPy and SciPy don't.
Currently, both NumPy and SciPy use either lower_underscore_separated or CapWords for class names.
NumPy ====== $ grep -r '^class [A-Z]' --include "*.py" * | wc -l 1014 $ grep -r '^class' --include "*.py" * | grep -v 'class [A-Z]' | wc -l 207
SciPy ===== $ grep -r '^class [A-Z]' --include "*.py" * | wc -l 587 $ grep -r '^class' --include "*.py" * | grep -v 'class [A-Z]' | wc -l 565
So far, there is Universal support for the basic idea of conforming to the Python Style Guide. Since it should effect the user API, we have already updated the TestCase classes. First, we checked in a change to allow TestCase classes to be prefixed with either 'test' or 'Test': http://projects.scipy.org/scipy/numpy/changeset/4144 Then, we updated both SciPy and NumPy to use CapWords for TestCase classes: http://projects.scipy.org/scipy/numpy/changeset/4151 http://projects.scipy.org/scipy/scipy/changeset/3388 In order to run the SciPy tests on the trunk you will need to install NumPy from svn revision 4144 or greater. Before SciPy 0.7.0 is released, we will release NumPy 1.0.4.
Also, if you are adding a new class to NumPy or SciPy, please use CapWords. Now we need to decide what to do about the remaining lower_underscore_separated class names. Obviously, it is important that we are careful to not break a lot of code just to bring our class names up to standards.
Cheers,
-- Jarrod Millman Computational Infrastructure for Research Labs 10 Giannini Hall, UC Berkeley phone: 510.643.4014 http://cirl.berkeley.edu/ _______________________________________________ Scipy-dev mailing list Scipy-dev@scipy.org http://projects.scipy.org/mailman/listinfo/scipy-dev

On 10/3/07, Perry Greenfield <perry@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/

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

On 10/3/07, Perry Greenfield <perry@stsci.edu> 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.
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.?
Just to express my worries: I hope that numpy stays "easily typable" as a numerical and interactive (!) environment. What I'm trying to say: IMHO, "arange" should stay lower case, like "range", even if it might be (internally) implemented as a class. Similarly, many functions/objects/classes have a functional "feeling" to them, even tough they be implemented as classes. My 2 cents. -Sebastian Haase

To help me understand, might someone offer some examples of NumPy names that really should be changed? Thank you, Alan Isaac

Alan G Isaac <aisaac@american.edu> writes:
To help me understand, might someone offer some examples of NumPy names that really should be changed?
Internal classes, like: - nd_grid, etc. in numpy/lib/index_tricks.py - masked_unary_operation, etc. in numpy/core/ma.py Things we probably wouldn't change: - array-like things, such as numpy.lib.polynomial.poly1d - ufuncs implemented in Python like vectorize - distributions from scipy.stats In numpy, outside of tests, distutils, and f2py, there's actually not that many classes defined in Python (as opposed to C). In scipy, most non-testing classes are already CamelCase (one exception is weave). -- |>|\/|< /--------------------------------------------------------------------------\ |David M. Cooke http://arbutus.physics.mcmaster.ca/dmc/ |cookedm@physics.mcmaster.ca

On Thursday 04 October 2007 13:08:08 David M. Cooke wrote:
Alan G Isaac <aisaac@american.edu> writes:
To help me understand, might someone offer some examples of NumPy names that really should be changed?
Internal classes, like: - masked_unary_operation, etc. in numpy/core/ma.py
FYI, the new style has been followed in maskedarray (and a couple of recent bugs fixed in the SVN).
participants (6)
-
Alan G Isaac
-
cookedm@physics.mcmaster.ca
-
Jarrod Millman
-
Perry Greenfield
-
Pierre GM
-
Sebastian Haase