[Numpy-discussion] New documentation web application

[John Hunter]

On Sat, May 31, 2008 at 4:05 AM, R. Bastian <rbastian@free.fr> wrote:

>> Neat!  I really like the layout.  The red format warnings are a nice touch:
>> http://sd-2116.dedibox.fr/pydocweb/doc/numpy.core.umath.exp/

Hi, I was just reading through this example when I noticed this usage:

  from matplotlib import pyplot as plt

Although this is of course perfectly valid python, I have been
encouraging people when importing modules from packages to use the
syntax:

    import somepackage.somemodule as somemod

rather than

    from somepackage import somemodule as somemod

The reason is that in the first usage it is unambiguous that
somemodule is a module and not a function or constant.   Eg, both of
these are valid python:

    In [7]: from numpy import arange

   In [8]: from numpy import fft

but only the module import is valid here:

    In [3]: import numpy.fft as fft

    In [4]: import numpy.arange as arange
    ImportError                               Traceback (most recent call last)
    ImportError: No module named arange

I taught a class on scientific computing in python to undergraduates,
and the students  were frequently confused about what was a module and
what was a function.  If you are coming from matlab, you are likely to
think fft is a function when you see this:

  from numpy import fft

By being consistent in importing modules using the 'import numpy.fft
as fft', it can make it more clear that we are importing a module.

I already recommend this usage in the matplotlib coding guide, and
numpy may want to adopt it as well.

JDH