[matplotlib-devel] Unifying numpy, scipy, and matplotlib docstring formats

Keir Mierle wrote:

p.s. This is part of my plan to kick off http://scipy.org/PyLab

Great Plan, and I think kicking it off with better docstrings is a good start.

One comment, from your Wiki Page:

"""
I feel strongly that the correct way to import the entire core PyLab API should be via

from pylab import *
"""

No, no, no, no NO!

see, I feel strongly too ;-).

You are trying to build something that is better than MATLAB. The one way you are almost guaranteed to achieve that is that it is built on the Python language, which is much more powerful and flexible than Matlab, but you know that already.

However, you are tossing away a lot of the advantage if you don't keep the focus on being pythonic, and that means, in this case:

"Namespaces are one honking great idea -- let's do more of those!"

note, NOT "fewer of those"

numpy + matplotlib + scipy

is a LOT of functionality. It should not be all in the same namespace. It's really not that hard to do something like:

import matplotlib as plot
import numpy as N
import Scipy.whatever as whatever.

I think it's very helpful to keep things clean and separated. Sure, you can work to remove duplication an name clashes among these three packages, but what if the user decides they also need PIL, or PyGame, or PyNetCDF, etc, etc. One of the real powers of Python is that it has broad use, and that there is a module for just about everything you need to do, all maintained by others -- you are guaranteed name clashes if you don't use namespaces -- that's what they are for.

Note python itself. A lot of common functionality is in modules you need to import: sys, os, sys.path, string (though string methods remove much of that need) This is a GOOD model!

Also, I'd really like to see far more use of an OO approach in matplotlib use (and maybe scipy -- I haven't used much of it). If you note, numpy has made lots of things ndarray methods that were functions in Numeric -- this makes NOT using "import *" much cleaner.

In short: I think your goals are great, most of your approach is good, but please: Keep PyLab pythonic -- don't try to make it more like matlab, or fortran, or any other language -- your users will thank you for it later!

See recent discussions on the matplotlib list about this topic. I think even John is shifting toward wanting more use of the OO interface.

-Chris

···

--
Christopher Barker, Ph.D.
Oceanographer

Emergency Response Division
NOAA/NOS/OR&R (206) 526-6959 voice
7600 Sand Point Way NE (206) 526-6329 fax
Seattle, WA 98115 (206) 526-6317 main reception

Chris.Barker@...259...

One more namespace "pro" (on point, since you're concerned w/ docstrings, and thus, presumably, usability): indicating the namespace makes your code more self-documenting (my favorite aspect of it).

DG

Christopher Barker wrote:

···

Keir Mierle wrote:
  

p.s. This is part of my plan to kick off http://scipy.org/PyLab
    
Great Plan, and I think kicking it off with better docstrings is a good start.

One comment, from your Wiki Page:

"""
I feel strongly that the correct way to import the entire core PyLab API should be via

from pylab import *
"""

No, no, no, no NO!

see, I feel strongly too ;-).

You are trying to build something that is better than MATLAB. The one way you are almost guaranteed to achieve that is that it is built on the Python language, which is much more powerful and flexible than Matlab, but you know that already.

However, you are tossing away a lot of the advantage if you don't keep the focus on being pythonic, and that means, in this case:

"Namespaces are one honking great idea -- let's do more of those!"

note, NOT "fewer of those"

numpy + matplotlib + scipy

is a LOT of functionality. It should not be all in the same namespace. It's really not that hard to do something like:

import matplotlib as plot
import numpy as N
import Scipy.whatever as whatever.

I think it's very helpful to keep things clean and separated. Sure, you can work to remove duplication an name clashes among these three packages, but what if the user decides they also need PIL, or PyGame, or PyNetCDF, etc, etc. One of the real powers of Python is that it has broad use, and that there is a module for just about everything you need to do, all maintained by others -- you are guaranteed name clashes if you don't use namespaces -- that's what they are for.

Note python itself. A lot of common functionality is in modules you need to import: sys, os, sys.path, string (though string methods remove much of that need) This is a GOOD model!

Also, I'd really like to see far more use of an OO approach in matplotlib use (and maybe scipy -- I haven't used much of it). If you note, numpy has made lots of things ndarray methods that were functions in Numeric -- this makes NOT using "import *" much cleaner.

In short: I think your goals are great, most of your approach is good, but please: Keep PyLab pythonic -- don't try to make it more like matlab, or fortran, or any other language -- your users will thank you for it later!

See recent discussions on the matplotlib list about this topic. I think even John is shifting toward wanting more use of the OO interface.

-Chris

--
ERD/ORR/NOS/NOAA <http://response.restoration.noaa.gov/emergencyresponse/>

One more thing: knowing Chris, I *think* that he wasn't saying that you should somehow *oblige* the coder to use namespace prefices, rather, don't do anything that would make it harder or less efficient to do so, right Chris?

DG

Christopher Barker wrote:

···

Keir Mierle wrote:
  

p.s. This is part of my plan to kick off http://scipy.org/PyLab
    
Great Plan, and I think kicking it off with better docstrings is a good start.

One comment, from your Wiki Page:

"""
I feel strongly that the correct way to import the entire core PyLab API should be via

from pylab import *
"""

No, no, no, no NO!

see, I feel strongly too ;-).

You are trying to build something that is better than MATLAB. The one way you are almost guaranteed to achieve that is that it is built on the Python language, which is much more powerful and flexible than Matlab, but you know that already.

However, you are tossing away a lot of the advantage if you don't keep the focus on being pythonic, and that means, in this case:

"Namespaces are one honking great idea -- let's do more of those!"

note, NOT "fewer of those"

numpy + matplotlib + scipy

is a LOT of functionality. It should not be all in the same namespace. It's really not that hard to do something like:

import matplotlib as plot
import numpy as N
import Scipy.whatever as whatever.

I think it's very helpful to keep things clean and separated. Sure, you can work to remove duplication an name clashes among these three packages, but what if the user decides they also need PIL, or PyGame, or PyNetCDF, etc, etc. One of the real powers of Python is that it has broad use, and that there is a module for just about everything you need to do, all maintained by others -- you are guaranteed name clashes if you don't use namespaces -- that's what they are for.

Note python itself. A lot of common functionality is in modules you need to import: sys, os, sys.path, string (though string methods remove much of that need) This is a GOOD model!

Also, I'd really like to see far more use of an OO approach in matplotlib use (and maybe scipy -- I haven't used much of it). If you note, numpy has made lots of things ndarray methods that were functions in Numeric -- this makes NOT using "import *" much cleaner.

In short: I think your goals are great, most of your approach is good, but please: Keep PyLab pythonic -- don't try to make it more like matlab, or fortran, or any other language -- your users will thank you for it later!

See recent discussions on the matplotlib list about this topic. I think even John is shifting toward wanting more use of the OO interface.

-Chris

--
ERD/ORR/NOS/NOAA <http://response.restoration.noaa.gov/emergencyresponse/>