On Wed, 13 Dec 2006 09:45:51 -0800, Nick Alexander <[EMAIL PROTECTED]>
wrote:
>> No. That is a result of a change in SAGE -- namely I added an option to
>> SAGEX
>> so it records the file and location where functions are defined. This
>> is
>> used at runtime for source code viewing, and displaying correct
>> functions
>> headers.
>> The update_script.py script doesn't know about this change. It could
>> be
>> used
>> to improve the quality of ref.tex (e.g., find the function headers
>> easily).
>
> I would very much like to enhance sagex to embed _more_ information
> about cdef'd functions. At the moment, the python inspect module gives
> very little information about them. While we might not be able to
> include code pointers, etc, we can definitely include arguments and
> default values. I'd like to use that information for better formatting
> and better tested documentation, but it would also make for better
> inline help.
Currently the file and line number allows one to extract all
necessary additional information with almost no additional
space overhead. Likewise, the Python inspect module
extracts much information of usual .py code from the actual
source files (and does not work if they are not present).
So I think the thing to do is implement (using the fact that
filename and location information are embedded in the docstring)
an inspect-like API for pyrex files. I do *not* think you should
change sagex to embed _more_ information -- since Python doesn't
even take that approach. Maybe information about function inputs
would be good though.
> I envision making docstrings hash tables, i.e. such that eval(__doc__)
> returns a dict. Your patch would be upgraded to make the docstring
>
> r"""
> { 'im_class' : 'sage.blah.module.Class'
> , 'im_func' : { 'attributes about function' : 'blah' }
> , '__doc__': 'original docstring'
> }"""
>
> etc.
>
> There are downsides. First, we're carting around a lot of information
> in the docstrings. There's a space penalty, and also a
> not-using-the-natural-structure penalty. I think docstring has to be a
> string, though, so we're stuck. If it can be an object with a
> __repr__, I'd be much happier.
No it is a string.
> Second, we'd be parsing the docstring
> ourselves or calling eval. One tends to be a little brittle, the other
> a security hole.
>
> Let me know what you think,
I am against enhancing the docstrings as you suggest. I think we should
write code to parse the original .pyx files, given the filename and line
number information. There is no extra overhead spacewise, and this fits
with how the rest of Python works better. Also, it is what I already
planned to do, but hadn't got to yet All I did was put something for
parsing out the source code -- try ?? on a sagex function.
William
--~--~---------~--~----~------------~-------~--~----~
To post to this group, send email to sage-devel@googlegroups.com
To unsubscribe from this group, send email to [EMAIL PROTECTED]
For more options, visit this group at http://groups.google.com/group/sage-devel
URLs: http://sage.scipy.org/sage/ and http://modular.math.washington.edu/sage/
-~----------~----~----~----~------~----~------~--~---
