2008/8/18 Andrew Dalke dalke@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@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