[Numpy-discussion] NumPy 1.2.0b2 released

[Stéfan van der Walt]

2008/8/18 Andrew Dalke <dalke at dalkescientific.com>:
> How do users know that those are present?  How do users
> view those docs?  You're the one who added that directory, yes?,
> so you've probably got the most experience with it.  I
> couldn't figure out it, and the README in the doc/ directory
> wasn't helpful.

The numpy/doc directory existed before I implemented this, which may
explain some "odd" design decisions.  Usage is meant to happen via
"help" or IPython's "?":

In [2]: np.doc?
Type:		module
Base Class:	<type 'module'>
String Form:	<module 'numpy.doc' from
'/Users/stefan/lib/python2.5/site-packages/numpy/doc/__init__.pyc'>
Namespace:	Interactive
File:		/Users/stefan/lib/python2.5/site-packages/numpy/doc/__init__.py
Docstring:
    The following topics are available:

    - basics
    - broadcasting
    - creation
    - glossary
    - howtofind
    - indexing
    - internals
    - io
    - jargon
    - methods_vs_functions
    - misc
    - performance
    - structured_arrays
    - ufuncs

In [3]: np.doc.broadcasting?
Type:             module
Base Class:       <type 'module'>
String Form:   <module 'numpy.doc.reference.broadcasting' from
'/Users/stefan/lib/python2.5/site-packages/numpy/doc/reference/broadcasting.pyc'>
Namespace:        Interactive
File:
/Users/stefan/lib/python2.5/site-packages/numpy/doc/reference/broadcasting.py
Docstring:
    ========================
    Broadcasting over arrays
    ========================

[...]

> I agree, the load time is very small.  But with all my patches
> in place the import time goes down from about 0.18 second to
> about 0.10 seconds.  Times add up.

Here are some of the timings I did, for interest's sake:

For each trial, I included N copies of the NumPy documentation
guide as topics under "numpy.do", and took the best of 3 trials.  The
topic number is currently 14.

Without numpy.doc:

real    0m0.259s
user    0m0.082s
sys     0m0.169s

--------------------

200 files

real    0m0.341s
user    0m0.095s
sys     0m0.232s

---------------------

100

real    0m0.282s
user    0m0.087s
sys     0m0.190s

---------------------

50

real    0m0.273s
user    0m0.085s
sys     0m0.179s
stefan at appel:/tmp$ time python -c 'import numpy'

---------------------

20

real    0m0.262s
user    0m0.083s
sys     0m0.173s

------------------------

>> I still think we are going about this the wrong way.  We have two
>> different sets of expectations, and we can't satisfy both by ripping
>> everything apart.  I'd much prefer two entry points into NumPy: one
>> for people who need speed, and one for those who need the convenience
>> of everything being at hand.
>
> I thought I was very careful to not rip things apart. :(
>
> Everything I did was API compatible except for the
> proposed removals of numpy.ctypeslib and numpy.doc.  I
> chose ctypeslib because importing ctypes takes 10% of
> the total load time on my box.  I chose numpy.doc because
> I couldn't figure out how it's used.

Sorry, I did not mean to make you sound like a back-yard surgeon!
Maybe hyperbole is best avoided.  I am quite happy with the non-API
changing modifications you propose, and probably with the others too:
I just want us to get our heads together and decide on a policy before
we proceed (see my reply to Travis).

> It seems like every time I use num* (which isn't often) I
> need to learn a new library.  I don't want to switch again
> for a few years.

Sure, we all need to get work done.  But in "we" I include those who
already wrote apps using numpy.ctypeslib.

Cheers
Stéfan