[Numpy-discussion] [Matplotlib-users] [matplotlib-devel] Unifying numpy, scipy, and matplotlib docstring formats

[Chris Barker]

There's probably a better forum for this conversation, but...

Barry Wark wrote:
> Perhaps we should consider two use cases: interactive use ala Matlab
> and larger code bases.

A couple key points -- yes, interactive use is different than larger 
code bases, but I think it's a "Bad Idea" to promite totally different 
coding styles for these cases for a couple reasons:

-- One usually is doing both at once. I was a long-time, every day 
Matlab user, and hardly did anything of consequence interactively. I 
learned very quickly that it made a whole lot more sense to write a five 
line script that I could save, edit, etc. than do stuff interactively. 
Once I got something working, parts of that five line script might get 
cut&pasted into "real" code.

I do still test one or two lines interactively, but even then, I want 
the style to be something I can put in my code.

2) consistency in docs and examples is important, recommending different 
styles for interactive and programming use is just going to confuse 
people more.

3) even for folks that do a lot of interactive use, they are likely to 
write larger scale code at some point, and then they would need to learn 
something new.

> In the first case, being able to import * saves
> a lot of typing

No, it saves a little typing, if you're using an OOO style anyway.

 > and the namespace polution problem isn't a big deal.

Yes, it can be. A good interactive environment will be able to do things 
like method and command completion -- namespace pollution keeps that 
from working well.

> Returning to the OP's questions, why couldn't both cases be helped by
> creating a "meta-package" for numpy, scipy, and matplotlib? For the
> sake of argument, lets call the package "plab". Existing code could be
> affected by changing the individual packages, but a package that
> essentially does
> 
> from pylab import *
> from numpy import *
> from scipy import *


The issue with this is that you've now hidden where things are coming 
from. People seeing examples using that package will have no idea where 
things come from.

and by the way, the current "pylab", as delivered with MPL, pretty much 
does this already. I think we need to move away from that, rather than 
putting even more into pylab.

Matthew Brett wrote:
>  The downside about making numpy / python like matlab is that
> you soon realize that you really have to think about your problems
> differently, and write code in a different way.

Good point. A part of good Pythonic code is namespaces and OOO style. 
New users might as well learn the whole pile at once.

That all being said, it would be nice to establish a standard convention 
for how to import the key packages. I use:

import numpy as N
import matplotlib as MPL

But I don't really care that much, if we can come to any kind of 
community consensus, I'll follow it. The goal would be for all docs, 
Wiki entries, examples on the mailing lists, etc. to use the same style.

-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@noaa.gov