[Python-Dev] Support for PyGetSetDefs in pydoc

[Barry Warsaw]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

On Jul 10, 2006, at 9:52 PM, Barry Warsaw wrote:

> Patch #1520294 adds support for attributes defined with PyGetSetDef  
> in extension modules to pydoc, specifically so things like help 
> (array.array.typecode) gives something useful, like the attribute's  
> docstring for instance.
>
> Along the way, I added types.GetSetterType and inspect.isgetsetter 
> (), along with tests and docs.  Now I definitely think that the  
> pydoc change should go into Python 2.5 and be backported to Python  
> 2.4, but it's a bit of a question whether the types.py and  
> inspect.py changes should go into Python 2.5 now that we're in beta.
>
> I personal think they're worthwhile changes to go it, but I won't  
> argue too hard for them since the pydoc fixes can be implemented  
> with local changes to pydoc.py alone.

Turns out there is at least one other type that I think should be  
better supported, but which I'm having a hard time figuring out the  
right way to do this.  Member descriptors are one such type, an  
example of which is datetime.timedelta.days

 >>> import datetime
 >>> type(datetime.timedelta.days)
<type 'member_descriptor'>

Do a help(datetime.timedelta.days) and you get nothing useful.

Now, I started down a similar path for solving this as I did the  
other day for getset descriptors, but I've run into a bit of a  
roadblock.  What you basically want to do is add a constant to the  
types module, then add an is-predicate to inspect.py, then add the  
necessary glue to pydoc.py.  The problem is that you have to have  
something readily available to call type() on to get a member  
descriptor type, and for that you have to go hunting around in  
Python's C layer.  Basically you're looking for a type initialized  
with PyObject_HEAD_INIT(NULL) /and/ has a tp_members slot.

There are a few of them around, such as the datetime.timedelta type  
mentioned above, but they all have a pretty serious problem.  You  
cannot import their module in types.py.  I'm not exactly sure why  
this is, but if you put

import datetime

in types.py, you'll get the "import site" failed error.  Run with -v  
and you get buried in the output:

'import site' failed; traceback:
Traceback (most recent call last):
   File "/Users/barry/projects/python/Lib/site.py", line 62, in <module>
     import os
   File "/Users/barry/projects/python/Lib/os.py", line 690, in <module>
     import copy_reg as _copy_reg
   File "/Users/barry/projects/python/Lib/copy_reg.py", line 7, in  
<module>
     from types import ClassType as _ClassType
   File "/Users/barry/projects/python/Lib/types.py", line 90, in  
<module>
     import datetime
ImportError: No module named datetime

I think the problem is that the platform-specific extension module  
directory isn't on sys.path yet, so it can't e.g. find datetime.so.   
Of course, datetime is perfectly importable later on.

As far as I can tell, there does not seem to be any candidate member  
descriptors that are built into the interpreter and guaranteed to be  
there early enough to import into types, but maybe I'm missing  
something.

I can think of a number of ways to address this, with varying levels  
of ickyness, but I wanted to see what you all thought.

For example, I could change inspect locally so that it gets the type  
of datetime.timedelta.days without adding a constant to types.py.  Or  
I could patch pydoc.py directly and leave even inspect.py out of it.   
Or I could create some stupid internal type in some stupid internal  
module who's only purpose would be to have a handle on member  
descriptors.  Or I could change datetime to be built-in.  (see what I  
mean about levels of ickyness? :).

I'm up for suggestions.  I think this would be worthwhile to address  
in Python 2.5 since I think it would be good to have an accurate  
representation of Python's built-in types in types.py.  Ultimately, I  
really care about teaching pydoc.help() about instances of these  
types so that users can get better help when they encounter them  
(such as might be the case in 3rd party extension modules).

Suggestions are welcome.
- -Barry

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.3 (Darwin)

iQCVAwUBRLVF6XEjvBPtnXfVAQJVmAP5ATS56TtrdUamo+CxdNHrP6j7zxwEef2t
fCM3XuEjv/Y+UH3goQIm34ENySjqYgC/whQqXGPWa/5GVc1MkhZo3W2BsA4NJ8yq
Za8+6+KsWaR625qj/mh/Fbw5I/2vOE3MClATuQ75aCJjLpSAwhxYqleYPTD7tBiF
P4zc+2OYedU=
=ikCK
-----END PGP SIGNATURE-----