[SciPy-dev] Namespaces in documentation

[John Hunter]

On Tue, Jun 3, 2008 at 9:11 AM, Joe Harrington <jh at physics.ucf.edu> wrote:

> Aside from the embarrassment of declaring a mistake on every page of
> documentation, the proposed path makes the documentation not work for
> several classes of users who should by all rights have it work for
> them.  These alienated users have more primary rights than those for
> whom abbreviations are conveniences, which admittedly is most of us
> (including me).  They include:

This is not an issue of having made a mistake that we are trying to
hide by using an alias.  It is an issue of trying to strike the right
balance between readability and usability.  Many of us write a lot of
code in three different environments: scripts, production libraries,
and interactively from the python shell, and find that the recommended
import semantics strike the right balance.  Ideally, we would like one
solution that works pretty well in all three context  so we don't have
to do the mental context switching: "I'm scripting now so I should do
this, I'm at the python shell now so I should do that, I'm working on
mpl src now so do something else"

Interactively from the python shell, it is easiest to type

    >>>  sin(2*pi*t)*exp(-t)

so it is nice to first do

    >>> from numpy import sin, pi, exp

But this idiom doesn't work very well for large pieces of production
code.  We did this in matplotlib for years, and were constantly moving
back and forth from the import section to the code section to find out
if a symbol is already imported.   It is very nice when writing large
pieces of code to know that some name is available, so we can do

   x = numpy.arange(10.)
   y = numpy.sin(2*numpy.pi*x) * numpy.exp(x)

w/o having to go looking at the import layer.  That is manageable, but
a bit ugly, which is why most people prefer an alias, and these
aliases are *widely* used throughout the entire code base of numpy,
scipy and matplotlib.  This is not an embarrassment or an admission of
a mistake, it is taking advantage of a language feature benevolently
bestowed upon us by Guido.

The nice thing about the

  import numpy as np

alias is that it is sufficiently short that you can use it in scripts
and interactive sessions, and sufficiently mnemonic that you can use
it in production code.  It is also easy to type, as are the other
recommended aliases.

Of course you are right that we run the risk of clashes with other
people who will be using np as a variable name or another package (a
little unlikely on the latter since it would be pretty foolish to name
a package with two letters for precisely the reason that it is likely
to clash).  Recognizing that aliases are a good thing, and any alias
will clash sometimes, several of us got together (including lead
developers of ipython, numpy, scipy and matplotlib) and decided to
recommend a usage, precisely to lower the risk of clashes.  If we are
consistent in the usage in the docs and code, and publicly recommend
it, then clashes are less likely.

As for those worried about an ipython requirement, there isn't one.
plain-ol-python  supports import configuration as well, so a python
shell properly configured for numpy/scipy will support pasting from
the docs anyhow.
http://docs.python.org/tut/node4.html#SECTION004240000000000000000

Finally, whatever standard you adopt for the docs, a decision has
already been made by the ipython, numpy, scipy and matplotlib
developers to use this alias convention in their source code.  Since
many users eventually become developers, it is nice to have a
consistent approach between what is advocated the user documentation
and the source code, where feasible.

JDH